diff --git a/content/assets/images/data-refresh-view.png b/content/assets/images/data-refresh-view.png index 0464c654..4ad64ed9 100644 Binary files a/content/assets/images/data-refresh-view.png and b/content/assets/images/data-refresh-view.png differ diff --git a/content/assets/images/data-refresh-view2.png b/content/assets/images/data-refresh-view2.png index 55a1d7d6..0a8d31db 100644 Binary files a/content/assets/images/data-refresh-view2.png and b/content/assets/images/data-refresh-view2.png differ diff --git a/content/assets/images/dax-package-manager-overview.png b/content/assets/images/dax-package-manager-overview.png index 3b3f7297..a532593c 100644 Binary files a/content/assets/images/dax-package-manager-overview.png and b/content/assets/images/dax-package-manager-overview.png differ diff --git a/content/assets/images/features/bpa-built-in-rules-kb-link.png b/content/assets/images/features/bpa-built-in-rules-kb-link.png new file mode 100644 index 00000000..21ecd12f Binary files /dev/null and b/content/assets/images/features/bpa-built-in-rules-kb-link.png differ diff --git a/content/assets/images/features/bpa-built-in-rules-notification.png b/content/assets/images/features/bpa-built-in-rules-notification.png new file mode 100644 index 00000000..92391a32 Binary files /dev/null and b/content/assets/images/features/bpa-built-in-rules-notification.png differ diff --git a/content/assets/images/features/bpa-built-in-rules-preferences.png b/content/assets/images/features/bpa-built-in-rules-preferences.png new file mode 100644 index 00000000..501d243b Binary files /dev/null and b/content/assets/images/features/bpa-built-in-rules-preferences.png differ diff --git a/content/assets/images/features/bpa-built-in-rules-readonly.png b/content/assets/images/features/bpa-built-in-rules-readonly.png new file mode 100644 index 00000000..66d8a750 Binary files /dev/null and b/content/assets/images/features/bpa-built-in-rules-readonly.png differ diff --git a/content/features/Command-line-Options.md b/content/features/Command-line-Options.md index 0c140f8e..a9bafeb0 100644 --- a/content/features/Command-line-Options.md +++ b/content/features/Command-line-Options.md @@ -214,6 +214,58 @@ $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` exit $p.ExitCode ``` +### Passing Parameters to Scripts via Environment Variables + +When executing C# scripts with the `-S` switch in Azure DevOps pipelines, the recommended way to pass parameters is through environment variables rather than command-line arguments. C# scripts can read environment variables using `Environment.GetEnvironmentVariable()`, and Azure DevOps automatically makes all pipeline variables available as environment variables. + +**Example - Setting environment variables in YAML:** + +```yaml +variables: + deployEnv: 'Production' + serverName: 'prod-sql-server' + +steps: +- script: TabularEditor.exe "Model.bim" -S "UpdateModel.csx" -D "$(serverName)" "MyDatabase" -O -V -E -W + displayName: 'Deploy with Script Parameters' + env: + DEPLOY_ENV: $(deployEnv) + SERVER_NAME: $(serverName) +``` + +**Example - PowerShell Task with environment variables:** + +```yaml +- task: PowerShell@2 + displayName: 'Run Tabular Editor Script' + env: + DEPLOY_ENV: 'UAT' + CONNECTION_STRING: $(sqldwConnectionString) + inputs: + targetType: 'inline' + script: | + $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` + -ArgumentList "`"Model.bim`" -S `"ConfigureModel.csx`" -B `"output/Model.bim`" -V" + exit $p.ExitCode +``` + +**In your C# script (e.g., UpdateModel.csx):** + +```csharp +var deployEnv = Environment.GetEnvironmentVariable("DEPLOY_ENV"); +var serverName = Environment.GetEnvironmentVariable("SERVER_NAME"); + +Info($"Configuring model for {deployEnv} environment on {serverName}"); + +// Apply environment-specific changes +foreach(var ds in Model.DataSources.OfType()) +{ + ds.ConnectionString = ds.ConnectionString.Replace("{SERVER}", serverName); +} +``` + +This approach is cleaner and more maintainable than hardcoding values in scripts or using complex string replacement techniques. For more information on using environment variables in C# scripts, see [C# Scripts - Accessing Environment Variables](xref:csharp-scripts#accessing-environment-variables). + ## Running the Best Practice Analyzer You can use the "-A" switch to have Tabular Editor scan your model for all objects that are in violation of any Best Practice Rules defined on the local machine (in the %AppData%\..\Local\TabularEditor\BPARules.json file), or as annotations within the model itself. Alternatively, you can specify a path of a .json file containing Best Practice Rules after the "-A" switch, to scan the model using the rules defined in the file. Objects that are in violation will be outputted to the console. diff --git a/content/features/built-in-bpa-rules.md b/content/features/built-in-bpa-rules.md index 29bca6f9..e96994eb 100644 --- a/content/features/built-in-bpa-rules.md +++ b/content/features/built-in-bpa-rules.md @@ -43,9 +43,7 @@ The 27 built-in rules cover four areas: - **Maintenance**: Descriptions, calculation groups, unused objects ### Global and Per-Rule Control - +![Screenshot showing BPA preferences with global enable/disable toggle and per-rule checkboxes](~/content/assets/images/features/bpa-built-in-rules-preferences.png) You can enable or disable built-in rules globally or individually. Settings persist across sessions and work independently from your custom rules. To manage built-in rules: @@ -55,28 +53,25 @@ To manage built-in rules: 4. Use the BPA Manager to enable or disable individual rules ### First-Run Notification - +![Screenshot of first-run notification dialog introducing built-in BPA rules](~/content/assets/images/features/bpa-built-in-rules-notification.png) + The first time you open a model after upgrading to a version with built-in rules, you'll see a notification explaining the feature with a link to preferences. This notification only appears once. ### Knowledge Base Integration - + +![Screenshot showing BPA window with rule selected and "View Documentation" button highlighted](~/content/assets/images/features/bpa-built-in-rules-kb-link.png) + Every built-in rule links to a knowledge base article through the `KnowledgeBaseArticle` property. Each article explains what the rule checks, why it matters, and how to fix violations. To view documentation, select a rule in the Best Practice Analyzer window. - ### Read-Only Protection Built-in rules can't be edited, cloned, or deleted. This ensures all users have the same rule definitions. You can disable individual rules, but the rule definitions themselves remain unchanged. - +![Screenshot showing built-in rule with read-only badge/icon in BPA window](~/content/assets/images/features/bpa-built-in-rules-readonly.png) + ### ID Collision Prevention Built-in rules use reserved ID prefixes. When you create a custom rule, Tabular Editor validates that your ID doesn't conflict with built-in rules and shows an error if it does. @@ -85,7 +80,7 @@ Built-in rules use reserved ID prefixes. When you create a custom rule, Tabular The initial release includes the following rules: - + ## Working with Built-in and Custom Rules diff --git a/content/features/csharp-scripts.md b/content/features/csharp-scripts.md index fd648553..29fa09bc 100644 --- a/content/features/csharp-scripts.md +++ b/content/features/csharp-scripts.md @@ -226,6 +226,86 @@ In addition, the following .NET Framework assemblies are loaded by default: - TabularEditor.Exe - Microsoft.AnalysisServices.Tabular.Dll +## Accessing Environment Variables + +When running C# scripts via the Tabular Editor CLI (especially in CI/CD pipelines), you can pass parameters to your scripts using environment variables. This is the recommended approach, as C# scripts executed by Tabular Editor CLI don't support traditional command-line arguments. + +### Reading Environment Variables + +Use the `Environment.GetEnvironmentVariable()` method to read environment variables in your script: + +```csharp +// Read environment variables +var serverName = Environment.GetEnvironmentVariable("SERVER_NAME"); +var environment = Environment.GetEnvironmentVariable("ENVIRONMENT"); + +// Use them in your script +foreach(var dataSource in Model.DataSources.OfType()) +{ + if(dataSource.Name == "SQLDW") + { + dataSource.ConnectionString = dataSource.ConnectionString + .Replace("{SERVER}", serverName) + .Replace("{ENV}", environment); + } +} + +Info($"Updated connection strings for {environment} environment"); +``` + +### Azure DevOps Integration + +Environment variables integrate seamlessly with Azure DevOps pipelines, as all pipeline variables are automatically available as environment variables by default. + +**Example Azure DevOps YAML Pipeline:** + +```yaml +variables: + targetServer: 'Production' + targetDatabase: 'AdventureWorks' + +steps: +- task: PowerShell@2 + displayName: 'Deploy Model with Parameters' + env: + SERVER_NAME: $(targetServer) + DATABASE_NAME: $(targetDatabase) + inputs: + targetType: 'inline' + script: | + TabularEditor.exe "Model.bim" -S "DeploymentScript.csx" -D "$(targetServer)" "$(targetDatabase)" -O -V -E -W +``` + +In this example, the script `DeploymentScript.csx` can access `SERVER_NAME` and `DATABASE_NAME` using `Environment.GetEnvironmentVariable()`. + +### Common Use Cases + +Environment variables are particularly useful for: + +- **Dynamic connection strings**: Update data source connections based on deployment environment (Dev, UAT, Production) +- **Conditional logic**: Apply different transformations based on target environment +- **Deployment configuration**: Control which objects to deploy or modify based on parameters +- **Multi-environment support**: Use the same script across different environments with different values + +**Example - Environment-specific modifications:** + +```csharp +var environment = Environment.GetEnvironmentVariable("DEPLOY_ENV") ?? "Development"; +var refreshPolicy = Environment.GetEnvironmentVariable("ENABLE_REFRESH_POLICY") == "true"; + +// Apply environment-specific settings +foreach(var table in Model.Tables) +{ + if(environment == "Production" && !refreshPolicy) + { + // Disable incremental refresh policies in production if specified + table.EnableRefreshPolicy = false; + } +} + +Info($"Configured model for {environment} environment"); +``` + ## Compatibility The scripting APIs for Tabular Editor 2 and Tabular Editor 3 are mostly compatible, however, there are cases where you want to conditionally compile code depending on which version you're using. For this, you can use preprocessor directives, which were introduced in Tabular Editor 3.10.0. diff --git a/content/features/tmdl.md b/content/features/tmdl.md index 952b9309..885bb4c0 100644 --- a/content/features/tmdl.md +++ b/content/features/tmdl.md @@ -36,6 +36,19 @@ When saving a new model for the first time, Tabular Editor (since v. 3.7.0), wil ![New Model Tmdl](~/content/assets/images/new-model-tmdl.png) +## TMDL and Microsoft Fabric Git Integration + +TMDL is fully compatible with Microsoft Fabric's Git integration feature. When you use the **Save with supporting files** option in Tabular Editor 3, the TMDL serialization format creates a folder structure that includes all necessary metadata files required by Fabric's Git integration. + +The resulting folder structure includes: +- **.platform** file with metadata (display name, description, logical ID) +- **definition.pbism** file with semantic model settings +- **definition/** folder containing your TMDL model files + +This combination allows you to commit your semantic models to Git repositories and synchronize them with Microsoft Fabric workspaces using Fabric's built-in Git integration capabilities. The human-readable nature of TMDL makes it particularly well-suited for code reviews and tracking changes in version control systems. + +For detailed information on using this feature, see [Save with supporting files](xref:save-with-supporting-files). + # Next steps - [TMDL overview (Microsoft Learn)](https://learn.microsoft.com/en-us/analysis-services/tmdl/tmdl-overview). diff --git a/content/features/using-bpa.md b/content/features/using-bpa.md index 3e1beda5..c59d79c2 100644 --- a/content/features/using-bpa.md +++ b/content/features/using-bpa.md @@ -21,6 +21,9 @@ applies_to: The Best Practice Analyzer (BPA) lets you define rules on the metadata of your model, to encourage certain conventions and best practices while developing your Power BI or Analysis Services Model. +> [!NOTE] +> Tabular Editor 3 includes a comprehensive set of [built-in Best Practice Analyzer rules](xref:built-in-bpa-rules) that are enabled by default for new users. + ## BPA Overview The BPA overview shows you all the rules defined in your model that are currently being broken: @@ -39,7 +42,7 @@ Clicking the link (or pressing F10), brings up the full BPA window. ### Functionality -Whenever a change is made to the model, the Best Practice Analyzer scans your model for issues in the background. You can disable this feature under File > Preferences. +Whenever a change is made to the model, the Best Practice Analyzer scans your model for issues in the background. You can disable this feature under **Tools > Preferences > Best Practice Analyzer**. The BPA Window in both TE2 and TE3 allows you to dock the window on one side of your desktop, while keeping the main window in the other side, allowing you to work with your model while you can see BPA issues. diff --git a/content/features/views/data-refresh-view.md b/content/features/views/data-refresh-view.md index 75fe0763..f6773fa3 100644 --- a/content/features/views/data-refresh-view.md +++ b/content/features/views/data-refresh-view.md @@ -26,7 +26,27 @@ A new active refresh will appear when a new refresh is triggered through the TOM
Figure 1: Data Refresh View in Tabular Editor. New refresh can be started by right-clicking a table and selecting refresh
-A new refresh will run in the background so that you can continue to build your dataset, and Tabular Editor will let you know if the refresh fails with a pop up. +A new refresh will run in the background so that you can continue to build your dataset, and Tabular Editor will let you know if the refresh fails with a pop up. + +## Data Refresh view columns + +The Data Refresh view displays the following information for each refresh operation: + +- **Object**: The name of the model object being refreshed (table, partition, or model) +- **Description**: Additional details about the refresh operation and its current state +- **Progress**: Shows the number of rows that have been imported so far. +- **Start Time**: The date and time when the refresh operation began. This is useful for tracking when operations were initiated, especially when multiple refreshes are queued +- **Duration**: The elapsed time since the refresh operation started, updated in real-time for active operations + +### Sorting refresh operations + +You can sort the refresh operations by clicking on any column header. This is particularly useful for: + +- Clicking the **Start Time** column to sort refresh operations chronologically, with the most recent operations appearing first (descending sort) or last (ascending sort) +- Sorting by **Duration** to identify long-running operations +- Sorting by **Object** to group refreshes by table or partition name + +Click a column header once to sort ascending, and click again to sort descending. This makes it easy to identify the latest refresh operations when working with multiple refresh queues. > [!NOTE] > All the messages and durations shown in the Data Refresh window are estimates only. Tabular Editor listens to [trace events from SSAS](https://learn.microsoft.com/en-us/analysis-services/trace-events/analysis-services-trace-events?view=asallproducts-allversions) during processing. SSAS is not guaranteed to send all trace messages to the client (for example it may throttle the trace event notifications during times of peak CPU/memory consumption). diff --git a/content/features/views/user-interface.md b/content/features/views/user-interface.md index 444a6274..22a48e4d 100644 --- a/content/features/views/user-interface.md +++ b/content/features/views/user-interface.md @@ -99,7 +99,7 @@ The **File** menu primarily contains menu items for dealing with loading and sav > In Tabular Editor 3 Desktop Edition the **Open > Model from file...** and **Open > Model from folder...** options are not available and the **Open > File...** dialog only allows opening [supporting files](xref:supported-files#supported-file-types), not files containing metadata. - **Revert**: This option lets you reload the model metadata from the source, discarding any changes that are made in Tabular Editor, which have not yet been saved. This option is useful when Tabular Editor 3 is used as an External Tool for Power BI Desktop, and a change is made in Power BI Desktop while Tabular Editor 3 is connected. By choosing **Revert**, Tabular Editor 3 can reload the model metadata from Power BI Desktop without having to reconnect. -- **Close**: This closes the active document (for example a DAX Query, a C# script or a data model diagram). If the document has unsaved changes, Tabular Editor will prompt you to save the changes before closing. +- **Close Document** (Ctrl+W): Closes the currently active document or panel in the main area, such as a DAX Query, a C# script, a data model diagram, or any other view with focus. If the document has unsaved changes, Tabular Editor will prompt you to save the changes before closing. This command is context-aware and will close whichever item is currently active in the main workspace area. - **Close model**: This unloads the currently loaded model metadata from Tabular Editor. If you made changes to the metadata, Tabular Editor will prompt you to save the changes before closing. - **Save**: This saves the active document back to the source file. If no document is active, this saves the model metadata back to the source, which could be a Model.bim file, a Database.json (folder structure) or a connected instance of Analysis Services (including Power BI Desktop) or the Power BI XMLA endpoint. - **Save as...** This allows you to save the active document as a new file. If no document is active, this allows you to save the model metadata as a new file, using the .bim (JSON-based) file. diff --git a/content/getting-started/bpa.md b/content/getting-started/bpa.md index 1cfbe94a..575040d3 100644 --- a/content/getting-started/bpa.md +++ b/content/getting-started/bpa.md @@ -31,7 +31,7 @@ Things you can check with the Best Practice Analyzer: The Best Practice Analyzer has access to the full metadata of the model, and can also access VertiPaq Analyzer statistics for more advanced scenarios. > [!NOTE] -> Tabular Editor does not ship with any rules out-of-the-box. You will have to define your own rules initially, or use a set of standard rules such as [those recommended by the Power BI CAT Team](https://powerbi.microsoft.com/en-ca/blog/best-practice-rules-to-improve-your-models-performance/). +> Tabular Editor 3 includes a comprehensive set of [built-in Best Practice Analyzer rules](xref:built-in-bpa-rules) that are enabled by default. # Managing Best Practice Rules @@ -98,6 +98,9 @@ Tabular Editor displays the best practice rule violations within the **Best Prac The **Best Practice Analyzer view** shows a list of all rules that have objects in violation. Below each rule is a list of the violating objects. You can double-click on an object in the list, to navigate to that object in the **TOM Explorer**. +> [!TIP] +> **Enterprise Edition users**: Built-in BPA rules are displayed alongside any custom rules you define. These rules are enabled by default and provide comprehensive best practice guidance. You can manage built-in rules through **Tools > Manage BPA Rules...** where they appear in the **(Built-in rules)** collection. For more information, see [Built-in BPA rules](xref:built-in-bpa-rules). + ![Item options](~/content/assets/images/bpa-options.png) When right-clicking on an object, you are presented with a number of options as shown above. These are: @@ -116,7 +119,7 @@ The options shown above are also available as toolbar buttons at the top of the In some cases, you may want to disable the Best Practice Analyzer background scan. For example, when you have rules that take a relatively long time to evaluate, or when you are working with very large models. -The background scan can be disabled under **Tools > Preferences > Features > Best Practice Analyzer** by unchecking the **Scan for Best Practice violations in the background**. +The background scan can be disabled under **Tools > Preferences > Best Practice Analyzer** by unchecking the **Scan for Best Practice violations in the background**. Note that you can still manually perform a scan using the **Refresh** button of the **Best Practice Analyzer view**, as mentioned above, even when background scans are disabled. diff --git a/content/getting-started/editions.md b/content/getting-started/editions.md index 88d37eba..c0e268a6 100644 --- a/content/getting-started/editions.md +++ b/content/getting-started/editions.md @@ -48,10 +48,13 @@ Please refer to the matrix below for the full overview of supported scenarios: |Power BI Premium Capacity (P SKUs)|❌|❌|✔| |Power BI Embedded Capacity (A/EM SKUs)|❌|❌|✔| |Fabric Capacity (F SKUs)|❌|❌|✔| +|Semantic Bridge (Databricks)|❌|❌|✔| +|[Advanced Refresh dialog](xref:advanced-refresh)|❌|✔|✔| +|[Free DAX Optimizer license](xref:dax-optimizer-integration)|❌|❌|✔| \***Note:** Enterprise Edition is required if the Analysis Services data model contains perspectives or tables with multiple partitions (does not apply to Power BI Desktop or Power BI Premium Per User models). -\*\***Note:** Supported file formats are: **.pbip** (Power BI Project) **.pbit** (Power BI Template), **.bim** (Analysis Services model metadata), **.vpax** (VertiPaq Analyzer) and **database.json** (Tabular Editor folder structure). +\*\***Note:** Supported file formats are: **.pbip** (Power BI Project) **.pbit** (Power BI Template), **.bim** (Analysis Services model metadata), **.vpax** (VertiPaq Analyzer) and **database.json** (Tabular Editor folder structure), **TMDL** (Tabular Model Definition Language). \*\*\***Note:** Workspace Mode allows Tabular Editor 3 to simultaneously save model metadata to disk and synchronize a database on any of the editions of Analysis Services or Power BI supported by the Tabular Editor 3 edition purchased. @@ -76,11 +79,11 @@ Similarly, [Power BI Premium-Per-User workspaces do not support Direct Lake data \***Note:** Analysis Services on SQL Server Standard Edition pre-2019 does not support DirectQuery. Nor does Azure AS Basic Tier. [Learn more](https://learn.microsoft.com/en-us/analysis-services/analysis-services-features-by-edition?view=asallproducts-allversions#tabular-models). -If you attemp to open a model that uses one or more of the restricted features listed above, while on a TE3 Business Edition license, you will see the error message below: +If you attempt to open a model that uses one or more of the modeling restrictions listed above, while on a TE3 Business Edition license, you will see the error message below: ![This edition of Tabular Editor 3 does not support Enterprise-tier semantic models](https://github.com/TabularEditor/TabularEditorDocs/assets/8976200/7ef69593-ea4b-4a16-a8df-543f5c31ac65) -There are no other feature differences between the Tabular Editor 3 editions, than the ones listed above. +There are no other feature differences between the Tabular Editor 3 editions, than the ones listed above. > [!NOTE] > Please keep in mind that Power BI Desktop [currently does not support all Data modeling operations](xref:desktop-limitations). For this reason, Tabular Editor 3 by default blocks operations that are not supported by Power BI Desktop. However, this restriction can be removed under Tools > Preferences > Power BI. diff --git a/content/getting-started/personalizing-te3.md b/content/getting-started/personalizing-te3.md index fe9b5922..d566eec8 100644 --- a/content/getting-started/personalizing-te3.md +++ b/content/getting-started/personalizing-te3.md @@ -25,6 +25,9 @@ Most of the settings covered in this article are accessed through the **Tools > ***Name of setting* (default value)**
Description of setting. +> [!TIP] +> Use the **search box** at the top of the Preferences dialog to quickly locate settings by name or keyword. The search filters the preferences tree in real-time, helping you navigate directly to the setting you need. + # General features The first page you will encounter within the **Preferences** dialog is the **Tabular Editor > Features** page (see screenshot below). Below is a short description of the features on this page, and what they are commonly used for: diff --git a/content/getting-started/refresh-preview-query.md b/content/getting-started/refresh-preview-query.md index ea2123f1..e3d80990 100644 --- a/content/getting-started/refresh-preview-query.md +++ b/content/getting-started/refresh-preview-query.md @@ -60,6 +60,9 @@ You may also initiate a refresh at the model level through the **Model > Refresh ![Data Refresh View2](~/content/assets/images/data-refresh-view2.png) +> [!TIP] +> The Data Refresh view includes a **Start Time** column that shows when each refresh operation began. Click the column header to sort operations chronologically, making it easy to see your most recent refreshes first. You can sort by any column to organize refresh operations according to your needs. See [Data Refresh view](xref:data-refresh-view) for more details. + While a refresh is in progress you can continue work on your data model, querying and previewing data or queueing new data refresh operations according to this article. However, you will not be able to save model changes to Analysis Services until the all data refresh operations complete. diff --git a/content/index.md b/content/index.md index eae00c0c..88f7525a 100644 --- a/content/index.md +++ b/content/index.md @@ -32,11 +32,19 @@ Tabular Editor 3 is a more advanced application which offers a premium experienc - World class [DAX editor](xref:dax-editor) with syntax highlighting, semantic checking, auto-complete, context awareness and much, much more - Table browser, Pivot Grid browser and DAX Query editor - [Import Table Wizard](xref:importing-tables) with support for Power Query data sources -- [Data Refresh view](xref:data-refresh-view) allows you to queue and execute refresh operations in the background +- [Data Refresh view](xref:data-refresh-view) with [Advanced Refresh dialog](xref:advanced-refresh) for queuing and executing refresh operations in the background - Diagram editor to easily visualize and edit table relationships -- New [DAX Scripting](xref:dax-scripts) capability to edit DAX expressions for multiple objects in a single document -- VertiPaq Analyzer integration +- [DAX Scripting](xref:dax-scripts) capability to edit DAX expressions for multiple objects in a single document +- [DAX User-Defined Functions (UDFs)](xref:udfs) with assistance, code actions and namespaces +- [Calendar Editor](xref:calendars) for creating and managing date tables with enhanced time intelligence +- [DAX Package Manager](xref:dax-package-manager) for installing and managing DAX packages +- [Built-in Best Practice Analyzer rules](xref:built-in-bpa-rules) +- VertiPaq Analyzer integration with [DAX Optimizer](xref:dax-optimizer-integration) - [DAX debugger](xref:dax-debugger) +- [Code Actions](xref:code-actions) for quick fixes and refactoring +- [Metadata Translation Editor](xref:metadata-translation-editor) and [Perspective Editor](xref:perspective-editor) +- [Save with supporting files](xref:save-with-supporting-files) for Fabric Git integration +- [Localization support](xref:references-application-language) (Chinese, Spanish, Japanese, German, French) ### [Tabular Editor 2.x](#tab/TE2) @@ -97,11 +105,17 @@ The table below lists all the main features of both tools. |[Table Groups](xref:table-groups)||✔| |[DAX Optimizer Integration](xref:dax-optimizer-integration)||✔| |[Code Actions](xref:code-actions)||✔| +|[DAX User-Defined Functions (UDFs)](xref:udfs) Assistance, Code Action and Namespaces||✔| +|[Calendar Editor](xref:calendars) for enhanced time intelligence||✔| +|[DAX Package Manager](xref:dax-package-manager)||✔| +|[Built-in Best Practice Analyzer rules](xref:built-in-bpa-rules) ||✔| +|[Advanced Refresh dialog](xref:advanced-refresh) with [refresh override profiles](xref:refresh-overrides) (Business/Enterprise Edition)||✔*| +|[Save with supporting files for Fabric](xref:save-with-supporting-files)||✔| +|Semantic Bridge for Databricks Metric Views (Enterprise Edition)||✔*| +|[Localization support](xref:references-application-language) (Chinese, Spanish, Japanese, German, French)||✔| \***Note:** Limitations apply depending on which [edition](xref:editions) of Tabular Editor 3 you are using. -Below is a more detailed description of some of the features listed above. - ### Common features Both tools provide the same features in terms of which data modeling options are available, by basically exposing every object and property of the [Tabular Object Model](https://docs.microsoft.com/en-us/analysis-services/tom/introduction-to-the-tabular-object-model-tom-in-analysis-services-amo?view=asallproducts-allversions), in an intuitive and responsive user interface. You can edit advanced object properties that are not available through the standard tools. The tools can load model metadata from files or from any instance of Analysis Services. Changes are only synchronized when you hit Ctrl+S (save) thus providing an "offline" editing experience which most people consider to be superior to the "always synchronized"-mode of the standard tools. This is especially noticable when working on large and complex data models. diff --git a/content/kb/index.md b/content/kb/index.md new file mode 100644 index 00000000..a4e2e21e --- /dev/null +++ b/content/kb/index.md @@ -0,0 +1,87 @@ +# Knowledge Base + +This section contains articles about best practices, code analysis rules, and DAX optimization patterns for Tabular Editor and Power BI models. + +## In this section + +### Best Practice Rules (BPA) + +Comprehensive guidelines for building high-quality, maintainable Power BI and Analysis Services models. + +- @kb.bpa-avoid-invalid-characters-descriptions - Prevent metadata corruption by removing control characters from descriptions +- @kb.bpa-avoid-invalid-characters-names - Ensure object names contain only valid characters +- @kb.bpa-data-column-source - Verify all data columns have proper source mappings +- @kb.bpa-relationship-same-datatype - Enforce data type consistency in relationships +- @kb.bpa-visible-objects-no-description - Ensure all visible objects have meaningful descriptions +- @kb.bpa-trim-object-names - Remove leading and trailing spaces from names +- @kb.bpa-expression-required - Validate that calculated objects have expressions +- @kb.bpa-format-string-columns - Apply consistent formatting to numeric and date columns +- @kb.bpa-format-string-measures - Provide format strings for all measures +- @kb.bpa-do-not-summarize-numeric - Prevent inappropriate summarization of numeric columns +- @kb.bpa-date-table-exists - Ensure proper date table configuration +- @kb.bpa-hide-foreign-keys - Hide foreign key columns from end users +- @kb.bpa-many-to-many-single-direction - Enforce single-direction filtering in many-to-many relationships +- @kb.bpa-avoid-provider-partitions-structured - Use proper partition sources for structured data +- @kb.bpa-translate-descriptions - Support multi-language descriptions +- @kb.bpa-translate-display-folders - Localize display folder names +- @kb.bpa-translate-hierarchy-levels - Translate hierarchy level captions +- @kb.bpa-translate-perspectives - Localize perspective names +- @kb.bpa-translate-visible-names - Translate visible object names for all cultures +- @kb.bpa-perspectives-no-objects - Ensure perspectives contain relevant objects +- @kb.bpa-calculation-groups-no-items - Validate calculation group definitions +- @kb.bpa-set-isavailableinmdx-false - Control MDX availability of objects +- @kb.bpa-set-isavailableinmdx-true-necessary - Enable MDX availability when required +- @kb.bpa-remove-auto-date-table - Clean up auto-generated date tables +- @kb.bpa-remove-unused-data-sources - Eliminate unused data source definitions +- @kb.bpa-specify-application-name - Set application names in connection strings for monitoring +- @kb.bpa-powerbi-latest-compatibility - Maintain compatibility with latest Power BI features + +## Code Actions +### DAX Code Analysis (DI) + +Improvement suggestions for DAX code structure and efficiency. These rules identify opportunities to simplify and optimize your expressions. + +- @DI001 - Remove unused variable +- @DI002 - Remove unused variable +- @DI003 - Remove table name +- @DI004 - Add table name +- @DI005 - Rewrite table filter as scalar predicate +- @DI006 - Split multi-column filter into multiple filters +- @DI007 - Simplify SWITCH statement +- @DI008 - Remove superfluous CALCULATE +- @DI009 - Avoid calculate shortcut syntax +- @DI010 - Use MIN/MAX instead of IF +- @DI011 - Use ISEMPTY instead of COUNTROWS +- @DI012 - Use DIVIDE instead of division +- @DI013 - Use division instead of DIVIDE +- @DI014 - Replace IFERROR with DIVIDE +- @DI015 - Replace IF with DIVIDE + +### DAX Refactoring (DR) + +Refactoring suggestions for complex or inefficient DAX patterns. These rules help modernize and improve readability of your DAX code. + +- @DR001 - Convert to scalar predicate +- @DR002 - Use aggregator instead of iterator +- @DR003 - Use VALUES instead of SUMMARIZE +- @DR004 - Prefix variable +- @DR005 - Prefix temporary column +- @DR006 - Move constant aggregation to variable +- @DR007 - Simplify 1-variable block +- @DR008 - Simplify multi-variable block +- @DR009 - Rewrite using DISTINCTCOUNT +- @DR010 - Rewrite using COALESCE +- @DR011 - Rewrite using ISBLANK +- @DR012 - Remove unnecessary BLANK +- @DR013 - Simplify negated logic +- @DR014 - Simplify using IN + +### DAX Rewrites (RW) + +Suggested rewrites for specific DAX patterns that can be expressed more effectively using alternative syntax. + +- @RW001 - Rewrite TOTALxTD using CALCULATE +- @RW002 - Rewrite using FILTER +- @RW003 - Invert IF + +--- diff --git a/content/kb/toc.md b/content/kb/toc.md index e69de29b..730d1f68 100644 --- a/content/kb/toc.md +++ b/content/kb/toc.md @@ -0,0 +1,67 @@ +# Best Practice Rules (BPA) +## @kb.bpa-avoid-invalid-characters-descriptions +## @kb.bpa-avoid-invalid-characters-names +## @kb.bpa-data-column-source +## @kb.bpa-relationship-same-datatype +## @kb.bpa-visible-objects-no-description +## @kb.bpa-trim-object-names +## @kb.bpa-expression-required +## @kb.bpa-format-string-columns +## @kb.bpa-format-string-measures +## @kb.bpa-do-not-summarize-numeric +## @kb.bpa-date-table-exists +## @kb.bpa-hide-foreign-keys +## @kb.bpa-many-to-many-single-direction +## @kb.bpa-avoid-provider-partitions-structured +## @kb.bpa-translate-descriptions +## @kb.bpa-translate-display-folders +## @kb.bpa-translate-hierarchy-levels +## @kb.bpa-translate-perspectives +## @kb.bpa-translate-visible-names +## @kb.bpa-perspectives-no-objects +## @kb.bpa-calculation-groups-no-items +## @kb.bpa-set-isavailableinmdx-false +## @kb.bpa-set-isavailableinmdx-true-necessary +## @kb.bpa-remove-auto-date-table +## @kb.bpa-remove-unused-data-sources +## @kb.bpa-specify-application-name +## @kb.bpa-powerbi-latest-compatibility + +# Code Actions +## DAX Code Analysis (DI) +### @DI001 +### @DI002 +### @DI003 +### @DI004 +### @DI005 +### @DI006 +### @DI007 +### @DI008 +### @DI009 +### @DI010 +### @DI011 +### @DI012 +### @DI013 +### @DI014 +### @DI015 + +## DAX Refactoring (DR) +### @DR001 +### @DR002 +### @DR003 +### @DR004 +### @DR005 +### @DR006 +### @DR007 +### @DR008 +### @DR009 +### @DR010 +### @DR011 +### @DR012 +### @DR013 +### @DR014 + +## DAX Rewrites (RW) +### @RW001 +### @RW002 +### @RW003 diff --git a/content/references/Roadmap2-h.md b/content/references/Roadmap2-h.md index 3826a2ff..efb8a757 100644 --- a/content/references/Roadmap2-h.md +++ b/content/references/Roadmap2-h.md @@ -1,5 +1,8 @@ # Roadmap +> [!IMPORTANT] +>Tabular Editor 2 is no longer under active development and will not receive any major feature additions or improvements from our side. We are, however, committed to keeping it up-to-date, ensuring support for new semantic modelling features as they are released from Microsoft, and also fixing any critical or blocking issues. As the project is open-source under MIT, anyone is welcome to submit pull requests, which will be reviewed and approved by our team. The following list should therefore be considered deprecated. + * Scripting objects into TMSL or DAX (compatible with DAX Editor) * IntelliSense in DAX expression editor * Create plug-in for Visual Studio, to launch Tabular Editor diff --git a/content/references/roadmap.md b/content/references/roadmap.md index 9d2fd106..6cb9e657 100644 --- a/content/references/roadmap.md +++ b/content/references/roadmap.md @@ -14,49 +14,81 @@ applies_to: Below is an overview of major new features to be shipped with Tabular Editor 3 updates in the short- to long term: +# [Upcoming](#tab/upcoming) -# [Planned 2026](#tab/Planned2026) +## In Development -- AI Assistant in Tabular Editor -- Localization -- Built in Best Practice Rules -- Power Query (M) Auto-Formatting -- Semantic Bridge -- Graphical Model Comparison -- .Net10 Support - - -## Shipped in 2025 -✅ New Code Actions + Knowledge Base for all Code Actions -✅ C# Editor Improvements -✅ Copy TMDL Scripts from TOM Explorer -✅ Direct Lake on One Lake support -✅ Day zero support for DAX User Defined Functions -✅ Support for Calendars -✅ DAX Package Manager -✅ Native ARM64 builds - -# [Future Features](#tab/FutureFeatures) +- **Semantic Bridge enhancements**: Support for v1.1 properties and enhanced import UI +- **Localization improvements**: Expanding language support and refining existing translations +- **Power Query (M) Auto-Formatting**: Advanced formatting capabilities for M expressions +- **Graphical Model Comparison**: See the changes that are applied to ## Up Next +- AI Assistant in Tabular Editor +- .NET 10 Support - Git integration - Power Query (M) Editing Enhancements -- TOM Properties shown as TMDL and TMSL Scripts. +- TOM Properties shown as TMDL and TMSL Scripts - Standalone CLI application -- Built in Macros +- Built-in Macros -## Non Planned Features +## Future - DAX Debugger Filter Context visualizer - Configurable Daxscilla autocomplete code snippets - Configurable theming for code editors (syntax highlighting colors) - Incremental deployment (a la [ALM Toolkit](http://alm-toolkit.com/)) -- Macro Actions improvements such as automatic application across model and preferences for which to apply. - +- Macro Actions improvements such as automatic application across model and preferences for which to apply # [Shipped](#tab/shipped) +For detailed information about each release, see the [full release history](xref:release-history). + +## Shipped in 2026 + +✅ [**Localization**](xref:references-application-language) - Chinese, Spanish (Preview), Japanese, German, and French (Experimental) language support (v3.25.0) + +✅ [**Built-in Best Practice Analyzer rules**](xref:built-in-bpa-rules) - Comprehensive set of BPA rules covering formatting, metadata, model layout, DAX expressions, and translations (v3.25.0) + +✅ **Semantic Bridge** - Create semantic models from Databricks Metric Views (Enterprise Edition, v3.25.0) + +✅ [**Save with supporting files for Fabric**](xref:save-with-supporting-files) - Support for .platform and definition.pbism files to match Fabric repository structure (v3.25.0) + +✅ **Calendar Editor** - Enhanced UI for managing calendar objects for time intelligence (v3.25.0) + +✅ [**Advanced Refresh dialog**](xref:advanced-refresh) - Configure parallelism, effective date for incremental refresh, and [refresh override profiles](xref:refresh-overrides) (Business/Enterprise Edition, v3.25.0) + +## Shipped in 2025 + +✅ [**DAX Package Manager**](xref:dax-package-manager) - Find and install DAX packages from daxlib.org with a single click (v3.24.0) + +✅ **UDF Namespaces** - Hierarchical organization of User-Defined Functions with customizable namespace properties (v3.24.0) + +✅ **Visual Calculations improvements** - Enhanced DAX editor support for Visual Calculation functions and visual column references (v3.24.0) + +✅ [**DAX User-Defined Functions (UDFs)**](xref:udfs) - Create and manage reusable DAX functions (v3.23.0) + +✅ [**Calendars**](xref:calendars) - Calendar-based time intelligence features with enhanced UI (v3.23.0) + +✅ **Fabric SQL Databases and Mirrored Databases support** - Import wizard support for new Fabric data sources in Import and Direct Lake modes (v3.23.0) + +✅ [**Direct Lake on OneLake and SQL**](xref:direct-lake-guidance) - Full support for Direct Lake modes including mixed mode/hybrid models (Enterprise Edition, v3.22.0) + +✅ **Word-based autocomplete** - DAX editor now supports multi-word search in autocomplete (v3.22.0) + +✅ **Diagram view enhancements** - Column data type icons, bi-directional relationship indicators, and improved table display options (v3.21.0) + +✅ **Copy TMDL scripts from TOM Explorer** - Export individual objects as TMDL to clipboard or file (v3.21.0) + +✅ **DAX Optimizer RLS support** - View DAX Optimizer results for RLS and Calculation Item expressions (v3.21.0) + +✅ **MetadataSource property** - New Model object property for C# scripts to access model metadata location (v3.21.0) + +✅ **C# Editor improvements** - Enhanced code editing experience with better IntelliSense and flexible search + +✅ **Native ARM64 builds** - Optimized performance on ARM64 processors (v3.23.0) + ## Shipped in 2024 ✅ DAX Debugger Locals Enhancement @@ -122,6 +154,8 @@ Below is an overview of major new features to be shipped with Tabular Editor 3 u ✅ Offline DAX formatting +*** + # Tabular Editor 2 Roadmap > [!NOTE] >Tabular Editor 2 is no longer under active development and will not receive any major feature additions or improvements from our side. We are, however, committed to keeping it up-to-date, ensuring support for new semantic modelling features as they are released from Microsoft, and also fixing any critical or blocking issues. As the project is open-source under MIT, anyone is welcome to submit pull requests, which will be reviewed and approved by our team. \ No newline at end of file diff --git a/content/references/shortcuts3.md b/content/references/shortcuts3.md index a7906ed5..26f0bb49 100644 --- a/content/references/shortcuts3.md +++ b/content/references/shortcuts3.md @@ -28,6 +28,7 @@ applies_to: |Load model from a database|Ctrl+Shift+O| |Save current item|Ctrl+S| |Save all|Ctrl+Shift+S| +|Close Document|Ctrl+W| |Exit|Alt+F4| |Deployment wizard|Ctrl+Shift+D| diff --git a/content/references/supported-files.md b/content/references/supported-files.md index a2bb3a6c..39c890a9 100644 --- a/content/references/supported-files.md +++ b/content/references/supported-files.md @@ -27,7 +27,9 @@ Example files are available for each several file type, based on the [learn.tabu ## Dataset file types -Tabular Editor supports four file types for semantic models: .bim, Power BI files (.pbit and.pbip), .json and .tmdl. Each file type has different features and limitations, which are explained below. +Tabular Editor supports four file types for semantic models: .bim, Power BI files (.pbit and .pbip), .json and .tmdl. Each file type has different features and limitations, which are explained below. + +Additionally, Tabular Editor 3 Business and Enterprise editions support **saving with supporting files** for Microsoft Fabric Git integration. This creates a folder structure containing .platform and definition.pbism metadata files alongside your model files, enabling seamless synchronization with Fabric workspaces. See [Save with supporting files](xref:save-with-supporting-files) for details. > [!NOTE] > Since **Tabular Editor 3 Desktop Edition** is only intended to be used as an External Tool for Power BI Desktop, this edition does not allow loading and saving semantic model files. You may however still use Tabular Editor 2.x for this purpose. See to learn more about the difference between the Tabular Editor 3 editions. @@ -44,6 +46,19 @@ However, it has a large drawback: as it's a single large file, it's difficult to [Download example .bim file ](https://raw.githubusercontent.com/TabularEditor/TabularEditorDocs/main/content/assets/file-types/bim-file-example.bim) +#### Save with supporting files for Fabric Git integration + +When using the **Save with supporting files** option (Business and Enterprise editions), Tabular Editor creates a folder structure compatible with Microsoft Fabric Git integration: + +``` +DatabaseName.SemanticModel/ +├── .platform +├── definition.pbism +└── model.bim +``` + +This structure enables you to commit your semantic models to Git repositories and synchronize them with Fabric workspaces. See [Save with supporting files](xref:save-with-supporting-files) for complete documentation. + ### [Power BI](#tab/PowerBI) @@ -124,8 +139,46 @@ For further reading please see: [TMDL](xref:tmdl) [Download example TMDL Folder Structure](https://raw.githubusercontent.com/TabularEditor/TabularEditorDocs/main/content/assets/file-types/tmdl-model-example.zip) +#### Save with supporting files for Fabric Git integration + +When using the **Save with supporting files** option (Business and Enterprise editions), Tabular Editor creates a folder structure compatible with Microsoft Fabric Git integration: + +``` +DatabaseName.SemanticModel/ +├── .platform +├── definition.pbism +└── definition/ + ├── database.tmdl + ├── tables.tmdl + └── ... +``` + +The human-readable TMDL format is particularly well-suited for version control and code reviews when using Fabric Git integration. See [Save with supporting files](xref:save-with-supporting-files) for complete documentation. + *** +## Fabric Git Integration files + +When using the **Save with supporting files** feature (Business and Enterprise editions), Tabular Editor creates additional metadata files required for Microsoft Fabric Git integration. These files are automatically generated and managed by Tabular Editor. + +### .platform + +The .platform file contains metadata about the semantic model item, including: +- **type**: Identifies the item as a SemanticModel +- **displayName**: The name displayed in Fabric workspaces (synchronized from the Database `Name` property) +- **description**: The description shown in Fabric (synchronized from the Database `Description` property) +- **logicalId**: An automatically generated cross-workspace identifier + +This file is a JSON file that should not be manually edited unless you understand the Fabric item format. + +### definition.pbism + +The definition.pbism file contains the overall definition and core settings of the semantic model. This file works alongside the model metadata (stored as either model.bim or in the definition/ folder) to provide complete semantic model information required by Microsoft Fabric. + +Both files are automatically created when you check the **Save with supporting files** option during save operations. The resulting folder structure (with .SemanticModel suffix) can be committed to Git repositories and synchronized with Fabric workspaces. + +For complete documentation on this feature, see [Save with supporting files](xref:save-with-supporting-files). + ## Tabular Editor Supporting files Supporting files are files which are not used by Analysis Services or Power BI. Instead, these files all support different kinds of development workflow in Tabular Editor 3 and other tools. diff --git a/redirects.json b/redirects.json index 97dfb5af..6ee21cef 100644 --- a/redirects.json +++ b/redirects.json @@ -26,9 +26,9 @@ "content/common/CSharpScripts/csharp-script-library-advanced.md": "/features/CSharpScripts/csharp-script-library-advanced.html", "content/common/CSharpScripts/csharp-script-library-beginner.md": "/features/CSharpScripts/csharp-script-library-beginner.html", "content/common/CSharpScripts/csharp-script-library.md": "/features/CSharpScripts/csharp-script-library.html", - "content/common/Semantic Model/direct-lake-sql-model.md": "/features/Semantic Model/direct-lake-sql-model.html", - "content/common/Semantic Model/direct-query-over-as.md": "/features/Semantic Model/direct-query-over-as.html", - "content/common/Semantic Model/semantic-model-types.md": "/features/Semantic Model/semantic-model-types.html", + "content/common/Semantic Model/direct-lake-sql-model.md": "/features/Semantic-Model/direct-lake-sql-model.html", + "content/common/Semantic Model/direct-query-over-as.md": "/features/Semantic-Model/direct-query-over-as.html", + "content/common/Semantic Model/semantic-model-types.md": "/features/Semantic-Model/semantic-model-types.html", "content/common/common-features.md": "/getting-started/Getting-Started-te2.html", "content/common/desktop-limitations.md": "/getting-started/desktop-limitations.html", "content/common/policies.md": "/references/policies.html",