diff --git a/localizedContent/es/content/_ui-strings.json b/localizedContent/es/content/_ui-strings.json index 5b6b37c6c..4c4cf6c8b 100644 --- a/localizedContent/es/content/_ui-strings.json +++ b/localizedContent/es/content/_ui-strings.json @@ -1,48 +1,52 @@ { - "aiTranslationWarning": "Este contenido se tradujo con IA y no ha sido revisado por un editor humano. Las imágenes y los gráficos se mantienen en su idioma original.", - "header.nav.pricing": "Precios", + "aiTranslationWarning": "This content was translated using AI and has not been reviewed by a human editor. Images and charts remain in their original language.", + "header.nav.pricing": "Pricing", "header.nav.download": "Descargar", - "header.nav.learn": "Aprender", - "header.nav.resources": "Recursos", + "header.nav.learn": "Learn", + "header.nav.resources": "Resources", "header.nav.blog": "Blog", - "header.nav.newsletter": "Boletín", + "header.nav.newsletter": "Newsletter", "header.nav.publications": "Publicaciones", - "header.nav.documentation": "Documentación", - "header.nav.supportCommunity": "Comunidad de soporte", - "header.nav.contactUs": "Contacta con nosotros", - "header.button1": "Prueba gratuita", - "header.button2": "Página principal", - "footer.heading": "¿Listo para empezar?", - "footer.button1": "Prueba Tabular Editor 3 gratis", + "header.nav.documentation": "Documentation", + "header.nav.supportCommunity": "Support community", + "header.nav.contactUs": "Contact Us", + "header.button1": "Free trial", + "header.button2": "Main page", + "footer.heading": "Ready to get started?", + "footer.button1": "Try Tabular Editor 3", "footer.button2": "Comprar Tabular Editor 3", "footer.aboutUs": "Sobre nosotros", + "footer.career": "Carreras", + "footer.newsroom": "Newsroom", "footer.contactUs": "Contacta con nosotros", "footer.technicalSupport": "Soporte técnico", - "footer.privacyPolicy": "Política de privacidad y de cookies", - "footer.termsConditions": "Términos y condiciones", - "footer.licenseTerms": "Términos de licencia", - "appliesTo": "Se aplica a: ", - "availableSince": "Disponible desde", - "availableIn": "Disponible en", - "inThisArticle": "En este artículo", - "searchResultsCount": "{count} resultados de \"{query}\"", - "searchNoResults": "No hay resultados para \"{query}\"", - "tocFilter": "Filtrar por título", - "nextArticle": "Siguiente", - "prevArticle": "Anterior", - "themeLight": "Claro", - "themeDark": "Oscuro", - "themeAuto": "Automático", - "changeTheme": "Cambiar tema", - "copy": "Copiar", - "downloadPdf": "Descargar PDF", - "search": "Buscar documentación", - "note": "Nota", - "warning": "Advertencia", - "tip": "Consejo", - "important": "Importante", - "caution": "Precaución", - "tableOfContents": "Tabla de contenidos", - "selectLanguage": "Seleccionar idioma", - "copyCode": "Copiar código" + "footer.securityTrust": "Security & Trust Center", + "footer.privacyPolicy": "Política de privacidad", + "footer.cookiePolicy": "Cookie policy", + "footer.siteTerms": "Términos del Sitio", + "footer.commercialTerms": "Commercial Terms & Conditions", + "appliesTo": "Applies to: ", + "availableSince": "Available since", + "availableIn": "Available in", + "inThisArticle": "In this article", + "searchResultsCount": "{count} results for \"{query}\"", + "searchNoResults": "No results for \"{query}\"", + "tocFilter": "Filter by title", + "nextArticle": "Next", + "prevArticle": "Previous", + "themeLight": "Light", + "themeDark": "Dark", + "themeAuto": "Auto", + "changeTheme": "Change theme", + "copy": "Copy", + "downloadPdf": "Download PDF", + "search": "Search documentation", + "note": "Note", + "warning": "Warning", + "tip": "Tip", + "important": "Important", + "caution": "Caution", + "tableOfContents": "Table of Contents", + "selectLanguage": "Select language", + "copyCode": "Copy code" } diff --git a/localizedContent/es/content/features/Command-line-Options.md b/localizedContent/es/content/features/Command-line-Options.md index bea1789d2..700113351 100644 --- a/localizedContent/es/content/features/Command-line-Options.md +++ b/localizedContent/es/content/features/Command-line-Options.md @@ -1,6 +1,6 @@ --- uid: command-line-options -title: Línea de comandos +title: Command Line (Tabular Editor 2) author: Daniel Otykier updated: 2021-08-26 applies_to: @@ -11,15 +11,18 @@ applies_to: none: true --- -# Línea de comandos +# Command Line (Tabular Editor 2) -Tabular Editor se puede ejecutar desde la línea de comandos para realizar diversas tareas, lo que puede ser útil en escenarios de compilación e implementación automatizadas, etc. +> [!TIP] +> Looking for the new cross-platform CLI? See @te-cli for the Tabular Editor CLI (Limited Public Preview), a successor that runs on Windows, macOS, and Linux. + +Tabular Editor can be executed from the command-line to perform various tasks, which may be useful in Automated Build and Deployment scenarios, etc. -**Nota:** Dado que TabularEditor.exe es una aplicación WinForms, si la ejecutas directamente desde un símbolo del sistema de Windows, el hilo volverá inmediatamente al símbolo del sistema. Esto puede provocar problemas en scripts de comandos, etc. Para esperar a que TabularEditor.exe termine sus tareas de línea de comandos, ejecútalo siempre así: `start /wait TabularEditor ...` +**Note:** Since TabularEditor.exe is a WinForms application, executing it directly from a windows command-prompt will cause the thread to return immediately to the prompt. This may cause issues in command scripts, etc. To wait for TabularEditor.exe to complete its command-line tasks, always execute it using: `start /wait TabularEditor ...` -Para ver las opciones de línea de comandos disponibles en Tabular Editor, ejecuta el siguiente comando: +To view the command-line options available in Tabular Editor, run the following command: -**Línea de comandos de Windows:** +**Windows Command line:** ```shell start /wait TabularEditor.exe /? @@ -31,10 +34,10 @@ start /wait TabularEditor.exe /? $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru -ArgumentList "/?" ``` -Salida: +Output: ```cmd -Uso: +Usage: TABULAREDITOR ( file | server database | -L [name] ) [-S script1 [script2] [...]] [-SC] [-A [rules] | -AX rules] [(-B | -F | -TMDL) output [id]] [-V | -G] [-T resultsfile] @@ -42,76 +45,76 @@ TABULAREDITOR ( file | server database | -L [name] ) [-S script1 [script2] [...] [-P [-Y]] [-S] [-R [-M]]] [-X xmla_script]] [-W] [-E]] -file Ruta completa del archivo Model.bim o de la carpeta del modelo database.json que se va a cargar. -server Nombre del servidor\instancia o cadena de conexión desde la que se cargará el modelo. -database Id de la base de datos del modelo que se va a cargar. Si se deja en blanco ("), se selecciona la primera - base de datos disponible en el servidor. --L / -LOCAL Se conecta a una instancia (local) de Analysis Services de Power BI Desktop. Si no se - especifica ningún nombre, se asume que hay exactamente 1 instancia en ejecución. En caso contrario, - el nombre debe coincidir con el nombre del archivo .pbix cargado en Power BI Desktop. --S / -SCRIPT Ejecuta el script especificado en el modelo después de cargarlo. - scriptN Ruta completa de uno o varios archivos que contienen un C# Script para ejecutar o un - script en línea. --SC / -SCHEMACHECK Intenta conectarse a todos los orígenes de datos del proveedor para detectar cambios en el esquema - de las tablas. Genera... - ...advertencias por tipos de datos no coincidentes y columnas de origen no asignadas - ...errores por columnas del modelo no asignadas. --A / -ANALYZE Ejecuta Best Practice Analyzer y muestra el resultado en la consola. - rules Ruta opcional de un archivo o la URL de reglas BPA adicionales que se van a analizar. Si - se especifica, el modelo no se analiza con las reglas del usuario local ni de la máquina local, - pero las reglas definidas dentro del modelo se siguen aplicando. --AX / -ANALYZEX Igual que -A / -ANALYZE, pero excluye las reglas especificadas en las anotaciones del modelo. --B / -BIM / -BUILD Guarda el modelo (después de la ejecución opcional del script) como un archivo Model.bim. - output Ruta completa del archivo Model.bim donde se guardará. - id Id/nombre opcional que se asignará al objeto Database al guardar. --F / -FOLDER Guarda el modelo (después de la ejecución opcional del script) como una estructura de carpetas. - output Ruta completa de la carpeta donde se guardará. La carpeta se crea si no existe. - id Id/nombre opcional que se asignará al objeto Database al guardar. --TMDL Guarda el modelo (después de la ejecución opcional del script) como una estructura de carpetas TMDL. - output Ruta completa de la carpeta TMDL donde se guardará. La carpeta se crea si no existe. - id Id/nombre opcional que se asignará al objeto Database al guardar. --V / -VSTS Genera comandos de registro de Visual Studio Team Services. --G / -GITHUB Genera comandos de flujo de trabajo para GitHub Actions. --T / -TRX Genera un archivo VSTEST (trx) con detalles de la ejecución. - resultsfile Nombre del archivo XML de VSTEST. --D / -DEPLOY Despliegue desde la línea de comandos - Si no se especifican parámetros adicionales, este modificador guardará los metadatos del modelo - de nuevo en el origen (archivo o base de datos). - server Nombre del servidor donde se realizará el despliegue o cadena de conexión a Analysis Services. - database Id de la base de datos que se va a desplegar (crear/sobrescribir). - -L / -LOGIN Desactiva la seguridad integrada al conectarse al servidor. Especifica: - user Nombre de usuario (debe ser un usuario con derechos de administrador en el servidor) - pass Contraseña - -F / -FULL Despliega todos los metadatos del modelo, permitiendo sobrescribir una base de datos existente. - -O / -OVERWRITE Permite desplegar (sobrescribir) una base de datos existente. - -C / -CONNECTIONS Despliega (sobrescribe) los Data sources existentes en el modelo. Después del modificador -C, - puedes especificar, opcionalmente, cualquier cantidad de pares marcador de posición/valor. Al hacerlo, - se reemplazará cualquier aparición de los marcadores de posición especificados (plch1, plch2, ...) en las - cadenas de conexión de cada Data source del modelo por los valores especificados +file Full path of the Model.bim file or database.json model folder to load. +server Server\instance name or connection string from which to load the model +database Database ID of the model to load. If blank (") picks the first available + database on the server. +-L / -LOCAL Connects to a Power BI Desktop (local) instance of Analysis Services. If no + name is specified, this assumes that exactly 1 instance is running. Otherwise, + name should match the name of the .pbix file loaded in Power BI Desktop. +-S / -SCRIPT Execute the specified script on the model after loading. + scriptN Full path of one or more files containing a C# script to execute or an inline + script. +-SC / -SCHEMACHECK Attempts to connect to all Provider Data Sources in order to detect table schema + changes. Outputs... + ...warnings for mismatched data types and unmapped source columns + ...errors for unmapped model columns. +-A / -ANALYZE Runs Best Practice Analyzer and outputs the result to the console. + rules Optional path of file or URL of additional BPA rules to be analyzed. If + specified, model is not analyzed against local user/local machine rules, + but rules defined within the model are still applied. +-AX / -ANALYZEX Same as -A / -ANALYZE but excludes rules specified in the model annotations. +-B / -BIM / -BUILD Saves the model (after optional script execution) as a Model.bim file. + output Full path of the Model.bim file to save to. + id Optional id/name to assign to the Database object when saving. +-F / -FOLDER Saves the model (after optional script execution) as a Folder structure. + output Full path of the folder to save to. Folder is created if it does not exist. + id Optional id/name to assign to the Database object when saving. +-TMDL Saves the model (after optional script execution) as a TMDL folder structure. + output Full path of the TMDL folder to save to. Folder is created if it does not exist. + id Optional id/name to assign to the Database object when saving. +-V / -VSTS Output Visual Studio Team Services logging commands. +-G / -GITHUB Output GitHub Actions workflow commands. +-T / -TRX Produces a VSTEST (trx) file with details on the execution. + resultsfile File name of the VSTEST XML file. +-D / -DEPLOY Command-line deployment + If no additional parameters are specified, this switch will save model metadata + back to the source (file or database). + server Name of server to deploy to or connection string to Analysis Services. + database ID of the database to deploy (create/overwrite). + -L / -LOGIN Disables integrated security when connecting to the server. Specify: + user Username (must be a user with admin rights on the server) + pass Password + -F / -FULL Deploy the full model metadata, allowing overwrite of an existing database. + -O / -OVERWRITE Allow deploy (overwrite) of an existing database. + -C / -CONNECTIONS Deploy (overwrite) existing data sources in the model. After the -C switch, you + can (optionally) specify any number of placeholder-value pairs. Doing so, will + replace any occurrence of the specified placeholders (plch1, plch2, ...) in the + connection strings of every data source in the model, with the specified values (value1, value2, ...). - -P / -PARTITIONS Despliega (sobrescribe) las particiones de tabla existentes en el modelo. - -Y / -SKIPPOLICY No sobrescribe las particiones que tengan definidas políticas de actualización incremental. - -S / -SHARED Despliega (sobrescribe) expresiones compartidas. - -R / -ROLES Despliega roles. - -M / -MEMBERS Despliega miembros del rol. - -X / -XMLA No realiza ningún despliegue. En su lugar, genera un script XMLA/TMSL para desplegarlo más tarde. - xmla_script Nombre del archivo de salida del nuevo script XMLA/TMSL. - -W / -WARN Muestra información sobre objetos sin procesar en forma de advertencias. - -E / -ERR Devuelve un código de salida distinto de cero si Analysis Services devuelve mensajes de error después de que - se hayan desplegado o actualizado los metadatos. + -P / -PARTITIONS Deploy (overwrite) existing table partitions in the model. + -Y / -SKIPPOLICY Do not overwrite partitions that have Incremental Refresh Policies defined. + -S / -SHARED Deploy (overwrite) shared expressions. + -R / -ROLES Deploy roles. + -M / -MEMBERS Deploy role members. + -X / -XMLA No deployment. Generate XMLA/TMSL script for later deployment instead. + xmla_script File name of the new XMLA/TMSL script output. + -W / -WARN Outputs information about unprocessed objects as warnings. + -E / -ERR Returns a non-zero exit code if Analysis Services returns any error messages after + the metadata was deployed / updated. ``` > [!WARNING] -> La incorporación de la opción de implementación `-S` / `-SHARED` en [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases/tag/2.27.0) es un **cambio incompatible**. Si estás usando la CLI de Tabular Editor para realizar implementaciones y vas a actualizar desde una versión anterior de Tabular Editor, asegúrate de incluir esa opción en tus comandos de la CLI, ya que, de lo contrario, **no se implementarán las expresiones compartidas**. +> The addition of the `-S` / `-SHARED` deployment option flag in [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases/tag/2.27.0) is a **breaking change**. If you're using the Tabular Editor CLI to perform deployments and you are upgrading from an earlier version of Tabular Editor, make sure to include that flag in your CLI commands, as **shared expressions will otherwise not be deployed**. > [!TIP] -> La opción `-F` se introdujo en [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases). Se usa para realizar una implementación "completa" y equivale a especificar `-O -C -P -S -R -M`. +> The `-F` flag was introduced in [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases). It is used to perform a "full" deployment and is equivalent to specifying `-O -C -P -S -R -M`. -## Conexión a Azure Analysis Services +## Connecting to Azure Analysis Services -Puedes usar cualquier cadena de conexión válida de SSAS en lugar de un nombre de servidor en el comando. El siguiente comando carga un modelo desde Azure Analysis Services y lo guarda localmente como un archivo Model.bim: +You can use any valid SSAS connection string in place of a server name in the command. The following command loads a model from Azure Analysis Services and saves it locally as a Model.bim file: -**Línea de comandos de Windows:** +**Windows Command Line:** ```shell start /wait TabularEditor.exe "Provider=MSOLAP;Data Source=asazure://northeurope.asazure.windows.net/MyAASServer;User ID=xxxx;Password=xxxx;Persist Security Info=True;Impersonation Level=Impersonate" MyModelDB -B "C:\Projects\FromAzure\Model.bim" @@ -124,17 +127,17 @@ $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` -ArgumentList "`"Provider=MSOLAP;Data Source=asazure://northeurope.asazure.windows.net/MyAASServer;User ID=xxxx;Password=xxxx;Persist Security Info=True;Impersonation Level=Impersonate`" MyModelDB -B C:\Projects\FromAzure\Model.bim" ``` -Si prefieres conectarte usando una entidad de servicio (ID de aplicación y clave) en lugar de la autenticación de Azure Active Directory, puedes usar la siguiente cadena de conexión: +If you prefer to connect using a Service Principal (Application ID and Key) instead of Azure Active Directory authentication, you can use the following connection string: ``` Provider=MSOLAP;Data Source=asazure://northeurope.asazure.windows.net/MyAASServer;User ID=app:@;Password=;Persist Security Info=True;Impersonation Level=Impersonate ``` -## Automatización de cambios de script +## Automating script changes -Si has creado un script dentro de Tabular Editor y quieres aplicarlo a un archivo Model.bim antes del despliegue, puedes usar la opción de línea de comandos "-S" (Script): +If you have created a script inside Tabular Editor, and you want to apply this script to a Model.bim file prior to deployment, you can use the command-line option "-S" (Script): -**Línea de comandos de Windows:** +**Windows Command Line:** ```shell start /wait TabularEditor.exe "C:\Projects\MyModel\Model.bim" -S "C:\Projects\MyModel\MyScript.cs" -D localhost\tabular MyModel @@ -147,34 +150,34 @@ $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` -ArgumentList "`"C:\Projects\MyModel\Model.bim`" -S `"C:\Projects\MyModel\MyScript.cs`" -D `"localhost\tabular`" `"MyModel`"" ``` -Este comando cargará el archivo Model.bim en Tabular Editor, aplicará el script especificado y desplegará el modelo modificado en el servidor "localhost\tabular" como una nueva base de datos "MyModel". Usa la opción "-O" (Overwrite) si quieres sobrescribir una base de datos existente en el servidor con el mismo nombre. +This command will load the Model.bim file in Tabular Editor, apply the specified script and deploy the modified model to the "localhost\tabular" server as a new database "MyModel". Use the "-O" (Overwrite) switch if you want to overwrite an existing database on the server with the same name. -Puedes usar la opción "-B" (Build) en lugar de la opción "-D" (Deploy) para generar el modelo modificado como un nuevo archivo Model.bim, en vez de desplegarlo directamente en un servidor. Esto es útil si quieres desplegar el modelo con otra herramienta de despliegue o si quieres inspeccionarlo en Visual Studio o Tabular Editor antes de desplegarlo. También puede ser útil en escenarios de compilación automatizada, donde quieres guardar el modelo modificado como un artefacto de la versión antes de desplegarlo. +You can use the "-B" (Build) switch instead of the "-D" (Deploy) switch, to output the modified model as a new Model.bim file, instead of deploying it directly to a server. This is useful if you want to deploy the model using another deployment tool, or if you want to inspect the model in Visual Studio or Tabular Editor prior to deployment. It could also be useful for automated build scenarios, where you want to store the modified model as an artifact of the release, before deploying. -## Modificar cadenas de conexión durante el despliegue +## Modifying connection strings during deployment -Supongamos que tienes un modelo que contiene un origen de datos con la siguiente cadena de conexión: +Let's assume you have a model containing a Data Source with the following connection string: ``` Provider=SQLOLEDB.1;Data Source=sqldwdev;Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=DW ``` -Durante el despliegue, quieres modificar la cadena para que apunte a una base de datos de UAT o de producción. La mejor manera de hacerlo es, primero, usar un script que cambie toda la cadena de conexión por un valor de marcador de posición y, después, usar la opción -C para sustituir el marcador por la cadena de conexión real. +During deployment, you want to modify the string, to point to a UAT or production database. The best way to do this, is to first use a script, that changes the entire connection string into a placeholder value, and then use the -C switch to swap the placeholder with the actual connection string. -Coloca el siguiente script en un archivo llamado "ClearConnectionStrings.cs" o similar: +Put the following script into a file called "ClearConnectionStrings.cs" or similar: ```csharp -// Esto reemplazará la cadena de conexión de todos los orígenes de datos del proveedor (heredados) del modelo -// por un marcador de posición basado en el nombre del Data source. Por ejemplo, si tu Data source se llama -// "SQLDW", la cadena de conexión después de ejecutar este script sería "SQLDW": +// This will replace the connection string of all Provider (legacy) data sources in the model +// with a placeholder based on the name of the data source. E.g., if your data source is called +// "SQLDW", the connection string after running this script would be "SQLDW": foreach(var ds in Model.DataSources.OfType()) ds.ConnectionString = ds.Name; ``` -Podemos indicar a Tabular Editor que ejecute el script y, a continuación, realizar la sustitución de marcadores de posición con el siguiente comando: +We can instruct Tabular Editor to execute the script, and then perform placeholder swapping using the following command: -**Línea de comandos de Windows:** +**Windows Command Line:** ```shell start /wait TabularEditor.exe "Model.bim" -S "ClearConnectionStrings.cs" -D localhost\tabular MyModel -C "SQLDW" "Provider=SQLOLEDB.1;Data Source=sqldwprod;Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=DW" @@ -187,40 +190,40 @@ $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` -ArgumentList "Model.bim -S ClearConnectionStrings.cs -D localhost\tabular MyModel -C SQLDW `"Provider=SQLOLEDB.1;Data Source=sqldwprod;Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=DW`"" ``` -El comando anterior desplegará el archivo Model.bim como una nueva base de datos de SSAS "MyModel" en la instancia de SSAS "localhost\tabular". Antes del despliegue, el script se usa para reemplazar todas las cadenas de conexión en los orígenes de datos del proveedor (heredados) por el nombre del origen de datos, que se usará como marcador de posición. Suponiendo que solo tengamos un único origen de datos llamado "SQLDW", el conmutador -C actualizará la cadena de conexión, reemplazando "SQLDW" por la cadena completa especificada. +The command above, will deploy the Model.bim file as a new SSAS database "MyModel" on the "localhost\tabular" SSAS instance. Before deployment, the script is used to replace all connection strings on provider (legacy) data sources, with the name of the data source, to be used as a placeholder. Assuming we only have a single data source called "SQLDW", the -C switch will then update the connection string, replacing "SQLDW" with the entire string specified. -Esta técnica es útil en escenarios en los que quieres desplegar el mismo modelo en varios entornos que deben procesar datos de diferentes orígenes (idénticos), por ejemplo, una base de datos de producción, preproducción o UAT. Si usas Azure DevOps (ver más abajo), considera usar una variable para almacenar la cadena de conexión real que se utilizará, en lugar de dejarla codificada en el comando. +This technique is useful for scenarios, where you want to deploy the same model to multiple environments that should process data from different (identical) sources - for example, a production, pre-prod or UAT database. If using Azure DevOps (see below), consider using a variable to store the actual connection string to be used, instead of hardcoding it in the command. -## Integración con Azure DevOps +## Integration with Azure DevOps -Si quieres usar el CLI de Tabular Editor dentro de una canalización de Azure DevOps, deberías usar el modificador "-V" en cualquier comando de TabularEditor.exe que ejecute tu script. Este modificador hará que Tabular Editor emita comandos de registro en un [formato legible por Azure DevOps](https://github.com/Microsoft/vsts-tasks/blob/master/docs/authoring/commands.md). Esto permite que Azure DevOps reaccione correctamente ante errores, etc. +If you want to use the Tabular Editor CLI inside an Azure DevOps pipeline, you should use the "-V" switch on any TabularEditor.exe command executed by your script. This switch will cause Tabular Editor to output logging commands in a [format readable by Azure DevOps](https://github.com/Microsoft/vsts-tasks/blob/master/docs/authoring/commands.md). These allow Azure DevOps to react properly to errors, etc. -Al realizar el despliegue desde la línea de comandos, se mostrará en la consola información sobre los objetos sin procesar. En escenarios de despliegue automatizado, puede que quieras que tu agente de compilación reaccione cuando haya objetos que queden sin procesar, por ejemplo al agregar nuevas columnas, cambiar la expresión DAX de una tabla calculada, etc. En ese caso, puedes usar el modificador "-W" además del modificador "-V" mencionado anteriormente, para emitir esta información como advertencias. Al hacerlo, el despliegue devolverá a Azure DevOps el estado "SucceededWithIssues" una vez que se haya completado el despliegue. También puede usar el modificador "-E" si desea que el despliegue devuelva el estado "Failed" en caso de que el servidor informe de cualquier error de DAX después de un despliegue satisfactorio. +When performing deployment through the command-line, information about unprocessed objects will be outputted to the prompt. In automated deployment scenarios, you may want your build agent to react to situations where objects become unprocessed, for example when adding new columns, changing the DAX expression of a calculated table, etc. In this case, you can use the "-W" switch in addition to the "-V" switch mentioned above, to output this information as warnings. Doing so, will cause the deployment to return the "SucceededWithIssues" status to Azure DevOps, after deployment is completed. You may also use the "-E" switch if you want the deployment to return status "Failed" in case the server reports any DAX errors back after successful deployment. -`start /wait` no es necesario al ejecutar TabularEditor.exe dentro de una tarea de línea de comandos en una canalización de Azure DevOps. Esto se debe a que la tarea de línea de comandos no finalizará hasta que todos los hilos iniciados por la tarea hayan terminado. Dicho de otro modo, solo necesitas usar `start /wait` si tienes comandos adicionales después de la llamada a TabularEditor.exe y, en ese caso, asegúrate de usar `start /B /wait`. El modificador `/B` es obligatorio para que la salida de TabularEditor.exe se redirija correctamente al registro de la canalización. +`start /wait` is not necessary when executing TabularEditor.exe within a Command Line Task in an Azure DevOps pipeline. This is because the Command Line Task will not complete, until all threads spawned by the task have terminated. In other words, you need only use `start /wait` if you have additional commands following the call to TabularEditor.exe, and in this case, make sure to use `start /B /wait`. The `/B` switch is required in order for the output from TabularEditor.exe to be correctly piped back to the pipeline log. ```shell TabularEditor.exe "C:\Projects\My Model\Model.bim" -D ssasserver databasename -O -C -P -S -V -E -W ``` -O con varios comandos: +Or with multiple commands: ```shell start /B /wait TabularEditor.exe "C:\Projects\Finance\Model.bim" -D ssasserver Finance -O -C -P -S -V -E -W start /B /wait TabularEditor.exe "C:\Projects\Sales\Model.bim" -D ssasserver Sales -O -C -P -S -V -E -W ``` -La figura siguiente muestra el aspecto de este tipo de compilación en Azure DevOps: +The figure below shows what such a build looks like in Azure DevOps: ![image](https://user-images.githubusercontent.com/8976200/27128146-bc044356-50fd-11e7-9a67-b893fc48ea50.png) -Si el despliegue falla por cualquier motivo, Tabular Editor devuelve el estado "Fallido" a Azure DevOps, independientemente de si está usando o no el modificador "-W". +If the deployment fails for any reason, Tabular Editor returns the "Failed" status to Azure DevOps, regardless of whether or not you are using the "-W" switch. -Para obtener más información sobre Azure DevOps y Tabular Editor, [eche un vistazo a esta serie de entradas del blog](https://tabulareditor.github.io/2019/02/20/DevOps1.html) (especialmente [el capítulo 3](https://tabulareditor.github.io/2019/10/08/DevOps3.html) y los capítulos posteriores). +For more information on Azure DevOps and Tabular Editor, [take a look at this blog series](https://tabulareditor.github.io/2019/02/20/DevOps1.html) (especially [chapter 3](https://tabulareditor.github.io/2019/10/08/DevOps3.html) and onward). -### Tarea de PowerShell de Azure DevOps +### Azure DevOps PowerShell Task -Si prefiere usar una tarea de PowerShell en lugar de una tarea de línea de comandos, debe ejecutar TabularEditor.exe con el cmdlet `Start-Process`, tal como se muestra arriba. Además, asegúrese de pasar el código de salida del proceso como el parámetro de salida en su script de PowerShell, para que los errores que se produzcan en Tabular Editor hagan que la tarea de PowerShell falle: +If you prefer to use a PowerShell task instead of a command line task, you must execute TabularEditor.exe using the `Start-Process` cmdlet, as demonstrated above. In addition, make sure to pass the process exit code as the exit parameter in your PowerShell script, so that errors occurring in Tabular Editor will cause the PowerShell task to fail: ```powershell $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` @@ -228,11 +231,11 @@ $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` exit $p.ExitCode ``` -### Pasar parámetros a scripts mediante variables de entorno +### Passing Parameters to Scripts via Environment Variables -Al ejecutar scripts de C# con la opción `-S` en pipelines de Azure DevOps, la forma recomendada de pasar parámetros es mediante variables de entorno en lugar de argumentos de la línea de comandos. Los scripts de C# pueden leer variables de entorno usando `Environment.GetEnvironmentVariable()`, y Azure DevOps pone automáticamente a disposición todas las variables del pipeline como variables de entorno. +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. -**Ejemplo: establecer variables de entorno en YAML:** +**Example - Setting environment variables in YAML:** ```yaml variables: @@ -241,17 +244,17 @@ variables: steps: - script: TabularEditor.exe "Model.bim" -S "UpdateModel.csx" -D "$(serverName)" "MyDatabase" -O -V -E -W - displayName: 'Despliegue con parámetros de script' + displayName: 'Deploy with Script Parameters' env: DEPLOY_ENV: $(deployEnv) SERVER_NAME: $(serverName) ``` -**Ejemplo: tarea de PowerShell con variables de entorno:** +**Example - PowerShell Task with environment variables:** ```yaml - task: PowerShell@2 - displayName: 'Ejecutar script de Tabular Editor' + displayName: 'Run Tabular Editor Script' env: DEPLOY_ENV: 'UAT' CONNECTION_STRING: $(sqldwConnectionString) @@ -263,64 +266,64 @@ steps: exit $p.ExitCode ``` -**En su script de C# (por ejemplo, UpdateModel.csx):** +**In your C# script (e.g., UpdateModel.csx):** ```csharp var deployEnv = Environment.GetEnvironmentVariable("DEPLOY_ENV"); var serverName = Environment.GetEnvironmentVariable("SERVER_NAME"); -Info($"Configurando el modelo para el entorno {deployEnv} en {serverName}"); +Info($"Configuring model for {deployEnv} environment on {serverName}"); -// Aplicar cambios específicos del entorno +// Apply environment-specific changes foreach(var ds in Model.DataSources.OfType()) { ds.ConnectionString = ds.ConnectionString.Replace("{SERVER}", serverName); } ``` -Este enfoque es más limpio y más fácil de mantener que codificar valores en los scripts o usar técnicas complejas de reemplazo de cadenas. Para más información sobre el uso de variables de entorno en scripts de C#, consulte [C# Scripts - Acceso a variables de entorno](xref:csharp-scripts#accessing-environment-variables). +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). -## Ejecutar Best Practice Analyzer +## Running the Best Practice Analyzer -Puede usar el modificador "-A" para que Tabular Editor analice su modelo y detecte todos los objetos que infrinjan cualquiera de las reglas de mejores prácticas definidas en el equipo local (en el archivo %AppData%\..\Local\TabularEditor\BPARules.json), o como anotaciones dentro del propio modelo. Como alternativa, puede especificar la ruta de un archivo .json que contenga reglas de mejores prácticas después del modificador "-A", para analizar el modelo con las reglas definidas en el archivo. Los objetos que incumplan las reglas se mostrarán en la consola. +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. -Si también está usando el modificador "-V", el nivel de gravedad de cada regla determinará cómo se notifica la infracción a la canalización de compilación: +If you're also using the "-V" switch, the severity level of each rule will determine how the rule violation is reported to the build pipeline: -- Gravedad = 1: solo informativo -- Gravedad = 2 generará una ADVERTENCIA -- Gravedad >= 3 generará un ERROR +- Severity = 1 will be informational only +- Severity = 2 will cause a WARNING +- Severity >= 3 will cause an ERROR -## Realizar una comprobación del esquema de la fuente de datos +## Performing a data source schema check -A partir de la [versión 2.8](https://github.com/TabularEditor/TabularEditor/releases/tag/2.8) (2.8), puede usar el modificador -SC (-SCHEMACHECK) para validar las consultas de origen de las tablas. Esto equivale a invocar la [interfaz de usuario de Refresh Table Metadata](xref:importing-tables-te2#refreshing-table-metadata), con la diferencia de que no se realizará ningún cambio en el modelo, pero las diferencias de esquema se notifican en la consola. Los tipos de datos cambiados y las columnas que se hayan agregado al origen se notificarán como advertencias. Las columnas de origen que falten se notificarán como errores. Si se especifican los modificadores -SC (-SCHEMACHECK) y -S (-SCRIPT), la comprobación de esquema se ejecutará después de que el script se haya ejecutado correctamente, lo que le permite modificar las propiedades de la fuente de datos antes de realizar la comprobación de esquema, por ejemplo, para especificar la contraseña de una credencial. +As of [version 2.8](https://github.com/TabularEditor/TabularEditor/releases/tag/2.8), you can use the -SC (-SCHEMACHECK) switch to validate table source queries. This is equivalent to invoking the [Refresh Table Metadata UI](xref:importing-tables-te2#refreshing-table-metadata) except that no changes will be made to the model, but schema differences will be reported to the console. Changed Data Types and columns that were added to the source will be reported as warnings. Missing source columns will be reported as errors. If both the -SC (-SCHEMACHECK) and -S (-SCRIPT) switch are specified, the schema check will run AFTER the script has successfully executed, allowing you to modify Data Source properties before the schema check is performed, for example in order to specify a credential password. -También puede anotar tablas y columnas si quiere que la comprobación de esquema las trate de una manera específica. [Más información aquí](xref:importing-tables-te2#ignoring-objects). +You can also annotate tables and columns if you want the schema check to treat them in a specific way. [More information here](xref:importing-tables-te2#ignoring-objects). -## Salida de la línea de comandos y códigos de salida +## Command Line output and Exit Codes -La línea de comandos proporciona varios detalles, en función de los parámetros usados y de los eventos que se produzcan durante la ejecución. Los códigos de salida se introdujeron en la [versión 2.7.4](https://github.com/TabularEditor/TabularEditor/releases/tag/2.7.4). +The command line provides various details, depending on the switches used and any events encountered during execution. Exit Codes were introduced in [version 2.7.4](https://github.com/TabularEditor/TabularEditor/releases/tag/2.7.4). -| Nivel | Comando | Mensaje | Aclaración | -| ----------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Error | (Cualquiera) | Sintaxis de argumentos no válida | Se proporcionaron argumentos no válidos al CLI de Tabular Editor | -| Error | (Cualquiera) | Archivo no encontrado: ... | | -| Error | (Cualquiera) | Error al cargar el archivo: ... | El archivo está dañado o no contiene metadatos TOM válidos en formato JSON | -| Error | (Cualquiera) | Error al cargar el modelo: ... | No se pudo conectar a la instancia de Analysis Services proporcionada; no se encontró la base de datos; los metadatos de la base de datos están dañados; o la base de datos no tiene un nivel de compatibilidad admitido | -| Error | -SCRIPT | No se encontró el archivo de script especificado | | -| Error | -SCRIPT | Errores de compilación del script: | El script contenía sintaxis de C# no válida. Los detalles se mostrarán en las líneas siguientes. | -| Error | -SCRIPT | Error al ejecutar el script: ... | Excepción no controlada al ejecutar el script. | -| Información | -SCRIPT | Nº de línea del script: ... | Uso de los métodos `Info(string)` o `Output(string)` dentro del script. | -| Advertencia | -SCRIPT | Advertencia del script: ... | Uso del método `Warning(string)` dentro del script. | -| Error | -SCRIPT | Error del script: ... | Uso del método `Error(string)` dentro del script. | -| Error | -FOLDER, -BIM | Los argumentos -FOLDER y -BIM son mutuamente excluyentes. | Tabular Editor no puede guardar el modelo cargado actualmente en una estructura de carpetas y en un archivo .bim al mismo tiempo. | -| Error | -ANALYZE | No se encontró el archivo de reglas: ... | | -| Error | -ANALYZE | Archivo de reglas no válido: ... | El archivo de reglas de BPA especificado está dañado o no contiene un JSON válido. | -| Información | -ANALYZE | ... viola la regla ... | Resultados del Best Practice Analyzer para reglas con un nivel de gravedad de 1 o inferior. | -| Advertencia | -ANALYZE | ... viola la regla ... | Resultados del Best Practice Analyzer para reglas con un nivel de gravedad de 2. | -| Error | -ANALYZE | ... viola la regla ... | Resultados del Best Practice Analyzer para reglas con un nivel de gravedad de 3 o superior. | -| Error | -DEPLOY | ¡Falló el despliegue! ... | Motivo del fallo devuelto directamente por la instancia de Analysis Service (por ejemplo: base de datos no encontrada, no se permite sobrescribir la base de datos, etc.) | -| Información | -DEPLOY | Objeto sin procesar: ... | Objetos que están en el estado "NoData" o "CalculationNeeded" tras una implementación correcta. Utilice el modificador -W para tratarlos como Nivel=Advertencia. | -| Advertencia | -DEPLOY | El objeto no está en estado "Ready": ... | Objetos que se encuentran en estado "DependencyError", "EvaluationError" o "SemanticError" después de un despliegue correcto. Si usa la opción -W, también incluye los objetos en estado "NoData" o "CalculationNeeded". | -| Advertencia | -DEPLOY | Error en X:... | Objetos que contienen DAX no válido después de un despliegue correcto (medidas, columnas calculadas, tablas calculadas, roles). Use la opción -E para tratarlos como Level=Error. | +| Level | Command | Message | Clarification | +| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Error | (Any) | Invalid argument syntax | Invalid arguments were provided to the Tabular Editor CLI | +| Error | (Any) | File not found: ... | | +| Error | (Any) | Error loading file: ... | The file is corrupt or does not contain valid TOM metadata in a JSON format | +| Error | (Any) | Error loading model: ... | Not able to connect to the provided Analysis Services instance, database not found, database metadata corrupt or database not of a supported compatibility level | +| Error | -SCRIPT | Specified script file not found | | +| Error | -SCRIPT | Script compilation errors: | Script contained invalid C# syntax. Details will be outputted on the following lines. | +| Error | -SCRIPT | Script execution error: ... | Unhandled exception when executing the script. | +| Information | -SCRIPT | Script line #: ... | Use of the `Info(string)` or `Output(string)` methods within the script. | +| Warning | -SCRIPT | Script warning: ... | Use of the `Warning(string)` method within the script. | +| Error | -SCRIPT | Script error: ... | Use of the `Error(string)` method within the script. | +| Error | -FOLDER, -BIM | -FOLDER and -BIM arguments are mutually exclusive. | Tabular Editor can not save the currently loaded model to a folder structure and a .bim file in a single execution. | +| Error | -ANALYZE | Rulefile not found: ... | | +| Error | -ANALYZE | Invalid rulefile: ... | The specified BPA rulefile is corrupt or does not contain valid JSON. | +| Information | -ANALYZE | ... violates rule ... | Best Practice Analyzer results for rules of severity level 1 or lower. | +| Warning | -ANALYZE | ... violates rule ... | Best Practice Analyzer results for rules of severity level 2. | +| Error | -ANALYZE | ... violates rule ... | Best Practice Analyzer results for rules of severity level 3 or higher. | +| Error | -DEPLOY | Deployment failed! ... | Failure reason returned directly from Analysis Service instance (for example: Database not found, Database override not allowed, etc.) | +| Information | -DEPLOY | Unprocessed object: ... | Objects that are in state "NoData" or "CalculationNeeded" after successful deployment. Use the -W switch to treat these as Level=Warning. | +| Warning | -DEPLOY | Object not in "Ready" state: ... | Objects that are in state "DependencyError", "EvaluationError" or "SemanticError" after successful deployment. If using the -W switch, also includes objects in state "NoData" or "CalculationNeeded". | +| Warning | -DEPLOY | Error on X:... | Objects containing invalid DAX after successful deployment (measures, calculated columns, calculated tables, roles). Use the -E switch to treat these as Level=Error. | -Si se encuentra alguno de los mensajes de nivel "Error", Tabular Editor devolverá el código de salida = 1. En caso contrario, 0. +If any of the "Error" level outputs are encountered, Tabular Editor will return Exit Code = 1. Otherwise 0. diff --git a/localizedContent/es/content/features/ai-assistant.md b/localizedContent/es/content/features/ai-assistant.md index ddd6aff5d..cc4c91b95 100644 --- a/localizedContent/es/content/features/ai-assistant.md +++ b/localizedContent/es/content/features/ai-assistant.md @@ -20,73 +20,73 @@ applies_to: # Asistente de IA -El Asistente de IA es una interfaz de chat para el desarrollo de modelos semánticos asistido por IA, diseñada para ayudarte a crear modelos semánticos con mayor rapidez. Con un diseño preparado para entornos empresariales, control total sobre lo que se envía a la IA y gestión del consentimiento integrada, puedes usar el Asistente de IA con confianza. El Asistente de IA se ha sometido a pruebas de penetración de seguridad independientes. Para más detalles, visita el [Centro de confianza de Tabular Editor](https://trust.tabulareditor.com). Puede explorar los metadatos de tu modelo, escribir y ejecutar consultas DAX, generar C# Scripts, ejecutar comprobaciones del Best Practice Analyzer, consultar estadísticas del Analizador VertiPaq y buscar en la base de conocimientos de Tabular Editor. +El Asistente de IA es una interfaz conversacional para el desarrollo de modelos semánticos con ayuda de IA, diseñada para ayudarte a crear modelos semánticos más rápido. Con un diseño preparado para entornos empresariales, control total sobre lo que se envía a la IA y gestión integrada del consentimiento, puedes usar el Asistente de IA con confianza. El Asistente de IA ha sido sometido a pruebas de penetración de seguridad independientes. Para obtener más información, visita el [Centro de confianza de Tabular Editor](https://trust.tabulareditor.com). El Asistente de IA puede explorar los metadatos de tu modelo, escribir y ejecutar consultas DAX, generar C# Scripts, ejecutar comprobaciones del Best Practice Analyzer, consultar las estadísticas del Analizador VertiPaq y buscar en la base de conocimientos de Tabular Editor. -El Asistente de IA utiliza un modelo BYOK de clave aportada por el usuario. Tú proporcionas una clave de API de uno de los proveedores compatibles y el asistente se ejecuta directamente a través de la API de ese proveedor. +El Asistente de IA utiliza un modelo BYOK, «trae tu propia clave». Proporcionas una clave de API de uno de los proveedores compatibles y el asistente se ejecuta directamente contra la API de ese proveedor. > [!NOTE] -> El Asistente de IA está en vista previa pública a partir de Tabular Editor 3.26.0. Agradecemos tus comentarios sobre la experiencia mientras seguimos mejorándola. +> El Asistente de IA está en vista previa pública a partir de Tabular Editor 3.26.0. Agradecemos tus comentarios sobre la experiencia mientras seguimos perfeccionándola. -![Primer panel del Asistente de IA al abrirlo](~/content/assets/images/ai-assistant/ai-assistant-panel-first-open.png) +![Panel del Asistente de IA al abrirlo por primera vez](~/content/assets/images/ai-assistant/ai-assistant-panel-first-open.png) ## Primeros pasos 1. Abre **Herramientas > Preferencias > Asistente de IA** -2. Selecciona tu proveedor de IA — en una instalación limpia, el valor predeterminado es **Ninguno (IA deshabilitada)** — y luego introduce tu clave de API -3. Abre el panel del Asistente de IA desde **Vista > Asistente de IA** -4. Escribe mensajes y pulsa **Enter** para iniciar una conversación +2. Selecciona tu proveedor de IA — en una instalación limpia, el valor predeterminado es **Ninguno (IA deshabilitada)** — y, a continuación, introduce tu clave de API +3. Abre el panel del Asistente de IA desde **Ver > Asistente de IA** +4. Escribe un mensaje y pulsa **Enter** para iniciar una conversación > [!TIP] > Usa nuestra [demo interactiva del Asistente de IA](https://demos.tabulareditor.com/psl/of150vcy?) para ver cómo configurarlo y usarlo. > [!NOTE] -> Las claves de API se almacenan cifradas en tu equipo local. +> Las claves de API se almacenan cifradas en tu máquina local. ## Proveedores compatibles -Configura tu proveedor de IA en **Herramientas > Preferencias > Asistente de IA > Proveedor de IA**. Selecciona un proveedor en la lista desplegable — el valor predeterminado es **Ninguno (IA deshabilitada)** hasta que configures uno — introduce tu clave de API y, si lo deseas, reemplaza el modelo predeterminado. Para OpenAI y Anthropic, el campo **Nombre del modelo** es un cuadro combinado rellenado previamente con modelos conocidos; también puedes escribir un nombre de modelo personalizado. +Configura tu proveedor de IA en **Herramientas > Preferencias > Asistente de IA > Proveedor de IA**. Selecciona un proveedor en la lista desplegable — el valor predeterminado es **Ninguno (IA deshabilitada)** hasta que configures uno —, introduce tu clave de API y, si quieres, sobrescribe el modelo predeterminado. Para OpenAI y Anthropic, el campo **Nombre del modelo** es un cuadro combinado precargado con modelos conocidos; también puedes escribir un nombre de modelo personalizado. -| Proveedor | Modelo predeterminado | Configuración necesaria | -| -------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------- | -| OpenAI | gpt-4o | Clave de API. URL base, ID de organización e ID de proyecto opcionales | -| Anthropic | claude-sonnet-4-6 | Clave de API. URL base opcional | -| Azure OpenAI | Dependiente de la implementación | Clave de API, URL del punto de conexión y nombre de la implementación | -| Personalizado (compatible con OpenAI) | Especificado por el usuario | Clave de API y URL personalizada del punto de conexión | +| Proveedor | Modelo predeterminado | Configuración requerida | +| -------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------ | +| OpenAI | gpt-4o | Clave de API. URL base opcional, ID de organización e ID de proyecto | +| Anthropic | claude-sonnet-4-6 | Clave de API. URL base opcional | +| Azure OpenAI | Depende del despliegue | Clave de API, URL del punto de conexión y nombre del despliegue | +| Personalizado (compatible con OpenAI) | Especificado por ti | Clave de API y URL del punto de conexión personalizada | ![Selección del proveedor del Asistente de IA en Preferencias](~/content/assets/images/ai-assistant/ai-assistant-provider-preferences.png) ### OpenAI -Selecciona **OpenAI** como proveedor e introduce tu clave de API. Opcionalmente, puedes especificar un ID de organización y un ID de proyecto si tu cuenta de OpenAI los usa. El modelo predeterminado es **gpt-4o**, pero puedes cambiarlo por cualquier modelo disponible en tu cuenta. +Selecciona **OpenAI** como proveedor e introduce tu clave de API. Opcionalmente, puedes especificar un ID de organización y un ID de proyecto si tu cuenta de OpenAI los utiliza. El modelo predeterminado es **gpt-4o**, pero puedes cambiarlo a cualquier modelo disponible en tu cuenta. -![Configuración de OpenAI en el Asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-openai-config.png) +![Configuración de OpenAI del asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-openai-config.png) ### Anthropic Selecciona **Anthropic** como proveedor e introduce tu clave de API. El modelo predeterminado es **claude-sonnet-4-6**. Puedes cambiar el nombre del modelo a cualquier modelo de Anthropic disponible en tu cuenta. -![Configuración de Anthropic en el Asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-anthropic-config.png) +![Configuración de Anthropic del asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-anthropic-config.png) > [!IMPORTANT] -> Anthropic aplica límites de velocidad de tokens de entrada por minuto (ITPM) en función del nivel de tu cuenta. Una nueva clave de API empieza en el Nivel 1 con 30.000 ITPM para Claude Sonnet 4.x. Una sola solicitud a un modelo grande puede superar este límite. Compra 40 USD o más en créditos de API para alcanzar el Nivel 2 (450.000 ITPM). Consulta la [documentación de límites de velocidad de Anthropic](https://docs.anthropic.com/en/api/rate-limits) para ver todos los detalles de los niveles. +> Anthropic impone límites de tasa de tokens de entrada por minuto (ITPM) según el nivel de tu cuenta. Una clave de API nueva empieza en el nivel 1, con 30.000 ITPM para Claude Sonnet 4.x. Una sola solicitud a un modelo grande puede superar este límite. Compra créditos de API por un importe de 40 USD o más para alcanzar el nivel 2 (450.000 ITPM). Consulta la [documentación sobre los límites de velocidad de Anthropic](https://docs.anthropic.com/en/api/rate-limits) para ver todos los detalles de cada nivel. ### Azure OpenAI -Selecciona **Azure OpenAI** como proveedor y configura tres campos: +Selecciona **Azure OpenAI** como proveedor y configura estos tres campos: - **Clave de API** — la clave de acceso de tu recurso de Azure OpenAI -- **Punto de conexión del servicio** — la URL del punto de conexión de tu recurso, por ejemplo `https://your-resource.openai.azure.com`. Usa la URL del recurso, no el alias `privatelink`; el certificado SSL se emite para `*.openai.azure.com` y, si te conectas directamente a `*.privatelink.openai.azure.com`, fallará la validación del certificado +- **Punto de conexión del servicio** — la URL del punto de conexión de tu recurso, por ejemplo `https://your-resource.openai.azure.com`. Usa la URL del recurso, no el alias `privatelink`; el certificado SSL se emite para `*.openai.azure.com`, y conectarse directamente a `*.privatelink.openai.azure.com` hace que falle la validación del certificado - **Nombre del modelo** — el **nombre de la implementación**, no el nombre del modelo subyacente ni el nombre del recurso -Azure OpenAI requiere el nombre de la implementación en cada llamada a la API. El nombre de la implementación se elige al crearla, así que puede ser cualquier cadena. Las implementaciones suelen llevar el nombre del modelo al que sirven (por ejemplo, `gpt-4o`), pero es una convención, no un requisito. Si introduces el nombre del recurso o un nombre de modelo que no exista como implementación, la solicitud fallará. +Azure OpenAI requiere el nombre de la implementación en cada llamada a la API. El nombre de la implementación se elige al crearla, así que puede ser cualquier cadena. Las implementaciones suelen llevar el nombre del modelo al que sirven (por ejemplo, `gpt-4o`), pero eso es una convención, no un requisito. Si introduces el nombre del recurso o un nombre de modelo base que no exista como implementación, la solicitud fallará. #### Cómo encontrar el nombre de tu implementación En el [portal de Azure AI Foundry](https://ai.azure.com): 1. Inicia sesión y selecciona tu recurso de Azure OpenAI -2. Abre **Implementaciones** (o **Modelos + puntos de conexión** si el recurso se ha actualizado a Foundry) -3. Copia el valor de la columna **Nombre** +2. Abre **Deployments** (o **Models + endpoints** si el recurso se ha actualizado a Foundry) +3. Copia el valor de la columna **Name** Es posible que las implementaciones creadas antes de que tu organización adoptara Azure AI Foundry no aparezcan en el portal. Enuméralas con la CLI de Azure: @@ -94,160 +94,160 @@ Es posible que las implementaciones creadas antes de que tu organización adopta az cognitiveservices account deployment list --name "" --resource-group "" --output table ``` -Consulta [Crear y desplegar un recurso de Azure OpenAI](https://learn.microsoft.com/azure/ai-foundry/openai/how-to/create-resource#deploy-a-model) para más detalles. +Consulta [Crear e implementar un recurso de Azure OpenAI](https://learn.microsoft.com/azure/ai-foundry/openai/how-to/create-resource#deploy-a-model) para obtener más información. Para errores 403, fallos de SSL o respuestas "DeploymentNotFound", consulta @azure-openai-connection-errors. > [!NOTE] -> El proveedor **Azure OpenAI** es para recursos clásicos de Azure OpenAI que usan el parámetro de consulta `api-version`. Si usas el nuevo **Microsoft Foundry**, consulta [Uso de Microsoft Foundry](#using-microsoft-foundry) más abajo. +> El proveedor **Azure OpenAI** está pensado para recursos clásicos de Azure OpenAI que usan el parámetro de consulta `api-version`. Si usas el nuevo **Microsoft Foundry**, consulta [Uso de Microsoft Foundry](#using-microsoft-foundry) a continuación. ### Personalizado (compatible con OpenAI) -La opción de proveedor Personalizado admite LLM locales o de tu organización que expongan un punto de conexión de API compatible con OpenAI. Introduce tu clave de API y la URL del punto de conexión personalizado. Esto te permite mantener todos los datos dentro de tu propia infraestructura por motivos de privacidad o requisitos de cumplimiento. +La opción del proveedor Personalizado admite LLM locales o de tu organización que expongan un punto de conexión de API compatible con OpenAI. Introduce tu clave de API y la URL del punto de conexión personalizado. Esto te permite mantener todos los datos dentro de tu propia infraestructura para cumplir con los requisitos de privacidad de datos o de cumplimiento normativo. ### Uso de un LLM local o de tu organización -Puedes ejecutar el Asistente de IA con un LLM autoalojado mediante el proveedor Personalizado. Esto mantiene todos los datos dentro de tu propia infraestructura, ya sea un modelo que se ejecuta en tu equipo local o un LLM alojado de forma centralizada dentro de la red de tu organización. En cualquier caso, no se envía ningún dato a un proveedor de nube de terceros. +Puedes ejecutar el Asistente de IA con un LLM autoalojado usando el proveedor Personalizado. Esto mantiene todos los datos dentro de tu propia infraestructura, ya sea un modelo que se ejecuta en tu equipo local o un LLM alojado de forma centralizada dentro de la red de tu organización. En cualquier caso, no se envían datos a un proveedor de nube externo. -Varias herramientas pueden alojar modelos con una API compatible con OpenAI: +Hay varias herramientas que pueden alojar modelos con una API compatible con OpenAI: - [Ollama](https://ollama.com) — CLI ligera para descargar y ejecutar modelos localmente - [LM Studio](https://lmstudio.ai) — aplicación de escritorio con interfaz gráfica para administrar y ejecutar modelos locales -- [LocalAI](https://localai.io) — alternativa autoalojada, impulsada por la comunidad, con una amplia compatibilidad de modelos +- [LocalAI](https://localai.io) — alternativa autoalojada, impulsada por la comunidad y con amplia compatibilidad de modelos -Estas herramientas pueden ejecutarse en la estación de trabajo de un desarrollador para uso individual o implementarse en un servidor compartido dentro de tu organización para ofrecer a tu equipo un punto de conexión de LLM gestionado de forma centralizada. +Estas herramientas pueden ejecutarse en la estación de trabajo de un desarrollador para uso individual o implementarse en un servidor compartido dentro de tu organización para proporcionar a tu equipo un punto de conexión de LLM gestionado de forma centralizada. #### Ejemplo: Ollama 1. [Descarga e instala Ollama](https://ollama.com/download) 2. Descarga un modelo, por ejemplo: `ollama pull llama3.1` -3. Inicia el servidor de Ollama (se ejecuta automáticamente tras la instalación y, de forma predeterminada, en el puerto 11434) +3. Inicia el servidor de Ollama (se ejecuta automáticamente después de la instalación, de forma predeterminada en el puerto 11434) 4. En Tabular Editor, ve a **Herramientas > Preferencias > Asistente de IA > Proveedor de IA** 5. Configura **Elegir proveedor** como **Personalizado (compatible con OpenAI)** -6. Establece **Punto de conexión del servicio** en `http://localhost:11434/v1` -7. Establece **Nombre del modelo** con el modelo que descargaste (p. ej., `llama3.1`) -8. El campo **Clave de API** puede establecerse con cualquier valor no vacío (p. ej., `ollama`) — Ollama no requiere autenticación, pero el campo no puede dejarse en blanco +6. Configura **Punto de conexión del servicio** como `http://localhost:11434/v1` +7. Configura **Nombre del modelo** como el modelo que descargaste (por ejemplo, `llama3.1`) +8. Puedes poner cualquier valor no vacío en el campo **Clave de API** (por ejemplo, `ollama`) — Ollama no requiere autenticación, pero el campo no puede dejarse en blanco #### Ejemplo: LM Studio 1. [Descargar LM Studio](https://lmstudio.ai/download) -2. Descarga un modelo. Ya sea desde la página de búsqueda de modelos del panel izquierdo o mediante la CLI. Por ejemplo: `lms get lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF` +2. Descarga un modelo. Ya sea desde la página de búsqueda de modelos del panel izquierdo o desde la CLI. Por ejemplo: `lms get lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF` 3. Inicia el servidor de LM Studio. Ya sea desde la página para desarrolladores del panel izquierdo o mediante la CLI. por ejemplo `lms server start` - Nota: tendrás que configurarlo para que use el modo compatible con OpenAI. Además, puede que tengas que cambiar el tamaño de contexto predeterminado para que sea superior a 100000 tokens. + Nota: tendrás que configurarlo para usar el modo compatible con OpenAI. Además, puede que tengas que cambiar el tamaño de contexto predeterminado para que supere los 100.000 tokens. 4. En Tabular Editor, ve a **Herramientas > Preferencias > Asistente de IA > Proveedor de IA** 5. Configura **Elegir proveedor** como **Personalizado (compatible con OpenAI)** -6. Establece **Punto de conexión del servicio** en `http://localhost:1234/v1` -7. Establece **Nombre del modelo** con el modelo que descargaste (p. ej., `lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF`) -8. El campo **Clave de API** puede establecerse con cualquier valor no vacío (p. ej., `lms`) — LM Studio no requiere autenticación, pero el campo no puede dejarse en blanco +6. Configura **Punto de conexión del servicio** como `http://localhost:1234/v1` +7. Configura **Nombre del modelo** con el modelo que descargaste (p. ej., `lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF`) +8. Puedes poner cualquier valor no vacío en el campo **Clave de API** (por ejemplo, `lms`) — LM Studio no requiere autenticación, pero el campo no puede dejarse en blanco > [!NOTE] -> La calidad de las respuestas con modelos locales depende del tamaño del modelo y de tu hardware. Los modelos más grandes suelen producir mejores resultados, pero requieren más RAM y una GPU capaz. Las capacidades de llamada a herramientas del Asistente de IA requieren un modelo que admita llamadas a funciones en el formato compatible con OpenAI. +> La calidad de las respuestas con modelos locales depende del tamaño del modelo y de tu hardware. En general, los modelos más grandes producen mejores resultados, pero requieren más RAM y una GPU potente. Las capacidades de llamada a herramientas del Asistente de IA requieren un modelo que admita la llamada a funciones en el formato compatible con OpenAI. > [!TIP] -> We recommend a model with a _minimum_ of 30 billion parameters but ideally at least 100 billion parameters. Por ejemplo, el modelo Qwen3.5-122B-A10B funcionó bien en nuestras pruebas internas. +> Recomendamos un modelo con un _mínimo_ de 30 mil millones de parámetros, pero idealmente de al menos 100 mil millones de parámetros. Por ejemplo, el modelo Qwen3.5-122B-A10B obtuvo buenos resultados en nuestras pruebas internas. ### Uso de Microsoft Foundry -[Microsoft Foundry](https://ai.azure.com) (antes llamado Azure AI Foundry) te permite desplegar modelos de OpenAI y Anthropic en tu entorno de Azure. Puedes acceder a estos modelos mediante el proveedor **OpenAI** o **Anthropic** en Tabular Editor — no mediante el proveedor **Azure OpenAI**, que es para recursos clásicos de Azure OpenAI. +[Microsoft Foundry](https://ai.azure.com) (anteriormente Azure AI Foundry) te permite implementar modelos de OpenAI y Anthropic en tu entorno de Azure. Se accede a estos modelos a través del proveedor **OpenAI** o **Anthropic** en Tabular Editor — no a través del proveedor **Azure OpenAI**, que es para recursos clásicos de Azure OpenAI. > [!IMPORTANT] > No uses el proveedor **Azure OpenAI** para modelos de Microsoft Foundry. El proveedor **Azure OpenAI** solo es compatible con recursos clásicos de Azure OpenAI. #### Modelos de OpenAI en Microsoft Foundry -Para usar un modelo de OpenAI (como GPT-4o o GPT-5.4-mini) desplegado en Microsoft Foundry: +Para usar un modelo de OpenAI (como GPT-4o o GPT-5.4-mini; 5,4) implementado en Microsoft Foundry: -1. En Tabular Editor, ve a **Herramientas > Preferencias > Asistente de IA > Proveedor de IA** -2. Selecciona **OpenAI** en **Elegir proveedor** -3. Configura **URL base** con el punto de conexión del recurso de Foundry y añade `/openai/v1` al final. La URL sigue uno de estos formatos: +1. En Tabular Editor, ve a **Herramientas > Preferencia > Asistente de IA > Proveedor de IA** +2. Establece **Choose provider** en **OpenAI** +3. Establece **Base URL** en el punto de conexión de tu recurso de Foundry y añade `/openai/v1` al final. La URL sigue uno de estos formatos: - `https://your-resource.services.ai.azure.com/openai/v1` - `https://your-resource.openai.azure.com/openai/v1` -4. Introduce tu **Clave de API** de Foundry -5. Configura **Nombre del modelo** como el nombre de tu implementación (por ejemplo, `gpt-5.4-mini`) +4. Introduce tu **API Key** de Foundry +5. Establece **Model name** en el nombre de tu implementación (p. ej., `gpt-5.4-mini`; 5,4) > [!NOTE] > La URL base no se muestra directamente en el portal de Microsoft Foundry. El portal muestra un **URI de destino** que incluye la ruta completa de la API (por ejemplo, `https://your-resource.services.ai.azure.com/api/projects/YourProject/openai/v1/responses`). Para la URL base, usa solo `https://your-resource.services.ai.azure.com/openai/v1`. #### Modelos de Anthropic en Microsoft Foundry -Para usar un modelo de Anthropic (como Claude Sonnet 4,6) desplegado en Microsoft Foundry: +Para usar un modelo de Anthropic (como Claude Sonnet 4.6; 4,6) implementado en Microsoft Foundry: -1. En Tabular Editor, ve a **Herramientas > Preferencias > Asistente de IA > Proveedor de IA** -2. Configura **Elegir proveedor** como **Anthropic** -3. Establece **URL base** en el punto de conexión de tu recurso de Foundry, con `/anthropic` añadido al final; por ejemplo: `https://your-resource.services.ai.azure.com/anthropic` -4. Introduce tu **clave de API** de Foundry -5. En **Nombre del modelo**, introduce el identificador del modelo (p. ej., `claude-sonnet-4-6`) +1. En Tabular Editor, ve a **Herramientas > Preferencia > Asistente de IA > Proveedor de IA** +2. Establece **Choose provider** en **Anthropic** +3. Establece **Base URL** en el punto de conexión de tu recurso de Foundry y añade `/anthropic` al final; por ejemplo, `https://your-resource.services.ai.azure.com/anthropic` +4. Introduce tu **API Key** de Foundry +5. Establece **Nombre del modelo** en el identificador del modelo (por ejemplo, `claude-sonnet-4-6`) > [!NOTE] -> El portal muestra un **URI de destino** como `https://your-resource.services.ai.azure.com/anthropic/v1/messages`. Para la URL base, usa solo la parte hasta `/anthropic` inclusive. +> El portal muestra un **URI de destino** como `https://your-resource.services.ai.azure.com/anthropic/v1/messages`. Para la URL base, usa solo la parte hasta e incluyendo `/anthropic`. ## Capacidades El Asistente de IA tiene acceso al contexto de tu modelo y puede realizar las siguientes acciones: -- **Exploración del modelo**: Consultar los metadatos del modelo, incluidas tablas, columnas, medidas, relaciones y sus propiedades -- **Redacción de Consultas DAX**: Generar Consultas DAX y ejecutarlas contra tu modelo en modo conectado, devolviendo conjuntos de resultados directamente en el chat -- **Generación de C# Scripts**: Crear C# Scripts para modificar el modelo, que se abren en una nueva ventana del editor. Cuando haces clic en **Ejecutar** en el chat, de forma predeterminada se muestra el cuadro de diálogo [Vista previa de cambios](xref:csharp-scripts#running-scripts-with-preview), lo que te permite revisar todos los cambios en los metadatos del modelo antes de aceptarlos. También puedes abrir el script en el editor y ejecutarlo desde la barra de herramientas de scripts, con o sin la vista previa. Los cambios en los metadatos del modelo se pueden deshacer con **Ctrl+Z** -- **Best Practice Analyzer**: Ejecutar el análisis de BPA, ver infracciones de las reglas y crear o modificar reglas de BPA +- **Exploración del modelo**: Consultar metadatos del modelo, incluidas tablas, columnas, medidas, relaciones y sus propiedades +- **Redacción de consultas DAX**: Generar Consultas DAX y ejecutarlas en modo conectado contra tu modelo, devolviendo conjuntos de resultados directamente en el chat +- **Generación de C# Script**: Crear C# Scripts para modificaciones del modelo que se abren en una nueva ventana del editor. Al hacer clic en **Ejecutar** en el chat, se muestra de forma predeterminada el cuadro de diálogo [vista previa de cambios](xref:csharp-scripts#run-c-scripts-with-preview), lo que te permite revisar todos los cambios en los metadatos del modelo antes de aceptarlos. También puedes abrir el script en el editor y ejecutarlo desde la barra de herramientas de scripts, con o sin la vista previa. Los cambios en los metadatos del modelo se pueden deshacer con **Ctrl+Z** +- **Best Practice Analyzer**: Ejecutar análisis de BPA, ver infracciones de reglas y crear o modificar reglas de BPA - **Analizador VertiPaq**: Consultar estadísticas de uso de memoria y cardinalidad de columnas - **Acceso a documentos**: Leer y modificar documentos abiertos, como scripts DAX y Consultas DAX -- **Búsqueda en la base de conocimientos**: Buscar en la documentación integrada de Tabular Editor para encontrar respuestas -- **Navegación por la interfaz de usuario**: Generar enlaces de acción `te3://` que abren cuadros de diálogo y funcionalidades específicas de Tabular Editor +- **Búsqueda en la base de conocimientos**: Buscar respuestas en la documentación integrada de Tabular Editor +- **Navegación por la interfaz de usuario**: Generar vínculos de acción `te3://` que abren cuadros de diálogo y funciones específicas de Tabular Editor > [!NOTE] -> Las herramientas que requieren una conexión activa a la base de datos —incluidas la ejecución de consultas DAX y las estadísticas del Analizador VertiPaq— se ocultan automáticamente cuando trabajas con un archivo de modelo (por ejemplo, un archivo `.bim` o una carpeta `.tmdl`) que no está conectado a Analysis Services o Power BI. El asistente seguirá escribiendo consultas DAX por ti, pero el botón **Ejecutar** de los artefactos de consulta DAX se deshabilita hasta que se establezca una conexión. Las estadísticas del Analizador VertiPaq siguen estando disponibles si se cargaron previamente desde un archivo `.vpax`. +> Las herramientas que requieren una conexión activa a la base de datos —como la ejecución de Consultas DAX y las estadísticas del Analizador VertiPaq— se ocultan automáticamente cuando trabajas con un archivo de modelo (por ejemplo, un archivo `.bim` o una carpeta `.tmdl`) que no está conectado a Analysis Services o Power BI. El asistente seguirá escribiendo Consultas DAX por ti, pero el botón **Ejecutar** en los artefactos de Consulta DAX estará deshabilitado hasta que se establezca una conexión. Las estadísticas del Analizador VertiPaq siguen estando disponibles si se cargaron previamente desde un archivo `.vpax`. ## Conversaciones El Asistente de IA admite varias conversaciones simultáneas. Cada conversación mantiene su propio historial de mensajes y contexto. -- Las conversaciones se conservan entre sesiones y se almacenan localmente en `%LocalAppData%\TabularEditor3\AI\Conversations\` -- Los títulos se generan automáticamente tras el primer intercambio. Puedes cambiar el nombre de las conversaciones manualmente -- **Compactación automática**: Cuando la conversación se acerca al límite de la ventana de contexto (~80%), los mensajes más antiguos se resumen automáticamente para liberar espacio. Se archiva una instantánea de la conversación completa antes de la compactación +- Las conversaciones persisten entre sesiones y se almacenan localmente en `%LocalAppData%\TabularEditor3\AI\Conversations\` +- Los títulos se generan automáticamente después del primer intercambio. Puedes cambiar manualmente el nombre de las conversaciones +- **Compactación automática**: Cuando la conversación se acerca al límite de la ventana de contexto (~80 %), los mensajes más antiguos se resumen automáticamente para liberar espacio. Se archiva una instantánea de toda la conversación antes de la compactación ## Artefactos Cuando el Asistente de IA genera código, crea **artefactos** que se abren directamente en ventanas del editor: -- **C# Scripts**: Se abren en un nuevo editor de C# Script con resaltado de sintaxis, compilación y compatibilidad con la ejecución -- **Consultas DAX**: Se abren en un nuevo editor de consultas DAX con resaltado de sintaxis y compatibilidad con la ejecución +- **C# Scripts**: Se abren en un nuevo editor de scripts de C# con resaltado de sintaxis y soporte para la compilación y la ejecución +- **Consultas DAX**: Se abren en un nuevo editor de consultas DAX con resaltado de sintaxis y soporte para la ejecución -Los artefactos se transmiten en tiempo real a medida que la IA los genera. Los artefactos de C# Script incluyen un análisis de seguridad que señala código potencialmente inseguro (p. ej., acceso al sistema de archivos u operaciones de red). +Los artefactos se muestran en tiempo real a medida que la IA los genera. Los artefactos de C# Script incluyen un análisis de seguridad que marca código potencialmente inseguro (por ejemplo, acceso al sistema de archivos u operaciones de red). -![Asistente de IA: generar un C# Script](~/content/assets/images/ai-assistant/ai-assistant-generate-c-sharp-script.png) +![Asistente de IA: generar C# Script](~/content/assets/images/ai-assistant/ai-assistant-generate-c-sharp-script.png) -Cuando ejecutas un C# Script desde el chat, el cuadro de diálogo **Vista previa del script** muestra una comparación en paralelo de todos los cambios de metadatos del modelo realizados por el script. Puedes aceptar los cambios o revertirlos. Consulta [Ejecutar scripts con vista previa](xref:csharp-scripts#run-c-scripts-with-preview) para obtener más información. +Cuando ejecutas un C# Script desde el chat, el cuadro de diálogo **Vista previa del script** muestra una comparación lado a lado de todos los cambios en los metadatos del modelo realizados por el script. Puedes aceptar los cambios o revertirlos. Consulta [Ejecutar scripts con vista previa](xref:csharp-scripts#run-c-scripts-with-preview) para más información. ![Vista previa del script: cambios del modelo](~/content/assets/images/preview-script-changes.png) ## Instrucciones personalizadas -Las instrucciones personalizadas son conjuntos de instrucciones que guían el comportamiento del Asistente de IA para tareas específicas. Se activan automáticamente según la detección de intenciones o se invocan de forma explícita. +Las instrucciones personalizadas son conjuntos de instrucciones que guían el comportamiento del Asistente de IA en tareas específicas. Se activan automáticamente según la detección de intención o se invocan de forma explícita. ### Instrucciones personalizadas integradas El Asistente de IA incluye las siguientes instrucciones personalizadas integradas: -| Instrucción personalizada | Se activa cuando | +| Instrucción personalizada | Se activa con | | ------------------------- | -------------------------------------------------- | -| Consulta DAX | DAX, consulta, EVALUATE, medida | +| Consulta DAX | DAX, consulta, evaluar, medida | | Modificación del modelo | Modificar, cambiar, agregar, actualizar, crear | | Diseño del modelo | Diseño, arquitectura, patrón, práctica recomendada | -| Organizar el modelo | Organizar, limpiar, carpeta, cambiar nombre | -| Optimizar el modelo | Optimizar, rendimiento, lento, velocidad | +| Organizar modelo | Organizar, limpiar, carpeta, renombrar | +| Optimizar modelo | Optimizar, rendimiento, lento, velocidad | | Macros | Macro, automatizar, grabar | | UDFs | UDF, función, definida por el usuario | | BPA | BPA, práctica recomendada, regla, infracción | -Las instrucciones personalizadas se muestran como indicadores encima de las respuestas del asistente, lo que indica qué instrucciones influyeron en la respuesta. Puedes activar o desactivar esta visualización en **Preferencia > Asistente de IA > Preferencia > Mostrar indicador de instrucciones personalizadas**. +Las instrucciones personalizadas se muestran como indicadores encima de las respuestas del asistente y señalan qué instrucciones influyeron en ellas. Puedes activar o desactivar esta visualización en **Preferencias > Asistente de IA > Preferencias > Mostrar indicador de instrucciones personalizadas**. ### Invocar una instrucción personalizada -Escribe `/` para explorar las instrucciones personalizadas disponibles, o escribe el `/instruction-id` completo al inicio de tu mensaje para invocar explícitamente una instrucción concreta. Por ejemplo, `/dax-querying` fuerza la instrucción de Consulta DAX independientemente del contenido de tu mensaje. +Escribe `/` para explorar las instrucciones personalizadas disponibles, o escribe el `/instruction-id` completo al principio de tu mensaje para invocar explícitamente una instrucción concreta. Por ejemplo, `/dax-querying` fuerza la instrucción de Consulta DAX independientemente del contenido del mensaje. ### Añade tus propias instrucciones personalizadas -Puedes crear instrucciones personalizadas colocando archivos `.md` en `%LocalAppData%\TabularEditor3\AI\CustomInstructions\`. Cada archivo requiere un front matter YAML que defina los metadatos de la instrucción: +Puedes crear instrucciones personalizadas colocando archivos `.md` en `%LocalAppData%\TabularEditor3\AI\CustomInstructions\`. Cada archivo requiere un bloque de frontmatter en YAML que defina los metadatos de la instrucción: ```yaml --- @@ -267,23 +267,23 @@ triggers: - model_loaded --- -Aquí va el contenido de tu instrucción. Este es el texto que se -insertará en el prompt del sistema de la IA cuando se active la instrucción. +Your instruction content goes here. This is the text that will be +injected into the AI's system prompt when the instruction is activated. ``` | Campo | Obligatorio | Predeterminado | Descripción | | --------------------------- | ----------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | `id` | No | Nombre de archivo sin `.md` | Identificador único; también se usa como `/id` para la invocación explícita | -| `name` | No | `id` con mayúsculas iniciales | Nombre para mostrar en el autocompletado | -| `description` | No | - | Breve descripción que se muestra debajo del nombre | -| `priority` | No | 100 | Los valores más altos se inyectan primero cuando coinciden varias instrucciones personalizadas | -| `always_inject` | No | false | Si es `true`, siempre se incluye en el prompt del sistema | -| `hidden` | No | false | Si es `true`, no se muestra en el autocompletado de `/command` | -| `triggers.keywords` | No | [] | Palabras que activan la instrucción (no distingue entre mayúsculas y minúsculas) | -| `triggers.patterns` | No | [] | Patrones de regex para coincidencias complejas | +| `name` | No | `id` con inicial mayúscula | Nombre para mostrar en el autocompletado | +| `description` | No | - | Descripción breve que se muestra debajo del nombre | +| `priority` | No | 100 | Los valores más altos se insertan primero cuando coinciden varias instrucciones personalizadas | +| `always_inject` | No | false | Si es true, se incluye siempre en el prompt del sistema | +| `hidden` | No | false | Si es true, no se muestra en el autocompletado de `/command` | +| `triggers.keywords` | No | [] | Palabras que activan la instrucción (sin distinguir entre mayúsculas y minúsculas) | +| `triggers.patterns` | No | [] | Patrones de expresiones regulares para coincidencias complejas | | `triggers.context_required` | No | [] | Condiciones que deben cumplirse (p. ej., `model_loaded`) | -Las instrucciones personalizadas con un `id` que coincida con el de una instrucción integrada sustituirán la versión integrada. +Las instrucciones personalizadas cuyo `id` coincida con el de una instrucción integrada sustituirán la versión integrada. ## Consentimiento @@ -293,25 +293,25 @@ El Asistente de IA solicita permiso antes de enviar datos al proveedor de IA. El | --------------------------- | ----------------------------------------------------------------------------------- | | Datos de consulta | Resultados de Consultas DAX y muestras de datos | | Leer documentos | Lectura del contenido de documentos abiertos, como scripts DAX y Consultas DAX | -| Modificar documentos | Realizar cambios en los documentos abiertos | +| Modificar documentos | Realizar cambios en documentos abiertos | | Metadatos del modelo | Esquemas de tablas y columnas, definiciones de medidas y otros metadatos del modelo | | Editar reglas de BPA | Crear o modificar reglas de Best Practice Analyzer | -| Leer macros | Lectura de las definiciones de macros | +| Leer macros | Leyendo definiciones de macros | -Cuando el Asistente de IA necesita acceder a un tipo de datos por primera vez, aparece un cuadro de diálogo de consentimiento. Puede elegir la duración de su consentimiento: +Cuando el Asistente de IA necesita acceder a un tipo de datos por primera vez, aparece un cuadro de diálogo de consentimiento. Puedes elegir la duración de tu consentimiento: -| Opción | Ámbito | -| ---------------- | ------------------------------------------------------------------------------------------------------ | -| Esta vez | Solo para esta solicitud | -| Esta sesión | Hasta que se reinicie Tabular Editor | -| Para este modelo | Se conserva en el archivo de opciones de usuario (.tmuo) del modelo | -| Siempre | Preferencia global, que se conserva en todos los modelos y sesiones | +| Opción | Alcance | +| ---------------- | ---------------------------------------------------------------------------------------------------- | +| Esta vez | Solo para una única solicitud | +| Esta sesión | Hasta que se reinicie Tabular Editor | +| Para este modelo | Se guarda en el archivo de opciones de usuario del modelo (.tmuo) | +| Siempre | Preferencia global, conservada en todos los modelos y sesiones | ![Cuadro de diálogo de consentimiento del Asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-generate-consent-dialog.png) ### Gestión de consentimientos -Puedes revisar y restablecer tus opciones de consentimiento en **Herramientas > Preferencias > Asistente de IA > Consentimientos de IA**. Cada categoría de consentimiento muestra su estado actual. Haz clic en **Restablecer** para revocar un consentimiento de "Siempre permitido" y volver a "Preguntar cuando sea necesario". +Puedes revisar y restablecer tus opciones de consentimiento en **Herramientas > Preferencias > Asistente de IA > Consentimientos de IA**. Cada categoría de consentimiento muestra su estado actual. Haz clic en **Restablecer** para revocar un consentimiento de "Siempre permitido" y devolverlo a "Preguntar cuando sea necesario". ![Configuración de consentimiento del Asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-consent-reset.png) @@ -321,13 +321,13 @@ Configura las opciones de visualización y comportamiento del Asistente de IA en ### Visualización del chat -| Preferencia | Predeterminado | Descripción | -| --------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- | -| Mostrar indicador de contexto de selección | true | Muestra el objeto del modelo seleccionado actualmente en el chat | -| Mostrar indicador de instrucciones personalizadas | true | Muestra los indicadores de instrucciones personalizadas encima de las respuestas del asistente | -| Mostrar indicador de búsqueda en la base de conocimientos | true | Muestra el progreso al buscar en la base de conocimientos | +| Preferencia | Predeterminado | Descripción | +| --------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------- | +| Mostrar el indicador de contexto de selección | true | Mostrar en el chat el objeto del modelo seleccionado | +| Mostrar indicador de instrucciones personalizadas | true | Mostrar indicadores de instrucciones personalizadas sobre las respuestas del asistente | +| Mostrar indicador de búsqueda en la base de conocimientos | true | Mostrar el progreso al buscar en la base de conocimientos | -### Compactación de contexto +### Compactación del contexto | Preferencia | Predeterminado | Descripción | | ----------------------------------- | -------------- | --------------------------------------------------------------------------------- | @@ -336,59 +336,59 @@ Configura las opciones de visualización y comportamiento del Asistente de IA en ### Base de conocimientos -| Preferencia | Predeterminado | Descripción | -| ------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------- | -| Buscar actualizaciones de la base de conocimientos al iniciar | true | Buscar automáticamente actualizaciones de la base de conocimientos cuando se inicie Tabular Editor | +| Preferencia | Predeterminado | Descripción | +| ----------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- | +| Comprobar si hay actualizaciones de la base de conocimientos al iniciar | true | Comprobar automáticamente si hay actualizaciones de la base de conocimiento al iniciar Tabular Editor | ### C# Script -| Preferencia | Predeterminado | Descripción | -| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | -| Previsualizar cambios | true | Mostrar el cuadro de diálogo de vista previa de cambios al ejecutar C# Scripts generados por IA desde el chat | +| Preferencia | Predeterminado | Descripción | +| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | +| Vista previa de cambios | true | Mostrar el cuadro de diálogo de vista previa de cambios al ejecutar C# Scripts generados por IA desde el chat | -![Preferencias del asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-preferences.png) +![Preferencias del Asistente de IA](~/content/assets/images/ai-assistant/ai-assistant-preferences.png) ## Uso de tokens -Cada mensaje al Asistente de IA consume tokens de entrada. El coste en tokens de un solo mensaje depende de qué contexto se incluya: +Cada mensaje que envías al Asistente de IA consume tokens de entrada. El coste en tokens de un solo mensaje depende del contexto que se incluya: - **Prompt del sistema e instrucciones personalizadas**: Se envían con cada mensaje. Normalmente, entre 5.000 y 15.000 tokens, según las instrucciones personalizadas que estén activas. -- **Metadatos del modelo**: Cuando el asistente necesita entender tu modelo, recupera los metadatos mediante llamadas a herramientas. Para ajustarse a los límites de tasa del proveedor en modelos grandes, el asistente usa un enfoque de revelación progresiva: primero obtiene un resumen ligero (nombres de tablas y medidas, relaciones); luego busca objetos relevantes por nombre, descripción o expresión DAX, y solo profundiza en los detalles completos de las tablas u objetos específicos que requiera la pregunta. Los resultados de las herramientas que, de otro modo, serían muy grandes se truncan e incluyen indicaciones sobre cómo el asistente puede recuperar los datos restantes. +- **Metadatos del modelo**: Cuando el asistente necesita comprender tu modelo, recupera metadatos mediante llamadas a herramientas. Para mantenerse dentro de los límites de frecuencia del proveedor en modelos grandes, el asistente usa un enfoque de revelación progresiva: primero obtiene un resumen ligero (nombres de tablas y medidas, relaciones); después busca los objetos relevantes por nombre, descripción o expresión DAX; y solo profundiza en los detalles completos de las tablas u objetos concretos que requiera la pregunta. Los resultados de las herramientas que, de otro modo, serían muy grandes se truncan con indicaciones sobre cómo el asistente puede recuperar los datos restantes. ### Contador de tokens -El contador de tokens, en la esquina inferior derecha del área de entrada del chat, muestra el uso acumulado de tokens de la conversación actual, incluidos los tokens de entrada de las idas y vueltas con herramientas. Pasa el cursor sobre el contador para ver el desglose: +El contador de tokens, en la esquina inferior derecha del área de entrada del chat, muestra el uso acumulado de tokens de la conversación actual, incluidos los tokens de entrada de los intercambios con herramientas. Pasa el cursor sobre el contador para ver un desglose: -- **Entrada** — tokens de entrada a precio completo de la conversación, con una sublínea que muestra cuántos de ellos se obtuvieron de la caché de prompts del proveedor -- **Escritura en caché** — tokens escritos en la caché de prompts (según el proveedor) +- **Entrada** — tokens de entrada a precio completo de la conversación, con una sublínea que muestra cuántos de ellos proceden de la caché de prompts del proveedor +- **Escritura en caché** — tokens escritos en la caché de prompts (depende del proveedor) - **Salida** — tokens generados por el modelo -- **Presión de contexto** — porcentaje de la ventana de contexto que está actualmente en uso; también se visualiza mediante la barra deslizante junto al contador +- **Presión de contexto** — porcentaje de la ventana de contexto que está en uso actualmente; también se visualiza en la barra deslizante junto al contador ### Reducir el uso de tokens -Selecciona objetos específicos en el **Explorador TOM** antes de hacer tu pregunta. Cuando hay objetos seleccionados, el asistente limita su contexto a esos objetos en lugar de obtener los metadatos de todo el modelo. Esta es la forma más eficaz de reducir tanto el uso de tokens como el coste de la API. +Selecciona objetos específicos en el **Explorador TOM** antes de hacer tu pregunta. Cuando se seleccionan objetos, el asistente acota su contexto a esos objetos en lugar de recuperar los metadatos de todo el modelo. Esta es la forma más eficaz de reducir tanto el uso de tokens como el costo de la API. Otras formas de reducir el uso de tokens: -- Haz preguntas concretas sobre tablas, medidas o columnas específicas en lugar de preguntas generales sobre todo el modelo. Una instrucción imprecisa como _"Establece carpetas de visualización en todas las medidas"_ obliga al asistente a recuperar metadatos de todo el modelo. Una instrucción específica como _"Establece carpetas de visualización en las medidas que he seleccionado"_ limita el contexto a la selección actual y usa muchos menos tokens -- Inicia nuevas conversaciones al cambiar de tema para evitar acumular historiales de conversación extensos +- Haz preguntas concretas sobre tablas, medidas o columnas específicas en lugar de preguntas generales sobre todo el modelo. Un prompt impreciso como _"Establece carpetas de visualización en todas las medidas"_ obliga al asistente a recuperar metadatos de todo el modelo. Un prompt específico como _"Establecer carpetas de visualización en las medidas que he seleccionado"_ limita el contexto a la selección actual y utiliza muchos menos tokens +- Inicia nuevas conversaciones al cambiar de tema para evitar acumular historiales de conversación largos - Usa un modelo más pequeño o menos costoso para preguntas exploratorias ## Limitaciones -- Requiere una clave de API proporcionada por el usuario. No se incluye ninguna clave de API integrada +- Requiere una clave de API proporcionada por el usuario. No se incluye una clave de API integrada - Las respuestas de la IA dependen del modelo seleccionado y de las capacidades del proveedor - La ventana de contexto máxima es de 200.000 tokens -- El Asistente de IA no sustituye la comprensión de los fundamentos de DAX y del diseño de modelos semánticos +- El Asistente de IA no sustituye el conocimiento de DAX ni los fundamentos del diseño de modelos semánticos - La calidad de las respuestas varía según el proveedor y el modelo seleccionado - El Asistente de IA no puede conectarse a archivos o servicios externos ni buscar en la web - El Asistente de IA no puede añadirse ni actuar como un servidor MCP -- El Asistente de IA no puede conectarse a otro modelo desde el chat. Usa la interfaz de usuario de Tabular Editor para cambiar las conexiones del modelo -- El Asistente de IA no puede administrar las preferencias +- El Asistente de IA no puede conectarse a un modelo diferente desde el chat. Usa la interfaz de usuario de Tabular Editor para cambiar las conexiones del modelo +- El Asistente de IA no puede gestionar las preferencias -## Desactivar el Asistente de IA +## Deshabilitar el Asistente de IA -El Asistente de IA es un componente opcional. Mientras la característica esté en versión preliminar pública, se excluirá de forma predeterminada durante la instalación, pero los usuarios tienen la opción de incluirla. Puedes modificar una instalación existente de Tabular Editor 3 para incluir o excluir el componente del Asistente de IA volviendo a ejecutar el instalador de Tabular Editor 3. Si usas la versión portable de Tabular Editor 3, puedes quitar el componente del Asistente de IA eliminando el archivo `TabularEditor3.AI.dll` del directorio de instalación. +El Asistente de IA es un componente opcional. Mientras la característica esté en versión preliminar pública, se excluirá de forma predeterminada durante la instalación, pero los usuarios pueden optar por incluirla. Puedes modificar una instalación existente de Tabular Editor 3 para incluir o excluir el componente Asistente de IA volviendo a ejecutar el instalador de Tabular Editor 3. Si usas la versión portátil de Tabular Editor 3, puedes quitar el componente del Asistente de IA borrando el archivo `TabularEditor3.AI.dll` del directorio de instalación. > [!NOTE] -> Independientemente de si el componente del Asistente de IA está instalado o no, un administrador del sistema puede desactivar toda la funcionalidad de IA en Tabular Editor 3 especificando la [directiva `DisableAi`](xref:policies). +> Independientemente de si el componente del Asistente de IA esté instalado o no, un administrador del sistema puede deshabilitar toda la funcionalidad de IA en Tabular Editor 3 mediante la [directiva `DisableAi`](xref:policies). diff --git a/localizedContent/es/content/features/code-actions.md b/localizedContent/es/content/features/code-actions.md index e97fef7bd..26081c5d5 100644 --- a/localizedContent/es/content/features/code-actions.md +++ b/localizedContent/es/content/features/code-actions.md @@ -122,7 +122,7 @@ Las acciones de código siguientes aparecerán con puntos verde azulado debajo d | DR011 | [Reescribir con ISBLANK](xref:DR011) | En lugar de comparar una expresión con [`BLANK()`](https://dax.guide/BLANK), usa la función [`ISBLANK`](https://dax.guide/ISBLANK). Ejemplo:
`IF([Sales] = BLANK(), [Budget], [Sales])` -> `IF(ISBLANK([Sales], [Budget], [Sales])` | | DR012 | [Eliminar BLANK innecesario](xref:DR012) | Algunas funciones de DAX, como [`IF`](https://dax.guide/IF) y [`SWITCH`](https://dax.guide/SWITCH), ya devuelven `BLANK()` cuando la condición es falsa, así que no hace falta especificar `BLANK()` explícitamente. Ejemplo:
`IF(a > b, a, BLANK())` -> `IF(a > b, a)` | | DR013 | [Simplificar la lógica negada](xref:DR013) | Cuando se niega una expresión lógica, suele ser más legible reescribirla usando el operador negado. Ejemplo:
`NOT(a = b)` -> `a <> b` | -| DR014 | [Simplificar con IN](xref:DR014) | Reescriba los predicados compuestos (comparaciones de igualdad de una misma expresión combinadas con [`OR`](https://dax.guide/OR) o [`\|\|`](https://dax.guide/op/or/)) con el operador [`IN`](https://dax.guide/IN). Ejemplo:
\`a = 1 \\ | +| DR014 | [Simplificar con IN](xref:DR014) | Reescriba los predicados compuestos (comparaciones de igualdad de una misma expresión combinadas con [`OR`](https://dax.guide/OR) o [`\|\|`](https://dax.guide/op/or/)) con el operador [`IN`](https://dax.guide/IN). Ejemplo:
`a = 1 \|\| a = 2 \|\| a = 100` -> `a IN { 1, 2, 100 }` | ### Reescrituras diff --git a/localizedContent/es/content/features/csharp-scripts.md b/localizedContent/es/content/features/csharp-scripts.md index 5f5dba34d..ae74a88d9 100644 --- a/localizedContent/es/content/features/csharp-scripts.md +++ b/localizedContent/es/content/features/csharp-scripts.md @@ -2,7 +2,7 @@ uid: csharp-scripts title: C# Scripts author: Daniel Otykier -updated: 2026-03-19 +updated: 2026-05-27 applies_to: products: - product: Tabular Editor 2 @@ -15,68 +15,70 @@ applies_to: full: true - edition: Enterprise full: true + - product: Tabular Editor CLI + full: true --- # C# Scripts -Esta es una introducción a las capacidades de C# Scripts de Tabular Editor 3. La información de este documento está sujeta a cambios. Además, no dejes de consultar nuestra biblioteca de scripts @csharp-script-library para ver más ejemplos reales de lo que puedes hacer con las capacidades de scripting de Tabular Editor. +This is an introduction to the C# Scripting capabilities of Tabular Editor 3. Information in this document is subject to change. Also, make sure to check out our script library @csharp-script-library, for some more real-life examples of what you can do with the scripting capabilities of Tabular Editor. -## ¿Por qué scripting en C#? +## Why C# scripting? -El objetivo de la interfaz de usuario de Tabular Editor es facilitar la realización de la mayoría de las tareas habituales al crear modelos tabulares. Por ejemplo, cambiar la carpeta de visualización de varias medidas a la vez es tan simple como seleccionar los objetos en el árbol del explorador y arrastrar y soltar. El menú contextual del árbol del explorador, al hacer clic con el botón derecho, ofrece una forma práctica de realizar muchas de estas tareas, como agregar o quitar objetos de perspectivas, cambiar el nombre de varios objetos, etc. +The goal of the UI of Tabular Editor is to make it easy to perform most tasks commonly needed when building Tabular Models. For example, changing the Display Folder of multiple measures at once is just a matter of selecting the objects in the explorer tree and then dragging and dropping them around. The right-click context menu of the explorer tree provides a convenient way to perform many of these tasks, such as adding/removing objects from perspectives, renaming multiple objects, etc. -Sin embargo, puede haber muchas otras tareas habituales del flujo de trabajo que no se realizan tan fácilmente desde la interfaz de usuario. Por este motivo, Tabular Editor ofrece scripting en C#, que permite a los usuarios avanzados escribir un script con sintaxis de C# para manipular de forma más directa los objetos del modelo tabular cargado. +There may be many other common workflow tasks, which are not as easily performed through the UI however. For this reason, Tabular Editor offers C# scripting, which lets advanced users write a script using C# syntax, to more directly manipulate the objects in the loaded Tabular Model. ## Code Assist -El editor de C# Scripts admite autocompletado y sugerencias de llamada basados en Roslyn y, desde Tabular Editor 3.23.0, el autocompletado admite la coincidencia por subcadenas y por acrónimos de letras mayúsculas. +The C# script editor supports Roslyn-powered completion and call tips and from Tabular Editor 3.23.0, completion supports substring and capital-letters acronym matching. -## Objetos +## Objects -La [API de scripting](xref:api-index) proporciona acceso a dos objetos de nivel superior, `Model` y `Selected`. El primero contiene métodos y propiedades que te permiten manipular todos los objetos del Modelo tabular, mientras que el segundo expone únicamente los objetos que están seleccionados actualmente en el árbol del explorador. +The [scripting API](xref:api-index) provides access to two top-level objects, `Model` and `Selected`. The former contains methods and properties that allow you to manipulate all objects in the Tabular Model, whereas the latter exposes only objects that are currently selected in the explorer tree. -El objeto `Model` es un contenedor de la clase [Microsoft.AnalysisServices.Tabular.Model](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx) y expone un subconjunto de sus propiedades, con algunos métodos y propiedades adicionales para facilitar las operaciones con traducciones, perspectivas y colecciones de objetos. Lo mismo se aplica a cualquier objeto descendiente, como Tabla, medida, Columna, etc., ya que todos tienen su correspondiente objeto envoltorio. Consulta para ver un listado completo de objetos, propiedades y métodos de la biblioteca de envoltorios de Tabular Editor. +The `Model` object is a wrapper of the [Microsoft.AnalysisServices.Tabular.Model](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx) class, exposing a subset of it’s properties, with some additional methods and properties for easier operations on translations, perspectives and object collections. The same applies to any descendant objects, such as Table, Measure, Column, etc. which all have corresponding wrapper objects. Please see for a complete listing of objects, properties and methods in the Tabular Editor wrapper library. -La principal ventaja de trabajar a través de este envoltorio es que todos los cambios se podrán deshacer desde la interfaz de usuario de Tabular Editor. Simplemente pulsa CTRL+Z después de ejecutar un script y verás que todos los cambios realizados por el script se deshacen inmediatamente. Además, el envoltorio proporciona métodos prácticos que convierten muchas tareas habituales en simples líneas de código. A continuación, mostraremos algunos ejemplos. Se da por hecho que el lector ya está algo familiarizado con C# y LINQ, ya que aquí no se tratarán estos aspectos de las capacidades de scripting de Tabular Editor. Los usuarios que no estén familiarizados con C# y LINQ aún deberían poder seguir los ejemplos que se muestran a continuación. +The main advantage of working through this wrapper is, that all changes will be undoable from the Tabular Editor UI. Simply press CTRL+Z after executing a script, and you will see that all changes made by the script are immediately undone. Furthermore, the wrapper provides convenient methods that turn many common tasks into simple one-liners. We will provide some examples below. It is assumed that the reader is already somewhat familiar with C# and LINQ, as these aspects of Tabular Editors scripting capabilities will not be covered here. Users unfamiliar with C# and LINQ should still be able to follow the examples given below. -## Establecer propiedades de objetos +## Setting object properties -Si quieres cambiar una propiedad de un objeto en concreto, obviamente la forma más sencilla de hacerlo es directamente desde la interfaz de usuario. Pero, a modo de ejemplo, veamos cómo podríamos lograr lo mismo mediante un script. +If you want to change a property of one object in particular, obviously the easiest way to do so would be directly through the UI. But as an example, let us see how we could achieve the same thing through scripting. -Supongamos que quieres cambiar la cadena de formato de tu medida [Sales Amount] en la tabla 'FactInternetSales'. Si localizas la medida en el árbol del explorador, puedes simplemente arrastrarla al editor de scripts. A continuación, Tabular Editor generará el siguiente código, que representa esa medida concreta en el Tabular Object Model: +Say you want to change the Format String of your [Sales Amount] measure in the 'FactInternetSales' table. If you locate the measure in the explorer tree, you can simply drag it onto the script editor. Tabular Editor will then generate the following code, which represents this particular measure in the Tabular Object Model: ```csharp Model.Tables["FactInternetSales"].Measures["Sales Amount"] ``` -Añadir un punto (.) adicional después del corchete situado más a la derecha, debería hacer que aparezca el menú de autocompletado, mostrándote qué propiedades y métodos existen en esa medida en concreto. Solo tienes que elegir "FormatString" en el menú, o escribir las primeras letras y pulsar Tab. Luego, escribe un signo igual seguido de "0.0%" (0,0%). Cambiemos también la carpeta de visualización de esta medida. El código final debería verse así: +Adding an extra dot (.) after the right-most bracket, should make the autocomplete menu pop up, showing you which properties and methods exist on this particular measure. Simply choose "FormatString" in the menu, or write the first few letters and hit Tab. Then, enter an equal sign followed by "0.0%". Let us also change the Display Folder of this measure. Your final code should look like this: ```csharp Model.Tables["FactInternetSales"].Measures["Sales Amount"].FormatString = "0.0%"; Model.Tables["FactInternetSales"].Measures["Sales Amount"].DisplayFolder = "New Folder"; ``` -**Nota:** Recuerda poner el punto y coma (;) al final de cada línea. Esto es un requisito de C#. Si lo olvidas, recibirás un mensaje de error de sintaxis al intentar ejecutar el script. +**Note:** Remember to put the semicolon (;) at the end of each line. This is a requirement of C#. If you forget it, you will get a syntax error message when trying to execute the script. -Pulsa F5 o el botón "Play" en la parte superior del editor de scripts para ejecutar el script. Inmediatamente deberías ver que la medida se desplaza por el árbol del explorador, reflejando el cambio en la carpeta de visualización. Si examinas la medida en la cuadrícula de propiedades, también verás que la propiedad Format String ha cambiado en consecuencia. +Hit F5 or the "Play" button above the script editor to execute the script. Immediately, you should see the measure moving around in the explorer tree, reflecting the changed Display Folder. If you examine the measure in the Property Grid, you should also see that the Format String property has changed accordingly. -### Trabajar con varios objetos a la vez +### Working with multiple objects at once -Muchos objetos del modelo de objetos son, en realidad, colecciones de varios objetos. Por ejemplo, cada objeto Table tiene una colección de medidas. El wrapper expone una serie de propiedades y métodos prácticos en estas colecciones, lo que facilita establecer la misma propiedad en varios objetos a la vez. Esto se describe en detalle a continuación. Además, puedes usar todos los métodos de extensión estándar de LINQ para filtrar y explorar los objetos de una colección. +Many objects in the object model, are actually collections of multiple objects. For example, each Table object has a Measures collection. The wrapper exposes a series of convenient properties and methods on these collections, to make it easy to set the same property on multiple objects at once. This is described in detail below. Additionally, you may use all the standard LINQ extension methods to filter and browse the objects of a collection. -A continuación hay unos pocos ejemplos de los métodos de extensión LINQ más utilizados: +Below is a few examples of the most commonly used LINQ extension methods: -- `Collection.First([predicate])` Devuelve el primer objeto de la colección que cumple la condición opcional [predicate]. -- `Collection.Any([predicate])` Devuelve `true` si la colección contiene algún objeto (opcionalmente, que cumpla la condición [predicate]). -- `Collection.Where(predicate)` Devuelve una colección que corresponde a la colección original filtrada según la condición del predicado. -- `Collection.Select(map)` Proyecta cada objeto de la colección en otro objeto según el mapeo especificado. -- `Collection.ForEach(action)` Ejecuta la acción especificada en cada elemento de la colección. +- `Collection.First([predicate])` Returns the first object in the collection satisfying the optional [predicate] condition. +- `Collection.Any([predicate])` Returns true if the collection contains any objects (optionally satisfying the [predicate] condition). +- `Collection.Where(predicate)` Returns a collection that is the original collection filtered by the predicate condition. +- `Collection.Select(map)` Projects each object in the collection into another object according to the specified map. +- `Collection.ForEach(action)` Performs the specified action on each element in the collection. -En los ejemplos anteriores, `predicate` es una expresión lambda que toma un único objeto como entrada y devuelve un valor booleano como salida. Por ejemplo, si `Collection` es una colección de medidas, un `predicate` típico podría ser: +In the above examples, `predicate` is a lambda expression that takes a single object as input, and returns a boolean value as output. For example, if `Collection` is a collection of measures, a typical `predicate` could look like: `m => m.Name.Contains("Reseller")` -Este predicado devolvería true solo si el Nombre de la medida contiene la cadena de caracteres "Reseller". Envuelve la expresión entre llaves y usa la palabra clave `return` si necesitas una lógica más avanzada: +This predicate would return true only if the Name of the measure contains the character string "Reseller". Wrap the expression in curly braces and use the `return` keyword, if you need more advanced logic: ```csharp .Where(obj => { @@ -87,51 +89,51 @@ Este predicado devolvería true solo si el Nombre de la medida contiene la caden }) ``` -Volviendo a los ejemplos anteriores, `map` es una expresión lambda que toma un único objeto como entrada y devuelve un único objeto como salida. `action` es una expresión lambda que toma un único objeto como entrada, pero no devuelve ningún valor. +Going back to the examples above, `map` is a lambda expression that takes a single object as input, and returns any single object as output. `action` is a lambda expression that takes a single object as input, but does not return any value. -## Trabajar con el objeto **Model** +## Working with the **Model** object -Para hacer referencia rápidamente a cualquier objeto en el modelo tabular cargado actualmente, se puede arrastrar y soltar el objeto desde el árbol del explorador al editor de C# Script: +To quickly reference any object in the currently loaded Tabular Model, you can drag and drop the object from the explorer tree and into the C# script editor: -![Arrastrando y soltando un objeto en el editor de scripts de C#](~/content/assets/images/drag-object-to-script.gif) +![Dragging and dropping an object into the C# script editor](~/content/assets/images/drag-object-to-script.gif) -Consulta la [documentación de TOM](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx) para obtener una visión general de las propiedades disponibles en el Modelo y en sus objetos descendientes. Además, consulta para obtener un listado completo de las propiedades y los métodos expuestos por el objeto envoltorio. +Please refer to the [TOM documentation](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx) for an overview of which properties exist on the Model and its descendant objects. Additionally, refer to for a complete listing of the properties and methods exposed by the wrapper object. -## Trabajando con el objeto **Selected** +## Working with the **Selected** object -Poder hacer referencia de forma explícita a cualquier objeto del Modelo tabular viene muy bien para algunos flujos de trabajo, pero a veces quieres elegir objetos concretos del árbol del explorador y luego ejecutar un script solo sobre los objetos seleccionados. Aquí es donde el objeto `Selected` resulta útil. +Being able to explicitly refer to any object in the Tabular Model is great for some workflows, but sometimes you want to cherry pick objects from the explorer tree, and then execute a script against only the selected objects. This is where the `Selected` object comes in handy. -El objeto `Selected` ofrece una serie de propiedades que facilitan identificar qué hay seleccionado en este momento, además de limitar la selección a objetos de un tipo concreto. Al explorar con carpetas de visualización, si se seleccionan una o varias carpetas en el árbol del explorador, todos sus elementos secundarios también se consideran seleccionados. -Para selecciones únicas, usa el nombre en singular del tipo de objeto al que quieres acceder. Por ejemplo, +The `Selected` object provides a range of properties that make it easy to identify what is currently selected, as well as limiting the selection to objects of a particular type. When browsing with Display Folders, and one or more folders are selected in the explorer tree, all their child items are considered to be selected as well. +For single selections, use the singular name for the type of object you want to access. For example, `Selected.Hierarchy` -hace referencia a la jerarquía seleccionada actualmente en el árbol, siempre que se haya seleccionado una y solo una jerarquía. Usa el nombre del tipo en plural si quieres trabajar con selecciones múltiples: +refers to the currently selected hierarchy in the tree, provided that one and only one hierarchy is selected. Use the plural type name, in case you want to work with multiselections: `Selected.Hierarchies` -Todas las propiedades que existen en el objeto en singular también existen en su forma plural, con algunas excepciones. Esto significa que puedes establecer el valor de estas propiedades para varios objetos a la vez, con una sola línea de código y sin usar los métodos de extensión LINQ mencionados anteriormente. Por ejemplo, imagina que quieres mover todas las medidas seleccionadas actualmente a una nueva carpeta de visualización llamada "Test": +All properties that exist on the singular object, also exist on its plural form, with a few exceptions. This means that you can set the value of these properties for multiple objects at once, with just one line of code and without using the LINQ extension methods mentioned above. For example, say you wanted to move all currently selected measures into a new Display Folder called "Test": `Selected.Measures.DisplayFolder = "Test";` -Si no hay medidas seleccionadas actualmente en el árbol, el código anterior no hace nada y no se genera ningún error. De lo contrario, la propiedad DisplayFolder se establecerá en "Test" en todas las medidas seleccionadas (incluso en las medidas que se encuentren dentro de carpetas, ya que el objeto `Selected` también incluye los objetos de las carpetas seleccionadas). Si usas la forma singular `Measure` en lugar de `Measures`, obtendrás un error a menos que la selección actual contenga exactamente una medida. +If no measures are currently selected in the tree, the above code does nothing, and no error is raised. Otherwise, the DisplayFolder property will be set to "Test" on all selected measures (even measures residing within folders, as the `Selected` object also includes objects in selected folders). If you use the singular form `Measure` instead of `Measures`, you will get an error unless the current selection contains exactly one measure. -Aunque no podemos establecer la propiedad `Name` de varios objetos a la vez, seguimos teniendo algunas opciones disponibles. Si solo queremos reemplazar todas las apariciones de una cadena de caracteres por otra, podemos usar el método "Rename" incluido, así: +Although we cannot set the Name property of multiple objects at once, we still have some options available. If we just want to replace all occurrences of some character string with another, we can use the provided "Rename" method, like so: ```csharp Selected.Measures .Rename("Amount", "Value"); ``` -Esto reemplazaría cualquier aparición de la palabra "Amount" por la palabra "Value" en los nombres de todas las medidas seleccionadas actualmente. -Como alternativa, podemos usar el método LINQ ForEach(), tal como se describió antes, para incluir lógica más avanzada: +This would replace any occurrence of the word "Amount" with the word "Value" in the names of all currently selected measures. +Alternatively, we may use the LINQ ForEach()-method, as described above, to include more advanced logic: ```csharp Selected.Measures .ForEach(m => if(m.Name.Contains("Reseller")) m.Name += " DEPRECATED"); ``` -Este ejemplo añadirá el texto " DEPRECATED" al final de los nombres de todas las medidas seleccionadas que contengan la palabra "Reseller". Como alternativa, podríamos usar el método de extensión LINQ `Where()` para filtrar la colección antes de aplicar la operación `ForEach()`, lo que daría exactamente el mismo resultado: +This example will append the text " DEPRECATED" to the names of all selected measures where the names contain the word "Reseller". Alternatively, we could use the LINQ extension method `Where()` to filter the collection before applying the `ForEach()` operation, which would yield exactly the same result: ```csharp Selected.Measures @@ -139,127 +141,127 @@ Selected.Measures .ForEach(m => m.Name += " DEPRECATED"); ``` -### Lista completa de los accesores de `Selected` - -La siguiente tabla enumera todos los accesores singulares y plurales disponibles en el objeto `Selected`. Los accesores singulares lanzan una `SelectionException` si la selección actual no contiene exactamente un objeto de ese tipo. Los accesores plurales devuelven una colección vacía si no se selecciona ningún objeto de ese tipo. - -| Singular | Plural | Tipo de objeto | -| ----------------------------------- | ------------------------------------ | ---------------------------------- | -| `Selected.Measure` | `Selected.Measures` | Medidas | -| `Selected.Column` | `Selected.Columns` | Todos los tipos de columna | -| `Selected.DataColumn` | `Selected.DataColumns` | Columnas de datos | -| `Selected.CalculatedColumn` | `Selected.CalculatedColumns` | Columnas calculadas | -| `Selected.CalculatedTableColumn` | `Selected.CalculatedTableColumns` | Columnas de tablas calculadas | -| `Selected.Hierarchy` | `Selected.Hierarchies` | Jerarquías | -| `Selected.Level` | `Selected.Levels` | Niveles de jerarquía | -| `Selected.Table` | `Selected.Tables` | Tablas | -| `Selected.CalculatedTable` | `Selected.CalculatedTables` | Tablas calculadas | -| `Selected.Partición` | `Selected.Particiones` | Particiones | -| `Selected.rol` | `Selected.Roles` | Roles del modelo | -| `Selected.TablePermission` | `Selected.TablePermissions` | Permisos de tabla | -| `Selected.KPI` | `Selected.KPIs` | KPI | -| `Selected.Calendar` | `Selected.Calendars` | Calendarios | -| `Selected.CalculationItem` | `Selected.CalculationItems` | Elementos de cálculo | -| `Selected.Function` | `Selected.Functions` | Funciones definidas por el usuario | -| `Selected.DataSource` | `Selected.DataSources` | Fuentes de datos | -| `Selected.SingleColumnRelationship` | `Selected.SingleColumnRelationships` | Relaciones | -| `Selected.Perspective` | `Selected.Perspectives` | Perspectivas | -| `Selected.Culture` | `Selected.Cultures` | Traducciones | +### Complete list of Selected accessors + +The following table lists all available singular and plural accessors on the `Selected` object. Singular accessors throw a `SelectionException` if the current selection does not contain exactly one object of that type. Plural accessors return an empty collection if no objects of that type are selected. + +| Singular | Plural | Object Type | +| ----------------------------------- | ------------------------------------ | ------------------------ | +| `Selected.Measure` | `Selected.Measures` | Measures | +| `Selected.Column` | `Selected.Columns` | All column types | +| `Selected.DataColumn` | `Selected.DataColumns` | Data columns | +| `Selected.CalculatedColumn` | `Selected.CalculatedColumns` | Calculated columns | +| `Selected.CalculatedTableColumn` | `Selected.CalculatedTableColumns` | Calculated table columns | +| `Selected.Hierarchy` | `Selected.Hierarchies` | Hierarchies | +| `Selected.Level` | `Selected.Levels` | Hierarchy levels | +| `Selected.Table` | `Selected.Tables` | Tables | +| `Selected.CalculatedTable` | `Selected.CalculatedTables` | Calculated tables | +| `Selected.Partition` | `Selected.Partitions` | Partitions | +| `Selected.Role` | `Selected.Roles` | Model roles | +| `Selected.TablePermission` | `Selected.TablePermissions` | Table permissions | +| `Selected.KPI` | `Selected.KPIs` | KPIs | +| `Selected.Calendar` | `Selected.Calendars` | Calendars | +| `Selected.CalculationItem` | `Selected.CalculationItems` | Calculation items | +| `Selected.Function` | `Selected.Functions` | User-defined functions | +| `Selected.DataSource` | `Selected.DataSources` | Data sources | +| `Selected.SingleColumnRelationship` | `Selected.SingleColumnRelationships` | Relationships | +| `Selected.Perspective` | `Selected.Perspectives` | Perspectives | +| `Selected.Culture` | `Selected.Cultures` | Translations | > [!NOTE] -> Los accesores de Rol, KPI, Calendar, CalculationItem, TablePermission, Function, DataSource, SingleColumnRelationship, CalculatedColumn, CalculatedTableColumn, DataColumn, CalculatedTable y Partición se agregaron en Tabular Editor 3.26.0. +> The accessors for Role, KPI, Calendar, CalculationItem, TablePermission, Function, DataSource, SingleColumnRelationship, CalculatedColumn, CalculatedTableColumn, DataColumn, CalculatedTable and Partition were added in Tabular Editor 3.26.0. -## Métodos auxiliares +## Helper methods -Tabular Editor proporciona un conjunto de métodos auxiliares especiales para facilitar la realización de determinadas tareas de scripting. Ten en cuenta que algunos de ellos pueden invocarse como métodos de extensión. Por ejemplo, `object.Output();` y `Output(object);` son equivalentes. +Tabular Editor provides a set of special helper methods to make certain script tasks easier to achieve. Note that some of these may be invoked as extension methods. For example, `object.Output();` and `Output(object);` are equivalent. -- `void Output(object value)` - detiene la ejecución del script y muestra información sobre el objeto proporcionado. Cuando el script se ejecuta como parte de una ejecución desde la línea de comandos, se escribirá en la consola una representación en cadena del objeto. -- `void SaveFile(string filePath, string content)` - forma práctica de guardar datos de texto en un archivo. -- `string ReadFile(string filePath)` - forma práctica de cargar datos de texto desde un archivo. -- `string ExportProperties(IEnumerable objects, string properties)` - forma práctica de exportar un conjunto de propiedades de varios objetos como una cadena TSV. -- `void ImportProperties(string tsvData)` - forma práctica de cargar propiedades en varios objetos desde una cadena TSV. -- `void CustomAction(string name)` - invoca una macro por su nombre. -- `void CustomAction(this IEnumerable objects, string name)` - invoca una macro en los objetos especificados. -- `string ConvertDax(string dax, bool useSemicolons)` - convierte una expresión DAX entre configuraciones regionales de EE. UU./Reino Unido y configuraciones regionales distintas de EE. UU./Reino Unido. Si `useSemicolons` es true (valor predeterminado), la cadena `dax` se convierte del formato nativo de EE. UU./Reino Unido al formato no EE. Es decir, las comas (separadores de lista) se convertirán en punto y coma, y los puntos (separadores decimales) se convertirán en comas. Y viceversa si `useSemicolons` se establece en false. -- `void FormatDax(this IEnumerable objects, bool shortFormat, bool? skipSpace)` - da formato a las expresiones DAX en todos los objetos de la colección proporcionada -- `void FormatDax(this IDaxDependantObject obj)` - pone un objeto en cola para dar formato a la expresión DAX cuando finalice la ejecución del script, o cuando se llame al método `CallDaxFormatter`. -- `void CallDaxFormatter(bool shortFormat, bool? skipSpace)` - da formato a todas las expresiones DAX de los objetos puestos en cola hasta el momento -- `void Info(string)` - Escribe un mensaje informativo en la consola (solo cuando el script se ejecuta como parte de una ejecución en la línea de comandos). -- `void Warning(string)` - Escribe un mensaje de advertencia en la consola (solo cuando el script se ejecuta como parte de una ejecución en la línea de comandos). -- `void Error(string)` - Escribe un mensaje de error en la consola (solo cuando el script se ejecuta como parte de una ejecución en la línea de comandos). -- `T SelectObject(this IEnumerable objects, T preselect = null, string label = "Select object") where T: TabularNamedObject` - Muestra un cuadro de diálogo para que el usuario seleccione uno de los objetos especificados. Si el usuario cancela el cuadro de diálogo, este método devuelve `null`. -- `void CollectVertiPaqAnalyzerStats()` - Si Tabular Editor está conectado a una instancia de Analysis Services, ejecuta el recopilador de estadísticas del Analizador VertiPaq. -- `long GetCardinality(this Column column)` - Si las estadísticas del Analizador VertiPaq están disponibles para el modelo actual, este método devuelve la cardinalidad de la columna especificada. +- `void Output(object value)` - halts script execution and displays information about the provided object. When the script is running as part of a command line execution, this will write a string representation of the object to the console. +- `void SaveFile(string filePath, string content)` - convenient way to save text data to a file. +- `string ReadFile(string filePath)` - convenient way to load text data from a file. +- `string ExportProperties(IEnumerable objects, string properties)` - convenient way to export a set of properties from multiple objects as a TSV string. +- `void ImportProperties(string tsvData)` - convenient way to load properties into multiple objects from a TSV string. +- `void CustomAction(string name)` - invoke a macro by name. +- `void CustomAction(this IEnumerable objects, string name)` - invoke a macro on the specified objects. +- `string ConvertDax(string dax, bool useSemicolons)` - converts a DAX expression between US/UK and non-US/UK locales. If `useSemicolons` is true (default) the `dax` string is converted from the native US/UK format to non-US/UK. That is, commas (list separators) will be converted to semicolons and periods (decimal separators) will be converted to commas. Vice versa if `useSemicolons` is set to false. +- `void FormatDax(this IEnumerable objects, bool shortFormat, bool? skipSpace)` - formats DAX expressions on all objects in the provided collection +- `void FormatDax(this IDaxDependantObject obj)` - queues an object for DAX expression formatting when script execution is complete, or when the `CallDaxFormatter` method is called. +- `void CallDaxFormatter(bool shortFormat, bool? skipSpace)` - formats all DAX expressions on objects enqueued so far +- `void Info(string)` - Writes an informational message to the console (only when the script is executed as part of a command line execution). +- `void Warning(string)` - Writes a warning message to the console (only when the script is executed as part of a command line execution). +- `void Error(string)` - Writes an error message to the console (only when the script is executed as part of a command line execution). +- `T SelectObject(this IEnumerable objects, T preselect = null, string label = "Select object") where T: TabularNamedObject` - Displays a dialog to the user prompting to select one of the objects specified. If the user cancels the dialog, this method returns null. +- `void CollectVertiPaqAnalyzerStats()` - If Tabular Editor is connected to an instance of Analysis Services, this runs the VertiPaq Analyzer statistics collector. +- `long GetCardinality(this Column column)` - If VertiPaq Analyzer statistics are available for the current model, this method returns the cardinality of the specified column. -Para ver la lista completa de métodos auxiliares disponibles y su sintaxis, consulte @script-helper-methods. +For a full list of available helper methods and their syntax, view @script-helper-methods. -### Depuración de scripts +### Debugging scripts -Como se mencionó anteriormente, puede usar el método `Output(object);` para pausar la ejecución del script y abrir un cuadro de diálogo con información sobre el objeto que se ha pasado. También puede usar este método como método de extensión, invocándolo como `object.Output();`. El script se reanuda cuando se cierra el cuadro de diálogo. +As mentioned above, you can use the `Output(object);` method to pause script execution, and open a dialog box with information about the passed object. You can also use this method as an extension method, invoking it as `object.Output();`. The script is resumed when the dialog is closed. -El cuadro de diálogo aparecerá de una de estas cuatro maneras, según el tipo de objeto que se esté enviando a la salida: +The dialog will appear in one of four different ways, depending on the kind of object being output: -- Los objetos singulares (como strings, ints y DateTimes, excepto cualquier objeto que derive de TabularNamedObject) se mostrarán como un cuadro de diálogo de mensaje simple, invocando el método `.ToString()` sobre el objeto: +- Singular objects (such as strings, ints and DateTimes, except any object that derives from TabularNamedObject) will be displayed as a simple message dialog, by invoking the `.ToString()` method on the object: ![C-sharp Output](~/content/assets/images/c-sharp-script-output-function.png) -- Los TabularNamedObjects singulares (como Tablas, Medidas o cualquier otro TOM NamedMetadataObject disponible en Tabular Editor) se mostrarán en una cuadrícula de propiedades, de forma similar a cuando se ha seleccionado un objeto en el Explorador de árboles. Las propiedades del objeto se pueden editar en la cuadrícula, pero tenga en cuenta que, si se encuentra un error más adelante durante la ejecución del script, la edición se deshará automáticamente si "Auto-Rollback" está habilitado: +- Singular TabularNamedObjects (such as Tables, Measures or any other TOM NamedMetadataObject available in Tabular Editor) will be shown in a Property Grid, similar to when an object has been selected in the Tree Explorer. Properties on the object may be edited in the grid, but note that if an error is encountered at a later point in the script execution, the edit will be automatically undone, if "Auto-Rollback" is enabled: ![C-sharp Output](~/content/assets/images/c-sharp-script-auto-rollback.png) -- Cualquier IEnumerable de objetos (excepto TabularNamedObjects) se mostrará en una lista, donde cada elemento de la lista muestra el valor `.ToString()` y el tipo del objeto dentro del IEnumerable: +- Any IEnumerable of objects (except TabularNamedObjects) will be displayed in a list, where each list item shows the `.ToString()` value and type of the object in the IEnumerable: ![C-sharp Output](~/content/assets/images/c-sharp-script-output-to-string-function.png) -- Cualquier IEnumerable de TabularNamedObjects hará que el cuadro de diálogo muestre una lista de objetos a la izquierda y una cuadrícula de propiedades a la derecha. La cuadrícula de propiedades se rellenará a partir del objeto seleccionado en la lista, y las propiedades se podrán editar igual que cuando se envía a la salida un único TabularNamedObject: +- Any IEnumerable of TabularNamedObjects will cause the dialog to display a list of the objects on the left, and a Property Grid on the right. The Property Grid will be populated from whatever object is selected in the list, and properties may be edited just as when a single TabularNamedObject is being output: ![C-sharp Output](~/content/assets/images/c-sharp-script-output-function-enumerated.png) -Puede marcar la casilla "No mostrar más salidas" en la esquina inferior izquierda para evitar que el script se detenga en futuras invocaciones de `.Output()`. +You can tick the "Don't show more outputs" checkbox at the lower left-hand corner, to prevent the script from halting on any further `.Output()` invocations. -## Ejecutar C# Scripts con vista previa +## Run C# Scripts with Preview -La acción **Ejecutar con vista previa** te permite revisar todos los cambios de metadatos del modelo realizados por un C# Script antes de confirmarlos. Esto resulta útil al ejecutar scripts desconocidos o al realizar modificaciones masivas. +The **Run with preview** action lets you review all model metadata changes made by a C# script before committing them. This is useful when running unfamiliar scripts or performing bulk modifications. -Para usar esta función, haz clic en **Script > Ejecutar con vista previa** en la barra de herramientas o en el menú. El flujo de trabajo es el siguiente: +To use this feature, click **Script > Run with preview** in the toolbar or menu. The workflow is: -1. Tabular Editor toma una instantánea de los metadatos del modelo antes de la ejecución -2. El script se ejecuta hasta completarse -3. Tabular Editor compara el estado actual de los metadatos del modelo con la instantánea tomada antes de la ejecución -4. Si se detectan cambios, aparecerá un cuadro de diálogo de vista previa que muestra, lado a lado, una comparación jerárquica de las diferencias del modelo (antes y después) -5. Los cambios se codifican por colores: verde para los objetos agregados, rojo para los eliminados y naranja para las propiedades modificadas -6. Usa la casilla **Mostrar solo cambios** para ocultar los elementos sin cambios y centrarte en lo que modificó el script -7. Haz clic en **OK** para aceptar los cambios, o en **Revert** para deshacer todos los cambios +1. Tabular Editor takes a snapshot of the model metadata before execution +2. The script runs to completion +3. Tabular Editor compares the current model metadata state to the snapshot taken before execution +4. If changes are detected, a preview dialog appears showing a side-by-side hierarchical diff of the model (before and after) +5. Changes are color-coded: green for added objects, red for deleted and orange for modified properties +6. Use the **Show changes only** checkbox to hide unchanged items and focus on what the script changed +7. Click **OK** to accept the changes, or **Revert** to undo all changes -![Vista previa del script: cambios en el modelo](~/content/assets/images/c-sharp-script-preview-changes.png) +![Script Preview - Model Changes](~/content/assets/images/c-sharp-script-preview-changes.png) -Si el script falla (error de compilación o en tiempo de ejecución), todos los cambios de metadatos del modelo se revierten automáticamente y no se muestra ningún cuadro de diálogo de vista previa. Si el script se ejecuta correctamente pero no realiza ningún cambio detectable en los metadatos, se muestran mensajes informativos en su lugar. +If the script fails (compilation or runtime error), all model metadata changes are automatically rolled back and no preview dialog is shown. If the script succeeds but makes no detectable metadata changes, an informational message is displayed instead. -Todos los cambios de metadatos del modelo derivados de la ejecución de un script se agrupan en una única transacción de deshacer. Incluso después de aceptar los cambios en el cuadro de diálogo de vista previa, aún puede deshacer toda la operación con **Ctrl+Z**. +All model metadata changes from a script execution are wrapped in a single undo transaction. Even after accepting changes through the preview dialog, you can still undo the entire operation with **Ctrl+Z**. > [!IMPORTANT] -> Las funciones de vista previa y deshacer solo se aplican a los cambios de metadatos del modelo. Si un script realiza operaciones externas, como escribir en archivos, bases de datos o realizar solicitudes web, esas operaciones se ejecutan de inmediato y no se pueden revertir. El cuadro de diálogo de vista previa no intenta analizar el código del script; funciona comparando el estado de los metadatos del modelo antes y después de la ejecución. +> The preview and undo features only apply to model metadata changes. If a script performs external operations such as writing to files, databases or making web requests, those operations are executed immediately and cannot be reverted. The preview dialog does not attempt to analyze the script code — it works by comparing the model metadata state before and after execution. > [!TIP] -> El [Asistente de IA](xref:ai-assistant) muestra automáticamente el cuadro de diálogo de vista previa de cambios cuando ejecuta C# Script desde el chat, de modo que siempre puede revisar los cambios del modelo generados por la IA antes de que se apliquen. +> The [AI Assistant](xref:ai-assistant) shows the preview changes dialog automatically when you execute C# scripts from the chat, so you always get a chance to review AI-generated model changes before they are applied. -## Referencias de .NET +## .NET references -Puede usar la palabra clave `using` para acortar nombres de clases, etc., igual que en el código fuente normal de C#. Además, puede incluir ensamblados externos utilizando la sintaxis `#r ""`, similar a los scripts .csx usados en Azure Functions. +You can use the `using` keyword to shorten class names, etc. just like in regular C# source code. In addition, you can include external assemblies by using the syntax `#r ""` similar to .csx scripts used in Azure Functions. -Por ejemplo, el siguiente script ahora funcionará como se espera: +For example, the following script will now work as expected: ```csharp -// Las referencias de ensamblados deben estar al principio del archivo: +// Assembly references must be at the very top of the file: #r "System.IO.Compression" -// Las palabras clave using deben ir antes que cualquier otra instrucción: +// Using keywords must come before any other statements: using System.IO.Compression; using System.IO; var xyz = 123; -// Las instrucciones using siguen funcionando como deben: +// Using statements still work the way they're supposed to: using(var data = new MemoryStream()) using(var zip = new ZipArchive(data, ZipArchiveMode.Create)) { @@ -267,7 +269,7 @@ using(var zip = new ZipArchive(data, ZipArchiveMode.Create)) } ``` -De forma predeterminada, Tabular Editor aplica las siguientes directivas `using` (aunque no se especifiquen en el script) para facilitar las tareas habituales: +By default, Tabular Editor applies the following `using` keyword (even though they are not specified in the script), to make common tasks easier: ```csharp using System; @@ -279,7 +281,7 @@ using TabularEditor.TOMWrapper.Utils; using TabularEditor.UI; ``` -Además, los siguientes ensamblados de .NET Framework se cargan de forma predeterminada: +In addition, the following .NET Framework assemblies are loaded by default: - System.Dll - System.Core.Dll @@ -293,13 +295,13 @@ Además, los siguientes ensamblados de .NET Framework se cargan de forma predete -## Acceso a variables de entorno +## Accessing Environment Variables -Al ejecutar scripts de C# mediante la CLI de Tabular Editor (especialmente en canalizaciones de CI/CD), puedes pasar parámetros a tus scripts usando variables de entorno. Este es el enfoque recomendado, ya que los C# Scripts ejecutados por Tabular Editor CLI no admiten argumentos tradicionales de línea de comandos. +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. -### Lectura de variables de entorno +### Reading Environment Variables -Usa el método `Environment.GetEnvironmentVariable()` para leer variables de entorno en tu script: +Use the `Environment.GetEnvironmentVariable()` method to read environment variables in your script: ```csharp // Read environment variables @@ -320,11 +322,11 @@ foreach(var dataSource in Model.DataSources.OfType()) Info($"Updated connection strings for {environment} environment"); ``` -### Integración con Azure DevOps +### Azure DevOps Integration -Las variables de entorno se integran sin problemas con las canalizaciones de Azure DevOps, ya que todas las variables de canalización están disponibles automáticamente como variables de entorno de forma predeterminada. +Environment variables integrate seamlessly with Azure DevOps pipelines, as all pipeline variables are automatically available as environment variables by default. -**Ejemplo de canalización YAML de Azure DevOps:** +**Example Azure DevOps YAML Pipeline:** ```yaml variables: @@ -343,60 +345,69 @@ steps: TabularEditor.exe "Model.bim" -S "DeploymentScript.csx" -D "$(targetServer)" "$(targetDatabase)" -O -V -E -W ``` -En este ejemplo, el script `DeploymentScript.csx` puede acceder a `SERVER_NAME` y `DATABASE_NAME` mediante `Environment.GetEnvironmentVariable()`. +In this example, the script `DeploymentScript.csx` can access `SERVER_NAME` and `DATABASE_NAME` using `Environment.GetEnvironmentVariable()`. -### Casos de uso comunes +### Common Use Cases -Las variables de entorno son especialmente útiles para: +Environment variables are particularly useful for: -- **Cadenas de conexión dinámicas**: Actualiza las conexiones a los orígenes de datos según el entorno de implementación (Dev, UAT, Producción) -- **Lógica condicional**: Aplica transformaciones distintas según el entorno de destino -- **Configuración de implementación**: Controla qué objetos se implementan o se modifican según los parámetros -- **Compatibilidad con varios entornos**: Usa el mismo script en distintos entornos con valores diferentes +- **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 -**Ejemplo: modificaciones específicas por entorno:** +**Example - Environment-specific modifications:** ```csharp var environment = Environment.GetEnvironmentVariable("DEPLOY_ENV") ?? "Development"; var refreshPolicy = Environment.GetEnvironmentVariable("ENABLE_REFRESH_POLICY") == "true"; -// Aplica configuración específica por entorno +// Apply environment-specific settings foreach(var table in Model.Tables) { if(environment == "Production" && !refreshPolicy) { - // Deshabilita las políticas de actualización incremental en producción si se especifica + // Disable incremental refresh policies in production if specified table.EnableRefreshPolicy = false; } } -Info($"Modelo configurado para el entorno {environment}"); +Info($"Configured model for {environment} environment"); ``` -## Compatibilidad +## Compatibility -Las API de scripting de Tabular Editor 2 y Tabular Editor 3 son en gran medida compatibles. Sin embargo, en algunos casos conviene compilar el código condicionalmente en función de la versión que estés usando. Para ello, puedes usar directivas de preprocesador, que se introdujeron en Tabular Editor 3.10.0. +The scripting APIs for Tabular Editor 2, Tabular Editor 3 (Desktop), and the Tabular Editor CLI are mostly compatible, but there are cases where you want to conditionally compile code depending on which host is running. The CLI host defines a `TECLI` preprocessor symbol; TE3 Desktop defines `TE3` (and version-bracketed symbols like `TE3_3_15_OR_GREATER` for the active minor); TE2 defines neither. Preprocessor directives were introduced in Tabular Editor 3.10.0. Use them to write portable scripts: ```csharp -#if TE3 - // This code will only be compiled when the script is running in TE3 (version 3.10.0 or newer). - Info("Hello from TE3!"); +#if TECLI + // CLI host - no UI APIs available + Info($"Running under the CLI on {Environment.OSVersion.Platform}"); +#elif TE3 + // TE3 Desktop - UI APIs are available + ShowMessage("Hello from TE3"); #else - // This code will be compiled in all other cases. - Info("Hello from TE2!"); + // TE2 (legacy) - neither TECLI nor TE3 is defined + Info("Hello from TE2"); +#endif + +#if TE3_3_15_OR_GREATER + // Gated on a specific TE3 minor version #endif ``` -Si necesitas conocer la versión exacta de Tabular Editor en tiempo de ejecución del script, puedes inspeccionar la versión del ensamblado: +One CLI-specific caveat: the TE3-Desktop UI helpers `SelectMeasure()`, `SelectTable()`, `SelectColumn()`, `SelectObject()`, and `SelectObjects()` throw `NotSupportedException` under `te script` since the CLI has no UI to pop up. Wrap such calls in `#if TE3` (or `try/catch`) when sharing scripts across hosts. + +If you need to know the exact version of Tabular Editor at script runtime, you can inspect the assembly version: ```csharp var currentVersion = typeof(Model).Assembly.GetName().Version; Info(currentVersion.ToString()); ``` -La versión pública del producto (por ejemplo, "2.20.2" o "3.10.1") se puede obtener con este código: +The public product version (for example, "2.20.2" or "3.10.1") can be found using this code: ```csharp using System.Diagnostics; @@ -405,18 +416,18 @@ var productVersion = FileVersionInfo.GetVersionInfo(Selected.GetType().Assembly. productVersion.Output(); // productVersion is a string ("2.20.2" or "3.10.1", for example) ``` -Si solo quieres el número de versión principal (como entero), usa: +If you just want the major version number (as an integer), use: ```csharp var majorVersion = Selected.GetType().Assembly.GetName().Version.Major; majorVersion.Output(); // majorVersion is an integer (2 or 3) ``` -## Problemas y limitaciones conocidos +## Known issues and limitations -- Algunas operaciones en los scripts pueden hacer que la aplicación Tabular Editor 3 se bloquee o deje de responder, debido a la forma en que se ejecutan los scripts. Por ejemplo, un script con un bucle infinito (`while(true) {}`) hará que la aplicación se quede colgada. Si esto ocurre, tendrás que finalizar el proceso de Tabular Editor desde el Administrador de tareas de Windows. +- Certain script operations may cause the Tabular Editor 3 application to crash or become unresponsive, due to the way scripts are executed. For example, a script with an infinite loop (`while(true) {}`) will cause the application to hang. If this happens, you will have to end the Tabular Editor process through the Windows Task Manager. -Si tienes pensado guardar el script como una [macro](xref:creating-macros), ten en cuenta las siguientes limitaciones: +If you intend to save the script as a [macro](xref:creating-macros), please be aware of the following limitations: -- Si el cuerpo del script contiene métodos locales con modificadores de acceso (`public`, `static`, etc.), el script no se puede guardar como una macro. Elimina los modificadores de acceso o, en su lugar, mueve el método a una clase. -- Actualmente, las macros no admiten la palabra clave `await` si se usa en el cuerpo del script. Si el cuerpo del script llama a métodos asíncronos, debes usar `MyAsyncMethod.Wait()` o `MyAsyncMethod.Result` en lugar de `await MyAsyncMethod()`. No hay problema en usar `await` en métodos `async` definidos en otra parte del script. \ No newline at end of file +- If the script body contains local methods with access modifiers (`public`, `static`, etc.), the script cannot be saved as a macro. Remove the access modifiers, or move the method into a class instead. +- Macros currently do not support the `await` keyword, if used in the script body. If your script body calls into asynchronous methods, you should use `MyAsyncMethod.Wait()` or `MyAsyncMethod.Result` instead of `await MyAsyncMethod()`. It is fine to use `await` in `async` methods that are defined elsewhere in the script. \ No newline at end of file diff --git a/localizedContent/es/content/features/dax-package-manager.md b/localizedContent/es/content/features/dax-package-manager.md index 4efbc47b6..e3b63a10e 100644 --- a/localizedContent/es/content/features/dax-package-manager.md +++ b/localizedContent/es/content/features/dax-package-manager.md @@ -1,6 +1,6 @@ --- uid: dax-package-manager -title: Administrador de paquetes de DAX +title: Administrador de paquete DAX author: Daniel Otykier updated: 2025-11-03 applies_to: @@ -17,48 +17,48 @@ applies_to: full: true --- -# Administrador de paquetes de DAX +# Administrador de paquetes DAX -## Descripción general +## Información general -El **Administrador de paquetes de DAX** (DPM) de Tabular Editor permite a los usuarios descubrir, instalar, actualizar y administrar bibliotecas de [funciones DAX definidas por el usuario (UDF)](xref:udfs) (llamadas paquetes de DAX), directamente en la aplicación. -Estas bibliotecas amplían sus capacidades de DAX con funciones reutilizables, lo que facilita crear modelos semánticos de Power BI coherentes y fáciles de mantener. +El **Administrador de paquetes DAX** (DPM) en Tabular Editor permite a los usuarios descubrir, instalar, actualizar y administrar fácilmente bibliotecas de [funciones DAX definidas por el usuario (UDF)](xref:udfs) (denominadas paquetes DAX), directamente dentro de la aplicación. +Estas bibliotecas amplían tus capacidades de DAX con funciones reutilizables, lo que facilita la creación de modelos semánticos de Power BI coherentes y fáciles de mantener. -Como su nombre indica, esta función actúa como un administrador de paquetes, de forma similar a cómo NuGet o npm gestionan bibliotecas de código para los desarrolladores. La fuente de los paquetes de DAX es https://daxlib.org, que es un proyecto de código abierto y sin ánimo de lucro de [SQLBI](https://sqlbi.com). +Como su nombre indica, esta característica actúa como un administrador de paquetes, similar a cómo NuGet o npm gestionan bibliotecas de código para los desarrolladores. La fuente de los paquetes DAX es https://daxlib.org, un proyecto de código abierto y sin ánimo de lucro de [SQLBI](https://sqlbi.com). -Puede usar el Administrador de paquetes de DAX con cualquier modelo que admita funciones DAX definidas por el usuario; es decir, el nivel de compatibilidad del modelo debe ser 1702 o superior. +Puedes usar el Administrador de paquetes DAX con cualquier modelo que admita funciones DAX definidas por el usuario; es decir, el nivel de compatibilidad del modelo debe ser 1702 o superior. > [!WARNING] -> Las funciones DAX definidas por el usuario son actualmente (a fecha de noviembre de 2025) una característica en versión preliminar de Power BI. Considere sus [limitaciones](https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions#considerations-and-limitations) antes de usarlas. +> Las funciones DAX definidas por el usuario están actualmente (a noviembre de 2025) en versión preliminar en Power BI. Ten en cuenta sus [limitaciones](https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions#considerations-and-limitations) antes de usarlas. --- -![Administrador de paquetes de DAX](~/content/assets/images/dax-package-manager-overview.png) +![Administrador de paquetes DAX](~/content/assets/images/dax-package-manager-overview.png) ## Diseño de la interfaz -### 1. Abrir el Administrador de paquetes de DAX +### 1. Abrir el Administrador de paquetes DAX -Puede abrir el panel de DPM desde el menú **Ver**. También es posible asignar un atajo personalizado al comando `View.DaxPackageManager` desde **Herramientas > Preferencias > Teclado**. +Puedes abrir el panel del Administrador de paquetes DAX desde el menú **Ver**. También puedes asignar un atajo personalizado al comando `View.DaxPackageManager` desde **Herramientas > Preferencias > Teclado**. -- **Menú:** `Ver → Administrador de paquetes de DAX` -- **Atajo:** _(si se ha asignado en Preferencias)_ +- **Menú:** `Ver → Administrador de paquetes DAX` +- **Atajo:** _(si lo has asignado en Preferencias)_ --- ### 2. Listas de paquetes -A la izquierda de la pantalla, encontrarás las tres pestañas siguientes. Cada pestaña va acompañada de una lista de paquetes relevantes para su contexto: +En la parte izquierda de la pantalla, encontrarás las tres pestañas siguientes. Cada pestaña va acompañada de una lista de paquetes pertinente para su contexto: -| Pestaña | Descripción | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Explorar** | Descubre los paquetes de DAX disponibles del proveedor (p. ej., `api.daxlib.org`). | -| **Instalados** | Consulta todos los paquetes instalados actualmente y sus versiones. | -| **Actualizaciones** | Consulta los paquetes para los que hay versiones más recientes disponibles. | +| Pestaña | Descripción | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Examinar** | Descubre los paquetes DAX disponibles del proveedor (p. ej., `api.daxlib.org`). | +| **Instalados** | Consulta todos los paquetes instalados actualmente y sus versiones. | +| **Actualizaciones** | Consulta los paquetes para los que hay versiones más recientes disponibles. | -Cada entrada de paquete incluye: +Cada entrada del paquete incluye: -- **Nombre y descripción breve** +- **Nombre y breve descripción** - **Número de versión** - **Autores o propietarios** - **URL del proveedor** @@ -69,10 +69,10 @@ Cada entrada de paquete incluye: ### 3. Barra de búsqueda -Escribe tus palabras clave de búsqueda o el nombre (parcial) del paquete para filtrar la lista de elementos y mostrar solo los que coincidan con los términos de búsqueda. Esta característica se aplica a las tres pestañas, es decir, **Explorar**, **Instalados** y **Actualizaciones**. +Introduce tus palabras clave de búsqueda o el nombre (parcial) del paquete para filtrar la lista y mostrar solo los elementos que coincidan con los términos de búsqueda. Esta función se aplica a las tres pestañas: **Examinar**, **Instalados** y **Actualizaciones**. > [!NOTE] -> Actualmente solo mostramos los primeros 20 paquetes que coinciden con los criterios de búsqueda. Todavía no hay una función de paginación; llegará en una actualización futura. Si necesitas explorar todos los paquetes disponibles, consulta la fuente; por ejemplo, https://daxlib.org. +> Actualmente solo mostramos los 20 primeros paquetes que coinciden con los criterios de búsqueda. Aún no hay paginación; llegará en una actualización futura. Si necesitas examinar todos los paquetes disponibles, consulta la fuente; por ejemplo, https://daxlib.org. --- @@ -83,62 +83,62 @@ Al seleccionar un paquete, se muestra información detallada: | Campo | Descripción | | -------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Instalado / Versión** | Versión actual y actualizaciones disponibles. | -| **Descripción** | Resumen de lo que ofrece la biblioteca. | -| **Notas de la versión** | Información sobre nuevas funciones o cambios en la versión más reciente. | +| **Descripción** | Resumen de lo que proporciona la biblioteca. | +| **Notas de la versión** | Información sobre las nuevas funciones o los cambios de la versión más reciente. | | **Proveedor / Propietarios / Autores** | Metadatos de atribución. | -| **Etiquetas** | Útiles para la categorización y la búsqueda. | +| **Etiquetas** | Útil para la categorización y la búsqueda. | | **Direcciones URL** | Enlaces directos a la documentación del proyecto, la API y el repositorio de GitHub. | | **Fecha de publicación** | Marca de tiempo de la versión actual. | -| **Descargas** | Instalaciones totales de todos los usuarios. | +| **Descargas** | Total de instalaciones realizadas por todos los usuarios. | -Un paquete que no esté instalado mostrará un botón **"Instalar"**. Al hacer clic en este botón, las UDF del paquete se añadirán al instante a tu modelo. +Un paquete que no esté instalado mostrará un botón **“Instalar”**. Al hacer clic en este botón, las UDF del paquete se añadirán al instante a tu modelo. -Los paquetes que ya están instalados mostrarán un botón **“Eliminar”**. +Los paquetes que ya estén instalados mostrarán un botón **“Quitar”**. -Los paquetes que tengan versiones más recientes disponibles mostrarán un botón **“Actualizar”**. +Los paquetes para los que haya versiones más recientes disponibles mostrarán un botón **“Actualizar”**. > [!WARNING] -> Si elimina o actualiza un paquete en el que haya realizado modificaciones en la expresión DAX de una o más UDF, verá un mensaje de advertencia indicando que se perderán sus cambios. +> Si quitas o actualizas un paquete en el que has modificado la expresión DAX de una o varias UDF, verás un mensaje de advertencia que indica que se perderán tus cambios. --- ### 5. Notificaciones de actualización -Al abrir un modelo que usa un paquete para el que hay una actualización disponible, verá una notificación de actualización en la parte inferior del **Explorador TOM**. +Al abrir un modelo que usa un paquete para el que hay una actualización disponible, verás una notificación de actualización en la parte inferior del **Explorador TOM**. -Haga clic en la notificación de actualización o abra la vista del Administrador de paquetes DAX para ver e instalar la actualización. +Haz clic en la notificación de actualización o abre la vista del **Administrador de paquetes DAX** para ver e instalar la actualización. --- ## Instalación de paquetes -1. Abra **Administrador de paquetes DAX**. -2. En la pestaña **Examinar**, seleccione un paquete (p. ej., `DaxLib.SVG`). Use la barra de búsqueda para acotar la búsqueda según sea necesario. -3. Haga clic en **Instalar**. +1. Abre el **Administrador de paquetes DAX**. +2. En la pestaña **Examinar**, selecciona un paquete (por ejemplo, `DaxLib.SVG`). Usa la barra de búsqueda para acotar la búsqueda según lo necesites. +3. Haz clic en **Instalar**. 4. Una vez instalado, el paquete y sus funciones aparecerán en el Explorador TOM. -También puede seleccionar **versiones** concretas antes de instalarlas —útil para pruebas de regresión o para garantizar la compatibilidad con modelos más antiguos. +También puedes seleccionar **versiones** específicas antes de instalar, lo que resulta útil para las pruebas de regresión o para garantizar la compatibilidad con modelos antiguos. --- ## Actualización de paquetes -1. Vaya a la pestaña **Actualizaciones** o seleccione un paquete con una versión más reciente disponible. -2. Haga clic en **Actualizar todo** para actualizar todos los paquetes instalados, o en **Actualizar** para uno en concreto. +1. Ve a la pestaña **Actualizaciones** o selecciona un paquete que tenga una versión más reciente disponible. +2. Haz clic en **Actualizar todo** para actualizar todos los paquetes instalados, o en **Actualizar** para uno concreto. 3. DPM obtiene las definiciones más recientes y reemplaza automáticamente las funciones existentes. --- -## Eliminación de paquetes +## Eliminar paquetes -1. Vaya a la pestaña **Instalados**. -2. Seleccione el paquete que quiera eliminar. -3. Haga clic en **Eliminar**. +1. Ve a la pestaña **Instalados**. +2. Selecciona el paquete que deseas eliminar. +3. Haz clic en **Quitar**. Todas las UDF asociadas se eliminarán del modelo. > [!CAUTION] -> Eliminar UDFs puede afectar a las expresiones DAX en otras áreas del modelo (medidas, columnas calculadas, etc.) queden inválidas. Si esto ocurre, siempre puedes pulsar **Deshacer** (Ctrl+Z) para revertir la eliminación del paquete. Usa la función **Mostrar dependencias** (Shift+F12) para identificar dónde se usan las UDF antes de eliminar un paquete. +> Eliminar UDFs puede provocar que las expresiones DAX en otras áreas del modelo (medidas, columnas calculadas, etc.) dejen de ser válidas. Si esto ocurre, siempre puedes pulsar **Deshacer** (Ctrl+Z) para deshacer la eliminación del paquete. Usa la función **Mostrar dependencias** (Mayús+F12) para identificar dónde se usan las UDF antes de eliminar un paquete. --- @@ -146,57 +146,57 @@ Todas las UDF asociadas se eliminarán del modelo. El DAX Package Manager usa [propiedades extendidas](https://learn.microsoft.com/en-us/dotnet/api/microsoft.analysisservices.tabular.extendedproperty?view=analysisservices-dotnet) para llevar un registro de los paquetes instalados. Las propiedades extendidas son similares a las anotaciones, pero se adaptan mejor al almacenamiento de metadatos personalizados en formato JSON. -El DAX Package Manager crea las siguientes propiedades extendidas en el objeto **Modelo**: +DAX Package Manager crea las siguientes propiedades extendidas en el objeto **Modelo**: -| Nombre de la propiedad | Descripción | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `TabularEditor_ModelDaxPkgTable` | Un diccionario JSON con una entrada por cada paquete instalado. La clave es un entero secuencial, mientras que el valor contiene información sobre el proveedor del paquete, el ID del paquete dentro del proveedor y la versión del paquete. | -| `TabularEditor_ModelDaxPkgSeq` | Un valor entero que se incrementa cada vez que se instala un paquete. Se usa para generar claves únicas para la propiedad `TabularEditor_ModelDaxPkgTable`. | +| Nombre de la propiedad | Descripción | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TabularEditor_ModelDaxPkgTable` | Un diccionario JSON con una entrada por cada paquete instalado. La clave es un entero secuencial, mientras que el valor contiene información sobre el proveedor del paquete, el identificador del paquete dentro del proveedor y la versión del paquete. | +| `TabularEditor_ModelDaxPkgSeq` | Un valor entero que se incrementa cada vez que se instala un paquete. Se usa para generar claves únicas para la propiedad `TabularEditor_ModelDaxPkgTable`. | -Además, cada UDF importada mediante el DAX Package Manager tendrá asignadas las siguientes propiedades extendidas: +Además, cada UDF importada a través del DAX Package Manager tendrá asignadas las siguientes propiedades extendidas: -| Nombre de la propiedad | Descripción | -| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `TabularEditor_ObjDaxPkgHandle` | Un valor entero que corresponde a la clave de la propiedad `TabularEditor_ModelDaxPkgTable` en el modelo. Esto permite a Tabular Editor identificar a qué paquete pertenece una UDF. | -| `TabularEditor_ObjDaxPkgContentHash` | Un valor hash calculado a partir de la expresión DAX de la UDF en el momento de la instalación. Se usa para detectar si una UDF se ha modificado desde la instalación, lo cual es importante al actualizar o eliminar paquetes. | +| Nombre de la propiedad | Descripción | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TabularEditor_ObjDaxPkgHandle` | Un valor entero que corresponde a la clave de la propiedad `TabularEditor_ModelDaxPkgTable` en el modelo. Esto permite a Tabular Editor identificar a qué paquete pertenece una UDF. | +| `TabularEditor_ObjDaxPkgContentHash` | Un valor de hash calculado a partir de la expresión DAX de la UDF en el momento de la instalación. Se utiliza para detectar si una UDF se ha modificado desde la instalación, lo cual es importante al actualizar o eliminar paquetes. | > [!CAUTION] > Modificar o eliminar manualmente estas propiedades extendidas puede provocar un comportamiento inesperado en el Administrador de paquetes DAX. ## Gestión de conflictos -### Modificar UDF procedentes de paquetes +### Modificar UDF de paquetes -Si modificas la expresión DAX de una UDF importada desde un paquete DAX, verás el siguiente aviso al actualizar o desinstalar el paquete: +Si modificas la expresión DAX de una UDF importada desde un paquete DAX, verás el siguiente mensaje al actualizar o eliminar el paquete: ![Actualizar UDF modificada](~/content/assets/images/dax-package-manager-update-modified.png) Tienes las siguientes opciones: -- **Sí**: La actualización continuará y sobrescribirá los cambios que hiciste en la UDF con la definición procedente del origen del Administrador de paquetes DAX. -- **No**: La actualización continuará, pero las UDF(s) modificadas permanecerán intactas, lo que podría causar problemas si la actualización del paquete incluyera cambios incompatibles. +- **Sí**: La actualización continuará y sobrescribirá los cambios que hiciste en la UDF con su definición del origen del Administrador de paquetes DAX. +- **No**: La actualización continuará, pero las UDF(s) modificadas permanecerán intactas, lo que podría causar problemas si la actualización del paquete incluyó cambios importantes. - **Cancelar**: Cancela la actualización. > [!TIP] -> Si deseas "desvincular" las UDF existentes del Administrador de paquetes DAX, elimina las propiedades extendidas `TabularEditor_ObjDaxPkgHandle` y `TabularEditor_ObjDaxPkgContentHash` de los objetos UDF. De este modo, el Administrador de paquetes DAX dejará de realizar el seguimiento de estas UDF y no se verán afectadas por futuras actualizaciones o desinstalaciones de paquetes. Aun así, debes tener en cuenta los conflictos de nombres. +> Si quieres "desvincular" las UDF existentes del Administrador de paquetes DAX, elimina las propiedades extendidas `TabularEditor_ObjDaxPkgHandle` y `TabularEditor_ObjDaxPkgContentHash` de los objetos UDF. De este modo, el Administrador de paquetes DAX dejará de realizar el seguimiento de estas UDF y no se verán afectadas por futuras actualizaciones o eliminaciones de paquetes. Aun así, debes seguir teniendo en cuenta los conflictos de nombres. ### Instalar un paquete con conflictos de nombres -Si intentas instalar un paquete que contiene una UDF con el mismo nombre que una UDF existente en el modelo (independientemente de si se importó de otro paquete o se creó manualmente), verás el siguiente aviso: +Si intentas instalar un paquete que contenga una UDF con el mismo nombre que una UDF existente en el modelo (independientemente de si se importó desde otro paquete o se creó manualmente), verás el siguiente mensaje: -![Instalar paquete: conflicto de nombres](~/content/assets/images/dax-package-manager-install-conflict.png) +![Conflicto de nombres al instalar un paquete](~/content/assets/images/dax-package-manager-install-conflict.png) Tienes las siguientes opciones: - **Sí**: La instalación continuará y la UDF del paquete sobrescribirá la UDF existente en el modelo. -- **No**: La instalación continuará, pero se omitirán las UDF(s) del paquete que entren en conflicto. +- **No**: La instalación continuará, pero se omitirán las UDF(s) en conflicto del paquete. - **Cancelar**: Cancela la instalación. --- ## Recursos adicionales -- [Sitio del proyecto DaxLib](https://daxlib.org) +- [Sitio del proyecto de DaxLib](https://daxlib.org) - [Repositorio de GitHub de DaxLib](https://github.com/daxlib/daxlib) - [Funciones DAX definidas por el usuario (Microsoft Learn)](https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions) - [Funciones definidas por el usuario en Tabular Editor 3](xref:udfs) diff --git a/localizedContent/es/content/features/pivot-grid.md b/localizedContent/es/content/features/pivot-grid.md index 3cc55bf21..662ecb0cc 100644 --- a/localizedContent/es/content/features/pivot-grid.md +++ b/localizedContent/es/content/features/pivot-grid.md @@ -1,8 +1,8 @@ --- uid: pivot-grid -title: Pivot Grids +title: Pivot Grid author: Daniel Otykier -updated: 2024-05-28 +updated: 2026-05-27 applies_to: products: - product: Tabular Editor 2 @@ -17,52 +17,52 @@ applies_to: full: true --- -# Pivot Grids +# Pivot Grid > [!NOTE] -> La información de este artículo se aplica a Tabular Editor 3.16.0 o posterior. Asegúrese de estar usando la versión más reciente de Tabular Editor 3 para aprovechar las nuevas funciones y mejoras. +> La información de este artículo se aplica a Tabular Editor 3.16.0 o versiones posteriores. Asegúrate de estar usando la versión más reciente de Tabular Editor 3 para aprovechar las nuevas funciones y mejoras. -Al desarrollar modelos semánticos, a menudo puede querer comprobar que sus expresiones DAX devuelven los valores esperados. Tradicionalmente, esto se hacía con herramientas cliente como Excel o Power BI. Con Tabular Editor 3, puede usar **Pivot Grids**, que se comportan de forma muy similar a las conocidas tablas dinámicas de Excel. El Pivot Grid le permite crear rápidamente vistas resumidas de los datos de su modelo, lo que le permite probar el comportamiento de sus medidas DAX al filtrar y segmentar por distintas columnas y jerarquías. +Al desarrollar modelos semánticos, a menudo querrás comprobar que tus expresiones DAX devuelven los valores esperados. Tradicionalmente, esto se hacía con herramientas cliente como Excel o Power BI. Con Tabular Editor 3, puedes usar **Pivot Grids**, que se comportan de forma muy similar a las conocidas tablas dinámicas de Excel. El Pivot Grid te permite crear rápidamente vistas resumidas de los datos de tu modelo y probar el comportamiento de tus medidas DAX al filtrar y segmentar por distintas columnas y jerarquías. ![Ejemplo de Pivot Grid](~/content/assets/images/pivot-grid-example.png) -La captura de pantalla anterior muestra un Pivot Grid con dos medidas, `[Total Net Order Value]` y `[Net Orders]`, segmentado horizontalmente por Año, filtrado a 2021 y 2022, y verticalmente por la jerarquía de productos. Los usuarios de Tabular Editor 3 pueden usar esta función para asegurarse de que las expresiones DAX detrás de las medidas funcionan como se espera y para validar rápidamente los datos del modelo. +La captura de pantalla anterior muestra un Pivot Grid que contiene dos medidas, `[Total Net Order Value]` y `[Net Orders]`, segmentado horizontalmente por Año, filtrado a 2021 y 2022, y verticalmente por la jerarquía de productos. Los usuarios de Tabular Editor 3 pueden usar esta característica para asegurarse de que las expresiones DAX de las medidas funcionan como se espera y para validar rápidamente los datos del modelo. -De forma predeterminada, el Pivot Grid se actualiza automáticamente cada vez que guarda cambios en el modelo semántico (Ctrl+S). Así, puede iterar rápidamente sobre sus expresiones DAX y ver los resultados en el Pivot Grid sin tener que esperar a que el modelo se actualice: cambie sus medidas, guarde el modelo y verá la nueva definición reflejada directamente en el Pivot Grid. Un buen flujo de trabajo consiste en abrir el Pivot Grid en una ventana independiente mientras trabaja en expresiones DAX en el **Editor de expresiones** o mediante un **Script DAX**. +De forma predeterminada, el Pivot Grid se actualiza automáticamente cada vez que guardas cambios en el modelo semántico (Ctrl+S). Así, puedes iterar rápidamente sobre tus expresiones DAX y ver los resultados en el Pivot Grid sin tener que esperar a que se actualice el modelo: cambia tus medidas, guarda el modelo y verás directamente la nueva definición de la medida reflejada en el Pivot Grid. Un buen flujo de trabajo es abrir el Pivot Grid en una ventana independiente mientras trabajas en expresiones DAX en el **Editor de expresiones** o con un **Script DAX**. > [!TIP] > Algunas aclaraciones sobre la terminología: > -> - **Campos** hace referencia a las medidas, KPI, columnas y jerarquías del modelo. En otras palabras, todo lo que se pueda arrastrar al Pivot Grid. -> - Los **KPIs** son un tipo especial de medida que se puede crear en Tabular Editor. Se muestran en el Pivot Grid igual que las medidas, pero con un icono especial para indicar que son KPIs. Cada KPI puede tener hasta 3 valores diferentes (objetivo, tendencia y estado), que se muestran por separado en el Pivot Grid. -> - Las **columnas** del Pivot Grid (como en el término "Área de columnas") no deben confundirse con las columnas del modelo. En el Pivot Grid, las columnas se usan para segmentar los datos horizontalmente, mientras que las filas se usan para segmentar los datos verticalmente. -> - Las **celdas** del Pivot Grid son los puntos de datos individuales donde se cruzan una fila y una columna. Cada celda contiene un único valor, que es el resultado de la expresión DAX de la medida específica, evaluada bajo el contexto de filtro producido por los valores del _Área de filas_ y el _Área de columnas_, en combinación con cualquier filtro aplicado a los campos del _Área de filtros_. +> - El término **Campos** se refiere a las medidas, los KPI, las columnas y las jerarquías del modelo. En otras palabras, cualquier elemento que se pueda arrastrar al Pivot Grid. +> - **Los KPI** son un tipo especial de medida que puedes crear en Tabular Editor. Se muestran en el Pivot Grid igual que las medidas, pero con un icono especial que indica que son KPI. Cada KPI puede tener hasta 3 valores diferentes (objetivo, tendencia y estado), que se muestran por separado en el Pivot Grid. +> - **Las columnas** en el Pivot Grid (como en el término "Área de columnas") no deben confundirse con las columnas del modelo. En el Pivot Grid, las columnas se usan para segmentar los datos horizontalmente, mientras que las filas se usan para segmentarlos verticalmente. +> - **Las celdas** del Pivot Grid son los puntos de datos individuales donde se cruzan una fila y una columna. Cada celda contiene un único valor, que es el resultado de la expresión DAX de la medida concreta, evaluada en el contexto de filtro generado por los valores del _Área de filas_ y del _Área de columnas_, en combinación con cualquier filtro aplicado a los campos del _Área de filtros_. > [!NOTE] -> Los desarrolladores con experiencia en modelos multidimensionales pueden estar más familiarizados con los términos _Dimensiones_ y _Atributos_. En los modelos semánticos, las _Dimensiones_ se representan mediante _tablas_ del modelo, y los _Atributos_ se representan mediante _columnas_ del modelo. Las _jerarquías_ en un modelo semántico son simplemente una forma de agrupar columnas, como en una jerarquía de calendario: Año > Trimestre > Mes > Día. En los modelos multidimensionales, estas jerarquías antes se llamaban _Jerarquías de atributos_ o _Jerarquías definidas por el usuario_. +> Los desarrolladores con experiencia en modelos multidimensionales pueden estar más familiarizados con los términos _Dimensiones_ y _Atributos_. En los modelos semánticos, las _Dimensiones_ se representan mediante _tablas_ del modelo, y los _Atributos_ mediante _columnas_ del modelo. Las _Jerarquías_ de un modelo semántico son simplemente una forma de agrupar columnas, como en una jerarquía de calendario: Año > Trimestre > Mes > Día. Estas jerarquías solían llamarse _Jerarquías de atributos_ o _Jerarquías definidas por el usuario_ en los modelos multidimensionales. ## Crear un Pivot Grid -Puedes crear un Pivot Grid nuevo y vacío desde la opción de menú **Archivo > Nuevo > Nuevo Pivot Grid**. Como alternativa, selecciona una o varias medidas en el **Explorador TOM**, haz clic con el botón derecho o ve al menú **Medida** y selecciona **Agregar al Pivot Grid** para crear un nuevo Pivot Grid con las medidas seleccionadas. +Puedes crear un nuevo Pivot Grid vacío mediante la opción de menú **Archivo > Nuevo > Nuevo Pivot Grid**. Como alternativa, selecciona una o más medidas en el **Explorador TOM** y haz clic con el botón derecho, o ve al menú **Medida** y selecciona **Agregar a Pivot Grid** para crear un nuevo Pivot Grid con las medidas seleccionadas. -![Crear un Pivot Grid desde el Explorador TOM](~/content/assets/images/create-pivot-grid-from-TOM-Explorer.png) +![Crear Pivot Grid desde el Explorador TOM](~/content/assets/images/create-pivot-grid-from-TOM-Explorer.png) Puedes crear tantos Pivot Grid como quieras. > [!IMPORTANT] -> La opción de crear un Pivot Grid solo está disponible mientras Tabular Editor 3 esté conectado a una instancia de Analysis Services o al punto de conexión XMLA de Power BI / Fabric. +> La opción para crear un Pivot Grid solo está disponible mientras Tabular Editor 3 esté conectado a una instancia de Analysis Services o al punto de conexión XMLA de Power BI / Fabric. ## Diseño del Pivot Grid -El Pivot Grid se divide en 4 áreas: **Área de filtros**, **Área de columnas**, **Área de filas** y **Área de datos**. Puedes arrastrar campos desde la **Lista de campos** o el **Explorador TOM** a estas áreas para crear un diseño de Pivot Grid. El **Área de datos** es donde colocas medidas o KPIs, mientras que el **Área de filas** y el **Área de columnas** se usan para segmentar los datos por jerarquías y columnas. El **Área de filtros** se usa para filtrar los datos en función de los valores de columnas o jerarquías. +El Pivot Grid se divide en 4 áreas: **Área de filtro**, **Área de columnas**, **Área de filas** y **Área de datos**. Puedes arrastrar campos desde la **Lista de campos** o el **Explorador TOM** a estas áreas para crear un diseño de Pivot Grid. El **Área de datos** es donde se colocan las medidas o los KPI, mientras que el **Área de filas** y el **Área de columnas** se usan para segmentar los datos por jerarquías y columnas. El **Área de filtro** se usa para filtrar los datos en función de los valores de columnas o jerarquías. ![Pivot Grid vacío resaltado](~/content/assets/images/empty-pivot-grid-highlighted.png) -La captura de pantalla anterior muestra un diseño de Pivot Grid vacío. Los 4 cuadros vacíos en la parte inferior de la Lista de campos representan las 4 áreas del Pivot Grid. Puedes arrastrar campos de la Lista de campos a estos cuadros de lista para crear un diseño de la Pivot Grid. También puedes arrastrar campos directamente a la Pivot Grid. +La captura de pantalla anterior muestra un diseño de Pivot Grid vacío. Los 4 cuadros vacíos de la parte inferior de la Lista de campos representan las 4 áreas del Pivot Grid. Puedes arrastrar campos desde la Lista de campos a estos cuadros de lista para crear un diseño de Pivot Grid. Como alternativa, puedes arrastrar campos directamente al Pivot Grid. -## Menú y barra de herramientas de Pivot Grid +## Menú y barra de herramientas del Pivot Grid -De forma predeterminada, cuando la Pivot Grid es la ventana activa en Tabular Editor 3, están disponibles un menú y una barra de herramientas de **Pivot Grid**. El menú contiene las mismas acciones que la barra de herramientas. +De forma predeterminada, cuando un Pivot Grid es la ventana activa en Tabular Editor 3, están disponibles un menú **Pivot Grid** y una barra de herramientas. El menú contiene las mismas acciones que la barra de herramientas. ![Barra de herramientas de Pivot Grid](~/content/assets/images/pivot-grid-toolbar.png) @@ -70,100 +70,102 @@ De forma predeterminada, cuando la Pivot Grid es la ventana activa en Tabular Ed Estas acciones son: -- **Suplantación...**: Muestra un cuadro de diálogo que te permite especificar un rol o usuario para suplantar a través de la Pivot Grid. Esto es útil cuando quieres probar el comportamiento de tu modelo para distintos usuarios o roles, por ejemplo, cuando se ha aplicado [RLS u OLS](xref:data-security-about) al modelo. -- **Actualizar**: Vuelve a ejecutar la consulta generada por la Pivot Grid. Esto es útil cuando la actualización automática está deshabilitada o si se han realizado cambios en el modelo fuera de Tabular Editor 3. -- **Actualización automática**: Activa o desactiva la actualización automática. Cuando la actualización automática está habilitada, la Pivot Grid se actualizará automáticamente cada vez que guardes cambios en el modelo o cuando finalice una [operación de actualización de datos](xref:data-refresh-view). -- **Borrar filtros**: Borra todos los filtros de la Pivot Grid. -- **Borrar**: Quita todos los campos de la Pivot Grid. -- **Mostrar valores vacíos en columnas**: Activa o desactiva la visualización de valores vacíos en la Pivot Grid para los campos que se agreguen al área de columnas de la Pivot Grid. -- **Mostrar valores vacíos en filas**: Activa o desactiva la visualización de valores vacíos en la Pivot Grid para los campos que se agreguen al área de filas de la Pivot Grid. -- **Lista de campos**: Activa o desactiva la lista de campos. +- **Suplantación...**: Muestra un cuadro de diálogo que te permite especificar un rol o un usuario que quieres suplantar a través del Pivot Grid. Esto es útil cuando quieres probar el comportamiento del modelo para distintos usuarios o roles, por ejemplo, cuando se ha aplicado [RLS u OLS](xref:data-security-about) al modelo. +- **Actualizar**: Vuelve a ejecutar la consulta generada por el Pivot Grid. Esto es útil cuando la actualización automática está desactivada o si se han realizado cambios en el modelo fuera de Tabular Editor 3. +- **Actualización automática**: Activa o desactiva la actualización automática. Cuando la actualización automática está activada, el Pivot Grid se actualizará automáticamente cada vez que guardes cambios en el modelo o cuando finalice una [operación de actualización de datos](xref:data-refresh-view). +- **Borrar filtros**: Borra todos los filtros del Pivot Grid. +- **Borrar**: Elimina todos los campos del Pivot Grid. +- **Mostrar valores vacíos en columnas**: Activa o desactiva la visualización de valores vacíos en el Pivot Grid para los campos que se agregan a su área de columnas. +- **Mostrar valores vacíos en filas**: Activa o desactiva la visualización de valores vacíos en el Pivot Grid para los campos que se agregan a su área de filas. +- **Lista de campos**: Muestra u oculta la lista de campos. ## Lista de campos -De forma predeterminada, la Lista de campos se muestra a la derecha de la Pivot Grid. La Lista de campos contiene todos los campos (medidas, KPIs, columnas y jerarquías) disponibles en el modelo. Puedes arrastrar campos de la Lista de campos a la Pivot Grid para crear un diseño. También puedes arrastrar campos entre las distintas áreas de la Pivot Grid para reorganizar el diseño. +De forma predeterminada, la Lista de campos se muestra a la derecha del Pivot Grid. La Lista de campos contiene todos los campos (medidas, KPI, columnas y jerarquías) que están disponibles en el modelo. Puedes arrastrar campos desde la Lista de campos al Pivot Grid para crear una disposición. También puedes arrastrar campos entre las distintas áreas del Pivot Grid para reorganizar la disposición. -La Lista de campos se puede acoplar al lado izquierdo o derecho de la Pivot Grid, encima o debajo; también se puede ocultar o desacoplar para que "flote" como una ventana independiente. Si tienes varias Pivot Grids abiertas, cada Pivot Grid tiene su propia Lista de campos. +La propia Lista de campos puede acoplarse al lado izquierdo o derecho del Pivot Grid, arriba o abajo; también puede ocultarse o desacoplarse para que "flote" como una ventana independiente. Si tienes varios Pivot Grid abiertos, cada Pivot Grid tiene su propia Lista de campos. -Si prefieres que la Lista de campos no se muestre de forma predeterminada, desmarca la opción **Mostrar siempre la lista de campos** en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Lista de campos**. +Si no quieres que la Lista de campos se muestre de forma predeterminada, desactiva la opción **Mostrar siempre la lista de campos** en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Lista de campos**. -Puedes cambiar el diseño predeterminado de la Lista de campos en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Lista de campos > Diseño**. También puedes cambiar el diseño de cualquier Lista de campos: haz clic con el botón derecho en un área vacía de la Lista de campos y selecciona el diseño que desees en el menú contextual. +Puedes cambiar la disposición predeterminada de la Lista de campos en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Lista de campos > Disposición**. También puedes cambiar la disposición de cualquier lista de campos haciendo clic con el botón derecho en un área vacía de la Lista de campos y eligiendo la disposición deseada en el menú contextual. -![Configuración de la Lista de campos](~/content/assets/images/field-list-settings.png) +![Configuración de la lista de campos](~/content/assets/images/field-list-settings.png) -De forma predeterminada, cualquier campo que agregues al Pivot Grid sigue siendo visible en la Lista de campos. Si quieres ocultar los campos que se agregan al Pivot Grid, puedes desmarcar la opción **Mantener los campos visibles** en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Lista de campos** (este comportamiento es similar a como funcionaba Pivot Grid antes de Tabular Editor v. 3.16.0). +De forma predeterminada, cualquier campo que agregues al Pivot Grid permanece visible en la Lista de campos. Si quieres ocultar los campos que se agregan al Pivot Grid, puedes desactivar la opción **Mantener los campos visibles** en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Lista de campos** (este comportamiento es similar a cómo funcionaba el Pivot Grid antes de Tabular Editor v. 3.16.0). -Si trabajas con un modelo grande y complejo, y esperas que las medidas usadas en el Pivot Grid tarden relativamente en calcularse, puedes activar la opción **Aplazar actualización del diseño** en la parte inferior de la Lista de campos. Esto evita que el Pivot Grid actualice el diseño cada vez que agregas o quitas un campo, lo que puede ser útil si quieres hacer varios cambios en el diseño del Pivot Grid antes de actualizarlo. Pulsa el botón **Actualizar** para aplicar los cambios al Pivot Grid. +Si estás trabajando en un modelo grande y complejo, y esperas que las medidas usadas en el Pivot Grid sean relativamente lentas, puedes activar la opción **Aplazar la actualización del diseño** en la parte inferior de la lista de campos. Esto evita que el Pivot Grid actualice el diseño cada vez que agregas o quitas un campo, lo que puede ser útil si piensas hacer varios cambios en el diseño del Pivot Grid antes de actualizarlo. Haz clic en el botón **Actualizar** para aplicar los cambios al Pivot Grid. > [!IMPORTANT] -> Las columnas sin una jerarquía de atributos (IsAvailableIn MDX = false) no se pueden usar en el Pivot Grid y no se muestran en la Lista de campos. +> Las columnas sin jerarquía de atributos (IsAvailableIn MDX = false) no se pueden usar en el Pivot Grid y no se muestran en la Lista de campos. ## Personalización de Pivot Grids ### Agregar campos -Hay varias formas de agregar un campo a un Pivot Grid: +Hay varias formas de agregar un campo al Pivot Grid: **Desde el Explorador TOM:** - Haz clic con el botón derecho en una o varias _medidas_ y elige **Agregar al Pivot Grid**. -- Haz clic con el botón derecho en una _columna_ o _jerarquía_ y elige cualquiera de las opciones de **Agregar a tabla dinámica** (elige entre filas, columnas o filtros). +- Haz clic con el botón derecho en una _columna_ o _jerarquía_ y elige cualquiera de las opciones de **Agregar al Pivot Grid** (filas, columnas o filtros). - Si una medida, columna o jerarquía ya se muestra en el Pivot Grid, las opciones al hacer clic con el botón derecho te permitirán **Quitar del Pivot Grid**. además, verás opciones para mover columnas o jerarquías entre las distintas áreas del Pivot Grid. -- Todas las opciones anteriores también están disponibles en los menús **Medida**, **Columna** y **Jerarquía** (respectivamente), cuando se seleccionan uno o varios de estos objetos en el Explorador TOM. -- Además de lo anterior, también puedes arrastrar una o varias medidas, columnas o jerarquías desde el Explorador TOM a las áreas del Pivot Grid. +- Todas las opciones anteriores también están disponibles en los menús **medida**, **Columna** y **Jerarquía** (respectivamente) cuando seleccionas uno o varios objetos de ese tipo en el Explorador TOM. +- Además de lo anterior, también puedes arrastrar una o varias medidas, columnas o jerarquías desde el Explorador TOM hasta las áreas del Pivot Grid. -![Agregar jerarquía a Pivot Grid desde el Explorador TOM](~/content/assets/images/add-through-tom-explorer.png) +![Agregar jerarquía al Pivot Grid desde el Explorador TOM](~/content/assets/images/add-through-tom-explorer.png) **Desde la Lista de campos:** -- Arrastra un campo desde la Lista de campos al Pivot Grid. -- Arrastra un campo desde la Lista de campos a los cuadros de lista de las áreas, en la parte inferior de la Lista de campos, para agregarlo al Pivot Grid. -- Haz clic con el botón derecho en un campo de la Lista de campos para ver las opciones para añadirlo al Pivot Grid. -- Si un campo ya se muestra en el Pivot Grid, el menú contextual al hacer clic con el botón derecho también incluirá una opción para quitar el campo o moverlo a otra área (solo para campos de columna/jerarquía). -- Al hacer doble clic en un campo, este se añade inmediatamente al Pivot Grid. Las medidas y los KPI se añaden al Área de datos, mientras que las columnas y las jerarquías se añaden al Área de filtros. +- Arrastra un campo desde la Lista de campos hasta el Pivot Grid. +- Arrastra un campo desde la Lista de campos hasta los cuadros de lista de áreas, en la parte inferior de la Lista de campos, para agregarlo al Pivot Grid. +- Haz clic con el botón derecho en un campo de la Lista de campos para ver opciones que permiten agregarlo al Pivot Grid. +- Si un campo ya se muestra en el Pivot Grid, el menú contextual que aparece al hacer clic con el botón derecho también incluirá una opción para quitar el campo o moverlo a otra área (solo para campos de columna o jerarquía). +- Al hacer doble clic en un campo, se agregará inmediatamente al Pivot Grid. Las medidas y los KPI se agregan al Área de datos, mientras que las columnas y las jerarquías se agregan al Área de filtros. -![Agregar mediante la Lista de campos](~/content/assets/images/add-through-field-list.png) +![Agregar desde la Lista de campos](~/content/assets/images/add-through-field-list.png) -### Ajuste de campos +### Ajustar campos -Después de añadir campos al Pivot Grid, puedes ajustar el ancho de las columnas para adaptarlo mejor a su contenido. Al hacer doble clic en el separador del encabezado de una columna, el ancho de la columna se ajustará automáticamente para adaptarse a su contenido. También puedes arrastrar el separador del encabezado de la columna para ajustar el ancho manualmente. Por último, puedes usar las opciones del menú contextual **Mejor ajuste** o **Establecer ancho...** haciendo clic con el botón derecho en el encabezado de la columna. +Después de agregar campos al Pivot Grid, puedes ajustar el ancho de las columnas para adaptarlo mejor a su contenido. Al hacer doble clic en el separador del encabezado de una columna, el ancho de la columna se ajustará automáticamente al contenido. También puedes arrastrar el separador del encabezado de la columna para ajustar manualmente el ancho de la columna. Por último, puedes usar las opciones **Ajuste óptimo** o **Establecer ancho...** del menú contextual haciendo clic con el botón derecho en el encabezado de la columna. -![Mejor ajuste de columnas 2](~/content/assets/images/best-fit-columns-2.png) +![Columnas con ajuste óptimo 2](~/content/assets/images/best-fit-columns-2.png) -Para aplicar un "Mejor ajuste" o establecer un ancho específico en píxeles para todas las columnas del Pivot Grid al mismo tiempo, haz clic con el botón derecho en el encabezado "Valores" y selecciona la opción deseada en el menú contextual. +Para aplicar un "Ajuste óptimo" o establecer un ancho específico en píxeles para todas las columnas del Pivot Grid al mismo tiempo, haz clic con el botón derecho en el encabezado "Valores" y selecciona la opción deseada en el menú contextual. -De forma predeterminada, los encabezados de campo se expandirán verticalmente para adaptarse al contenido del nombre del campo. Si quieres limitar la altura de los encabezados de campo a una sola fila, puedes desactivar la opción **Ajustar texto en encabezados de campo** en **Herramientas > Preferencias > Pivot Grid > Encabezados de campo**. +De forma predeterminada, los encabezados de campo se expanden verticalmente para ajustarse al contenido del nombre del campo. Si quieres limitar la altura de los encabezados de campo a una sola fila, puedes desactivar la opción **Ajustar texto en encabezados de campo** en **Herramientas > Preferencia > Pivot Grid > Encabezados de campo**. -Para cambiar el orden de los campos en el Pivot Grid, puedes arrastrar campos entre las distintas áreas del Pivot Grid. También puedes arrastrar campos dentro de la misma área para cambiar su orden. Para quitar un campo del Pivot Grid, arrástralo de vuelta a la Lista de campos o haz clic con el botón derecho en el campo y elige **Quitar del Pivot Grid** en el menú contextual. +Para cambiar el orden de los campos en el Pivot Grid, puedes arrastrarlos entre las distintas áreas del Pivot Grid. También puedes arrastrar campos dentro de la misma área para cambiar su orden. Para quitar un campo del Pivot Grid, arrástralo de vuelta a la Lista de campos o haz clic con el botón derecho en el campo y elige **Quitar del Pivot Grid** en el menú contextual. Si quieres que las medidas se muestren en filas en lugar de en columnas, arrastra el campo "Valores" del Área de columnas al Área de filas. ### Reglas de visualización -Puedes añadir reglas de visualización a las celdas de los Pivot Grid, lo cual resulta útil para resaltarlas en función de sus valores; por ejemplo, para detectar mejor los valores atípicos. Para añadir reglas de visualización, haz clic con el botón derecho en cualquier celda del Área de datos del Pivot Grid y elige qué reglas aplicar desde el menú contextual (consulta la captura de pantalla a continuación). +Puedes agregar reglas de visualización a las celdas de los Pivot Grids, lo que resulta útil para resaltarlas en función de sus valores; por ejemplo, para detectar mejor los valores atípicos. Para agregar reglas de visualización, haz clic con el botón derecho en cualquier celda del Área de datos del Pivot Grid y elige las reglas que desees aplicar en el menú contextual (consulta la siguiente captura de pantalla). -![Personalizar Pivot Grid](~/content/assets/images/customizing-pivot-grids.png) +![Personalización de Pivot Grids](~/content/assets/images/customizing-pivot-grids.png) -## Persistencia de diseños del Pivot Grid +## Conservar diseños de Pivot Grid -Al cerrar un Pivot Grid, Tabular Editor te pedirá que guardes el diseño del Pivot Grid. Si decides guardar el diseño, la próxima vez que abras el Pivot Grid se restaurará con el mismo diseño que tenía cuando lo cerraste. También puedes guardar el diseño de un Pivot Grid manualmente pulsando (Ctrl+S) o usando la opción **Archivo > Guardar**, mientras el Pivot Grid sea la ventana activa. +Al cerrar un Pivot Grid, Tabular Editor te pedirá que guardes el diseño del Pivot Grid. Si decides guardar el diseño, la próxima vez que abras el Pivot Grid se restaurará con el mismo diseño que tenía al cerrarlo. También puedes guardar manualmente el diseño de un Pivot Grid pulsando (Ctrl+S) o usando la opción **Archivo > Guardar**, mientras el Pivot Grid es la ventana activa. -La extensión de archivo usada para guardar diseños del Pivot Grid es `.te3pivot`. Es un archivo json sencillo que especifica qué objetos del modelo se muestran en el Pivot Grid y en qué áreas se colocan. Se hace referencia a los objetos por su nombre y su etiqueta de linaje (si existe), por lo que, por lo general, el diseño de Pivot Grid puede restaurarse incluso si el modelo se ha modificado desde que se guardó el diseño. +La extensión de archivo que se usa para guardar diseños de Pivot Grid es `.te3pivot`. Se trata de un archivo json sencillo que especifica qué objetos del modelo se muestran en el Pivot Grid y en qué áreas se ubican. Los objetos se referencian por su nombre y su etiqueta de linaje (si existe), por lo que el diseño del Pivot Grid, por lo general, puede restaurarse incluso si el modelo se ha modificado desde que se guardó el diseño. > [!NOTE] -> Es posible abrir un diseño de Pivot Grid que se creó en un modelo diferente, pero tenga en cuenta que los campos del diseño pueden no existir en el modelo al que está conectado actualmente. En esos casos, el Pivot Grid mostrará un mensaje de advertencia y se quitarán del diseño los campos que no existan en el modelo. El mensaje de advertencia se puede desactivar en **Herramientas > Preferencias > Exploración de datos > Pivot Grid > Mostrar advertencia si Pivot Grid no coincide con el modelo**. +> Es posible abrir un diseño de Pivot Grid que se haya creado en otro modelo, pero ten en cuenta que los campos del diseño pueden no existir en el modelo al que estás conectado actualmente. En esos casos, el Pivot Grid mostrará un mensaje de advertencia y todos los campos que no existan en el modelo se quitarán del diseño. Puedes desactivar el mensaje de advertencia en **Herramientas > Preferencia > Exploración de datos > Pivot Grid > Mostrar advertencia si Pivot Grid no coincide con el modelo**. -## Características adicionales +## Funciones adicionales -El Pivot Grid tiene algunas funciones más que conviene conocer: +El Pivot Grid tiene algunas funciones adicionales que es útil conocer: -- Si hace clic con el botón derecho en un campo, tendrá la opción **Ir a** ese campo. Esto pone el Explorador TOM en primer plano, con el objeto de modelo equivalente seleccionado. Para las medidas y las columnas calculadas, se enfocará el **Editor de expresiones**, en el que se mostrará la expresión DAX de la medida. -- Si hace clic con el botón derecho en una celda del Pivot Grid, puede seleccionar la opción **Depurar este valor**. Esto iniciará el [**DAX Debugger**](xref:dax-debugger) a partir de la medida específica y el contexto de filtro que generaron el valor de la celda. -- Mientras un Pivot Grid se está **actualizando**, algunos elementos de la barra de herramientas se deshabilitan y las acciones del menú contextual no están disponibles temporalmente. +- Si haces clic con el botón derecho en un campo, tendrás la opción de **Ir a** ese campo. Esto llevará el foco al Explorador TOM, con el objeto del modelo equivalente seleccionado. En el caso de las medidas y las columnas calculadas, el **Editor de expresiones** pasará a primer plano y se mostrará la expresión DAX correspondiente. +- Si haces clic con el botón derecho en una celda del Pivot Grid, puedes seleccionar la opción **Depurar este valor**. Esto iniciará el [**DAX Debugger**](xref:dax-debugger) a partir de la medida concreta y del contexto de filtro que produjeron el valor de la celda. +- Mientras un Pivot Grid se está **actualizando**, algunos elementos de la barra de herramientas se deshabilitan y las acciones del menú contextual dejan de estar disponibles temporalmente. ## Limitaciones y problemas conocidos -A continuación se muestra una lista de limitaciones y problemas conocidos de los Pivot Grid en Tabular Editor 3.16.0, que estamos trabajando para resolver en próximas versiones: +A continuación tienes una lista de las limitaciones y los problemas conocidos de los Pivot Grid en Tabular Editor 3.16.0 que estamos trabajando para corregir en versiones futuras: -- Reglas de formato (como conjuntos de iconos, barras de datos, etc.) no se conservan correctamente al guardar un diseño de Pivot Grid como archivo `.te3pivot`. -- Si abre un archivo .te3pivot en un modelo distinto de aquel del que se guardó el diseño, los campos que no existan en el modelo actual se eliminarán del diseño. Al pulsar Guardar (Ctrl+S), se guardará el diseño con esos campos ya eliminados. Es posible que cambiemos este comportamiento en una versión futura para que el archivo .te3pivot no se sobrescriba sin una confirmación explícita. \ No newline at end of file +- Las reglas de formato (como conjuntos de iconos, barras de datos, etc.) no se conservan correctamente al guardar un diseño de Pivot Grid como archivo `.te3pivot`. +- Si abres un archivo .te3pivot en un modelo distinto de aquel del que se guardó el diseño, los campos que no existan en el modelo actual se eliminarán del diseño. Al pulsar Guardar (Ctrl+S), se guardará el diseño con esos campos eliminados. Es posible que cambiemos este comportamiento en una versión futura para que el archivo .te3pivot no se sobrescriba sin una confirmación explícita. +- Las columnas que usan la propiedad **Group By Columns** (incluidas las columnas de parámetros de campo) no se pueden agregar por sí solas al Área de filas ni al Área de columnas. Si lo haces, se producirá el error _"Column X is part of a composite key, but not all columns of the composite key are included in the expression or its dependent expression"_. Esta es una limitación general de los clientes MDX y también se produce al usar una columna de este tipo en una tabla dinámica de Excel. Para evitarlo, agrega la columna Group By Column relacionada al Pivot Grid _antes_ de agregar la columna dependiente. Por ejemplo, si `[ProductKey]` está configurado como la Group By Column de `[ProductName]`, agrega primero `[ProductKey]` al Área de filas o al Área de columnas y, después, agrega `[ProductName]`. +- Al aplicar una ordenación ascendente o descendente explícita a una columna del Área de filas o del Área de columnas, los valores se ordenan alfabéticamente como cadenas, independientemente del tipo de datos de la columna. Las fechas con formato de fecha larga (por ejemplo, "4 de mayo de 2024") y los enteros se ordenan lexicográficamente en lugar de cronológicamente o numéricamente. Esta es una limitación de cómo ordenan los clientes MDX, y el mismo comportamiento se produce en una tabla dinámica de Excel conectada al modelo. Para obtener un orden cronológico o numérico, confía en la ordenación natural de la columna (no apliques una ordenación explícita) o usa la propiedad **Ordenar por columna** de la columna del modelo para que apunte a otra columna con un valor subyacente que se pueda ordenar. \ No newline at end of file diff --git a/localizedContent/es/content/features/te-cli/includes/te-cli-preview-notice.md b/localizedContent/es/content/features/te-cli/includes/te-cli-preview-notice.md new file mode 100644 index 000000000..791c29254 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/includes/te-cli-preview-notice.md @@ -0,0 +1,2 @@ +> [!IMPORTANT] +> The Tabular Editor CLI is in **Limited Public Preview**. It is offered for evaluation with a Tabular Editor account; no license is required during preview. Commands, flags, and outputs may change before general availability. **The preview build stops functioning after 2026-09-30.** We recommend against using the CLI in production CI/CD pipelines during preview. Please refer to our license agreement. diff --git a/localizedContent/es/content/features/te-cli/te-cli-auth.md b/localizedContent/es/content/features/te-cli/te-cli-auth.md new file mode 100644 index 000000000..054f1fdb9 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-auth.md @@ -0,0 +1,226 @@ +--- +uid: te-cli-auth +title: Authentication and Connections +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Authentication and Connections + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI authenticates to Power BI Service, Microsoft Fabric, and Azure Analysis Services using the same Power BI Desktop client ID that Tabular Editor 3 uses. Tokens are cached locally so you authenticate once and re-run commands silently until the refresh token expires (typically 90 days). + +## Authentication methods + +The CLI supports the full Azure Identity credential chain: + +| Method | When to use | `--auth` value | +| ---------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- | +| Interactive browser | Local development - opens the system browser | `interactive` (default) | +| Service principal (client secret) | Automation, CI/CD, headless / SSH / WSL | `spn` (with `-u / -p / -t`) or `env` | +| Service principal (certificate) | Automation with certificate-based auth | `spn` (with `-u / -t / --certificate`) | +| Environment variables | `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID` | `env` | +| Managed identity | Azure VMs, Azure Container Apps, Azure Functions | `managed-identity` | + +> [!NOTE] +> `--auth` is a **global** option, available on every `te` command - not just `te auth login`. Pass it to [`te deploy`](xref:te-cli-commands#deploy), [`te refresh`](xref:te-cli-commands#refresh), [`te query`](xref:te-cli-commands#query), [`te connect`](xref:te-cli-commands#connect), or any other command that connects to a remote endpoint, to override the default chain for that invocation. The default (`auto`) tries environment credentials first, then falls back to the cached or interactive browser login. + +For headless, SSH, WSL, or devcontainer scenarios, use a service principal - `te auth login -u -p -t ` (or `--certificate`). The login is cached, so subsequent commands acquire tokens silently with `--auth auto`. + +## `te auth login` + +Authenticate and cache the result for subsequent commands: + +```bash +# Browser-based interactive login (default) +te auth login + +# Service principal with client secret +te auth login -u "$AZURE_CLIENT_ID" -p "$AZURE_CLIENT_SECRET" -t "$AZURE_TENANT_ID" + +# Service principal - read secret from stdin +echo "$AZURE_CLIENT_SECRET" | te auth login -u "$AZURE_CLIENT_ID" -p - -t "$AZURE_TENANT_ID" + +# Service principal with certificate +te auth login -u "$AZURE_CLIENT_ID" -t "$AZURE_TENANT_ID" --certificate ./sp.pfx --certificate-password "$CERT_PASSWORD" + +# Managed identity (Azure-hosted) +te auth login --identity +``` + +After a successful service-principal login the CLI **caches the credentials** so every subsequent `te` command can acquire tokens silently - no need to re-pass `-u / -p / -t` or set the `AZURE_CLIENT_*` environment variables. Pass `--save=false` for a one-shot login that doesn't update the cache, or run `te auth logout` to clear it. + +> [!WARNING] +> Passing secrets directly on the command line exposes them to process listings and shell history. Prefer the `AZURE_CLIENT_SECRET` environment variable, or pipe the secret via stdin with `-p -`. + +## `te auth status` + +Display the current authentication state without opening a browser: + +```bash +te auth status +te auth status --output-format json +``` + +This returns an exit code of `0` when a valid session exists, `1` when not logged in or expired. + +## `te auth logout` + +Clear all cached credentials: + +```bash +te auth logout +``` + +## Credential storage + +The CLI stores access/refresh tokens and service-principal records in the **OS-native secure store** by default. A `0600` file fallback is selected automatically only when the OS keystore is unavailable (e.g., headless Linux without libsecret/D-Bus). + +| Platform | Backend | Storage location | +| --------------------------------- | --------------------------------------------- | -------------------------------------------------------------- | +| Windows | DPAPI | Per-user, managed by MSAL | +| Linux | libsecret (system keyring) | Per-user, managed by MSAL | +| macOS | Keychain | Service `com.tabulareditor.cli.*`, account `te-msal-cache.bin` | +| Any (fallback) | `0600` file | `~/.te-cli/te-msal-cache.bin` and per-key `.bin` blobs | + +Interactive browser and service-principal flows share the same cache; MSAL's account model distinguishes them - there are no separate `auth-record*.json` sidecar files. Run any command with `--debug` to see which backend was selected at startup. + +`te auth logout` clears every cached record (both the MSAL token cache and any SPN blobs) regardless of which backend is in use. + +## `te connect` - set the active connection + +`te connect` persists an active connection for the current terminal session. Subsequent commands that take `-s` / `-d` can omit them: + +```bash +# Remote workspace +te connect my-workspace my-model + +# Local TMDL folder, .bim file, or .SemanticModel container +te connect ./my-model + +# Connect to a running Power BI Desktop instance (Windows only) +te connect --local + +# Show the active connection +te connect + +# Clear the active connection (and any workspace mirror) +te connect --clear +``` + +Active-connection state is per-terminal-session: opening a new terminal starts fresh. + +### Workspace mode (`-w` / `--workspace`) + +`te connect -w ` pairs a primary source with a secondary mirror so every subsequent `--save` writes to both. Use it to keep a local working copy of a remote model in sync, or to push local edits to a workspace as you save: + +```bash +# Mirror remote workspace ↔ local TMDL folder +te connect Finance "Revenue Model" -w ./revenue-model + +# Mirror local source ↔ remote workspace (initial deploy + auto-redeploy on save) +te connect ./revenue-model -w Finance "Revenue Model" +``` + +Save order is always **local first, then remote**, so the on-disk copy reflects the latest user change even if the server push fails. See @te-cli-commands#workspace-mode-w--workspace for `--workspace-format`, overwrite semantics, and clearing the mirror. + +## Connecting to different clouds + +The CLI detects the correct scope from the server URL for: + +- Power BI Service and Fabric (commercial, US Gov, China, Germany clouds) +- Azure Analysis Services (`asazure://...`) +- Local SSAS (`localhost`, named instances - Windows only) + +Pass an XMLA endpoint, workspace name, or `powerbi://` URL as `--server`: + +```bash +te connect "powerbi://api.powerbi.com/v1.0/myorg/Finance" "Revenue Model" +te connect "powerbi://api.powerbi.com/v1.0/SpaceParts/Finance" "Revenue Model" +te connect "asazure://westeurope.asazure.windows.net/myaas" "MyModel" +te connect localhost "AdventureWorks" +``` + +## Connection profiles + +For repeated use of the same connection - especially when you deploy to multiple environments - save named profiles: + +```bash +# Save remote and local profiles +te profile set prod -s my-workspace -d my-model --description "Production" +te profile set dev --model ./model --description "Local dev TMDL" + +# List and inspect +te profile list +te profile show prod + +# Use a profile as the active connection +te connect --profile prod + +# One-shot use without changing the active connection +te deploy ./model --profile staging --force +``` + +Profiles can also carry behavioral overrides that take effect whenever the profile is active: + +```bash +# In dev, disable the BPA gate on deploy and loosen validation +te profile set dev --bpa-on-deploy false --validate-on-mutation false + +# In prod, force auto-format before any mutation +te profile set prod --auto-format true +``` + +See @te-cli-config for the full list of overridable behaviors. + +## Non-interactive authentication + +For CI/CD pipelines, agents, or any unattended context, avoid interactive flows by combining: + +- The `--non-interactive` global flag (fails fast instead of prompting). +- One of the non-interactive auth methods: `env`, `managed-identity`, or explicit service principal credentials. + +Environment-based example for a pipeline: + +```bash +export AZURE_CLIENT_ID="your-app-id" +export AZURE_CLIENT_SECRET="your-client-secret" +export AZURE_TENANT_ID="your-tenant-id" + +te deploy ./model -s my-workspace -d my-model \ + --auth env \ + --non-interactive \ + --force \ + --ci github +``` + +See @te-cli-cicd for complete GitHub Actions and Azure DevOps Pipelines examples. + +## Authentication environment variables + +The CLI honors the standard Azure.Identity environment variables when you use `--auth env` (and as part of the `auto` chain): + +| Variable | Purpose | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AZURE_CLIENT_ID` | Service principal application ID. | +| `AZURE_CLIENT_SECRET` | Service principal client secret. Used together with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. | +| `AZURE_TENANT_ID` | Service principal tenant (directory) ID. | +| `AZURE_CLIENT_CERTIFICATE_PATH` | Path to a PEM or PKCS12 certificate file for certificate-based service principal auth. Used together with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. | +| `AZURE_AUTHORITY_HOST` | Override the authority host for sovereign clouds (e.g., `login.microsoftonline.us`, `login.partner.microsoftonline.cn`, `login.microsoftonline.de`). Defaults to the commercial cloud. | + +For CLI-specific environment variables (config paths, debug logging, TE2 compatibility), see @te-cli-config. + +## Next steps + +- @te-cli-commands - what you can do once connected. +- @te-cli-config - configuration and profile behavior. +- @te-cli-cicd - pipeline examples using service principals and managed identity. diff --git a/localizedContent/es/content/features/te-cli/te-cli-automation.md b/localizedContent/es/content/features/te-cli/te-cli-automation.md new file mode 100644 index 000000000..9ff078182 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-automation.md @@ -0,0 +1,193 @@ +--- +uid: te-cli-automation +title: Automation and Scripting +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Automation and Scripting + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI is composable; every command supports structured output, disables interactive prompts on demand, and returns predictable exit codes. The same primitives work equally well for shell pipelines, Python scripts, PowerShell automation, and agent-driven workflows. + +## Structured output + +Use `--output-format` to switch any command between text (human-readable) and machine-readable formats: + +| Format | Use for | Notes | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `text` (default) | Human-readable use | Plain text on stdout regardless of whether the stream is a TTY or piped. | +| `json` | Machine-readable use | Always valid JSON to stdout. Use `--error-format json` if you also want machine-readable errors on stderr. | +| `csv` | Tabular results (`query`, `bpa run`, `bpa rules`, `vertipaq`, `validate`, `test`, `refresh`, `profile list`, `session list`, `find`, `replace`, `get`, `ls`) | RFC 4180 escaping. | +| `tmsl` (alias `bim`) | Whole-object TMSL/BIM serialization | Accepted by `te get` and `te ls`. | +| `tmdl` | Whole-object TMDL serialization | Accepted by `te get` only (single object). | + +```bash +te ls --output-format json +te query -q "EVALUATE VALUES('Date'[Year])" --output-format csv +te bpa run --output-format json +``` + +> [!NOTE] +> `--output-format` and `--error-format` are independent. Setting `--output-format json` does _not_ switch stderr to JSON; pass `--error-format json` for that. There is no automatic format switching when stdout is redirected - the default is always `text` unless you ask otherwise. + +## Non-interactive mode + +Add `--non-interactive` to any command to disable confirmation prompts, credential picklists, and guided wizards. If the command needs input it cannot resolve from flags, environment, or config, it exits non-zero with an actionable error instead of hanging. + +```bash +te deploy ./model --non-interactive --force --ci github +``` + +## Exit codes + +Every `te` command exits with a predictable status code so callers can branch on success or failure without parsing stdout. + +| Exit | Meaning | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `0` | Success. | +| `1` | Generic failure - invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity ≥ error. | +| `2` | Used by `te diff` to indicate models differ (distinct from `0` identical and non-zero errors). | + +Combine exit codes with `--ci ` annotations and `--trx ` to surface rich failure information in CI - see @te-cli-cicd. + +## Errors on stderr + +Errors, warnings, and the preview banner are written to **stderr**; structured data is written to **stdout**. This means you can pipe JSON safely without it being contaminated by progress indicators or diagnostic messages: + +```bash +te ls --output-format json | jq '.[] | .name' +te vertipaq --output-format json > stats.json +``` + +## Python + +Python is a natural host for orchestrating CLI calls from data pipelines, notebooks, or test harnesses. Invoke `te` with `subprocess.run`, request JSON, and parse stdout: + +```python +import json +import subprocess + +def query(server: str, database: str, dax: str) -> list[dict]: + result = subprocess.run( + ["te", "query", + "-s", server, + "-d", database, + "-q", dax, + "--output-format", "json", + "--non-interactive"], + check=True, + capture_output=True, + text=True, + ) + return json.loads(result.stdout) + +rows = query("Finance", "Revenue Model", "EVALUATE TOPN(10, 'Sales')") +for row in rows: + print(row) +``` + +To capture structured errors from stderr: + +```python +import json +import subprocess + +result = subprocess.run( + ["te", "deploy", "./model", + "-s", "Finance", "-d", "Revenue", + "--output-format", "json", "--non-interactive", "--force"], + capture_output=True, text=True, +) + +if result.returncode != 0: + try: + err = json.loads(result.stderr.strip().splitlines()[-1]) + print("Deploy failed:", err.get("error"), "- hint:", err.get("hint")) + except json.JSONDecodeError: + print("Deploy failed:\n", result.stderr) +``` + +## PowerShell + +PowerShell handles JSON natively. `te` is a regular console binary that works directly in PowerShell pipelines (see @te-cli-migrate if you're porting from the older `TabularEditor.exe` CLI): + +```powershell +$rows = te query -s Finance -d Revenue -q "EVALUATE TOPN(10, 'Sales')" --output-format json --non-interactive + | ConvertFrom-Json + +$rows | Format-Table + +# Check exit code after the pipeline +if ($LASTEXITCODE -ne 0) { + Write-Error "Query failed with exit $LASTEXITCODE" + exit $LASTEXITCODE +} +``` + +Read secrets from the environment rather than passing them as plaintext: + +```powershell +$env:AZURE_CLIENT_ID = "your-app-id" +$env:AZURE_CLIENT_SECRET = "your-client-secret" +$env:AZURE_TENANT_ID = "your-tenant-id" + +te deploy ./model ` + -s my-workspace -d my-model ` + --auth env --non-interactive --force --ci vsts +``` + +## Bash + +Compose commands with pipes and `jq`. The CLI's text output is colorized for humans, but switching to `--output-format json` gives you a clean shape to work with: + +```bash +# Count measures per table +te ls --type measure --output-format json \ + | jq -r '.[] | .table' \ + | sort | uniq -c | sort -rn +``` + +```bash +# Fail the shell script if BPA finds any errors +te bpa run --fail-on error --output-format json > bpa.json \ + || { echo "BPA gate failed"; jq '.violations' bpa.json; exit 1; } +``` + +## Composability example + +Generating a refresh TMSL script and version-controlling it is three commands: + +```bash +te connect MyWorkspace MyModel +te refresh --type full --dry-run > refresh.tmsl +cat refresh.tmsl +``` + +The resulting TMSL can be reviewed in a pull request, committed, executed by the CLI (`te refresh --type full`), handed to a DBA, or applied by any XMLA-compatible tool. The CLI becomes a building block rather than a black box. + +## Useful patterns + +A handful of small idioms that come up often when composing `te` commands in scripts or pipelines: + +- **Idempotent creates and removes.** `te add Sales/Marker -t Measure -i "0" --if-not-exists --save` and `te rm Sales/OldMeasure --if-exists --save` both exit `0` whether or not the object existed - safe to re-run in CI. +- **Dry-run diffs.** `te replace` is dry-run by default; add `--save` only when you're satisfied with the preview. +- **Emit TMSL for review.** `te deploy ./model --xmla deploy.tmsl` produces the deployment script without touching the server - useful for DBA review or manual apply. +- **Path-only output.** `te ls --paths-only` and `te find --paths-only` emit one object path per line, ideal for piping to `xargs`, `te get`, or `te set`. The model-level containers (`te ls Measures`, `te ls Columns`) compose well with this for whole-model sweeps. +- **Benchmarking queries.** `te query --trace --cold --runs 5` runs a DAX query with cold cache, five iterations, and captures FE/SE trace events. +- **Step timings in CI logs.** Long-running commands (`te deploy`, `te refresh`, `te script`, `te validate`) include a `durationMs` field in JSON output - useful for surfacing per-step timings in pipeline summaries. + +## Related pages + +- @te-cli-cicd - pipeline-specific patterns and YAML examples. +- @te-cli-commands - full command reference. +- @te-cli-interactive - when interactive mode fits better than scripting. diff --git a/localizedContent/es/content/features/te-cli/te-cli-cicd.md b/localizedContent/es/content/features/te-cli/te-cli-cicd.md new file mode 100644 index 000000000..d39da955b --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-cicd.md @@ -0,0 +1,235 @@ +--- +uid: te-cli-cicd +title: CI/CD Integration +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# CI/CD Integration + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI is designed for unattended execution in continuous integration and delivery pipelines. A single binary, structured output, non-interactive mode, native CI annotations for GitHub Actions and Azure DevOps, and VSTEST-compatible test results make it a natural replacement for ad-hoc TE2 invocations. + +> [!WARNING] +> **Do not use the CLI in production pipelines during Limited Public Preview.** Two preview-specific risks apply to pipeline owners: +> +> - **Hard expiry.** The preview binary stops functioning on **2026-09-30** - any pipeline depending on it will fail on that date, regardless of your release calendar. +> - **No backwards-compatibility guarantee.** Commands, flags, output shapes, and exit codes may change between preview builds, so pipeline steps may need updating when you refresh the vendored binary. +> +> Build and evaluate in non-production pipelines, and share feedback in the public [TabularEditor/CLI](https://github.com/TabularEditor/CLI) repository so the GA version matches your needs. + +## What makes the CLI CI-friendly + +- **Single self-contained binary.** No runtime install, no `TabularEditor.exe`, no `start /wait`. +- **`--non-interactive` global flag.** Disables every prompt; fails fast with actionable errors. +- **`--force`** on mutating commands (`te deploy`, `te refresh`) skips confirmation prompts. +- **`--ci vsts` / `--ci github`.** Emit native pipeline annotations to stderr. +- **`--trx `.** Produce VSTEST results consumable by Azure DevOps test publishing. +- **Structured errors.** `--output-format json` emits `{"error": "...", "hint": "..."}` to stderr so pipeline steps can fail with a useful message. + +## Adding the CLI to your repo + +During Limited Public Preview, the CLI is gated behind sign-in on [tabulareditor.com](https://tabulareditor.com/download-tabular-editor-cli), so pipelines cannot fetch the archive from a public URL. The simplest reproducible approach is to commit the binary that matches your runner into your repository and reference it from each pipeline step. + +A common layout: + +``` +your-repo/ +└── tools/ + └── te/ + ├── te # Linux / macOS binary (needs chmod +x at runtime) + └── te.exe # Windows binary +``` + +Place the **extracted** binary - not the archive - so the pipeline can call it directly. Pick the build that matches your runner OS/arch; see @te-cli-install for the filename table. The self-contained binary is ~70 MB; consider Git LFS if your repo is sensitive to size. + +> [!NOTE] +> Committing the binary also pins the CLI version to whatever you checked in, which is desirable for CI reproducibility. To upgrade, replace the binary in `tools/te/` and commit it - the commit message is your version log. Keep in mind that the preview binary still expires on **2026-09-30** regardless of when you committed it, so a vendored copy is not a permanent dependency - plan to refresh it (and re-validate your pipeline against the new API surface) on preview-build cadence. + +## GitHub Actions + +A complete deploy + test workflow. The example assumes the Linux `te` binary is committed at `tools/te/te`, and a service principal is stored in repository secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`). + +```yaml +name: Deploy semantic model + +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + env: + AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }} + AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }} + AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }} + steps: + - uses: actions/checkout@v4 + + - name: Set up Tabular Editor CLI + run: | + chmod +x ./tools/te/te + echo "$GITHUB_WORKSPACE/tools/te" >> $GITHUB_PATH + + - name: Validate + run: te validate ./model --ci github --trx validate.trx + + - name: Best Practice Analyzer (gate) + run: te bpa run ./model --fail-on error --ci github --trx bpa.trx + + - name: Deploy + run: | + te deploy ./model \ + -s "${{ vars.WORKSPACE }}" \ + -d "${{ vars.MODEL }}" \ + --auth env \ + --non-interactive \ + --force \ + --ci github + + - name: Regression tests + run: | + te test run \ + -s "${{ vars.WORKSPACE }}" \ + -d "${{ vars.MODEL }}" \ + --auth env --non-interactive \ + --ci github --trx tests.trx + + - name: Publish test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: trx-results + path: '*.trx' +``` + +## Azure DevOps Pipelines + +The Azure DevOps Pipelines equivalent of the GitHub Actions workflow above. The example assumes `te.exe` is committed at `tools\te\te.exe`. `--ci vsts` emits `##vso[...]` commands that the pipeline interprets as errors, warnings, and task-status updates. + +```yaml +trigger: + - main + +pool: + vmImage: 'windows-latest' + +variables: + - group: 'te-cli-secrets' # Contains AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID + +steps: + - checkout: self + + - powershell: Write-Host "##vso[task.prependpath]$(Build.SourcesDirectory)\tools\te" + displayName: 'Set up Tabular Editor CLI' + + - script: te validate ./model --ci vsts --trx validate.trx + displayName: 'Validate' + + - script: te bpa run ./model --fail-on error --ci vsts --trx bpa.trx + displayName: 'BPA gate' + + - script: | + te deploy ./model ^ + -s "$(WORKSPACE)" -d "$(MODEL)" ^ + --auth env --non-interactive --force --ci vsts + displayName: 'Deploy' + env: + AZURE_CLIENT_ID: $(AZURE_CLIENT_ID) + AZURE_CLIENT_SECRET: $(AZURE_CLIENT_SECRET) + AZURE_TENANT_ID: $(AZURE_TENANT_ID) + + - script: te test run -s "$(WORKSPACE)" -d "$(MODEL)" --auth env --non-interactive --ci vsts --trx tests.trx + displayName: 'Regression tests' + env: + AZURE_CLIENT_ID: $(AZURE_CLIENT_ID) + AZURE_CLIENT_SECRET: $(AZURE_CLIENT_SECRET) + AZURE_TENANT_ID: $(AZURE_TENANT_ID) + + - task: PublishTestResults@2 + condition: always() + inputs: + testResultsFormat: 'VSTest' + testResultsFiles: '*.trx' +``` + +## BPA gate patterns + +`te deploy` and `te save` run the Best Practice Analyzer as a pre-flight gate by default. Three behaviors are worth determining up-front: + +- **Enforce** - the default. Pipeline fails if BPA finds violations at severity ≥ error. Pair with `--fail-on warning` on a standalone `te bpa run` step if you want warnings to fail too. +- **Auto-fix** - `--fix-bpa` applies `fixExpression`s in memory for the deployed artifact. Source files are not modified. Useful when the source of truth lives in the model and you want deploys to normalize style without developer intervention. +- **Bypass** - `--skip-bpa` disables the gate for a single command. Useful for emergency hotfixes; not recommended as a default. + +```bash +# Treat warnings as failures in PR validation +te bpa run ./model --fail-on warning --ci github --trx bpa.trx + +# Auto-fix during deploy (source unchanged) +te deploy ./model -s my-ws -d my-model --fix-bpa --force --ci github + +# Emergency bypass +te deploy ./model -s my-ws -d my-model --skip-bpa --force --ci github +``` + +See @te-cli-config for controlling the BPA gate globally via `bpa.onDeploy` / `bpa.onSave` config keys. + +## Refresh patterns + +Refresh in pipelines is typically a follow-up step after deployment. Use `--non-interactive` and pick a deterministic `--type`: + +```bash +# Full refresh of the whole model after deploy +te refresh -s my-ws -d my-model --type full --non-interactive + +# Refresh a single fact table (e.g., daily incremental pipeline) +te refresh -s my-ws -d my-model --table Sales --type full --non-interactive + +# Recalculate only (useful after calculation-group changes) +te refresh -s my-ws -d my-model --type calculate --non-interactive +``` + +For incremental refresh workflows, combine `--apply-refresh-policy`, `--effective-date `, and `--partition ` flags. See @te-cli-commands for details. + +## Artifact patterns + +Emit TMSL or XMLA as an artifact without deploying, so DBAs or a later job can review or apply it: + +```bash +# Produce the XMLA/TMSL script that would deploy - do not deploy +te deploy ./model -s my-ws -d my-model --xmla deploy.tmsl --force + +# Produce the TMSL refresh command - do not execute +te refresh -s my-ws -d my-model --type full --dry-run > refresh.tmsl +``` + +Commit these artifacts to git, upload them to the pipeline's artifact storage, or pass them between jobs. They're plain text and diff cleanly in pull requests. + +## Secret handling + +| Approach | When to use | Notes | +| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Service principal via env vars (`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`, `--auth env`) | General CI/CD | Map pipeline secrets to environment variables at the step or job level. Never pass secrets in command arguments. | +| Service principal via `te auth login` once per job (`echo $SECRET \| te auth login -u $ID -p - -t $TENANT`) | Multi-step jobs | The login is cached, so subsequent `te` commands acquire tokens silently - no need to set `AZURE_CLIENT_*` for every step or re-pass `-u/-p/-t`. Pipe the secret via stdin rather than interpolating it. | +| Managed identity (`--auth managed-identity`) | Azure VMs, Container Apps, Azure Functions | No secrets to manage. Preferred in Azure-hosted environments. | +| Certificate (`--certificate `) | Enterprise scenarios with cert rotation | Mount the certificate as a secure file step; pass `--certificate-password` via env. | + +> [!WARNING] +> Do not echo secrets or the output of `te auth status` to pipeline logs. The CLI writes warnings to stderr when secrets are passed on the command line - respect those warnings in CI. + +## Related pages + +- @te-cli-auth - authentication methods in detail. +- @te-cli-config - configuration and profile overrides. +- @te-cli-automation - general scripting patterns. +- @te-cli-migrate - migrating an existing TE2-based pipeline. diff --git a/localizedContent/es/content/features/te-cli/te-cli-commands.md b/localizedContent/es/content/features/te-cli/te-cli-commands.md new file mode 100644 index 000000000..c8c10b520 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-commands.md @@ -0,0 +1,870 @@ +--- +uid: te-cli-commands +title: Command Reference +author: Peer Grønnerup +updated: 2026-05-12 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Command Reference + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +This page gives a short description and one example per command. Every command accepts `--help` for exhaustive flag documentation: + +```bash +te deploy --help # Help for a single command +te bpa run --help # Help for a command with subcommands +``` + +> [!NOTE] +> During preview, the CLI's `--help` output is the authoritative reference for flags and options. The content on this page is hand-curated and will lag `--help` for anything added between preview releases. + +## Object paths + +Object addressing in the CLI uses a single grammar that's shared across every command. Two flavours of path appear in the reference below: + +- **``** - resolves to **exactly one** object or container. Used by commands that operate on a single target: `te get`, `te set`, `te add`, `te rm`, `te mv`, `te format -p`, `te deps`, `te macro run --on`. +- **``** - resolves to **zero or more** objects, with wildcard support. Used by commands that operate on a set: `te ls`, `te bpa run --path`, and other inspection-style commands. + +Both path forms share the same syntax rules; they differ in only two places: + +- Filter paths allow `*` wildcards; object paths do not. +- Object paths allow DAX bracket-suffix (e.g. `Sales[Amount]`); filter paths do not. + +### Segments and separators + +A path is a slash-separated sequence of **segments**. Each segment names a single step - a table, a child object, or a container keyword. + +- `Sales` — one segment +- `Sales/Revenue` — two segments +- `Roles/Admin/Members/bob` — four segments + +Empty input and `.` both mean "the model root" - the implicit starting point for filter paths and the explicit subject for `te get .`-style queries. + +### Quoting + +Most segment names work as-is. Quote a segment when its name contains spaces, slashes, brackets, or any character that would otherwise be parsed as syntax. The CLI follows DAX quoting conventions, so quoting in `te` paths matches what you'd type inside a DAX expression: + +| Form | Use for | Escape rule | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `'Net Sales'` | Tables, named objects with spaces. | Double the quote (`'Bob''s'` → `Bob's`). | +| `"Net Sales"` | Same as above; cross-shell convenience when single-quote escaping is awkward. | Double the quote (`"He said ""hi"""` → `He said "hi"`). | +| `[Sales Amount]` | DAX bracket-suffix on a table (`'Sales'[Sales Amount]`) or a lone-bracket model-wide reference (`[Total Sales]`). Object paths only. | Double the closing bracket (`[foo]]bar]` → `foo]bar`). | + +Inside quoted segments, `*` is treated as a literal character, not a wildcard. So `'Sa*'` matches a table named exactly `Sa*`. + +### DAX-style references (object paths only) + +Two DAX-shaped forms are accepted anywhere a `` is allowed: + +- **`'Table'[Member]`** - equivalent to `Table/Member`. The bracket-suffix biases ambiguous matches toward columns and measures over hierarchies/partitions. +- **`[Member]`** - a _lone_ measure or column, with no preceding table. Searches the whole model for a measure or column with that name. Measures win when both exist. + +```bash +te get "'Sales'[Amount]" # Same as te get Sales/Amount +te get "'Net Sales'[Sales Amount]" # Spaced names via DAX form +te get "[Total Sales]" # Model-wide measure-or-column lookup +``` + +### Containers and keywords + +Several names act as container keywords. A keyword can stand alone (listing the whole container) or appear inside a path (jumping into that sub-collection on the current parent). + +| Keyword | Scope | Meaning | +| ----------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------- | +| `Tables`, `Measures`, `Columns`, `Hierarchies`, `Partitions` | Model | All objects of that kind across the model. | +| `Relationships`, `Roles`, `Perspectives`, `Cultures`, `DataSources`, `Expressions`, `CalculationGroups`, `Functions`, `Annotations` | Model | Model-level containers. | +| `Measures`, `Columns`, `Hierarchies`, `Partitions`, `Calendars`, `CalculationItems` | Table | Sub-containers under a table. | +| `Levels` | Hierarchy | Levels of a hierarchy. | +| `Members`, `TablePermissions` (alias `Permissions`) | Role | Children of a role. | + +A few examples show how plain and container-scoped paths differ: + +```bash +te get Sales/Revenue # Measure or column on Sales +te get Sales/Measures/Revenue # Same, container-scoped - disambiguates if other kinds share the name +te get Sales/Geography/Levels/Year # Specific level of a hierarchy +te get Roles/Admin/Members/bob@example.com # Role member +te get Sales/refreshPolicy # Refresh-policy sub-object on a table +te get "Measures/Revenue/KPI" # KPI sub-object of a measure +``` + +Quote a segment to force literal-name matching when a real object name happens to coincide with a keyword. The table literally named `Tables` is `'Tables'`, addressed by `te get "'Tables'"`. + +### Wildcards in filter paths + +Filter paths add a single wildcard character - `*` - that matches any run of characters within one segment (greedy, single-segment). Wildcards are how `te ls` and similar commands narrow their results. + +```bash +te ls 'Sa*' # Tables whose name starts with Sa +te ls 'Sales/*Amount' # Children of Sales whose name ends with Amount +te ls '*/Amount' # An Amount column/measure across every table +te ls 'Roles/Re*/Members' # Members of every role matching Re* +``` + +A filter path with **N segments** produces **N-level-deep** results - wildcards never auto-expand a level beyond what you typed. The single-segment shortcut `te ls Sales` is the exception: an unqualified, non-wildcarded table name expands to the table's direct children to match the "show me what's in Sales" intent. `te ls Sa*`, in contrast, returns just the matching tables - no expansion. + +DAX bracket-suffix is rejected in filter paths; quote names containing `[` and `]` if you need to match them literally. + +### Errors and hints + +Misspelled segments emit a contextual error with a "did you mean" hint when the CLI can guess what you meant. Missing-parent paths fail before the leaf check, so the message points at the segment that's actually wrong. Empty containers (e.g., `te ls Hierarchies` on a model without hierarchies) emit a simply "nothing here" hint rather than an error. + +## Global options + +These flags are available on every command and can be used before or after the subcommand name. + +| Option | Description | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-m, --model ` | Path to semantic model (TMDL folder, `.bim` file, or TE folder). | +| `-s, --server ` | Workspace name or endpoint (e.g., `MyWorkspace`, `powerbi://...`, `asazure://...`, `localhost`). | +| `-d, --database ` | Semantic model name on the workspace. | +| `--local` | Connect to a locally running Power BI Desktop instance (Windows only). | +| `--auth ` | Auth method: `auto`, `interactive`, `spn`, `env`, `managed-identity` (default: `auto`). | +| `--output-format ` | Stdout format: `text` (default), `json`, `csv`, `tmsl` (alias `bim`), `tmdl`. `csv` is honored by commands that emit tabular data; `tmsl`/`tmdl` only by `te get` and `te ls` for whole-object serialization. Commands reject formats they don't support. | +| `--error-format ` | Stderr format for errors, warnings, and hints: `text` (default) or `json`. Other values fall back to text. Independent of `--output-format`, so you can pair JSON stdout with plain-text errors (or vice versa). | +| `--recent [N]` | Use a recently used model. No value = interactive picker; `N` = Nth most recent (1 = last used). | +| `--non-interactive` | Disable all interactive prompts. Fail with an actionable error if required input is missing. | +| `--debug` | Enable debug logging to stderr (connection strings, auth flow, timing). | + +For commands that read a model, the resolution order is: + +positional `` argument → `--model` global flag → `--server`/`--database` (remote) → active connection from `te connect` → `--recent`. + +## Model I/O + +### load + +Load a semantic model and display a summary of the model — name, compatibility level, and high-level object counts (tables, measures, columns). + +```bash +te load ./model # TMDL folder +te load model.bim # BIM file +te load -s MyWorkspace -d MyModel # Remote workspace +``` + +### save + +Save a model to disk. Use it to write a remote workspace model to local files, convert formats, or persist edits back to the source. + +`te save` accepts: + +- `-o, --output-path ` - target file or folder. **Optional** - when omitted, `te save` writes back to the source location, preserving the original format. +- `--serialization ` - `tmdl`, `bim`, `te-folder`, `pbip`, `database.json`. Defaults to inferring from the loaded model (BIM source → BIM, TMDL `SemanticModel/` → TMDL under `definition/`). +- `--force` - skip validation and overwrite existing output. Some refusals (ambiguous containers, multi-`SemanticModel` project roots) fire even under `--force`. +- `--skip-bpa` - bypass the BPA gate entirely. +- `--fix-bpa` - auto-fix BPA violations where rules define a fix expression. +- `--bpa-rules ` - repeatable; override `bpa.rules` from your CLI config for this single save. Built-in rules still apply unless `bpa.builtInRules` is `false`. +- `--skip-validation` - skip DAX semantic analysis and validation for fast passthrough downloads. +- `--supporting-files` - generate Fabric supporting files (`.platform`, `definition.pbism`). + +```bash +te save # Save back to source (no -o needed) +te save ./model.bim -o ./tmdl-out # Convert BIM to TMDL +te save -o ./project --serialization pbip # Save as a PBIP project +te save -o ./out -s my-workspace -d my-model --skip-validation # Fast download +``` + +> [!TIP] +> Use `te save -o -s -d ` to download a remote model to disk. Pair with `--skip-validation` for the fastest passthrough when you only need the bytes (no DAX semantic analysis). + +### open + +Open a model in Tabular Editor 3 Desktop. **Windows only** (requires TE3 to be installed). + +```bash +te open ./my-model +``` + +### init + +Create a new empty semantic model at the given path. + +```bash +te init ./new-model +``` + +## Model editing + +### set + +Set a property on a model object. Accepts a ``. + +`te set` accepts: + +- `-q ` - property name (e.g., `expression`, `formatString`, `description`, `isHidden`). +- `-i ` - value (use `-` to read from stdin). +- `--save` / `--save-to ` - persist changes. + +```bash +te set Sales/Amount -q expression -i "SUM(Sales[Amt])" --save +te set "'Net Sales'[Sales Amount]" -q formatString -i "#,0" --save # DAX form with spaced names +te set Sales -q isHidden -i true --save +``` + +### add + +Add an object to the model. Pass a `` for the new object (the parent must already exist; the leaf segment is the new name) and the type via `-t` / `--type`. Relationships keep their shorthand syntax (`Sales[Key]->Dim[Key]`). + +`te add` accepts: + +- `-t, --type ` - object type. Common values: `Table`, `Measure`, `Column`, `CalculatedColumn`, `Hierarchy`, `Role`, `Perspective`, `Culture`, `CalculationGroup`, `CalculationItem`. Tab-completion is supported; the full list can be retrieved by running `te add --help`. +- `--if-not-exists` - exit `0` without error if the object already exists. Use this for idempotent CI/CD pipelines. + +```bash +te add Sales/Revenue -t Measure -i "SUM(Sales[Amount])" --save +te add Sales -t Table --save +te add "Sales[ProdKey]->Product[ProdKey]" --save # Relationship shorthand +te add Sales/MarketingFlag -t CalculatedColumn -i "Sales[Amount] > 1000" --if-not-exists --save +te add Perspectives/Default/Sales --save # Include Sales in the Default perspective +te add Roles/Reader -t Role --save # New role at the model level +``` + +For data-bound tables, `te add` also supports schema detection from SQL, Lakehouse, or Warehouse sources. See `te add --help` for `--source`, `--endpoint`, `--source-table`, `--columns`, etc. + +### rm + +Remove an object. Checks dependents by default to prevent breaking existing references. + +`te rm` accepts: + +- `` — positional argument: the object to remove. +- `--force` — bypass the dependents check. +- `--if-exists` — exit `0` without error if the object doesn't exist. Use this for idempotent CI/CD pipelines. +- `--dry-run` — preview the removal without applying it. +- `--save` — persist the change to the loaded model. + +```bash +te rm Sales/Revenue --save +te rm "'Sales'[Revenue]" --save # DAX form +te rm Sales/Revenue --dry-run # Preview only +te rm Sales/OldMeasure --if-exists --save # Idempotent +``` + +### mv + +Move or rename a model object. Both source and destination are `` arguments. + +```bash +te mv Sales/Revenue Finance/Revenue --save # Move measure to another table +te mv Sales/Revenue Sales/TotalRevenue --save # Rename measure +``` + +### replace + +Find and replace text across model objects. Dry-run by default; add `--save` to apply. + +`te replace` accepts: + +- `--in ` - scope: `names`, `expressions`, `descriptions`, `displayFolders`, `formatStrings`, `annotations`, `all` (default: `all`). +- `--regex` - treat the find pattern as a regular expression. +- `--case-sensitive` - enable case-sensitive matching. +- `--dry-run` - preview changes without applying. Default behavior. +- `--save` - persist the mutation to the source location. Mutually exclusive with `--revert` and `--stage`. +- `--save-to ` - save to a different path (implies `--save`). +- `--serialization ` - model serialization: `tmdl`, `bim`, `te-folder`. +- `--force` - save even if the replacement introduces DAX validation errors. + +`--in expressions` walks every expression-bearing property: + +- **Measure**: `Expression`, `DetailRowsExpression` +- **KPI**: `TargetExpression`, `StatusExpression`, `TrendExpression` +- **Partition**: source M, polling M +- **Table permission**: `FilterExpression` +- **Calculation group**: selection expressions +- **Calculated column**: DAX expression + +Adding new expression-shaped properties to the model surfaces them automatically. + +```bash +te replace "OldTable" "NewTable" --in expressions --save +te replace "SUM" "SUMX" --regex --in expressions --save +``` + +## Inspection + +### ls + +List objects with filesystem-like navigation. Takes a `` argument supporting wildcards. Both model-level containers (`Tables`, `Measures`, `Columns`, `Hierarchies`, `Relationships`, `Roles`, `Perspectives`, `Cultures`) and table-scoped containers (`Sales/Measures`, `Sales/Columns`, …) are supported. + +`te ls` accepts: + +- `--type ` - narrow to one object kind (`table`, `measure`, `column`, `hierarchy`, `partition`, `relationship`, `role`, `perspective`, `culture`). With no `` this is equivalent to typing the matching container keyword. +- `--paths-only` - emit one object path per line, suitable for piping to `xargs`, `te get`, or `te set`. +- `--no-multiline` - collapse multi-line cells (typically DAX or M expressions) to a single line and truncate, so rows stay scannable in wide tables. Text output only; JSON/CSV/TMSL output is unaffected. +- `--output-format tmsl` (alias `bim`) - emit the matching objects as a TMSL/BIM script. Useful for `te ls Tables --output-format bim > tables.json`. `--output-format tmdl` is not supported by `ls` (TMDL is single-object only - use `te get`). + +```bash +te ls # All tables in the model +te ls Sales # All children of Sales (columns + measures + hierarchies + partitions) +te ls Sales/Measures # Just Sales's measures +te ls 'Sales/*Amount' # Children of Sales whose name ends with Amount +te ls 'Sa*' # Tables whose name starts with Sa (no auto-expansion) +te ls '*/Amount' # An Amount column/measure across every table +te ls 'Roles/Re*/Members' # Members of every role matching Re* +te ls Sales/Geography/Levels # All levels of the Geography hierarchy +te ls "'Net Sales'/'Sales Amount'" # Quote names containing spaces +te ls Measures --paths-only # One Table/Measure per line for piping +te ls --type measure # Same as `te ls Measures` +te ls Measures --no-multiline # Wide table with column dividers, single-line DAX +te ls Tables --output-format bim > tables.json # All tables emitted as TMSL/BIM +``` + +### get + +Get properties of a model object. Takes a ``. + +`te get` accepts: + +- `-q, --query ` - fetch a single property (e.g. `expression`, `formatString`). +- `-t, --type ` - disambiguate when the path matches multiple table-children (e.g. a column and a hierarchy with the same name). Values: `Measure`, `Column`, `CalculatedColumn`, `Hierarchy`, `Calendar`, `Partition`, `CalculationItem`. +- `--output-format tmsl` (alias `bim`) - emit the resolved object as TMSL/BIM JSON. +- `--output-format tmdl` - emit the resolved object as TMDL (named objects only). + +`te get` and `te ls` share a single descriptor catalog, so every property surfaces the same way across formats - the text table, JSON, and CSV all see the same set, and adding a new property to the model exposes it everywhere. + +```bash +te get Sales/Amount -q expression # Print DAX +te get "'Sales'[Amount]" # DAX form: same as Sales/Amount +te get "[Total Sales]" # Lone-bracket: model-wide measure-or-column +te get "'Net Sales'[Sales Amount]" -q expression # DAX form with spaced names +te get "Sales/Revenue/KPI" # KPI sub-object of a measure +te get Sales --output-format tmdl # Emit the table as TMDL +te get Sales --output-format bim # Emit the table as TMSL/BIM +te get Model -q description +``` + +### find + +Search for text across model objects. + +`te find` accepts: + +- `--in ` - as per `te replace` (default `all`). +- `--regex`, `--case-sensitive`, `--paths-only`. +- `--no-multiline` - collapse multi-line match context to a single line. Text output only. + +`--in expressions` covers every `IExpressionObject` in the model - including KPI `TargetExpression` / `StatusExpression` / `TrendExpression`, measure `DetailRowsExpression`, partition source/polling M, table-permission `FilterExpression`, and calculation-group `MultipleOrEmptySelection` / `NoSelection` expressions - so a literal like `123` set on a KPI's target turns up the same way a measure body would. + +```bash +te find "CALCULATE" --in expressions +te find "Revenue" --in names +te find "CALCULATE" --in expressions --paths-only | xargs -I{} te get {} -q expression +``` + +### diff + +Compare two models for structural differences. Returns the following exit codes: `0` = identical, `1` = differences found, `2` = error. + +```bash +te diff ./model-v1 ./model-v2 +te diff old.bim new.bim +``` + +### deps + +Analyze an object's upstream and downstream dependencies, or surface unused objects across the model. The single-object form takes a ``. + +`te deps` accepts: + +- `--unused` - list measures, calculated columns, and **all data columns** that no DAX references and that aren't used in any relationship, hierarchy level, sort-by, variation, AlternateOf base, or calendar time role. Each result shows `(hidden)` in text mode and an `isHidden` field in JSON. +- `--hidden` - narrow `--unused` to hidden objects only. Hidden, unused objects are the safest prune candidates because nothing user-facing depends on them. + +```bash +te deps Sales/Revenue # Upstream + downstream for one object +te deps "'Sales'[Revenue]" # DAX form is accepted everywhere a is +te deps --unused # All unused measures and columns +te deps --unused --hidden # Only hidden, unused objects +``` + +## Analysis and quality + +### validate + +Validate model expressions, schema integrity, and TOM errors. + +`te validate` accepts: + +- `--ci ` - emit CI annotations to stderr: `vsts` or `github`. +- `--trx ` - write results as a VSTEST `.trx` file. + +```bash +te validate ./model +te validate --ci github --trx results.trx +``` + +### bpa run + +Run Best Practice Analyzer rules against a model. + +`te bpa run` accepts: + +- `` - positional argument: path to model (alternative to the `--model` global flag). +- `-r, --rules ` - path(s) or URL(s) to additional BPA rule file(s) in JSON format. Repeatable. +- `--no-model-rules` - exclude BPA rules embedded in the model's annotations. +- `--no-defaults` - exclude built-in default BPA rules. +- `--vpax ` - load VertiPaq Analyzer stats from a `.vpax` file to enable VPA-aware rules. +- `--vpa-rules` - include built-in VPA-aware rules (requires `--vpax` or a pre-annotated model). +- `--allow-external-rules` - allow fetching BPA rule files from URLs embedded in model annotations. +- `--rule ` - run only specific rule(s) by ID. Repeatable. +- `--path ` - limit analysis to the tables containing the matched objects. Accepts literal names, container keywords, and wildcards (e.g., `'Sales'`, `'Sa*'`, `'Sales/Measures'`, `'*/Amount'`). +- `--fix` - apply fix expressions to auto-fix violations where possible. +- `--save` - save the model back to source after applying fixes. +- `--save-to ` - save the model to a different path after applying fixes. +- `--serialization ` - model serialization: `tmdl`, `bim`, `te-folder`. +- `--fail-on ` - failure threshold: `error` (default) or `warning`. Exits with code `1` when violations meet the threshold. +- `--ci ` - emit CI logging commands to stderr: `vsts` (Azure DevOps), `github` (GitHub Actions). +- `--trx ` - write results as a VSTEST `.trx` file to the specified path. +- `--no-multiline` - collapse multi-line cell content in the violations table to a single line. Text output only. + +```bash +te bpa run --fail-on error --ci github +te bpa run --fix --save +te bpa run --rule PERF_UNUSED_HIDDEN_COLUMN +te bpa run --path Sales # Tables touched by the Sales filter only +te bpa run --path 'Sa*' # Wildcard - every table starting with Sa +te bpa run --path Sales/Measures # Path filter applied to the matched tables +``` + +### bpa rules + +Manage BPA rule collections — list, inspect, initialize, and toggle rules in your local rules file or in model annotations. Built-in rules are read-only - to skip one without losing the rest, use `te bpa rules disable` (do not edit the built-in set directly). + +Subcommands: + +| Subcommand | Purpose | +| ------------------------------- | -------------------------------------------------------------------- | +| `add [model]` | Add a new BPA rule. | +| [`disable`](#bpa-rules-disable) | Disable a built-in BPA rule for the current user. | +| [`enable`](#bpa-rules-enable) | Re-enable a previously disabled built-in BPA rule. | +| `ignore [model]` | Add a rule to the model's ignore list. | +| [`init`](#bpa-rules-init) | Create an empty BPA rules file at the resolved path. | +| [`list`](#bpa-rules-list) | List BPA rules from all sources with status. | +| `rm [model]` | Remove a BPA rule. | +| `set [model]` | Update a BPA rule's properties. | +| `unignore [model]` | Remove a rule from the model's ignore list. | + +All `te bpa rules` subcommands accept: + +- `--rules-file ` - path to a BPA rules JSON file. Defaults to the first existing entry of `bpa.rules` in your CLI config (`~/.config/te/config.json`), or the `TE_BPA_RULES` environment variable. +- `--model-rules` - operate on rules embedded in the model annotation instead of a file. + +> [!IMPORTANT] +> `te bpa rules set` and `te bpa rules rm` refuse to mutate built-in rule IDs. Attempting to do so exits with code `1` and points at `te bpa rules disable`. To customize a built-in rule's behavior, disable the built-in and add a custom copy with a different ID: +> +> ```bash +> te bpa rules disable TE3_BUILT_IN_DATE_TABLE_EXISTS +> te bpa rules add MY_DATE_TABLE_EXISTS +> ``` + +#### bpa rules list + +List rules from all sources (built-in, user, model). + +`te bpa rules list` accepts: + +- (default) Active rules only. +- `--all` - include disabled and ignored rules. +- `--disabled` - only built-in rule IDs the user has disabled via `te bpa rules disable`. +- `--ignored` - only rules whose IDs appear in `BestPracticeAnalyzer_IgnoreRules` on the model. +- `--no-defaults` - exclude built-in rules from output. + +```bash +te bpa rules list # Active rules +te bpa rules list --all # Include disabled and ignored rules +te bpa rules list --ignored +``` + +Disabled built-in rules are flagged with a `[disabled]` marker next to the rule ID. + +#### bpa rules init + +Create an empty BPA rules file (`[]`) at the configured path. Use this once before invoking `te bpa rules set` / `te bpa rules rm` against a path that does not yet exist. + +`te bpa rules init` accepts: + +- `--force` - overwrite an existing file with `[]`. Required if the target file exists. +- `--rules-file ` - target file path. Can appear before or after the `init` subcommand. + +Path resolution (first match wins): `--rules-file` → `TE_BPA_RULES` env var → first entry of `bpa.rules[]` in your CLI config → `./BPARules.json` (current working directory). + +```bash +te bpa rules init +te bpa rules init --rules-file ./MyRules.json +te bpa rules init --force +``` + +#### bpa rules disable + +Disable an individual built-in BPA rule. The rule ID is added to `bpa.disabledBuiltInRuleIds` in your CLI config. Subsequent gate runs (deploy, save, mutation) and `te bpa run` skip the disabled rule. + +The command is idempotent — running `disable` against an already-disabled rule succeeds without modifying the config. It exits with code `1` if `` is not a built-in rule; use `te bpa rules list` to see valid built-in IDs. + +```bash +te bpa rules disable TE3_BUILT_IN_DATE_TABLE_EXISTS +``` + +#### bpa rules enable + +Re-enable a previously disabled built-in BPA rule by removing the rule ID from `bpa.disabledBuiltInRuleIds`. Exits with code `1` if the rule isn't currently disabled. + +```bash +te bpa rules enable TE3_BUILT_IN_DATE_TABLE_EXISTS +``` + +### vertipaq + +Analyze VertiPaq storage statistics. + +`te vertipaq` accepts: + +- `--columns`, `--relationships`, `--partitions`, `--all`. +- `--export ` - export VertiPaq stats to a `.vpax` file for offline analysis. +- `--import ` - load a previously exported `.vpax` file and analyze it offline. +- `--obfuscate` - obfuscate names and expressions in exported VPAX. +- `--top `, `--stats`, `--annotate`, `--save`. + +```bash +te vertipaq # Columns by size (default) +te vertipaq --all # Tables, columns, relationships, partitions +te vertipaq --export stats.vpax +te vertipaq --import stats.vpax # Analyze offline +``` + +### format + +Format DAX or M/Power Query expressions. + +`te format` accepts: + +- `-e, --expression ` - format a single inline expression. +- `-p, --path ` - format a specific measure/column. +- `--lang ` - default `dax`. +- `--save` / `--save-to` - persist formatted expressions. + +```bash +te format --save # Format all DAX +te format -p Sales/Amount --save # Single measure +te format -e "SUM ( Sales[Amount] )" # Inline +te format --lang m --save # Format M +``` + +## Execution + +### query + +Execute a DAX query against a deployed model. + +`te query` accepts: + +- `-q, --query ` - inline query. +- `--file ` - query from file. +- `--limit ` - default 100. +- `-o, --output-file ` - write results to file (`.csv`, `.tsv`, `.json`, `.dax`). +- `--trace`, `--cold`, `--plan`, `--runs ` - performance tracing and benchmarking. +- `--no-validate` - skip pre-execution DAX semantic validation. + +```bash +te query -q "EVALUATE TOPN(5, 'Sales')" -s my-ws -d my-model +te query --file query.dax --output-format json +``` + +### script + +Execute one or more C# scripts against a semantic model. The CLI uses the same scripting host as Tabular Editor 3 Desktop, so a script that runs in TE3 runs unchanged here. + +`te script` accepts: + +- `-S, --script ` - `.cs` / `.csx` file (repeatable). +- `-e, --expression ` - inline C# (use `-` for stdin). +- `--save` / `--save-to` / `--serialization`. +- `--dry-run`, `--timeout `. + +```bash +te script --script fix.cs --save +te script -e "Info(Model.Tables.Count)" +echo "Info(Model.Name);" | te script -e - +``` + +> [!IMPORTANT] +> Two behavioral details to know if you're porting an older script: +> +> - **No interactive selection in CLI scripts.** The TE3 Desktop helpers `SelectMeasure()`, `SelectTable()`, `SelectColumn()`, `SelectObject()`, and `SelectObjects()` throw `NotSupportedException` when called from `te script` - the CLI has no UI to pop up. Pre-resolve the object(s) outside the script and pass them in, or wrap the call in `try/catch` if the script is shared with TE3. +> - **Default `using` directives match TE3 Desktop.** Scripts that use `DataTable`, `File`, `StringBuilder`, or `Regex` must include the corresponding `using System.Data;` / `using System.IO;` / `using System.Text;` / `using System.Text.RegularExpressions;` directive explicitly. + +> [!NOTE] +> **Preprocessor symbols for cross-host scripts.** Scripts compiled by `te script` have the symbol `TECLI` defined. TE3 Desktop scripts have `TE3` defined instead, plus version-bracketed symbols like `TE3_3_10_OR_GREATER` ... `TE3_3_X_OR_GREATER` for the current TE3 minor version. TE2 defines neither symbol. Use these to write portable scripts: +> +> ```csharp +> #if TECLI +> // CLI-only code - no UI calls +> Info($"Running under the CLI on {Environment.OSVersion.Platform}"); +> #elif TE3 +> // TE3 Desktop-only code - UI APIs available +> ShowMessage("Hello from TE3"); +> #else +> // TE2 (legacy) - neither TECLI nor TE3 is defined +> Info("Hello from TE2"); +> #endif +> +> #if TE3_3_15_OR_GREATER +> // Gated on a specific TE3 minor version +> #endif +> ``` +> +> See @csharp-scripts for the broader cross-version scripting story. + +### macro + +Manage and run macros from a macros JSON file (typically `MacroActions.json`). The macros file is resolved in this order: `--macros ` → `TE_MACROS_PATH` env var → `macros` in CLI config → `./MacroActions.json`. + +Subcommands: + +| Subcommand | Purpose | +| -------------------------------- | ----------------------------------------------------------------- | +| `list` | List macros. | +| [`run `](#macro-run) | Run a macro. | +| `add ` | Add a macro. | +| `set ` | Update macro properties. | +| `rm ` | Remove a macro. | +| `sort` | Sort and re-assign IDs. | +| [`init`](#macro-init) | Create an empty macros file at the resolved path. | + +#### macro init + +Create an empty macros file (`{"Actions":[]}`) at the configured path. Use this once when the resolved macros file does not yet exist. + +`te macro init` accepts: + +- `--force` - overwrite an existing file. Required if the target exists. +- `--macros ` - target file path. Can appear before or after the `init` subcommand. + +```bash +te macro init +te macro init --macros ./project-macros.json +te macro init --force +``` + +#### macro run + +Run a macro. Macros that emit tables via `dataTable.Output()` render formatted output in the terminal, so DAX-style query macros work the same in `te macro run` as they do in TE3. + +`te macro run` accepts: + +- `--on ` - set the macro's selection context to a single named object (a table, measure, column, …). Equivalent to right-clicking that object in TE3 and invoking the macro from the context menu. +- `--save` / `--save-to` - persist any changes the macro makes. + +```bash +te macro run "Hide all measures" +te macro run "Format DAX" --on Sales/Revenue --save +te macro run "Format DAX" --on "'Net Sales'[Sales Amount]" --save # DAX form works in --on too +``` + +## Deployment and refresh + +### deploy + +Deploy a semantic model to Power BI, Fabric, or Azure Analysis Services. + +`te deploy` accepts: + +- `-s, --server` / `-d, --database` - target workspace and model. +- `--deploy-full` - overwrite + connections + partitions + shared expressions + roles + role members. +- `--deploy-connections` +- `--deploy-partitions` +- `--skip-refresh-policy` +- `--deploy-roles` +- `--deploy-role-members` +- `--deploy-shared-expressions` +- `--create-only` +- `--xmla ` - generate XMLA/TMSL script instead of deploying (`-` for stdout). +- `--skip-bpa` - bypass the BPA gate entirely. +- `--fix-bpa` - auto-fix BPA violations where rules define a fix expression. +- `--bpa-rules ` - repeatable; override `bpa.rules` from your CLI config for this single deploy. Built-in rules still apply unless `bpa.builtInRules` is `false`. +- `--force` - skip interactive confirmation (required for CI). +- `--ci ` - `vsts` or `github`. +- `--profile ` - one-shot use of a saved @te-cli-auth profile. + +```bash +te deploy ./model -s my-workspace -d my-model --force --ci github +te deploy ./model --xmla script.tmsl # Generate TMSL only +te deploy ./model --profile staging --force +``` + +> [!IMPORTANT] +> `te deploy` runs the Best Practice Analyzer as a gate before executing. In interactive mode, a summary + confirmation prompt is shown with **`n` as the safe default**. In CI, pass `--force` to skip the prompt. See @te-cli-config for BPA gate configuration. + +### refresh + +Trigger a data refresh on a deployed model. + +`te refresh` accepts: + +- `--type ` - `full`, `dataonly`, `automatic`, `calculate`, `clearvalues`, `defragment`, `add` (default: `automatic`). +- `--table ` - refresh specific table(s); repeatable. +- `--partition ` - refresh specific partition(s). +- `--apply-refresh-policy` - apply the incremental refresh policy to determine which partitions are refreshed. +- `--effective-date ` - set the effective date used by the refresh policy. +- `--max-parallelism ` - set the maximum number of partitions to refresh in parallel. +- `--dry-run` - output the TMSL script without executing. +- `--no-progress`, `--trace [path]`. + +```bash +te refresh --type full # Full refresh +te refresh --table Sales --type full # Single table +te refresh --type full --dry-run > refresh.tmsl # Emit TMSL only +``` + +### incremental-refresh + +Manage incremental refresh policies on tables. + +```bash +te incremental-refresh show +``` + +Additional subcommands (`set`, `remove`, `apply`) are documented via `te incremental-refresh --help`. + +## Testing + +### test run + +Run a suite of DAX assertion tests against a deployed model. + +`te test run` accepts: + +- `--suite ` - test-suite directory (default: `.te-tests/`). +- `--tag ` - only tests with this tag. +- `--fail-on ` - `error` (default) or `warning`. +- `--ci `, `--trx ` - CI annotations and TRX output. + +```bash +te test run --ci github --trx results.trx +te test run --tag revenue +``` + +### test init / spec / use / list / snapshot / compare + +Additional subcommands scaffold tests, print the assertion spec format, switch the active suite, list suites, capture snapshots, and compare models. See `te test --help` for details. + +```bash +te test init --example # Scaffold an example suite +te test spec # Print the full assertion format reference +te test init --from-model --model ./my-model # Generate stubs from your measures +``` + +## Connection and authentication + +### connect + +Set (or display) the active connection for the current terminal session. See @te-cli-auth. + +```bash +te connect # Show current active connection +te connect my-workspace my-model # Remote +te connect ./model # Local +te connect --local # Power BI Desktop (Windows) +te connect --profile prod # Activate a saved profile +te connect --clear # Clear the active connection (and any workspace mirror) +``` + +#### Workspace mode (`-w` / `--workspace`) + +Pair a primary source with a secondary target so every subsequent `--save` mirrors the model between the two. Useful for keeping a local working copy of a remote workspace, or pushing local edits to a workspace as you save. + +- `te connect -w ./src` - primary is remote; `./src` receives an initial TMDL export and mirrors every save. +- `te connect ./src -w ` - primary is local; an initial deploy pushes the model to the workspace, and subsequent saves re-deploy automatically. +- `--workspace-format ` - choose the on-disk format when mirroring to a folder/file (e.g., `-w ./model.bim` infers BIM). +- `--force` - required when the target already exists (non-empty folder, existing database). Without it, `te connect` shows an interactive `y/n` prompt with `n` as the safe default. + +Once active, `te set --save`, `te rm --save`, `te script --save`, etc. all dual-save transparently. Save order is always **local first, then remote** so the on-disk copy reflects the latest user change even if the server push fails. Clear the mirror with `te connect --clear`. + +```bash +te connect Finance "Revenue Model" -w ./revenue-model # Mirror remote → local TMDL +te connect ./revenue-model -w Finance "Revenue Model" # Mirror local → remote +``` + +### auth login / status / logout + +Manage cached authentication. See @te-cli-auth. + +### profile list / show / set / remove + +Manage named connection profiles. See @te-cli-auth. + +## Configuration + +### config show / paths / init / set + +View and manage CLI configuration and TE3 path overrides. See @te-cli-config. + +```bash +te config show # Display all settings +te config paths # Resolved TE3 file paths +te config init # Create default config +te config set autoFormat true +``` + +### license + +`te license` is reserved for the GA release and is not available in this preview build. The command is still wired up to the parser - so existing scripts that invoke it won't blow up at parse time - but every subcommand exits with status `1` and a "not available in this preview build" message. See the [Preview notice](xref:te-cli#preview-notice) on the overview page for the broader licensing outlook. + +### migrate + +Reference guide showing how legacy Tabular Editor 2 CLI flags map to the new CLI. Useful as a live lookup while porting a TE2-based pipeline. See @te-cli-migrate for the full migration guide. + +```bash +te migrate # Full flag mapping table +te migrate -A # Look up a single TE2 flag +te migrate --output-format json # Machine-readable mapping +``` + +## Shell + +### interactive + +Start a guided REPL session with a model-aware prompt. See @te-cli-interactive. + +```bash +te interactive # Connect later +te interactive ./model # Start with a local model +te interactive -s MyWorkspace -d MyModel # Start with a remote model +``` + +Quoting and DAX-style references work the same as outside the session - see the [Object paths](#object-paths) section above and @te-cli-interactive for details on bracket-aware argv splitting inside the REPL. + +### completion + +Generate a shell completion script. See @te-cli-install. + +```bash +te completion bash +te completion zsh +te completion pwsh +``` + +## Exit codes + +| Exit | Meaning | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0` | Success. | +| `1` | Generic failure (invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity ≥ error). | +| `2` | Non-zero diff (`te diff`) - models differ. | + +For fine-grained control in CI pipelines, combine exit codes with `--ci ` annotations and `--trx` results files - see @te-cli-cicd. + +## Related pages + +- @te-cli - overview and framing. +- @te-cli-install - install and set up the CLI. +- @te-cli-auth - authenticate and manage connections. +- @te-cli-config - configuration file, BPA gate, post-mutation behavior. +- @te-cli-migrate - TE2 → TE3 flag mapping. diff --git a/localizedContent/es/content/features/te-cli/te-cli-config.md b/localizedContent/es/content/features/te-cli/te-cli-config.md new file mode 100644 index 000000000..bcda9ee41 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-config.md @@ -0,0 +1,258 @@ +--- +uid: te-cli-config +title: Custom Configuration +author: Peer Grønnerup +updated: 2026-04-20 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Custom Configuration + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI reads optional configuration from a JSON file. Configuration controls three things: + +- **File paths** — where the CLI reads macros, BPA rules, and (optionally) the TE3 Desktop executable, and where to write the query log. +- **Behavioral defaults** — BPA gates, auto-format, validation. +- **Saved connection profiles** — the list of named profiles you can switch between. + +The CLI is self-contained - it does not read from or write to any Tabular Editor 3 desktop install path. BPA rules and macros files must be set explicitly via this config (or initialized on demand with `te bpa rules init` / `te macro init`). + +Most users don't need to edit the config file directly - `te config show`, `te config set `, and `te profile set` cover the common operations. + +## Config file location + +The following locations are checked in this order: + +1. `$TE_CONFIG` environment variable (if set and the file exists). +2. `~/.config/te/config.json` (on Windows, `%USERPROFILE%\.config\te\config.json`). +3. No config file - the CLI uses built-in defaults. + +`TE_CONFIG` is honored consistently by every config-file operation - `te config show`, `te config set`, `te config init`, and `te config paths` all read and write at the resolved path. This is primarily intended for testing, scripted installs, and per-environment configuration. + +To create a default config: + +```bash +te config init # Create config at TE_CONFIG (or ~/.config/te/config.json) +te config init --force # Overwrite existing config +``` + +## Viewing configuration + +```bash +te config show # Display all settings +te config show --output-format json # Machine-readable +te config paths # Show resolved macros and BPA rule paths +``` + +Use `te config paths` to see which files the CLI will actually use for macros and BPA rules. It's handy when debugging missing data files. The output shows two rows: `macros` (the resolved macros file path or `[not set]`) and `bpa.rules` (the first existing BPA rules file resolved by the path resolver, or `[not set]`). + +> [!NOTE] +> `te config paths` emits `null` fields explicitly in `--output-format json` mode (e.g., `{"macros": null, "bpa": {"rules": null}}`). Reporting resolution outcomes is the command's whole purpose, so `null` is a meaningful "tried but resolved to nothing" answer. `te config show --output-format json` strips null fields by default, so consumers should parse it tolerantly. + +## Setting values + +```bash +te config set autoFormat true +te config set bpa.onDeploy false +te config set hidePreviewNotice true +te config set macros null # Clear a path override +``` + +Unknown keys fail with exit code `1` and an error that lists the valid keys. + +If no config file exists, `te config set` auto-creates one at the resolved path (`$TE_CONFIG` if set, otherwise `~/.config/te/config.json`) before applying the change. + +> [!NOTE] +> Every key in the schema is settable via `te config set`, including nested keys via dotted paths (`bpa.onDeploy`, `formatOptions.useSqlBiDaxFormatter`, etc.). The only exception is `formatVersion`, which the CLI manages automatically. Run `te config paths` to find the config file if you'd rather edit the JSON directly. + +## Full schema + +The complete JSON config schema with all keys at their default values. Use this as a reference when editing the config file directly, or when looking up the dotted path for a `te config set` call. + +```json +{ + "formatVersion": 1, + "macros": null, + "autoFormat": false, + "validateOnMutation": true, + "vertipaqOnRefresh": false, + + "bpa": { + "rules": null, + "onDeploy": true, + "onSave": true, + "onMutation": false, + "builtInRules": true, + "disabledBuiltInRuleIds": null + }, + + "interactiveEditMode": "stage", + + "formatOptions": { + "useSemicolons": false, + "shortFormat": false, + "skipSpaceAfterFunction": false, + "useSqlBiDaxFormatter": false + }, + + "hidePreviewNotice": false, + "spinner": true, + "debug": false, + "disableTelemetry": false, + + "queryLog": null, + "te3ExePath": null, + + "profiles": {} +} +``` + +### File paths + +Set these in your config to avoid passing the same paths on every command. Per-command flags and environment variables override config values; see [Path resolution priority](#path-resolution-priority) below. + +| Key | Meaning | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `macros` | Explicit path to a macros JSON file (typically `MacroActions.json`). Resolved by every `te macro` command. Point at a shared file (network share, repo-local, or even the TE3 desktop file) to reuse the same set of macros across machines and between the CLI and TE3 Desktop. | +| `bpa.rules` | Ordered list of paths or URLs to BPA rule files. The deploy/save gate loads **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. | +| `te3ExePath` | Explicit path to the Tabular Editor 3 Desktop executable (`TabularEditor.exe`). Used **only** by `te open` to launch the desktop app; safe to leave unset on Linux/macOS or when you don't use `te open`. If unset, `te open` falls back to a `PATH` lookup. | +| `queryLog` | Path to a log file where every `te query` invocation appends its query text and execution metadata. Useful for audit trails or analyzing query patterns over time. Supports `~` for the home directory (e.g., `~/.config/te/queries.log`). | + +### Path resolution priority + +For each user-provided file (macros, BPA rules), the CLI resolves the path in this order: + +1. **Command-line flag** - `--macros ` for macro commands; `--bpa-rules ` for the deploy/save gate; `--rules-file ` for `te bpa rules` subcommands. +2. **Environment variable** - `TE_MACROS_PATH` for macros, `TE_BPA_RULES` for BPA rules. +3. **CLI config** - `macros` for macros, the first existing entry of `bpa.rules[]` for BPA rules. + +The CLI does not auto-detect any TE3 install location - configure these explicitly. To start from a default file in the current working directory, run `te macro init` (creates `./MacroActions.json`) or `te bpa rules init` (creates `./BPARules.json`). + +Run `te config paths` to see which file the CLI actually resolved. + +### Behavioral defaults + +All BPA-related settings live under the `bpa` object and are addressed via dotted keys on `te config set`. + +| Key | Default | Description | +| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `autoFormat` | `false` | Run the DAX Formatter on modified expressions after `te add` / `te set` / `te mv` / `te macro run`. Uses the in-house formatter by default; opt into the SQL BI web service via `formatOptions.useSqlBiDaxFormatter`. | +| `validateOnMutation` | `true` | After a mutating command (`add`, `set`, `mv`, `replace --save`, `macro run`), check that every `Table[Column]` reference in the model still resolves. Catches dangling references introduced by renames or removals before they reach deploy. | +| `bpa.onMutation` | `false` | Run a scoped BPA analysis after each mutating command (`set`, `add`, `mv`, `rm`, `macro run`). Only the affected table's objects are checked, not the whole model - useful for fast feedback during iterative edits. | +| `bpa.onDeploy` | `true` | Run the BPA gate before `te deploy` executes. The deploy is aborted if any rule fires at severity ≥ error. Bypass per-invocation with `--skip-bpa`, or auto-fix with `--fix-bpa`. | +| `bpa.onSave` | `true` | Run the BPA gate before `te save -o` writes to disk. Bypass per-invocation with `--skip-bpa` or `--force`. | +| `bpa.builtInRules` | `true` | Include the curated built-in BPA rule set whenever the gate runs. Set to `false` to ignore built-ins entirely; the gate then runs only the rules configured via `bpa.rules` and any model-embedded rules. | +| `bpa.disabledBuiltInRuleIds` | `null` | IDs of individual built-in rules to exclude from the gate. Mutated by `te bpa rules disable ` / `te bpa rules enable ` - prefer those over editing the array directly. | +| `vertipaqOnRefresh` | `false` | After a successful refresh (`full`, `dataonly`, `automatic`, or `add`), automatically run VertiPaq analysis to show storage stats for the refreshed tables. Useful for catching unexpected cardinality or memory regressions immediately. | +| `interactiveEditMode` | `stage` | Default behavior for in-memory mutations inside `te interactive`. `stage` keeps mutations in memory until `save` is invoked (safest); `save` writes to source after every mutating command (use with care on remote sources - every `set` triggers an XMLA write); `revert` discards mutations after each command unless `--save` or `--stage` was passed. Per-command `--save` / `--revert` / `--stage` flags always override. | +| `disableTelemetry` | `false` | Opt out of anonymous usage telemetry. The CLI collects coarse-grained command usage data (command name, exit code, duration) to inform feature priority. The CLI never collects model content, paths, or query text. | + +```bash +te config set bpa.rules "/etc/te/team.json,/etc/te/strict.json" +te config set bpa.onDeploy true +te config set bpa.builtInRules false +te config set bpa.disabledBuiltInRuleIds "TE3_BUILT_IN_DATE_TABLE_EXISTS,TE3_BUILT_IN_HIDE_FOREIGN_KEYS" +``` + +### Format options + +Applied whenever the CLI invokes a DAX formatter (for `te format` and, when enabled, `autoFormat` on mutations). The CLI ships with an in-house formatter that works fully offline; opt into the SQL BI [daxformatter.com](https://www.daxformatter.com) web service via `formatOptions.useSqlBiDaxFormatter` if you need that style or want to match the behavior of TE2 or TE3 with "Use daxformatter.com..." enabled. + +| Key | Default | Description | +| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `formatOptions.useSemicolons` | `false` | Use `;` as the list separator (European/EU locale convention). The default `,` matches the en-US locale. | +| `formatOptions.shortFormat` | `false` | Prefer short, single-line formatting where possible instead of the default multi-line layout. | +| `formatOptions.skipSpaceAfterFunction` | `false` | Omit the space between a function name and its opening parenthesis (e.g. `SUM(x)` instead of `SUM (x)`). | +| `formatOptions.useSqlBiDaxFormatter` | `false` | Format DAX via the [SQL BI daxformatter.com](https://www.daxformatter.com) web service instead of the in-house formatter. Requires internet access. The in-house formatter (default) works offline and matches the Tabular Editor 3 Desktop default. | + +### Display + +Settings that control the CLI's terminal output and diagnostic verbosity. + +| Key | Default | Description | +| ------------------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `hidePreviewNotice` | `false` | Suppress the yellow preview banner. **Ignored within 14 days of expiry.** | +| `spinner` | `true` | Show animated progress indicators in the terminal. Disable for CI. | +| `debug` | `false` | Always enable debug logging (same as passing `--debug`). | + +### Profiles + +Saved connection profiles live under the `profiles` key. Don't edit them by hand - use `te profile set / remove / list`. See @te-cli-auth for profile management. + +Profiles can carry **overrides** that override the behavioral defaults above whenever the profile is active. This is how a dev profile can relax validation and BPA while a prod profile keeps them strict: + +```bash +te profile set dev --validate-on-mutation false --bpa-on-deploy false +te profile set prod --auto-format true +``` + +## BPA gate + +The BPA gate is the safety net that prevents a model with rule violations from being saved or deployed. It runs automatically when the following commands are executed: + +- `te deploy` runs the gate unless `--skip-bpa` is passed or `bpa.onDeploy` is `false`. +- `te save` runs the gate unless `--skip-bpa` (or `--force`) is passed or `bpa.onSave` is `false`. +- `te add`, `te set`, `te mv`, `te macro run` run the gate only when `bpa.onMutation` is `true`. + +The gate loads BPA rules from `bpa.rules` and, by default, the built-in rule set (controlled by `bpa.builtInRules`). Built-in rules can be individually excluded via `bpa.disabledBuiltInRuleIds` - managed with `te bpa rules disable ` / `te bpa rules enable `. + +When the gate fires and finds violations at severity ≥ `error`, the command fails with exit code `1` and a summary of the violations. Options to resolve: + +- `--fix-bpa` - apply the rule's `fixExpression` in memory for the deploy/save artifact; source files are not modified. +- `--skip-bpa` - disable the gate for this one command. +- `--bpa-rules ` - repeatable; override `bpa.rules` for this single `te deploy` or `te save` invocation. Built-in rules still apply unless `bpa.builtInRules` is `false`. + +Run `te bpa run` independently to preview the gate's behavior without deploying: + +```bash +te bpa run ./model --fail-on error +te bpa run ./model --fix --save # Apply fixes to the source +``` + +### Built-in BPA rules + +The CLI ships a single canonical set of built-in BPA rules embedded as a JSON resource. Built-in rules are read-only - `te bpa rules set` and `te bpa rules rm` refuse to mutate built-in IDs and point users at `te bpa rules disable` instead. To customize a built-in rule's behavior, copy it into your local rules file as a new rule with a different ID and disable the built-in. + +Both `bpa.builtInRules` and `bpa.disabledBuiltInRuleIds` apply consistently to the deploy/save/mutation gate **and** the manual `te bpa run` command - disabling a rule once via `te bpa rules disable` excludes it everywhere. + +## Post-mutation behavior + +When you run a mutating command (`te add`, `te set`, `te mv`, `te replace --save`, `te macro run`), the CLI performs these checks automatically: + +1. **TOM errors** are always surfaced. Invalid DAX or M in measures, columns, partitions, or calculation items always fails the command. +2. **Schema validation** (`validateOnMutation`, default `true`) verifies that `Table[Column]` references in DAX still resolve, cross-checking metadata consistency. +3. **DAX auto-format** (`autoFormat`, default `false`) formats any expressions touched by the mutation via the built-in DAX Formatter when enabled. +4. **BPA on mutation** (`bpa.onMutation`, default `false`) runs BPA after the mutation when enabled, warning or failing based on `--fail-on`. + +Disable a check with `te config set false`, or scope the relaxation to a specific environment via a profile. + +## Environment variables + +Use the following CLI-specific environment variables for paths, behavior, and diagnostics. For Azure authentication variables (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_CERTIFICATE_PATH`, etc.), see @te-cli-auth. + +| Variable | Purpose | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TE_CONFIG` | Path to an alternative config file. Honored by every `te config` operation (`show`, `set`, `init`, `paths`). | +| `TE_MACROS_PATH` | Override the macros file path (second in resolution order - see above). Read by `te macro` commands. | +| `TE_BPA_RULES` | Override the BPA rules file/URL list used by `te bpa run` and `te bpa rules` subcommands. | +| `TE_BPA_CONFIG` | Override the path to the BPA gate config (`.te-bpa.json`) the deploy/save gate reads. | +| `TE3_EXE_PATH` | Path to the Tabular Editor 3 desktop binary. Used **only** by `te open`; safe to leave unset on Linux/macOS or when you don't use `te open`. Falls back to `PATH` lookup. | +| `TE_DEBUG` | Set to `1` to enable debug logging globally (same as `--debug` or `debug: true` in config). | +| `NO_SPINNER` | Set to `1` or `true` to disable animated progress indicators (alternative to `spinner: false` in config). | +| `CI` | Auto-detected. When `1` or `true`, the CLI disables the spinner and switches to plain output. Most CI runners set this automatically. | +| `TE_SESSION` | Override the per-terminal session ID used for active-connection state. Useful for running multiple isolated CLI sessions inside the same shell, e.g. in parallel CI matrix jobs. | +| `TE_COMPAT` | Set to `te2` to force TE2-compatibility mode - see @te-cli-migrate. | + +## Related pages + +- @te-cli-auth - profiles, authentication, and credential storage. +- @te-cli-commands - `te config` subcommands. +- @te-cli-cicd - configuring the BPA gate for pipelines. diff --git a/localizedContent/es/content/features/te-cli/te-cli-install.md b/localizedContent/es/content/features/te-cli/te-cli-install.md new file mode 100644 index 000000000..11c270639 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-install.md @@ -0,0 +1,201 @@ +--- +uid: te-cli-install +title: Installation and Setup +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Installation and Setup + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI ships as a single self-contained executable named `te` (`te.exe` on Windows). It has no external runtime dependencies. + +## Descargar + +1. Sign in at [tabulareditor.com](https://tabulareditor.com/download-tabular-editor-cli) with a Tabular Editor account. +2. Download the archive for your platform and architecture: + + | Platform | 64-bit (Intel/AMD) | ARM64 | Archive | + | -------- | ---------------------------------------------- | -------------------------------------------------------- | --------- | + | Windows | `te-win-x64.zip` | `te-win-arm64.zip` | `.zip` | + | macOS | `te-osx-x64.tar.gz` (Intel) | `te-osx-arm64.tar.gz` (Apple Silicon) | `.tar.gz` | + | Linux | `te-linux-x64.tar.gz` | `te-linux-arm64.tar.gz` | `.tar.gz` | + + Pick the ARM64 build on Apple Silicon Macs (M1 and newer), Windows on ARM devices, and ARM-based Linux servers (including AWS Graviton, Azure Ampere, and Raspberry Pi 64-bit). Pick the `x64` build on everything else. + +## Install + +Unzip the archive into a folder of your choice and add that folder to `PATH` so you can invoke `te` from any working directory. + +### Windows (PowerShell) + +#### x64 + +```powershell +Expand-Archive te-win-x64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\te" +[Environment]::SetEnvironmentVariable( + "PATH", + [Environment]::GetEnvironmentVariable("PATH", "User") + ";$env:LOCALAPPDATA\Programs\te", + "User") +``` + +#### ARM64 + +```powershell +Expand-Archive te-win-arm64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\te" +[Environment]::SetEnvironmentVariable( + "PATH", + [Environment]::GetEnvironmentVariable("PATH", "User") + ";$env:LOCALAPPDATA\Programs\te", + "User") +``` + +### macOS + +#### Apple Silicon (ARM64) + +```bash +mkdir -p ~/.local/bin +tar -xzf te-osx-arm64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc +``` + +#### Intel (x64) + +```bash +mkdir -p ~/.local/bin +tar -xzf te-osx-x64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc +``` + +On macOS, the binary is signed with our Apple Developer ID and notarized by Apple, so the first run completes without a "cannot verify developer" Gatekeeper warning. Network access on first run is recommended so Gatekeeper can fetch the notarization ticket; offline first-runs may briefly prompt before being unblocked once network returns. + +### Linux + +#### x64 + +```bash +mkdir -p ~/.local/bin +tar -xzf te-linux-x64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc +``` + +#### ARM64 + +```bash +mkdir -p ~/.local/bin +tar -xzf te-linux-arm64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc +``` + +> [!NOTE] +> The PATH change takes effect in **new** shell sessions. To run `te` in the shell where you ran the install, open a new terminal, or reload your profile: `source ~/.bashrc` / `source ~/.zshrc` on macOS/Linux, or close and reopen PowerShell on Windows. + +## Verify + +Check the installed version and list available commands: + +```bash +te --version +te --help +``` + +`te --help` prints a colorized help index grouping commands by family. Every subcommand accepts `--help` for detailed usage: + +```bash +te deploy --help +te bpa run --help +``` + +## Hide the preview banner + +The CLI prints a yellow preview banner on stderr by default. To suppress it run: + +```bash +te config set hidePreviewNotice true +``` + +> [!WARNING] +> The banner reappears on every command within **14 days of the preview end date** (2026-09-30), regardless of `hidePreviewNotice`. This ensures you have visible warning before the CLI stops functioning. + +## Shell completion + +The CLI provides tab-completion scripts for **Bash**, **Zsh**, and **PowerShell**. Pick the block that matches your shell — each one installs the completion persistently for new shell sessions. + +### Bash (macOS/Linux) + +```bash +mkdir -p ~/.local/share/bash-completion/completions +te completion bash > ~/.local/share/bash-completion/completions/te +``` + +### Zsh (macOS/Linux) + +```zsh +mkdir -p ~/.zfunc +te completion zsh > ~/.zfunc/_te +echo 'fpath=(~/.zfunc $fpath); autoload -U compinit; compinit' >> ~/.zshrc +``` + +### PowerShell (Windows/macOS/Linux) + +```powershell +Add-Content $PROFILE 'te completion pwsh | Out-String | Invoke-Expression' +``` + +Open a new shell session for completion to take effect. + +Completion covers subcommands, global flags, and model paths (where tab-completion against the filesystem is meaningful). + +## Cross-platform feature matrix + +Most features are identical across platforms. A handful depend on Windows-only transports: + +| Feature | Windows | macOS / Linux | +| ---------------------------------------------------------------------------------------------- | ------- | ------------- | +| Load/save BIM and TMDL | Yes | Yes | +| Deploy to Power BI / Fabric / Azure Analysis Services | Yes | Yes | +| Best Practice Analyzer and VertiPaq Analyzer | Yes | Yes | +| C# scripting | Yes | Yes | +| DAX queries against cloud models | Yes | Yes | +| Authentication: browser, device-code, service principal, env, managed identity | Yes | Yes | +| Connect to local SSAS instance (TCP transport) | Yes | **No** | +| Connect to Power BI Desktop (named-pipe transport) | Yes | **No** | + +> [!IMPORTANT] +> Local SSAS and Power BI Desktop connections rely on Windows-only transport protocols. All cloud-based workflows (Power BI Service, Fabric, Azure Analysis Services) work on every platform. + +## Updating + +To update to a newer preview build, download the latest archive and overwrite the previous installation. Configuration and cached credentials are stored outside the install folder (see and ) and are preserved across updates. + +## Uninstalling + +1. Delete the install folder. +2. Remove the PATH entry. +3. (Optional) Clear cached credentials and config: + - Run `te auth logout` first - it removes all cached tokens and SPN records from the active backend (OS keystore or file fallback). + - Delete `~/.config/te/` (config and saved profiles). + - Delete `~/.te-cli/` (residual cache files; only present when the file fallback was in use, or as legacy from older CLI builds). + - To also purge the OS-native keystore entries - usually unnecessary, since `te auth logout` already clears them - see: + - **Windows:** Credential Manager → Windows Credentials → entries named `com.tabulareditor.cli...` or `te-cli`. + - **Linux:** `secret-tool search Component te-cli` and `secret-tool clear ...`, or use seahorse. + - **macOS:** Keychain Access → search for `com.tabulareditor.cli`. + +## Next steps + +- @te-cli-auth - authenticate to Power BI, Fabric, or Azure Analysis Services. +- @te-cli-commands - full command reference. +- @te-cli-interactive - guided REPL mode. diff --git a/localizedContent/es/content/features/te-cli/te-cli-interactive.md b/localizedContent/es/content/features/te-cli/te-cli-interactive.md new file mode 100644 index 000000000..c264d93f0 --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-interactive.md @@ -0,0 +1,98 @@ +--- +uid: te-cli-interactive +title: Interactive Mode +author: Peer Grønnerup +updated: 2026-05-12 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Interactive Mode + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +Interactive mode is a guided read-eval-print loop (REPL) for exploring a model from the terminal. It's the gentlest on-ramp for users who are new to command lines, and a convenient workspace for ad-hoc sessions against a single model. + +## Starting a session + +To Start a session run any of these commands: + +```bash +te interactive # Start and connect to a model later +te interactive ./model # Start with a local model +te interactive -s MyWorkspace -d MyModel # Start with a remote model +``` + +The session prints a welcome banner, shows the active model, and opens you at a model-aware prompt: + +![Tabular Editor CLI interactive mode session](~/content/assets/images/features/cli/cli-interactive-mode.png) + +If no model is set, the prompt is just `te>` - simply use `connect` for connection picker, `connect ` or `connect ` to connect to one. + +## Commands inside the session + +Once a REPL has started, every `te` subcommand is available **without the `te` prefix**: + +``` +ls tables +get "Sales/Revenue" -q expression +query -q "EVALUATE TOPN(5, 'Sales')" +bpa run --fail-on error +``` + +Each command accepts `--help` the same way it does outside the session: + +``` +deploy --help +``` + +## Quoting and DAX-style paths + +The REPL line splitter recognises the same quoting forms as [object paths](xref:te-cli-commands#object-paths) so DAX-shaped references are interpreted as a single argument: + +- `'...'` and `"..."` - single- and double-quoted segments. The quote characters are stripped, doubled quotes escape a literal occurrence. +- `[...]` - bracketed segment. **Brackets are preserved** in the resulting argument so a path like `'Internet Sales'[Sales Amount]` reaches the command as one token that the path parser can re-interpret as a DAX reference. Doubled closing brackets (`]]`) stay verbatim for the same reason. + +``` +get 'Internet Sales'[Sales Amount] # One argument, DAX form +get [Total Sales] # Lone-bracket model-wide lookup +ls 'Net Sales'/'Sales Amount' # Quoted segments with a slash separator +``` + +Unterminated groups absorb to end of line, so a stray opening quote or bracket fails with an explicit error rather than splitting silently. + +## Built-in REPL commands + +These are handled by the REPL itself, not the regular command tree: + +| Command | Purpose | +| ---------------------- | ------------------------------------------------- | +| `help` or `?` | List available commands. | +| `status` or `pwd` | Show the active model/connection. | +| `clear` or `cls` | Clear the screen. | +| `exit`, `quit`, or `q` | Exit interactive mode. | + +## Guided prompts + +When interactive mode is active, commands that need missing input prompt for it instead of failing. Running `auth` without a subcommand opens a picker for Login / Status / Logout; running `deploy` without `--force` shows a summary and asks for confirmation (`n` is the safe default). + +To disable prompts for a single command inside the session, pass `--non-interactive`. + +## When to use interactive vs. non-interactive + +- **Interactive mode** is best for exploration, learning the CLI, one-off bulk edits against a single model, and demos. +- **Non-interactive mode** (the default outside `te interactive`) is what you reach for when scripting, automating, or running in CI. See @te-cli-automation and @te-cli-cicd. + +The two share the same command tree - anything you run inside `te interactive` can be pasted into a shell script by prefixing it with `te`. + +## Related pages + +- @te-cli-commands - full command reference. +- @te-cli-auth - connect to workspaces and manage profiles. +- @te-cli-automation - when to leave interactive mode. diff --git a/localizedContent/es/content/features/te-cli/te-cli-limitations.md b/localizedContent/es/content/features/te-cli/te-cli-limitations.md new file mode 100644 index 000000000..d7d378f8d --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-limitations.md @@ -0,0 +1,90 @@ +--- +uid: te-cli-limitations +title: Known Limitations +author: Peer Grønnerup +updated: 2026-05-20 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Known Limitations + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +This page lists known limitations of the Tabular Editor CLI (`te`) so you can plan around them and avoid common pitfalls. It is updated with each release; if you find an issue that is not listed here, please file it in the public [TabularEditor/CLI](https://github.com/TabularEditor/CLI) repository. + +> [!NOTE] +> Limitations are grouped by area. Each entry describes the constraint and, where one exists, a workaround or the recommended CLI-friendly alternative. + +## Scripting + +The CLI runs C# scripts (`te script`) against the same `Model` object you use in Tabular Editor 2 and 3, but it is a headless console host. Anything that depends on a Windows Forms UI, on the TOM Explorer selection, or on a live UI-side service (macro registry, online DAX Formatter, live VertiPaq Analyzer) behaves differently - usually by being empty, no-op, or returning an error. + +| Limitation | Notes / Workaround | +| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`System.Windows.Forms` not loaded** | The CLI uses a cross-platform `TOMWrapper` build that strips all WinForms-coupled code; the WinForms assembly is never loaded into the AppDomain. Scripts that reference `System.Windows.Forms` types (`MessageBox`, `Form`, file pickers, custom dialogs, …) fail to compile. Refactor any UI interaction into script arguments, environment variables, or stdin. | +| **`Selected.` returns an empty enumerable** | `Selected.Tables`, `Selected.Measures`, `Selected.Columns`, `Selected.Hierarchies`, etc. iterate to nothing in the CLI - no compile or runtime error, just no rows. Replace with explicit lookups: `Model.AllMeasures.Where(...)`, `Model.Tables["Sales"].Measures`, or pass object paths via `te script --args`. | +| **`Selected.` throws an error at runtime** | `Selected.Table`, `Selected.Measure`, `Selected.Column`, `Selected.Hierarchy`, etc. return an error because they require exactly one selected object of that type and the CLI selection is always empty. Reference the object directly - e.g. `Model.Tables["Sales"]`. | +| **`Selected.ActivePerspectives` and `Selected.ActiveCulture`** | Always return an empty collection and `null` respectively. Set the perspective or culture explicitly in the script if needed. | +| **`Select` dialogs throw `NotSupportedException`** | `SelectTable`, `SelectColumn`, `SelectMeasure`, `SelectObject`, `SelectObjects` (and all overloads) return the following error: _"Object selection dialogs … are not available in CLI scripts. Pre-select the object by name or path before scripting."_ Resolve targets up front from script arguments, config, or by querying the model. | +| **`Info` / `Warning` / `Error` / `Output` write to the console** | These still work, but route to stdout/stderr instead of opening a dialog. They never block and never offer an "ignore further popups" prompt. Safe to use in CI. | +| **`ShowPrompt(...)` always returns `Cancel`** | No interactive confirmation is possible. Pre-decide the answer via script arguments or configuration. | +| **`SuspendWaitForm` / `WaitFormVisible` are no-ops** | The "Please wait" spinner is a TE3 UI element. `WaitFormVisible` is a settable flag with no visual effect, and `SuspendWaitForm` is silently ignored - existing scripts continue to compile. | +| **`host.Macro(...)` / `CustomAction(...)` throws and error** | The CLI does not load `%APPDATA%/TabularEditor3/MacroActions.json`, so invoking a macro from inside a script returns an error. Inline the macro logic, or call the macro's underlying script file directly. | +| **`table.GetCardinality()` / `column.GetTotalSize()` return 0** | The in-script VertiPaq cardinality helpers have no live VPA in the CLI host. For VPA statistics, load a VPAX explicitly and use `host.Vpa.*`, or run [`te vertipaq`](xref:te-cli-commands#vertipaq). | + +## Best Practice Analyzer + +| Limitation | Notes / Workaround | +| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **BPA rule sources must be HTTPS URLs or local file paths** | Only `https://` URLs and bare local file paths are accepted. `http://` is recognized but deliberately rejected at load time with a clear error - BPA rules are executable rule expressions, and fetching them over an unauthenticated channel would be a tampering risk. Other URL schemes (`file://`, `ftp://`, …) are not supported. Applies to both `te bpa run --rules` and the rule list configured via [`te config set`](xref:te-cli-commands#config-show--paths--init--set). | +| **Rule-URL validation runs at gate time, not on `te config set`** | A typo such as `http://` is accepted by `te config set` and only surfaces when BPA actually runs. After editing the configured rule sources, run `te bpa run` (or `te validate`) once to verify each URL loads. | +| **`--rules` does not suppress built-in rules** | When `te bpa run --rules ` is passed, the supplied rules replace the entries in [`bpa.rules`](xref:te-cli-commands#config-show--paths--init--set) and `TE_BPA_PATH` for that invocation, but the built-in defaults still load alongside. To run only the explicit rule file, also pass `--no-defaults`. | +| **No per-invocation flag to skip `bpa.rules` config** | Once `bpa.rules` is configured, every `te bpa run` loads those rules in addition to the built-ins. There is currently no flag to skip the configured rule files for a single run. Workaround: pass `--rules ` explicitly - the flag fully replaces `bpa.rules` and `TE_BPA_PATH` for that invocation. | + +## Validation + +| Limitation | Notes / Workaround | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`te validate` cannot auto-fix Code Action violations** | `te validate` reports Code Action violations but offers no CLI flag to apply the suggested fix. Apply the fix in Tabular Editor 3, or use `te bpa run --fix` for the subset of Code Actions that overlap with BPA rules. | + +## Model I/O + +| Limitation | Notes / Workaround | +| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **`--serialization` cannot combine a serialization with a PBIP container** | The `--serialization` option on [`te save`](xref:te-cli-commands#save) treats `bim`, `tmdl`, `te-folder`, and `pbip` as mutually exclusive, so you cannot currently produce a PBIP container around a TMSL-serialized (`.bim`) model. Save TMDL inside PBIP, or save `.bim` outside a PBIP wrapper. | + +## Authentication + +| Limitation | Notes / Workaround | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Only one cached identity per auth method** | The CLI caches one UPN (interactive) identity and one SPN (service principal) identity at a time. Switching to a different user or tenant under the same auth method requires `te auth logout` followed by `te auth login` again, which invalidates the previous cache. | + +## Command-line input + +| Limitation | Notes / Workaround | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **DAX object paths with spaces must be enclosed in shell quotes** | When a table or column name contains spaces, the entire DAX object reference must be wrapped in shell quotes from the terminal: `te get "'My Table'[My Column]"`. Without the outer quotes, the shell splits the path into multiple arguments and parsing fails. Inside [`te interactive`](xref:te-cli-interactive) no shell quoting is needed because the REPL receives the raw input before the shell breaks it into arguments. | + +## TE2 parity + +| Limitation | Notes / Workaround | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`te schemacheck` is not yet implemented** | The TE2 `-SC` / `-SCHEMACHECK` flag has no `te` equivalent today; schema-drift detection against source data sources is planned for a future release. See @te-cli-migrate for the full TE2-to-`te` flag-mapping table. | + +## Reporting a missing limitation + +If a behavior surprises you and it's not listed here, please open an issue at [TabularEditor/CLI](https://github.com/TabularEditor/CLI/issues) with the command you ran, the output you saw, and the output you expected. Confirmed limitations are added to this page in the next release. + +## Related pages + +- @csharp-scripts - full C# scripting reference (UI and CLI). +- @script-helper-methods - list of `ScriptHost` helper methods and how they behave in the CLI. +- @te-cli-commands - full CLI command reference. +- @te-cli-automation - patterns for using the CLI in scripts and pipelines. diff --git a/localizedContent/es/content/features/te-cli/te-cli-migrate.md b/localizedContent/es/content/features/te-cli/te-cli-migrate.md new file mode 100644 index 000000000..6ae97fa4f --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli-migrate.md @@ -0,0 +1,111 @@ +--- +uid: te-cli-migrate +title: Migrating from the TE2 Command Line +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Migrating from the TE2 Command Line + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +Teams with existing build pipelines that invoke `TabularEditor.exe` with TE2-style flags (`-S`, `-A`, `-D`, `-O`, `-C`, etc.) can adopt the new CLI incrementally. The Tabular Editor CLI accepts both command shapes: the new subcommand-based form (`te deploy`, `te bpa run`, …) and the legacy TE2 flag syntax, via a built-in compatibility layer. + +For the legacy TE2 Windows command-line reference, see @command-line-options. + +## How TE2 compatibility works + +TE2 compatibility mode is activated in any of three ways: + +1. **Binary name.** Rename `te` to `te2` (or symlink it) and the CLI runs in TE2-exact mode. This is the drop-in replacement path: swap `TabularEditor.exe` for `te2` in your existing pipeline and the same arguments work. +2. **Environment variable.** Set `TE_COMPAT=te2` before invoking `te` to force TE2 mode. +3. **Auto-detection.** If the first argument isn't a `te` subcommand (`load`, `deploy`, …) and at least one recognized TE2 flag appears somewhere in the argument list, the CLI auto-routes to TE2 mode. This means most existing TE2 invocations work without any changes. + +```bash +# All three are equivalent - each runs in TE2 mode +./te2 Model.bim -S fix.csx -D "localhost\tabular" MyDB -O +TE_COMPAT=te2 te Model.bim -S fix.csx -D "localhost\tabular" MyDB -O +te Model.bim -S fix.csx -D "localhost\tabular" MyDB -O +``` + +> [!NOTE] +> TE2 mode runs the same `Load → Scripts → Schema Check → Save → BPA → Deploy → TRX` pipeline as `TabularEditor.exe`, including context-sensitive flag behavior (e.g., `-S` after `-D` means `-SHARED`, not `-SCRIPT`). + +## The migrate command + +Use `te migrate` as a live reference for how TE2 flags map to the new CLI. It prints a colorized table of every known TE2 flag, its status (supported, renamed, planned), and the equivalent `te` command. + +```bash +te migrate # Full flag mapping table +te migrate -A # Look up a single flag +te migrate --output-format json # Machine-readable mapping +``` + +Refer to the output of the `te migrate` command for the current mapping that reflects the CLI version you have installed. + +## Flag mapping (curated subset) + +A non-exhaustive summary of the most commonly used flags. Run `te migrate` for the full list. + +| TE2 flag | New CLI equivalent | Notes | +| ------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `file` (positional) | `te ` or global `--model` | First positional arg on most commands. | +| `server`, `database` | `te connect ` or `te deploy ` | Server is no longer a global positional. | +| `-L` / `-LOCAL` | `te connect --local` | Windows only. | +| `-S` / `-SCRIPT` | `te script -s ` or `-e "code"` | Supports multiple scripts, inline code, and stdin. | +| `-A` / `-ANALYZE` | `te bpa run --rules ` | Supports `--fail-on`, `--fix`, multiple rule files. | +| `-AX` / `-ANALYZEX` | `te bpa run --rules ` (without `--model-rules`) | Excluding model-embedded rules is the new default. | +| `-B` / `-BIM` | `te save -o --serialization bim` | | +| `-F` / `-FOLDER` | `te save -o --serialization te-folder` | After `-D`, TE2's `-F` means `-FULL` - see `--deploy-full`. | +| `-TMDL` | `te save -o --serialization tmdl` | TMDL is the default save format. | +| `-D` / `-DEPLOY` | `te deploy ` | Separate command with named options. | +| `-O` / `-OVERWRITE` | (default) or `--create-only` to opt out | Overwrite is the default in the new CLI. | +| `-C` / `-CONNECTIONS` | `te deploy --deploy-connections` | | +| `-P` / `-PARTITIONS` | `te deploy --deploy-partitions` | | +| `-Y` / `-SKIPPOLICY` | `te deploy --deploy-partitions --skip-refresh-policy` | Requires `--deploy-partitions`. | +| `-SHARED` | `te deploy --deploy-shared-expressions` | After `-D`, TE2's `-S` means `-SHARED`. | +| `-R` / `-ROLES` | `te deploy --deploy-roles` | | +| `-M` / `-MEMBERS` | `te deploy --deploy-role-members` | | +| `-FULL` (after `-D`) | `te deploy --deploy-full` | Equivalent to overwrite + connections + partitions + shared + roles + role-members. | +| `-X` / `-XMLA ` | `te deploy ... --xmla ` | Use `-` for stdout. | +| `-V` / `-VSTS` | `--ci vsts` on `validate`, `bpa run`, `deploy` | Emits `##vso[...]` annotations to stderr. | +| `-G` / `-GITHUB` | `--ci github` | Emits `::error::` / `::warning::` annotations. | +| `-T` / `-TRX ` | `--trx ` on `validate`, `bpa run`, `test run` | VSTEST `.trx` file for Azure DevOps test publishing. | +| `-W` / `-WARN` | (default) | Warnings always reported in deploy results. | +| `-E` / `-ERR` | (default) | Deploy returns non-zero exit on DAX errors. | +| `-SC` / `-SCHEMACHECK` | _Not yet implemented._ | TE2 schema check connects to actual data sources. Different from `te validate` (DAX semantic validation, no data source connection). | +| `-L` / `-LOGIN ` (after `-D`) | `te auth login -u -p -t ` | Use service principal or env-based credentials. The login is cached, so subsequent commands acquire tokens silently - see @te-cli-auth. | + +## Migration playbook + +The recommended path from a TE2-based pipeline to the new CLI: + +1. **Drop-in replacement.** Replace `TabularEditor.exe` with `te` (or `te2`) in your existing pipeline. Verify the pipeline still runs - TE2 compatibility handles most invocations unchanged. +2. **Replace flags incrementally.** Convert one flag group at a time: + - Start with `-A` / `-AX` → `te bpa run` to pick up richer BPA output (`--fail-on`, `--fix`, `--trx`). + - Then `-D` → `te deploy` for fine-grained deploy control. + - Finally `-V` / `-G` → `--ci vsts` / `--ci github`. +3. **Switch to non-interactive CI flags.** Add `--non-interactive --ci ` to every `te` command and remove any `start /wait` wrappers - the new CLI is a regular console binary and doesn't need them. +4. **Adopt service principal auth.** Replace `-D -L ` with `te auth login -u ... -p ... -t ...` or an environment-credential pipeline step. See @te-cli-auth. + +## Important differences + +- **BPA gate on deploy.** `te deploy` now runs BPA as a pre-flight gate by default. Use `--skip-bpa` to preserve the old behavior, or `--fix-bpa` to auto-fix violations before deploy. See @te-cli-config. +- **Interactive confirmation on deploy.** `te deploy` prompts for confirmation by default (with `n` as the safe default answer). CI pipelines must pass `--force`. +- **Structured output.** Every command supports `--output-format json` for machine-readable output - see @te-cli-automation. +- **No `start /wait` needed.** The new CLI is a regular console binary; invoke it directly in shell scripts, PowerShell, and CI tasks. +- **Cross-platform.** The CLI runs on Windows, macOS, and Linux. Local SSAS and Power BI Desktop connections remain Windows-only. + +## Related pages + +- @command-line-options - the legacy TE2 command-line reference. +- @te-cli-commands - the new CLI's full command reference. +- @te-cli-cicd - pipeline examples for GitHub Actions and Azure DevOps. diff --git a/localizedContent/es/content/features/te-cli/te-cli.md b/localizedContent/es/content/features/te-cli/te-cli.md new file mode 100644 index 000000000..c3c43e33c --- /dev/null +++ b/localizedContent/es/content/features/te-cli/te-cli.md @@ -0,0 +1,112 @@ +--- +uid: te-cli +title: Tabular Editor CLI (Limited Public Preview) +author: Peer Grønnerup +updated: 2026-05-12 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Tabular Editor CLI (Limited Public Preview) + +The Tabular Editor CLI (`te`) is a cross-platform command-line interface for Power BI and Analysis Services semantic models. It runs on Windows, macOS, and Linux as a single self-contained executable and is based on the same foundation that powers Tabular Editor 3. + +With the Tabular Editor CLI you can inspect, edit, validate, deploy, refresh, and test semantic models from a terminal - against local TMDL or BIM files, Power BI Desktop, or semantic models in Fabric and Power BI Service workspaces. + +Unlike the Windows-only `TabularEditor.exe` command-line options (TE2) - which was designed primarily to automate C# scripts and macros from a desktop binary - `te` is a purpose-built, cross-platform CLI with structured output, predictable exit codes, and an interactive shell. This unlocks scenarios that our existing [TE2 CLI](xref:command-line-options) can't cover well: terminal-driven model work on macOS and Linux, AI agents driving model changes directly, and clean drop-in for any modern CI runner. + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +## Built for three audiences + +Three design pillars run through every command: + +- **Structured output** — JSON, CSV, TMDL, TMSL alongside default human-readable text. +- **Non-interactive mode** — a global `--non-interactive` flag that disables prompts and fails fast. +- **Clear errors** — written to stderr with predictable exit codes. + +Together they make the same binary work well for three very different audiences: + +- **Humans** - scripting bulk edits, exploring a model from the terminal, composing commands in shell pipelines. +- **AI agents** - token-lean JSON, machine-parseable error shapes, exit codes that signal success or failure without parsing stdout. +- **CI/CD pipelines** - non-interactive execution, GitHub Actions and Azure DevOps annotations, VSTEST-compatible test results. + +## What the CLI can do + +The CLI organizes more than 50 commands into 10 families. Each family maps to a concrete stage of the semantic-model lifecycle. + +See @te-cli-commands for a full command reference with syntax, options, and examples for each command. Click any example command in the table to jump straight to its reference entry. + +| Family | What it does | Example commands | +| ------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Model I/O](xref:te-cli-commands#model-io) | Load, save, convert, initialize models | [`te load`](xref:te-cli-commands#load), [`te save`](xref:te-cli-commands#save), [`te init`](xref:te-cli-commands#init) | +| [Model Editing](xref:te-cli-commands#model-editing) | Get/set properties, add/remove/move objects | [`te set`](xref:te-cli-commands#set), [`te add`](xref:te-cli-commands#add), [`te rm`](xref:te-cli-commands#rm), [`te mv`](xref:te-cli-commands#mv) | +| [Inspection](xref:te-cli-commands#inspection) | List objects, search, diff, dependency analysis | [`te ls`](xref:te-cli-commands#ls), [`te find`](xref:te-cli-commands#find), [`te diff`](xref:te-cli-commands#diff), [`te deps`](xref:te-cli-commands#deps) | +| [Analysis & Quality](xref:te-cli-commands#analysis-and-quality) | Validate, run BPA, format DAX, analyze storage | [`te validate`](xref:te-cli-commands#validate), [`te bpa run`](xref:te-cli-commands#bpa-run), [`te format`](xref:te-cli-commands#format), [`te vertipaq`](xref:te-cli-commands#vertipaq) | +| [Execution](xref:te-cli-commands#execution) | Run DAX queries, C# scripts, macros | [`te query`](xref:te-cli-commands#query), [`te script`](xref:te-cli-commands#script), [`te macro`](xref:te-cli-commands#macro) | +| [Deployment & Refresh](xref:te-cli-commands#deployment-and-refresh) | Deploy to workspace, trigger refresh, incremental refresh | [`te deploy`](xref:te-cli-commands#deploy), [`te refresh`](xref:te-cli-commands#refresh), [`te incremental-refresh`](xref:te-cli-commands#incremental-refresh) | +| [Testing](xref:te-cli-commands#testing) | Assertion tests, snapshots, A/B comparison | [`te test run`](xref:te-cli-commands#test-run) | +| [Connection & Authentication](xref:te-cli-commands#connection-and-auth) | Connect to workspaces, manage authentication and profiles | [`te connect`](xref:te-cli-commands#connect), [`te auth`](xref:te-cli-commands#auth-login--status--logout), [`te profile`](xref:te-cli-commands#profile-list--show--set--remove) | +| [Configuration](xref:te-cli-commands#configuration) | Settings and licensing | [`te config`](xref:te-cli-commands#config-show--paths--init--set) | +| [Shell](xref:te-cli-commands#shell) | Interactive mode, shell completions | [`te interactive`](xref:te-cli-commands#interactive), [`te completion`](xref:te-cli-commands#completion) | + +## Getting started + +1. **Sign up or sign in** at [tabulareditor.com](https://tabulareditor.com/download-tabular-editor-cli) with a Tabular Editor account. +2. **Download and install** - see @te-cli-install for Windows, macOS, and Linux instructions. +3. **Authenticate** - run `te auth login` to connect to Power BI or Fabric. See @te-cli-auth. +4. **Run your first command** - `te --help` lists every command; `te --help` shows detailed options. + +A first look at a live model takes two commands: + +```bash +te auth login +te ls -s MyWorkspace -d MyModel +``` + +![Tabular Editor CLI te ls example output](~/content/assets/images/features/cli/cli-command-ls.png) + +## Preview notice + +Every command prints a yellow preview banner on stderr by default: + +![Tabular Editor CLI preview notice banner](~/content/assets/images/features/cli/cli-preview-notice.png) + +To hide the preview notice, simply run: + +```bash +te config set hidePreviewNotice true +``` + +> [!WARNING] +> The banner reappears on every command within **14 days of the preview end date** (2026-09-30), regardless of `hidePreviewNotice`. This ensures you have visible warning before the CLI stops functioning. + +## License outlook + +During Limited Public Preview, the CLI does not require a license; you only need a Tabular Editor account to download it. At General Availability (GA) the CLI will require a license; pricing is still being finalized and will be announced ahead of GA. + +## Feedback and community + +During the preview, bug reports, feature requests, and general discussion happen in the public [TabularEditor/CLI](https://github.com/TabularEditor/CLI) repository on GitHub: + +- **Issues** - report bugs, request features, and track known problems. +- **Discussions** - ask questions, share feedback, and swap usage tips with other early adopters. + +The repository does not host the CLI source code; it exists to give the community a public place to reach us during the preview. + +## Next steps + +- @te-cli-install - download, install, verify. +- @te-cli-auth - authenticate to Power BI, Fabric, and Azure Analysis Services. +- @te-cli-commands - full command reference. +- @te-cli-config - configuration file and path overrides. +- @te-cli-interactive - guided REPL mode for new users. +- @te-cli-automation - structured output, scripting patterns for Python, PowerShell, and Bash. +- @te-cli-cicd - GitHub Actions and Azure DevOps pipeline examples. +- @te-cli-migrate - migrating from the Tabular Editor 2 command line. diff --git a/localizedContent/es/content/getting-started/editions.md b/localizedContent/es/content/getting-started/editions.md index 31d219674..1b94d45f9 100644 --- a/localizedContent/es/content/getting-started/editions.md +++ b/localizedContent/es/content/getting-started/editions.md @@ -13,129 +13,129 @@ applies_to: # Ediciones de Tabular Editor 3 -Este documento ofrece una visión general y una comparación de las distintas ediciones de Tabular Editor 3. +Este documento ofrece una descripción general y una comparación de las distintas ediciones de Tabular Editor 3. > [!NOTE] -> Las licencias de Tabular Editor 3 son **por desarrollador**. En otras palabras, solo las personas que usan el producto Tabular Editor 3 necesitarán una licencia. +> Las licencias de Tabular Editor 3 son **por desarrollador**. En otras palabras, solo necesitan licencia las personas que usan el producto Tabular Editor 3. -## Escenarios compatibles de modelado de Data model +## Escenarios de modelado de Data model compatibles -La principal diferencia entre las distintas ediciones de Tabular Editor 3 es qué tipos de escenarios de modelado de Data model tabulares admiten. Para entender esta diferencia, tenga en cuenta que Analysis Services (Tabular) existe en varias “variantes”: +La principal diferencia entre las distintas ediciones de Tabular Editor 3 es qué tipos de escenarios de modelado de Data model tabulares admiten. Para entender esta diferencia, tenga en cuenta que Analysis Services (Tabular) existe en varias "variantes": -- Power BI Desktop (asegúrate de entender las [limitaciones](xref:desktop-limitations)) -- Power BI Premium a través del punto de conexión XMLA (Premium Per User, **Premium Capacity [SKUs A, EM o P]**, **Fabric Capacity [SKUs F]**) -- SQL Server (2016+) Analysis Services (ediciones: Developer, Standard y **Enterprise**) -- Azure Analysis Services (niveles: Developer, Basic y **Standard**) +- Power BI Desktop (asegúrate de comprender las [limitaciones](xref:desktop-limitations)) +- Power BI Premium a través del punto de conexión XMLA (Premium Per User, **capacidad Premium [SKU A, EM o P]**, **capacidad de Fabric [SKU F]**) +- SQL Server (2016+) Analysis Services (ediciones: Developer, Standard, **Enterprise**) +- Azure Analysis Services (niveles: Developer, Basic, **Standard**) -Consideramos que las variantes **resaltadas** de Analysis Services son de nivel Enterprise y, por tanto, solo se pueden usar con la Edición Enterprise de Tabular Editor 3. +Consideramos que las variantes de Analysis Services **resaltadas** son de nivel Enterprise y, por tanto, solo pueden usarse con la Edición Enterprise de Tabular Editor 3. > [!IMPORTANT] -> Tabular Editor solo permite editar Data models con un nivel de compatibilidad 1200 o superior. Este es el valor predeterminado en cualquier instancia de Analysis Services a partir de SQL Server 2016. Por el mismo motivo, Tabular Editor no es compatible con Excel PowerPivot, ya que usa un nivel de compatibilidad anterior. - -Consulta la matriz siguiente para ver el resumen completo de escenarios compatibles: - -| Escenario / Edición | Desktop | Business | Enterprise | -| ------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------- | -| Herramienta externa para Power BI Desktop | ✔ | ✔ | ✔ | -| Cargar/guardar metadatos del modelo en disco\*\* | ❌ | ✔\* | ✔ | -| Modo del área de trabajo\*\*\* | ❌ | ✔\* | ✔ | -| Power BI Premium por usuario | ❌ | ✔ | ✔ | -| SQL Server Developer Edition - edición para desarrolladores | ❌ | ✔\* | ✔ | -| Edición Standard de SQL Server | ❌ | ✔ | ✔ | -| Edición Enterprise de SQL Server | ❌ | ❌ | ✔ | -| Nivel para desarrolladores de Azure AS | ❌ | ✔\* | ✔ | -| Nivel básico de Azure AS | ❌ | ✔ | ✔ | -| Nivel estándar de Azure AS | ❌ | ❌ | ✔ | -| Capacidad de Power BI Premium (SKUs P) | ❌ | ❌ | ✔ | -| Capacidad de Power BI Embedded (SKUs A/EM) | ❌ | ❌ | ✔ | -| Capacidad de Fabric (SKUs F) | ❌ | ❌ | ✔ | -| Semantic Bridge (Databricks) | ❌ | ❌ | ✔ | -| [Cuadro de diálogo de actualización avanzada](xref:advanced-refresh) | ❌ | ✔ | ✔ | -| [Licencia gratuita de Optimizador de DAX](xref:dax-optimizer-integration) | ❌ | ❌ | ✔ | - -\***Nota:** Se requiere la Edición Enterprise si el Data model de Analysis Services contiene perspectivas o tablas con varias particiones (no se aplica a los modelos de Power BI Desktop ni de Power BI Premium Per User). - -\*\***Nota:** Los formatos de archivo compatibles son: **.pbip** (Proyecto de Power BI), **.pbit** (Plantilla de Power BI), **.bim** (metadatos del modelo de Analysis Services), **.vpax** (Analizador VertiPaq) y **Database.json** (estructura de carpetas de Tabular Editor), **TMDL** (Lenguaje de definición de modelos tabulares). - -\*\*\***Nota:** El modo del área de trabajo permite a Tabular Editor 3 guardar simultáneamente los metadatos del modelo en disco y sincronizar una base de datos en cualquiera de las ediciones de Analysis Services o Power BI compatibles con la edición de Tabular Editor 3 adquirida. +> Tabular Editor solo permite editar Data models con nivel de compatibilidad 1200 o superior. Este es el valor predeterminado en cualquier instancia de Analysis Services a partir de SQL Server 2016. Por el mismo motivo, Tabular Editor no es compatible con PowerPivot para Excel, ya que usa un nivel de compatibilidad anterior. + +Consulta la matriz siguiente para ver el resumen completo de los escenarios compatibles: + +| Escenario / Edición | Desktop | Business | Enterprise | +| -------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------- | +| Herramienta externa para Power BI Desktop | ✔ | ✔ | ✔ | +| Cargar/guardar los metadatos del modelo en el disco\*\* | ❌ | ✔\* | ✔ | +| Modo del área de trabajo\*\*\* | ❌ | ✔\* | ✔ | +| Power BI Premium por usuario | ❌ | ✔ | ✔ | +| SQL Server Developer Edition | ❌ | ✔\* | ✔ | +| SQL Server Standard Edition | ❌ | ✔ | ✔ | +| SQL Server Edición Enterprise | ❌ | ❌ | ✔ | +| Nivel para desarrolladores de Azure AS | ❌ | ✔\* | ✔ | +| Nivel básico de Azure AS | ❌ | ✔ | ✔ | +| Nivel estándar de Azure AS | ❌ | ❌ | ✔ | +| Capacidad de Power BI Premium (SKUs P) | ❌ | ❌ | ✔ | +| Capacidad de Power BI Embedded (SKUs A/EM) | ❌ | ❌ | ✔ | +| Capacidad de Fabric (SKUs F) | ❌ | ❌ | ✔ | +| Puente semántico (Databricks) | ❌ | ❌ | ✔ | +| [Cuadro de diálogo de actualización avanzada](xref:advanced-refresh) | ❌ | ✔ | ✔ | +| [Licencia gratuita del Optimizador de DAX](xref:dax-optimizer-integration) | ❌ | ❌ | ✔ | + +\***Nota:** Se requiere la Edición Enterprise si el Data model de Analysis Services contiene perspectivas o tablas con varias particiones (no se aplica a los modelos de Power BI Desktop ni a los de Power BI Premium Per User). + +\*\***Nota:** Los formatos de archivo compatibles son: **.pbip** (Proyecto de Power BI), **.pbit** (Plantilla de Power BI), **.bim** (metadatos del modelo de Analysis Services), **.vpax** (Analizador VertiPaq) y **Database.json** (estructura de carpetas de Tabular Editor) y **TMDL** (Tabular Model Definition Language). + +\*\*\***Nota:** El modo del área de trabajo permite a Tabular Editor 3 guardar simultáneamente metadatos del modelo en disco y sincronizar una base de datos en cualquiera de las ediciones de Analysis Services o Power BI compatibles con la edición de Tabular Editor 3 adquirida. ## Restricciones de modelado -También restringimos algunas operaciones de modelado de datos dentro de Tabular Editor 3, en línea con las limitaciones de algunos niveles de servicio de Microsoft (Azure Analysis Services _Basic Tier_, SQL Server Analysis Services _Standard Edition_ y Power BI _Premium-Per-User_). +También restringimos algunas operaciones de modelado de datos dentro de Tabular Editor 3, en línea con las restricciones de determinados niveles de servicio de Microsoft (Azure Analysis Services _Basic Tier_, SQL Server Analysis Services _Standard Edition_ y Power BI _Premium-Per-User_). -En concreto, [Azure AS Basic Tier y SQL Server Standard Edition no admiten perspectivas, múltiples particiones ni DirectQuery](https://azure.microsoft.com/en-us/pricing/details/analysis-services/), por lo que los modelos de SSAS/Azure AS que usan estas funciones requieren la Edición Enterprise de TE3. +En concreto, [Azure AS Basic Tier y SQL Server Standard Edition no admiten perspectivas, varias particiones ni DirectQuery](https://azure.microsoft.com/en-us/pricing/details/analysis-services/), por lo que los modelos de SSAS/Azure AS que usan estas características requieren la Edición Enterprise de TE3. -Del mismo modo, [los Workspaces de Power BI Premium-Per-User no admiten los Datasets de Direct Lake](https://learn.microsoft.com/en-us/power-bi/enterprise/directlake-overview#prerequisites), por eso los modelos de Power BI que usan esta función también requieren la Edición Enterprise de TE3. +Del mismo modo, [los Workspace de Power BI Premium-Per-User no admiten los Dataset de Direct Lake](https://learn.microsoft.com/en-us/power-bi/enterprise/directlake-overview#prerequisites), por lo que los modelos de Power BI que usan esta característica también requieren la Edición Enterprise de TE3. -| Tipo de modelo | Funcionalidad | Business | Enterprise | -| --------------- | ------------------------- | ------------------------------------------------------- | ------------------------------------------------------- | -| Azure AS / SSAS | Perspectivas | ❌ | ✔ | -| Azure AS / SSAS | Múltiples particiones | ❌ | ✔ | -| Azure AS / SSAS | DirectQuery\* | ✔ | ✔ | -| Azure AS / SSAS | Direct Lake | N/D | N/D | -| Power BI | Perspectivas\*\* | ✔ | ✔ | -| Power BI | Múltiples particiones\*\* | ✔ | ✔ | -| Power BI | DirectQuery | ✔ | ✔ | -| Power BI | Direct Lake | ❌ | ✔ | +| Tipo de modelo | Característica | Business | Enterprise | +| --------------- | ---------------------- | ------------------------------------------------------- | ------------------------------------------------------- | +| Azure AS / SSAS | Perspectivas | ❌ | ✔ | +| Azure AS / SSAS | Varias particiones | ❌ | ✔ | +| Azure AS / SSAS | DirectQuery\* | ✔ | ✔ | +| Azure AS / SSAS | Direct Lake | N/A | N/A | +| Power BI | Perspectivas\*\* | ✔ | ✔ | +| Power BI | Varias particiones\*\* | ✔ | ✔ | +| Power BI | DirectQuery | ✔ | ✔ | +| Power BI | Direct Lake | ❌ | ✔ | -\***Nota:** Analysis Services en SQL Server Standard Edition anterior a 2019 no admite DirectQuery. Tampoco lo admite el nivel Basic de Azure AS. [Más información](https://learn.microsoft.com/en-us/analysis-services/analysis-services-features-by-edition?view=asallproducts-allversions#tabular-models). +\***Nota:** Analysis Services en SQL Server Standard Edition anteriores a 2019 no admite DirectQuery. Azure AS Basic Tier tampoco. [Más información](https://learn.microsoft.com/en-us/analysis-services/analysis-services-features-by-edition?view=asallproducts-allversions#tabular-models). -\*\***Nota:** Las perspectivas y las múltiples particiones están disponibles en la Edición Business para modelos de Power BI, pero el `CompatibilityMode` del modelo debe establecerse en `PowerBI`. Consulte [Cambiar el modo de compatibilidad](xref:change-compatibility-mode) para obtener instrucciones. +\*\***Nota:** Las perspectivas y varias particiones están disponibles en la Edición Business para los modelos de Power BI, pero el `CompatibilityMode` del modelo debe establecerse en `PowerBI`. Consulta [Cambiar el modo de compatibilidad](xref:change-compatibility-mode) para obtener instrucciones. -Si intentas abrir un modelo que utiliza una o más de las restricciones de modelado indicadas anteriormente con una licencia TE3 de Edición Business, verás los siguientes mensajes de error: +Si intentas abrir un modelo que usa una o varias de las restricciones de modelado indicadas arriba mientras usas una licencia de la Edición Business de TE3, verás el siguiente mensaje de error: ![Esta edición de Tabular Editor 3 no admite modelos semánticos de nivel Enterprise](https://github.com/TabularEditor/TabularEditorDocs/assets/8976200/7ef69593-ea4b-4a16-a8df-543f5c31ac65) -No hay más diferencias de funcionalidades entre las ediciones de Tabular Editor 3 que las enumeradas arriba. +No hay más diferencias de funcionalidades entre las ediciones de Tabular Editor 3 que las indicadas arriba. > [!NOTE] -> Tenga en cuenta que Power BI Desktop [actualmente no admite todas las operaciones de modelado de datos](xref:desktop-limitations). Por este motivo, Tabular Editor 3 bloquea, de forma predeterminada, las operaciones que Power BI Desktop no admite. Sin embargo, esta restricción se puede quitar en Herramientas > Preferencias > Power BI. +> Ten en cuenta que Power BI Desktop [actualmente no admite todas las operaciones de Data model](xref:desktop-limitations). Por este motivo, Tabular Editor 3 bloquea de forma predeterminada las operaciones que Power BI Desktop no admite. Sin embargo, puedes quitar esta restricción en Herramientas > Preferencias > Power BI. > [!IMPORTANT] -> Tabular Editor solo puede usarse como herramienta externa para Power BI Desktop cuando el archivo de Report de Power BI (.pbix, .pbip o .pbit) contiene un Data model (Importación, DirectQuery o compuesto). **No se admiten los Report que usan Live connection** porque estos Report no incluyen un Data model. [Más información](xref:desktop-limitations). +> Tabular Editor solo se puede usar como herramienta externa para Power BI Desktop cuando el archivo de Report de Power BI (.pbix, .pbip o .pbit) contiene un Data model (Importación, DirectQuery o Compuesto). **No se admiten los Reports con conexión en vivo** porque no contienen un Data model. [Más información](xref:desktop-limitations). -## Licencias personales vs. transferibles +## Licencias personales frente a transferibles -Nuestra Edición de escritorio y la Edición Business utilizan un modelo de licencia **personal**. Esto significa que cada usuario recibe su propia clave de licencia personal, que no se puede compartir ni transferir a otros usuarios. Cuando un usuario ya no necesite el producto, debe cancelar su suscripción para evitar pagos recurrentes. +Nuestra Edición de escritorio y la Edición Business utilizan un modelo de licencia **personal**. Esto significa que cada usuario recibe su propia clave de licencia personal, que no se puede compartir ni transferir a otros usuarios. Cuando un usuario ya no necesite el producto, debe cancelarse la suscripción para evitar pagos recurrentes. -Nuestra Edición Enterprise usa un modelo de licencias **transferible**. El administrador de licencias recibe una única clave de licencia, que luego es válida para un número de usuarios nominados, hasta la cantidad adquirida. Los usuarios se identifican por su dirección de correo electrónico, que se introduce la primera vez que un usuario activa una instalación de Tabular Editor 3. La primera vez que un usuario activa una instalación de Tabular Editor 3 con la clave de licencia, queda "vinculado" a esa licencia durante 30 días. Después del periodo de vinculación de 30 días, se puede quitar a un usuario de la licencia en cualquier momento, liberando un asiento de licencia para otro usuario. Los administradores de licencias pueden ver y administrar usuarios a través de nuestro [portal de autoservicio](https://tabulareditor.com/my-account). También puedes ponerte en contacto con el equipo de soporte para obtener ayuda. +Nuestra Edición Enterprise usa un modelo de licencia **transferible**. El administrador de licencias recibe una única clave de licencia, que es válida para un número de usuarios con nombre hasta el límite de la cantidad adquirida. Los usuarios se identifican por su dirección de correo electrónico, que se introduce la primera vez que un usuario activa una instalación de Tabular Editor 3. La primera vez que un usuario activa una instalación de Tabular Editor 3 con la clave de licencia, queda vinculado a esa licencia durante 30 días. Una vez transcurrido el período de vinculación de 30 días, se puede desvincular a un usuario de la licencia en cualquier momento, liberando el cupo de licencia para otro usuario. Los administradores de licencias pueden ver y administrar usuarios desde nuestro [portal de autoservicio](https://tabulareditor.com/my-account). También puedes ponerte en contacto con el servicio de soporte para obtener ayuda. ## Varias instalaciones -Cada usuario de Tabular Editor 3 puede instalar la herramienta en varias máquinas, según el tipo de licencia que tenga: +Cada usuario de Tabular Editor 3 puede instalar la herramienta en varios equipos, según el tipo de licencia que tenga: -| | Escritorio | Business | Enterprise | -| ------------------------- | ---------- | -------- | ---------- | -| Instalaciones simultáneas | 1 | 2 | 3 | +| | Desktop | Business | Enterprise | +| ------------------------- | ------- | -------- | ---------- | +| Instalaciones simultáneas | 1 | 2 | 3 | > [!NOTE] -> Compartir una sola licencia entre varios usuarios va en contra de nuestros [términos de licencia](https://tabulareditor.com/license-terms). +> Compartir una única licencia entre varios usuarios incumple nuestros [términos de licencia](https://tabulareditor.com/license-terms). -Puedes desactivar una instalación existente en cualquier momento desde la propia herramienta; para ello, elige la opción "Change license key..." en "Help > About Tabular Editor". También puedes desactivar una instalación a través de nuestro [portal de autoservicio](https://tabulareditor.com/sign-in) yendo a la pestaña "Licenses". +Puedes desactivar una instalación existente en cualquier momento desde la propia herramienta, seleccionando la opción "Change license key..." en "Help > About Tabular Editor". También puedes desactivar una instalación desde nuestro [portal de autoservicio](https://tabulareditor.com/sign-in) yendo a la pestaña "Licenses". -Si necesitas más instalaciones simultáneas de Tabular Editor 3 de las indicadas anteriormente, ponte en contacto con [licensing@tabulareditor.com](mailto:licensing@tabulareditor.com). +Si necesitas más instalaciones simultáneas de Tabular Editor 3 de las indicadas arriba, ponte en contacto con [licensing@tabulareditor.com](mailto:licensing@tabulareditor.com). -## Descuentos por volumen para la Edición Enterprise +## Descuentos por volumen de la Edición Enterprise -Nuestra Edición Enterprise tiene precios por niveles, según la siguiente tabla (también se aplican tasas de descuento similares para los compromisos mensuales): +El precio de nuestra Edición Enterprise se estructura en niveles, según la siguiente tabla (se aplican tasas de descuento similares con el compromiso mensual): -| Nivel | Precio anual por puesto | -| ------------------------- | ----------------------- | -| Primeros 5 puestos | $950,00 USD | -| Siguientes 6-10 asientos | $900,00 USD | -| Siguientes 11-20 asientos | $850,00 USD | -| Siguientes 21-50 asientos | $800,00 USD | -| Puestos 51 y en adelante | $750,00 USD | +| Tramo | Precio anual por puesto | +| ---------------------------- | ----------------------- | +| Primeros 5 puestos | $950,00 USD | +| Siguientes 6-10 puestos | $900,00 USD | +| Siguientes 11-20 puestos | $850,00 USD | +| Siguientes 21 a 50 licencias | $800,00 USD | +| 51 o más licencias | $750,00 USD | -Por ejemplo, si necesitas 12 licencias, el precio se desglosa de la siguiente manera: +A modo de ejemplo, si necesitas 12 asientos, el precio se desglosa de la siguiente manera: ```text -Asientos 1-5: 5 x 950,00 = $ 4.750,00 -Asientos 6-10: 5 x 900,00 = $ 4.500,00 -Asientos 11-12: 2 x 850,00 = $ 1.700,00 +Seats 1-5: 5 x 950.00 = $ 4,750.00 +Seats 6-10: 5 x 900.00 = $ 4,500.00 +Seats 11-12: 2 x 850.00 = $ 1,700.00 -------------------------------------- -Total $ 10.950,00 +Total $ 10,950.00 ====================================== ``` -Si necesitas más de 100 puestos, contacta con ventas para solicitar un presupuesto. +Si necesitas más de 100 asientos, ponte en contacto con Ventas para solicitar un presupuesto. diff --git a/localizedContent/es/content/getting-started/getting-started.md b/localizedContent/es/content/getting-started/getting-started.md index 28b139d79..c7d55f8d8 100644 --- a/localizedContent/es/content/getting-started/getting-started.md +++ b/localizedContent/es/content/getting-started/getting-started.md @@ -2,7 +2,7 @@ uid: getting-started title: Instalación y activación author: Morten Lønskov -updated: 2026-03-27 +updated: 2026-05-19 applies_to: products: - product: Tabular Editor 2 @@ -23,142 +23,116 @@ applies_to: Descarga la versión más reciente de Tabular Editor 3 desde nuestra [página de descargas](xref:downloads). -## Requisitos previos +Recomendamos el instalador MSI de 64 bits para la mayoría de los escenarios. Una vez descargado, haz doble clic en el archivo MSI y sigue los pasos del asistente de instalación. + +![Instalar](~/content/assets/images/getting-started/install.png) + +### Requisitos previos Ninguno. -## Requisitos del sistema +### Requisitos del sistema -- **Sistema operativo:** Windows 10, Windows 11, Windows Server 2016, Windows Server 2019 o versiones posteriores -- **Arquitectura:** x64, ARM64 (nativo a partir de 3.23.0) -- **Runtime de .NET:** [.NET Runtime de Escritorio 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) +- **Sistema operativo:** Windows 10, Windows 11, Windows Server 2016, Windows Server 2019 o posterior +- **Arquitectura:** x64, ARM64 (nativa desde la versión 3.23.0) +- **Tiempo de ejecución de .NET:** [.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) -Consulta la directiva de sistemas operativos compatibles de .NET para ver qué versiones actuales de Windows admite cada entorno de ejecución. +Consulta la directiva de sistemas operativos compatibles de .NET para saber qué versiones actuales de Windows admite cada entorno de ejecución. -## Activación de su instalación +## Activación de la instalación -Tabular Editor 3 es software comercial. Visita nuestra [página principal](https://tabulareditor.com) para conocer los precios y las opciones de compra. Si no ha usado Tabular Editor 3 previamente, puede optar a una prueba gratuita de 30 días. +Tabular Editor 3 es software comercial. Visita nuestra [página principal](https://tabulareditor.com) para consultar los precios y las opciones de compra. Si no has usado Tabular Editor 3 antes, puedes acceder a una prueba gratuita de 30 días. -La primera vez que inicie Tabular Editor 3 en un equipo nuevo, se le pedirá que active el producto. +La primera vez que abres Tabular Editor 3 en un equipo nuevo, se te pedirá que actives el producto. ![Activación del producto](~/content/assets/images/getting-started/product-activation.png) -### Activación con una clave de licencia existente +### Activar con una clave de licencia existente -Una vez que compres una licencia de Tabular Editor 3, deberías recibir un correo electrónico con una cadena de 25 caracteres; esa es tu clave de licencia. Cuando se te solicite, introduce la clave de licencia y pulsa "Siguiente >" para activar el producto. +Una vez que compres una licencia de Tabular Editor 3, recibirás un correo electrónico con una cadena de 25 caracteres, que es tu clave de licencia. Cuando se te pida, introduce la clave de licencia y haz clic en **Siguiente >** para activar el producto. ![Introducir clave de licencia](~/content/assets/images/getting-started/enter-license-key.png) > [!NOTE] -> Para los tipos de licencia multiusuario, tendrás que introducir tu dirección de correo electrónico además de la clave de licencia. Tabular Editor 3 te lo solicitará si la clave de licencia que introduces corresponde a una licencia multiusuario. - -Ten en cuenta que las instalaciones de Tabular Editor 3 se activan **por usuario**. En otras palabras, si varios usuarios comparten el mismo equipo, cada uno tendrá que activar el producto en su perfil de usuario de Windows. - -### Solicitar una licencia de prueba - -Si no ha usado Tabular Editor 3 antes, puede optar a una prueba gratuita de 30 días. Al elegir esta opción, se te solicitará una dirección de correo electrónico. Usamos la dirección de correo electrónico para validar si ya tienes una activación de Tabular Editor 3. - -> [!NOTE] -> Al registrarse para obtener una licencia de prueba de 30 días, Tabular Editor ApS no le enviará correos electrónicos no solicitados ni reenviará su dirección de correo electrónico a terceros. Consulta nuestra @privacy-policy para obtener más información. - -### Cambiar una clave de licencia - -Cuando Tabular Editor 3 esté activado, puedes cambiar tu clave de licencia en el menú Ayuda seleccionando "Acerca de Tabular Editor". +> En las licencias multiusuario, además de la clave de licencia, también debes introducir tu dirección de correo electrónico. Tabular Editor 3 te lo pedirá cuando la clave de licencia corresponda a una licencia multiusuario. -![About Te3](~/content/assets/images/getting-started/about-te3.png) +Las instalaciones de Tabular Editor 3 se activan **por usuario**. Si varios usuarios comparten el mismo equipo, cada usuario debe activar el producto en su propio perfil de usuario de Windows. -En el cuadro de diálogo, selecciona "Cambiar clave de licencia". Ten en cuenta que esta opción solo está disponible si no hay ningún modelo cargado en Tabular Editor. Si ya has cargado un modelo, puedes cerrarlo desde Archivo > Cerrar modelo. Cuando hagas clic en "Cambiar clave de licencia", Tabular Editor te preguntará si quieres eliminar la licencia actual: +### Cuenta de Windows frente a cuenta de Power BI / Entra -![imagen](https://user-images.githubusercontent.com/8976200/146754154-e691810b-342d-4311-8278-33da240d8d08.png) - -Al aceptarlo, se quita la licencia actual y tendrás que volver a introducir una clave de licencia para usar el producto. - -> [!IMPORTANT] -> Una vez que se quita una clave de licencia, tal como se describe arriba, el usuario actual no podrá usar el producto en ese equipo hasta que se introduzca una nueva clave de licencia. - - +La cuenta de Windows en la que está instalado Tabular Editor 3 es independiente de la cuenta de Microsoft Entra que se usa para autenticarse en un Workspace de Power BI / Fabric. -#### Detalles del registro +- **La activación de la licencia** se almacena en el Registro de Windows, bajo `HKEY_CURRENT_USER`, del usuario de Windows que activó el producto. La licencia no está vinculada a ninguna identidad en la nube. +- **La autenticación del Workspace** se realiza en el momento de la conexión, en el cuadro de diálogo **Cargar modelo semántico desde la base de datos**. Inicia sesión con la cuenta de Microsoft Entra que tiene permisos sobre el Workspace. -Tabular Editor 3 usa el Registro de Windows para almacenar los detalles de activación. +No necesitas ejecutar Tabular Editor 3 con **Ejecutar como** usando otra cuenta de Windows solo porque utilices una cuenta independiente de Entra (por ejemplo, una cuenta de administrador sin correo habilitado) para administrar el Workspace de Power BI. Inicia Tabular Editor 3 con tu cuenta habitual de Windows, actívalo con tu clave de licencia en esa cuenta e introduce tus credenciales de administrador de Entra en el cuadro de diálogo de conexión. -Para ver la clave de licencia actual asignada al equipo, ejecuta el siguiente comando en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): +Para más información sobre cómo Tabular Editor se autentica con el punto de conexión XMLA y cómo elegir el modo de autenticación adecuado (por ejemplo, **Microsoft Entra MFA** cuando tu inicio de sesión de Windows no coincide con tu cuenta de Power BI), consulta @xmla-as-connectivity. -```cmd -REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey -``` +### Solicitar una licencia de prueba -Un administrador del sistema también puede asignar por adelantado licencias de Tabular Editor 3 a un equipo, especificando los valores **LicenseKey** y **User** en la clave de registro `SOFTWARE\\Kapacity\\Tabular Editor 3` de cada usuario. +Si todavía no has usado Tabular Editor 3, puedes acceder a una prueba gratuita de 30 días. Al elegir esta opción, se te pedirá una dirección de correo electrónico. Usamos la dirección de correo electrónico para comprobar si ya tienes una activación previa de Tabular Editor 3. -También puedes usar `regedit.exe` (Editor del Registro de Windows) y navegar a `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3` para ver y modificar los valores **LicenseKey** y **User**. +> [!NOTE] +> Tabular Editor ApS no envía correos electrónicos no solicitados ni reenvía tu dirección de correo electrónico a terceros cuando te registras para obtener una licencia de prueba de 30 días. Consulta nuestra @privacy-policy para obtener más información. -![Editor del Registro](~/content/assets/images/troubleshooting/registry-editor.png) +### Cambiar una clave de licencia -### Cambiar una clave de licencia mediante el Registro +Cuando Tabular Editor 3 está activado, puedes cambiar la clave de licencia desde el menú Ayuda, seleccionando **Acerca de Tabular Editor**. -Si por cualquier motivo no puedes cambiar la clave de licencia siguiendo el procedimiento descrito anteriormente, siempre puedes restablecer la licencia asignada a Tabular Editor 3 mediante el Editor del Registro: +![Acerca de Te3](~/content/assets/images/getting-started/about-te3.png) -1. Cierra todas las instancias de Tabular Editor 3. -2. Abre el Editor del Registro en Windows (Inicio > Ejecutar > regedit.msc). -3. Localiza `HKEY_CURRENT_USER\\SOFTWARE\\Kapacity\\Tabular Editor 3` (consulta la captura de pantalla anterior). -4. Elimina todos los valores dentro de esta clave. -5. Cierra el Editor del Registro y reinicia Tabular Editor 3. +En el cuadro de diálogo, selecciona **Cambiar clave de licencia**. Esta opción solo está disponible cuando no hay ningún modelo cargado en Tabular Editor. Si hay un modelo abierto, ciérralo desde **Archivo > Cerrar modelo**. Cuando hagas clic en **Cambiar clave de licencia**, Tabular Editor te preguntará si quieres quitar la licencia actual: -Como alternativa, ejecuta el siguiente comando en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): +![imagen](https://user-images.githubusercontent.com/8976200/146754154-e691810b-342d-4311-8278-33da240d8d08.png) -```cmd -REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va -``` +Si aceptas, se quitará la licencia actual y tendrás que volver a introducir una clave de licencia para usar el producto. -La próxima vez que inicies Tabular Editor 3, se te pedirá una clave de licencia, igual que cuando la herramienta se instaló por primera vez en el equipo. +> [!IMPORTANT] +> Una vez eliminada una clave de licencia, el usuario actual no podrá usar el producto en ese equipo hasta que se introduzca una nueva clave de licencia. -### Instalación silenciosa y aprovisionamiento previo de licencias +## Configuración posterior a la instalación -Puedes implementar Tabular Editor de forma silenciosa y aprovisionar previamente la licencia mediante el Registro de Windows. +Tabular Editor 3 ofrece muchas opciones de configuración. La configuración predeterminada es suficiente para la mayoría de los escenarios de desarrollo, pero revisa las opciones siguientes. -1. **Instalar de forma silenciosa** (sin interfaz de usuario, sin reinicio): +### Buscar actualizaciones al iniciar - ```powershell - msiexec /i TabularEditor..x64.Net8.msi /qn /norestart /l*v C:\Temp\TE3_install.log - ``` +De forma predeterminada, cada vez que inicias Tabular Editor 3, la herramienta comprueba en línea si hay una versión más reciente disponible. Puedes controlar cómo se realiza la comprobación de actualizaciones en **Herramientas > Preferencias > Actualizaciones y comentarios**. - Para incluir la característica **Asistente de IA**, especifique la propiedad `ADDLOCAL`. El Asistente de IA no se instala de forma predeterminada. +> [!NOTE] +> Usa siempre la versión más reciente de Tabular Editor 3. Nuestro equipo de soporte da por hecho que utilizas la versión más reciente antes de enviar un Report de error. - ```powershell - msiexec /i TabularEditor..x64.Net8.msi /qn /norestart ADDLOCAL=MainFeature,AIAssistant /l*v C:\Temp\TE3_install.log - ``` +### Desactivar la recopilación de telemetría - | Característica de MSI | Descripción | Instalado de forma predeterminada | - | --------------------- | ---------------------------------------- | ----------------------------------- | - | `MainFeature` | Aplicación principal de Tabular Editor 3 | Sí (obligatorio) | - | `AIAssistant` | Asistente de IA para Tabular Editor 3 | No | +Tabular Editor 3 recopila datos de uso anónimos y telemetría, lo que nos ayuda a mejorar el producto. Puedes desactivarla en cualquier momento abriendo Tabular Editor 3 y yendo a **Herramientas > Preferencias > Actualizaciones y comentarios**. Desmarca la casilla **Ayuda a mejorar Tabular Editor recopilando datos de uso anónimos** para dejar de participar. - > [!NOTE]> When using `ADDLOCAL`, you must include `MainFeature` alongside any optional features. Especificar solo `AIAssistant` sin `MainFeature` da como resultado una instalación incompleta. +![Recopilar telemetría](~/content/assets/images/getting-started/collect-telemetry.png) -También puedes usar `/package` en lugar de `/i`. Sustituye `` por la cadena de versión real. Usa el MSI de ARM64 si corresponde. +### Configuración del proxy -Para obtener más información sobre las opciones disponibles de la línea de comandos de MSI, consulte la documentación oficial de Microsoft: -[Opciones de línea de comandos de Microsoft Standard Installer - aplicaciones Win32 | Microsoft Learn](https://learn.microsoft.com/windows/win32/msi/command-line-options) +Si estás en una red con conectividad limitada a Internet, especifica la dirección, el nombre de usuario y la contraseña de un servidor proxy en **Herramientas > Preferencias > Configuración del proxy**. Esto es necesario para que Tabular Editor 3 pueda usar cualquier función que dependa de solicitudes web salientes. En concreto: -2. **Escribe la licencia en el Registro** **antes de la primera ejecución** de la aplicación: +- Comprobaciones de actualizaciones +- Activación del producto +- Formato de DAX +- Descarga de reglas de mejores prácticas desde URL externas - ```bat - REM Clave de licencia por usuario (HKCU) - REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey /t REG_SZ /d YOUR-25-CHAR-KEY /f - ``` +> [!TIP] +> La configuración del proxy puede, en ocasiones, interferir con los cuadros de diálogo de autenticación u otras indicaciones externas. Prueba a cambiar la configuración del proxy entre **Sistema** y **Ninguno** y, después, cierra y vuelve a abrir Tabular Editor 3 para comprobarlo. - Si utilizas una clave de licencia de **Edición Enterprise**, establece también el correo electrónico del usuario con licencia: +### Otras preferencias - ```bat - REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v User /t REG_SZ /d user@example.com /f - ``` +Tabular Editor 3 incluye muchas otras opciones para controlar el comportamiento de la aplicación. Para obtener más información, consulta @preferences. -**Notas** +## Escenarios avanzados -- El instalador **no** acepta un parámetro de licencia; la gestión de licencias se realiza mediante las entradas del Registro indicadas arriba. -- Las claves se almacenan en **HKCU** (por usuario). Asegúrese de que los comandos se ejecuten en el contexto del usuario de destino (por ejemplo, mediante un script de inicio de sesión o similar) para que los valores se escriban en el perfil correcto. -- Para ver claves y valores adicionales, consulte los [detalles del Registro](#registry-details). +Para la activación manual (sin Internet), la administración de licencias basada en el Registro, la implementación silenciosa y la administración de asientos de Enterprise, consulta @installation-activation-basic. -## Siguientes pasos +## Pasos siguientes -- [Información general sobre la interfaz de usuario de Tabular Editor 3](xref:user-interface) +- [Información general de la interfaz de usuario de Tabular Editor 3](xref:user-interface) +- @xmla-as-connectivity +- @migrate-from-vs +- @migrate-from-desktop +- @migrate-from-te2 +- @installation-activation-basic diff --git a/localizedContent/es/content/getting-started/index.md b/localizedContent/es/content/getting-started/index.md index a5f74f37a..ee01f0c0c 100644 --- a/localizedContent/es/content/getting-started/index.md +++ b/localizedContent/es/content/getting-started/index.md @@ -1,7 +1,8 @@ --- uid: onboarding-te3 title: Te damos la bienvenida -author: Daniel Otykier +author: Morten Lønskov +updated: 2026-05-19 --- # Te damos la bienvenida @@ -12,57 +13,70 @@ author: Daniel Otykier **¡Gracias por elegir Tabular Editor 3!** -Para ayudarte a sacarle el máximo partido a la herramienta, hemos reunido todo nuestro material de introducción en esta sección de primeros pasos, que esperamos que disfrutes. Recomendamos a todos los nuevos usuarios de Tabular Editor 3 que lean esta guía y se salten los temas con los que ya estén familiarizados. +Para ayudarte a sacar el máximo partido a la herramienta, hemos reunido todo nuestro material de incorporación en esta sección de primeros pasos. Si eres nuevo en Tabular Editor 3, te recomendamos que leas esta guía y te saltes los temas que ya conozcas. > [!NOTE] -> Algunos artículos de esta guía hacen referencia a Tabular Editor 2, en concreto a la interfaz de línea de comandos (CLI), para fines de implementación y pruebas automatizadas. Está previsto publicar más adelante una aplicación CLI independiente para acompañar a Tabular Editor 3. +> Algunos artículos de esta guía hacen referencia a Tabular Editor 2, en concreto a la interfaz de línea de comandos (CLI), para el despliegue y las pruebas automatizados. Está previsto publicar más adelante una aplicación CLI independiente para complementar Tabular Editor 3. -Como este material de formación se centra en el producto Tabular Editor, asumimos que ya tienes una comprensión básica del modelado de datos tabulares (ya sea con Power BI Desktop, Visual Studio o Tabular Editor 2.x). Si eres nuevo en el modelado de datos tabulares, te recomendamos encarecidamente que consultes material de formación y cursos ofrecidos por terceros como [sqlbi.com](https://sqlbi.com). +Este material de formación se centra en el producto Tabular Editor, por lo que damos por hecho que ya tienes conocimientos básicos de Data model tabular (ya sea con Power BI Desktop, Visual Studio o Tabular Editor 2.x). Si te estás iniciando en el Data model tabular, te recomendamos el material de formación y los cursos ofrecidos por terceros, como [sqlbi.com](https://sqlbi.com). **Temas tratados en esta guía:** -- @general-introduction - - @installation-activation-basic - - @migrate-from-vs - - @migrate-from-desktop - - @migrate-from-te2 +**Primeros pasos con Tabular Editor 3** +- @general-introduction - @getting-started - - @editions - - @training-telearn +- @installation-activation-basic +- @migrate-from-vs +- @migrate-from-desktop +- @migrate-from-te2 +- @azure-marketplace +- @editions +- @training-telearn + +**Tabular Editor 2** - @getting-started-te2 -- @desktop-integration - - @desktop-limitations +**Power BI Desktop y Tabular Editor** + +- @integración con Desktop +- @limitaciones de Desktop + +**Interfaz de usuario** + +- @referencia de la interfaz de usuario +- @bpa-view-reference +- @referencia de la vista de actualización de datos +- @referencia de la función Buscar y reemplazar +- @referencia de la vista de macros +- @referencia de la vista de mensajes +- @referencia de la vista de propiedades +- @tom-explorer-view-reference +- @referencia de la vista de diagrama + +**Desarrollo en paralelo** -- @user-interface - - @bpa-view - - @data-refresh-view - - @find-replace - - @macros-view - - @messages-view - - @properties-view - - @tom-explorer-view - - @diagram-view +- @desarrollo en paralelo +- @optimización del flujo de trabajo en el modo de espacio de trabajo -- @parallel-development - - @optimizing-workflow-workspace-mode +**Crea modelos más rápido con Tabular Editor** - @boosting-productivity-te3 - - @importing-tables-data-modeling - - @refresh-preview-query - - @creating-and-testing-dax - - @dax-script-introduction - - @bpa - - @cs-scripts-and-macros - - @personalizing-te3 +- @importación de tablas para el modelado de datos +- @actualización de la vista previa de la consulta +- @creating-and-testing-dax +- @dax-script-introduction +- @bpa +- @scripts de C# y macros +- @personalizing-te3 **Recursos adicionales:** -- [Documentación de referencia de TE3](xref:getting-started) +- [Primeros pasos con Tabular Editor 3](xref:getting-started) +- [Instalación y activación avanzadas](xref:installation-activation-basic) - [Descargar Tabular Editor](https://tabulareditor.com/download) -- [Tabular Editor Learn](https://tabulareditor.com/learn) +- [Aprende Tabular Editor](https://tabulareditor.com/learn) - [Soporte dedicado (solo para clientes de la Edición Enterprise)](mailto:support@tabulareditor.com) - [Soporte de la comunidad](https://github.com/TabularEditor/TabularEditor3/issues) -- [Discusiones de la comunidad](https://github.com/TabularEditor/TabularEditor3/discussions) \ No newline at end of file +- [Discusiones de la comunidad](https://github.com/TabularEditor/TabularEditor3/discussions) diff --git a/localizedContent/es/content/getting-started/installation.md b/localizedContent/es/content/getting-started/installation.md index c06c3a45e..29009e3ad 100644 --- a/localizedContent/es/content/getting-started/installation.md +++ b/localizedContent/es/content/getting-started/installation.md @@ -1,8 +1,8 @@ --- uid: installation-activation-basic -title: Instalación, activación y configuración básica -author: Daniel Otykier -updated: 2021-09-30 +title: Instalación y activación avanzadas +author: Morten Lønskov +updated: 2026-05-19 applies_to: products: - product: Tabular Editor 2 @@ -17,97 +17,119 @@ applies_to: full: true --- -## Instalación +## Información general -Para instalar Tabular Editor 3, descarga la versión más reciente desde nuestra [página de descargas](xref:downloads). +En esta página se tratan escenarios avanzados de instalación y activación para Tabular Editor 3: activación manual (sin conexión), administración de licencias basada en el Registro, implementación silenciosa y administración de asientos de la edición Enterprise. -Recomendamos descargar el instalador MSI de 64 bits, que es adecuado para la mayoría de los casos. Una vez descargado, haz doble clic en el archivo MSI y sigue los pasos del asistente de instalación. +Para el flujo de activación estándar, consulta @getting-started. -![Instalar](~/content/assets/images/getting-started/install.png) + + +## Activación manual (sin Internet) + +Si no tienes acceso a Internet, por ejemplo, por un proxy, Tabular Editor te solicitará que realices una activación manual. + +![Mensaje de activación manual](~/content/assets/images/getting-started/Activation_manual_firstprompt.png) + +Después de introducir tu correo electrónico, aparece un cuadro de diálogo con un enlace a una clave de activación. Copia la URL y ábrela en un navegador web que tenga conexión a Internet. + +La URL devuelve un objeto JSON: -## Activar la instalación +![Objeto JSON de activación manual](~/content/assets/images/getting-started/activation_manual_jsonobject.png) -La primera vez que inicias Tabular Editor 3 en un equipo nuevo, se te pedirá que actives el producto. +Copia el objeto JSON completo y pégalo en el cuadro de diálogo. El cuadro de diálogo de activación manual se verá como en la captura de pantalla siguiente. -![Activación del producto](~/content/assets/images/getting-started/product-activation.png) +![Activación manual completada](~/content/assets/images/getting-started/activation_manual_dialogbox_filled.png) -### Activación con una clave de licencia existente +A continuación, se verifica tu licencia de Tabular Editor 3. -Una vez que compres una licencia de Tabular Editor 3, deberías recibir un correo electrónico con una cadena de 25 caracteres; esa es tu clave de licencia. Cuando se te solicite, introduce la clave de licencia y haz clic en "Siguiente >" para activar el producto. +## Cambiar asientos en la Edición Enterprise -![Introducir clave de licencia](~/content/assets/images/getting-started/enter-license-key.png) +Para cambiar un asiento de la edición Enterprise, anula el registro del usuario actual de ese asiento a través del [portal de autoservicio de Tabular Editor](https://tabulareditor.com/my-account/). El propietario de la suscripción o el administrador de licencias crea una cuenta o inicia sesión con una existente para administrar los asientos de licencia. > [!NOTE] -> Para los tipos de licencia para varios usuarios, tendrás que introducir tu dirección de correo electrónico además de la clave de licencia. Tabular Editor 3 te lo solicitará si la clave de licencia que introduces corresponde a una licencia multiusuario. +> Cambiar de usuario solo es posible en la Edición Enterprise. - + -#### Activación manual (sin Internet) +## Detalles del Registro -Si no tienes acceso a Internet, por ejemplo, debido a un proxy, Tabular Editor te pedirá que realices una activación manual. +Tabular Editor 3 usa el Registro de Windows para almacenar los datos de activación. -![Aviso de activación manual](~/content/assets/images/getting-started/Activation_manual_firstprompt.png) +Para ver la clave de licencia actual asignada al equipo, ejecuta el siguiente comando en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): -Después de introducir tu correo electrónico, aparece un cuadro de diálogo con un enlace a una clave de activación. -Copia la URL y ábrela en un navegador web conectado a Internet. +```cmd +REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey +``` -La URL devuelve un objeto JSON: +También puedes usar `regedit.exe` (Editor del Registro de Windows) y navegar hasta `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3` para ver y modificar los valores **LicenseKey** y **User**. -![Objeto JSON de activación manual](~/content/assets/images/getting-started/activation_manual_jsonobject.png) +![Editor del Registro](~/content/assets/images/troubleshooting/registry-editor.png) -Copia el objeto JSON completo y pégalo en el cuadro de diálogo. -El cuadro de diálogo de activación manual debería quedar como el que se muestra a continuación. +Un administrador del sistema también puede asignar de forma proactiva licencias de Tabular Editor 3 a un equipo especificando los valores **LicenseKey** y **User** en la clave del registro `SOFTWARE\Kapacity\Tabular Editor 3` de cada usuario. Consulta [Instalación desatendida y preaprovisionamiento de licencias](#instalacion-desatendida-y-preaprovisionamiento-de-licencias) para ver el procedimiento de implementación completo. -![Activación manual completada](~/content/assets/images/getting-started/activation_manual_dialogbox_filled.png) +## Cambiar una clave de licencia a través del Registro -De este modo, se verificará tu licencia de Tabular Editor 3. +Si, por cualquier motivo, no puedes cambiar la clave de licencia mediante la opción estándar **Cambiar clave de licencia** del cuadro de diálogo **Acerca de Tabular Editor**, restablece la licencia desde el Editor del Registro: -### Cambiar una clave de licencia +1. Cierra todas las instancias de Tabular Editor 3. +2. Abre el Editor del Registro en Windows (Inicio > Ejecutar > regedit.msc). +3. Busca `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3` (consulta la captura de pantalla anterior). +4. Elimina todos los valores dentro de esta clave. +5. Cierra el Editor del Registro y reinicia Tabular Editor 3. -Cuando Tabular Editor 3 está activado, puedes cambiar la clave de licencia en el menú Ayuda seleccionando "Acerca de Tabular Editor". +Como alternativa, ejecuta el siguiente comando en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): -![Acerca de Te3](~/content/assets/images/getting-started/about-te3.png) +```cmd +REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va +``` -En el cuadro de diálogo, selecciona "Cambiar clave de licencia". Ten en cuenta que esta opción solo está disponible si no hay ningún modelo cargado en Tabular Editor. Si ya has cargado un modelo, puedes cerrarlo en Archivo > Cerrar modelo. +La próxima vez que inicies Tabular Editor 3, se te solicitará una clave de licencia, igual que cuando la herramienta se instaló por primera vez en el equipo. -Para obtener más detalles sobre la administración de las claves de licencia, consulta [Detalles del registro](xref:getting-started#registry-details). +## Instalación desatendida y preaprovisionamiento de licencias -## Configuración básica +Puedes implementar Tabular Editor de forma desatendida y preaprovisionar la licencia mediante el Registro de Windows. -Después de activar Tabular Editor 3, te recomendamos dedicar unos minutos a familiarizarte con la [interfaz básica](xref:user-interface). Además, Tabular Editor 3 ofrece muchas opciones de configuración. La configuración predeterminada es suficiente para la mayoría de los escenarios de desarrollo, pero hay algunas opciones de configuración importantes que deberías revisar siempre. +1. **Instalar de forma silenciosa** (sin interfaz de usuario, sin reinicio): -### Buscar actualizaciones al iniciar + ```powershell + msiexec /i TabularEditor..x64.Net8.msi /qn /norestart /l*v C:\Temp\TE3_install.log + ``` -De forma predeterminada, cada vez que inicias Tabular Editor 3, la herramienta comprueba en línea si hay una versión más reciente disponible. Puedes controlar cómo se realiza esta comprobación de actualizaciones en **Herramientas > Preferencias > Actualizaciones y comentarios**. + Para incluir la característica **Asistente de IA**, especifica la propiedad `ADDLOCAL`. El Asistente de IA no se instala de forma predeterminada. -> [!NOTE] -> Recomendamos usar siempre la versión más reciente de Tabular Editor 3. Por lo general, nuestro equipo de soporte asumirá que siempre estás usando la versión más reciente antes de enviar un Report de errores. + ```powershell + msiexec /i TabularEditor..x64.Net8.msi /qn /norestart ADDLOCAL=MainFeature,AIAssistant /l*v C:\Temp\TE3_install.log + ``` -### No participar en la recopilación de telemetría + | Característica MSI | Descripción | Instalado de forma predeterminada | + | ------------------ | ------------------------------------- | ----------------------------------- | + | `MainFeature` | Aplicación base de Tabular Editor 3 | Sí (obligatorio) | + | `AIAssistant` | Asistente de IA para Tabular Editor 3 | No | -Tabular Editor 3 recopila datos de uso anónimos y telemetría, lo que nos ayuda a mejorar el producto. Puedes optar por no participar en cualquier momento: abre Tabular Editor 3 y ve a **Herramientas > Preferencias > Actualizaciones y comentarios**. Desmarca la casilla **Ayuda a mejorar Tabular Editor recopilando datos de uso anónimos** para no participar. + > [!NOTE]> Al usar `ADDLOCAL`, incluye `MainFeature` junto con cualquier característica opcional. Si especificas solo `AIAssistant` sin `MainFeature`, la instalación quedará incompleta. -![Recopilar telemetría](~/content/assets/images/getting-started/collect-telemetry.png) +También puedes usar `/package` en lugar de `/i`. Reemplaza `` por la cadena de la versión real. Usa el MSI de ARM64 si corresponde. -### Configuración del proxy +Para obtener más información sobre las opciones de línea de comandos de MSI disponibles, consulta la documentación oficial de Microsoft: +[Opciones de línea de comandos de Microsoft Standard Installer: aplicaciones Win32 | Microsoft Learn](https://learn.microsoft.com/windows/win32/msi/command-line-options) -Si estás en una red con conectividad a Internet limitada, puedes especificar la dirección, el nombre de usuario y la contraseña de un servidor proxy en **Herramientas > Preferencias > Configuración del proxy**. Esto es necesario antes de que Tabular Editor 3 pueda usar cualquier función que dependa de solicitudes web salientes. En concreto, son: +2. **Escribe la licencia en el Registro** **antes de iniciar la aplicación por primera vez**: -- Comprobación de actualizaciones -- Activación del producto -- Formato de DAX -- Descarga de reglas de prácticas recomendadas desde URL externas + ```bat + REM Per-user license key (HKCU) + REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey /t REG_SZ /d YOUR-25-CHAR-KEY /f + ``` -> [!TIP] -> En ocasiones, la configuración del proxy puede interferir con los cuadros de diálogo de autenticación u otras indicaciones externas. -> Intenta cambiar la configuración del proxy entre "Sistema" y "Ninguno"; cierra y vuelve a abrir Tabular Editor 3 para comprobarlo. + Si usas una clave de licencia de la **Edición Enterprise**, establece también el correo electrónico del usuario con licencia: -### Otras preferencias + ```bat + REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v User /t REG_SZ /d user@example.com /f + ``` -Además de la configuración mencionada anteriormente, Tabular Editor 3 incluye muchas otras opciones para controlar distintos comportamientos de la aplicación, lo que te permite ajustar la herramienta a tus necesidades. Para obtener más información sobre estas otras preferencias, consulta @preferences. +**Notas** -## Siguientes pasos +- El instalador no acepta un parámetro de licencia; la licencia se administra mediante las entradas del Registro indicadas arriba. +- Las claves se almacenan en **HKCU** (por usuario). Asegúrate de que los comandos se ejecuten en el contexto del usuario de destino (por ejemplo, mediante un script de inicio de sesión) para que los valores se escriban en el perfil correcto. +- Para ver más claves y valores, consulta [detalles del Registro](#registry-details). -- @migrate-from-vs -- @migrate-from-desktop -- @migrate-from-te2 \ No newline at end of file diff --git a/localizedContent/es/content/how-tos/scripting-dynamic-linq-vs-csharp.md b/localizedContent/es/content/how-tos/scripting-dynamic-linq-vs-csharp.md index 67083c45e..551543cc9 100644 --- a/localizedContent/es/content/how-tos/scripting-dynamic-linq-vs-csharp.md +++ b/localizedContent/es/content/how-tos/scripting-dynamic-linq-vs-csharp.md @@ -11,7 +11,7 @@ applies_to: full: true --- -# En qué se diferencia Dynamic LINQ de LINQ de C\\# +# En qué se diferencia Dynamic LINQ de LINQ de C\# Los C# Scripts usan LINQ estándar de C# con expresiones lambda. Las reglas de Best Practice Analyzer (BPA) y los filtros del árbol del Explorador usan [Dynamic LINQ](https://dynamic-linq.net/expression-language), un lenguaje de expresiones basado en cadenas con una sintaxis diferente. Este artículo es una guía de traducción entre ambos. diff --git a/localizedContent/es/content/how-tos/scripting-filter-query-linq.md b/localizedContent/es/content/how-tos/scripting-filter-query-linq.md index 1e15fdff5..6e1733aed 100644 --- a/localizedContent/es/content/how-tos/scripting-filter-query-linq.md +++ b/localizedContent/es/content/how-tos/scripting-filter-query-linq.md @@ -151,7 +151,7 @@ En las expresiones de reglas de BPA, la sintaxis difiere de la de LINQ en C#. Dy | --------------------------------------------- | ----------------------------------------------------------- | | `m.IsHidden` | `IsHidden` | | `m.DataType == DataType.String` | `DataType = "String"` | -| `&&` / \`\\ | `and` / `or` / `not` | +| `&&` / `\\|\\|` / `!` | `and` / `or` / `not` | | `==` / `!=` | `=` / `!=` o `<>` | | `table.Columns.Count(c => c.IsHidden)` | `Columns.Count(IsHidden)` | | `table.Medidas.Any(m => m.IsHidden)` | `Medidas.Any(IsHidden)` | diff --git a/localizedContent/es/content/references/preferences.md b/localizedContent/es/content/references/preferences.md index 5f4562805..8c13f1e8f 100644 --- a/localizedContent/es/content/references/preferences.md +++ b/localizedContent/es/content/references/preferences.md @@ -714,7 +714,7 @@ Define prefijos aceptables para nombres de variables (p. ej., `_`, `__`, `var_`, Define prefijos aceptables para nombres de columnas temporales (p. ej., `@`, `_`, `x`, `x_`). Las acciones de código sugerirán añadir estos prefijos a los nombres de columnas temporales que no sigan la convención. -## Editor SQL / Editor M / Editor de C\\\# +## Editor SQL / Editor M / Editor C\# ![Marcador de posición: captura de pantalla de las páginas de preferencias de los editores SQL/M/C#] diff --git a/localizedContent/es/content/security/index.md b/localizedContent/es/content/security/index.md index 60b288807..8ed78f4ec 100644 --- a/localizedContent/es/content/security/index.md +++ b/localizedContent/es/content/security/index.md @@ -1,14 +1,14 @@ # Seguridad -Esta sección contiene información sobre seguridad, privacidad y licencias. +This section contains information about security, privacy, and licensing. -## En esta sección +## In this section -- @security-privacy - Consideraciones de seguridad y privacidad de Tabular Editor 3 -- @privacy-policy - Política de privacidad y tratamiento de datos -- @gdpr-delete - Eliminación de datos del usuario -- @te3-eula - La versión más reciente de nuestros términos de licencia -- @third-party-notices - Licencias y avisos de componentes de terceros +- @security-privacy - Security and privacy considerations of Tabular Editor 3 +- @privacy-policy - Privacy policy and data handling +- @gdpr-delete - User Data Deletion +- @terms - The latest version of our Terms & Conditions +- @third-party-notices - Third-party component licenses and notices --- diff --git a/localizedContent/es/content/security/terms.md b/localizedContent/es/content/security/terms.md new file mode 100644 index 000000000..e5133dcea --- /dev/null +++ b/localizedContent/es/content/security/terms.md @@ -0,0 +1,22 @@ +--- +uid: terms +title: Terms and Conditions +author: Søren Toft Joensen +updated: 2026-05-29 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + full: true + - product: TE CLI + full: true +--- + +# Terms and Conditions + +Please find the latest version of our terms and conditions below: + +- [Commercial Terms & Conditions](https://tabulareditor.com/commercial-terms) +- [Tabular Editor 3 EULA](https://tabulareditor.com/eula-te3) +- [Tabular Editor CLI EULA](https://tabulareditor.com/eula-cli) diff --git a/localizedContent/es/content/troubleshooting/licensing-activation.md b/localizedContent/es/content/troubleshooting/licensing-activation.md index 0c2e496a7..fe351269f 100644 --- a/localizedContent/es/content/troubleshooting/licensing-activation.md +++ b/localizedContent/es/content/troubleshooting/licensing-activation.md @@ -1,7 +1,8 @@ --- uid: licensing-activation title: Instalar y activar Tabular Editor 3 -author: Daniel Otykier +author: Morten Lønskov +updated: 2026-05-19 applies_to: products: - product: Tabular Editor 2 @@ -16,90 +17,124 @@ applies_to: full: true --- -# Tabular Editor 3 +# Instalar y activar Tabular Editor 3 -## Instalación +Esta página aborda los problemas habituales de instalación y activación de Tabular Editor 3 y cómo resolverlos. Para el flujo de activación estándar, consulta @getting-started. Para escenarios avanzados de implementación (instalación silenciosa, aprovisionamiento previo de licencias, configuración posterior a la instalación), consulta @installation-activation-basic. -Descarga la versión más reciente de Tabular Editor 3 desde nuestra [página de descargas](xref:downloads). +## Comprobar los requisitos del sistema -## Requisitos previos +Comprueba que el equipo cumpla los requisitos antes de continuar con la solución de problemas: -Ninguno. +- **Sistema operativo:** Windows 10, Windows 11, Windows Server 2016, Windows Server 2019 o versiones posteriores +- **Arquitectura:** x64, ARM64 (nativo a partir de la versión 3.23.0) +- **Runtime de .NET:** [.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) -## Requisitos del sistema +Usa el MSI correspondiente a tu arquitectura desde la [página de descargas](xref:downloads). Una incompatibilidad entre el instalador y la arquitectura es una causa frecuente de instalaciones fallidas y de errores de dependencias faltantes al iniciarlo por primera vez. -- **Sistema operativo:** Windows 7, Windows 8, Windows 10, Windows Server 2016, Windows Server 2019 o posterior -- **.NET Framework:** [4.7.2](https://dotnet.microsoft.com/download/dotnet-framework) + -## Activación de la instalación +## Comprobar la licencia activada -Tabular Editor 3 es software comercial. Visita nuestra [página principal](https://tabulareditor.com) para consultar precios y opciones de compra. Si no has usado Tabular Editor 3 anteriormente, puedes optar a una prueba gratuita de 30 días. +Tabular Editor 3 almacena los detalles de activación en el Registro de Windows, en `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`. -La primera vez que inicies Tabular Editor 3 en un equipo nuevo, se te pedirá que actives el producto. +Para ver la clave de licencia actual del usuario de Windows activo, ejecuta lo siguiente en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): -![Activación del producto](~/content/assets/images/getting-started/product-activation.png) +```cmd +REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey +``` + +También puedes inspeccionar y editar directamente los valores **LicenseKey** y **User** con `regedit.exe`. -### Activación con una clave de licencia existente +![Editor del Registro](~/content/assets/images/troubleshooting/registry-editor.png) -Una vez que compres una licencia de Tabular Editor 3, recibirás un correo electrónico con una cadena de 25 caracteres, que será tu clave de licencia. Cuando se te solicite, introduce la clave de licencia y pulsa "Siguiente >" para activar el producto. +## El cuadro de diálogo de activación sigue apareciendo -![Introducir la clave de licencia](~/content/assets/images/getting-started/enter-license-key.png) +Tabular Editor 3 se conecta a `https://api.tabulareditor.com` al iniciarse y periódicamente para validar la licencia. Si no se puede acceder a este endpoint debido a un firewall o un proxy, la aplicación debe reactivarse cada 30 días. Consulta @policies para ver la lista completa de endpoints utilizados. -> [!NOTE] -> Para los tipos de licencia multiusuario, tendrás que introducir tu dirección de correo electrónico además de la clave de licencia. Tabular Editor 3 te lo solicitará si la clave de licencia que introduces corresponde a una licencia multiusuario. +Si los avisos de activación siguen apareciendo: -#### Cambiar asientos en la Edición Enterprise +1. Confirma que se puede acceder a `api.tabulareditor.com` desde la máquina afectada. +2. Configura las opciones de proxy en **Herramientas > Preferencias > Configuración de proxy**. Consulta @proxy-settings para la resolución de problemas específicos del proxy, incluida la anulación en **AnalysisServices.AppSettings.json** que habilita la compatibilidad de MSAL con proxies externos. +3. Si la red bloquea el tráfico saliente hacia el endpoint de activación, utiliza [Activación manual](#manual-activation-no-internet) más abajo. -Para cambiar un asiento de Enterprise, primero hay que dar de baja al usuario actual del asiento a través del [portal de autoservicio de Tabular Editor](https://tabulareditor.com/my-account/). El propietario de la suscripción o el administrador de licencias puede crear una cuenta o iniciar sesión con una cuenta existente para administrar los asientos de la licencia. + -> [!NOTE] -> Cambiar un usuario solo es posible en la Edición Enterprise. +## Activación manual (sin conexión a Internet) -### Solicitar una licencia de prueba +Si el equipo en el que se ejecuta Tabular Editor no puede acceder al endpoint de activación, el aviso de activación ofrece un procedimiento manual. -Si aún no has usado Tabular Editor 3, tienes derecho a una prueba gratuita de 30 días. Al elegir esta opción, se te pedirá una dirección de correo electrónico. Usamos la dirección de correo electrónico para validar si ya tienes una activación de Tabular Editor 3. +![Aviso de activación manual](~/content/assets/images/getting-started/Activation_manual_firstprompt.png) -> [!NOTE] -> Tabular Editor ApS no enviará correos electrónicos no solicitados ni compartirá tu dirección de correo electrónico con terceros al registrarte para obtener una licencia de prueba de 30 días. Consulta nuestra @privacy-policy para obtener más información. +1. Introduce tu correo electrónico. Aparece un cuadro de diálogo con un enlace a una clave de activación. -### Cambiar una clave de licencia +2. Copia la URL y ábrela en otra máquina que tenga acceso a Internet. La URL devuelve un objeto JSON. -Cuando Tabular Editor 3 esté activado, puedes cambiar tu clave de licencia en el menú Ayuda seleccionando "Acerca de Tabular Editor". + ![Objeto JSON de activación manual](~/content/assets/images/getting-started/activation_manual_jsonobject.png) -![Acerca de Te3](~/content/assets/images/getting-started/about-te3.png) +3. Copia el objeto JSON completo y pégalo en el cuadro de diálogo de la máquina sin conexión. -En el cuadro de diálogo, selecciona "Cambiar clave de licencia". Ten en cuenta que esta opción solo está disponible si no hay ningún modelo cargado en Tabular Editor. Si ya has cargado un modelo, puedes cerrarlo en Archivo > Cerrar modelo. + ![Activación manual completada](~/content/assets/images/getting-started/activation_manual_dialogbox_filled.png) -#### Detalles del Registro de Windows +A continuación, Tabular Editor 3 verifica la licencia. -Tabular Editor 3 usa el Registro de Windows para almacenar los detalles de activación. +## No se puede cambiar la clave de licencia desde la interfaz de usuario -Para ver la clave de licencia actual asignada al equipo, ejecuta el siguiente comando en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): +El botón **Cambiar clave de licencia** de **Ayuda > Acerca de Tabular Editor** solo está habilitado cuando no hay ningún modelo cargado. Si el botón aparece atenuado, cierra el modelo abierto en **Archivo > Cerrar modelo** e inténtalo de nuevo. + +Si la opción de la interfaz de usuario sigue fallando, restablece la licencia desde el Editor del Registro: + +1. Cierra todas las instancias de Tabular Editor 3. +2. Abre el Editor del Registro (Inicio > Ejecutar > regedit.msc). +3. Busca `HKEY_CURRENT_USER\\SOFTWARE\\Kapacity\\Tabular Editor 3`. +4. Elimina todos los valores de esta clave. +5. Reinicia Tabular Editor 3. + +Como alternativa, ejecuta lo siguiente en el Símbolo del sistema de Windows: ```cmd -REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey +REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va ``` -También puedes usar `regedit.exe` (Editor del Registro de Windows) y navegar a `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3` para ver y modificar los valores **LicenseKey** y **User**. +En el siguiente inicio, se solicitará una clave de licencia como si la aplicación acabara de instalarse. -Un administrador del sistema también puede asignar de forma proactiva licencias de Tabular Editor 3 a un equipo especificando los valores **LicenseKey** y **User** en la clave del Registro `SOFTWARE\Kapacity\Tabular Editor 3` de cada usuario. +> [!IMPORTANT] +> Una vez eliminada la clave de licencia, el usuario actual de Windows no podrá usar el producto en ese equipo hasta que introduzca una nueva clave de licencia. -![Editor del Registro](~/content/assets/images/troubleshooting/registry-editor.png) +## La licencia está en el usuario de Windows incorrecto -### Cambiar una clave de licencia a través del Registro de Windows +Las activaciones de Tabular Editor 3 se almacenan **por usuario** en `HKEY_CURRENT_USER`. Si varios usuarios comparten un equipo, cada usuario activa el producto en su propio perfil de Windows. Una licencia activada en una cuenta de Windows no es visible desde otra cuenta de Windows del mismo equipo. -Si por cualquier motivo no puedes cambiar la clave de licencia mediante el procedimiento descrito anteriormente, siempre puedes restablecer la licencia asignada a Tabular Editor 3 mediante el Editor del Registro: +Para comprobar qué cuenta de Windows tiene la licencia, inicia sesión como ese usuario y ejecuta la consulta del registro en [Inspeccionar la licencia activada](#inspect-the-activated-license). -1. Cierra todas las instancias de Tabular Editor 3. -2. Abre el Editor del Registro en Windows (Inicio > Ejecutar > regedit.msc). -3. Busca `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3` (consulta la captura de pantalla anterior). -4. Elimina todos los valores de esta clave. -5. Cierra el Editor del Registro y reinicia Tabular Editor 3. +### Cuenta de Windows vs. cuenta de Power BI / Entra -Como alternativa, ejecuta el siguiente comando en el Símbolo del sistema de Windows (Inicio > Ejecutar > cmd.exe): +Una fuente habitual de confusión: la cuenta de Windows que ejecuta Tabular Editor 3 es independiente de la cuenta de Microsoft Entra usada para autenticarse en un Workspace de Power BI / Fabric. -```cmd -REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va -``` +- **La activación de la licencia** se almacena en `HKEY_CURRENT_USER` del usuario de Windows que activó el producto. No está vinculada a ninguna identidad en la nube. +- **Autenticación del Workspace** se realiza en el momento de la conexión, en el cuadro de diálogo **Cargar modelo semántico desde base de datos**. Inicia sesión allí con la cuenta de Microsoft Entra que tenga permisos en el Workspace. + +No necesitas iniciar Tabular Editor 3 con **Ejecutar como** usando otra cuenta de Windows solo porque te conectes a Power BI con una cuenta de Entra distinta (por ejemplo, una cuenta de administrador sin correo habilitado). Inícialo con tu cuenta habitual de Windows, activa la licencia con esa cuenta y proporciona las credenciales de Entra de administrador en el cuadro de diálogo de conexión. + +Para obtener información sobre cómo elegir el modo de autenticación adecuado (por ejemplo, **Microsoft Entra MFA** cuando tu inicio de sesión de Windows no coincide con tu cuenta de Power BI), consulta @xmla-as-connectivity. + +## El puesto Enterprise está en uso por otro usuario + +Las licencias Enterprise son por puesto. Para activar Tabular Editor 3 para un usuario nuevo cuando todos los puestos estén ocupados, primero hay que dar de baja al usuario existente de un puesto a través del [portal de autoservicio de Tabular Editor](https://tabulareditor.com/my-account/). Esta acción la realiza el propietario de la suscripción o el administrador de licencias. + +> [!NOTE] +> La reasignación de asientos solo es posible en la Edición Enterprise. + +## Activación detrás de un proxy + +Tabular Editor 3 envía solicitudes web salientes para la activación del producto, la comprobación de actualizaciones, el formato de DAX y la descarga de reglas externas de prácticas recomendadas. Si está detrás de un proxy: + +1. Configure **Tools > Preferencias > Proxy Settings**. Cambie **Proxy Type** entre `System` y `None`, reinicie Tabular Editor 3 y vuelva a intentar la activación. +2. Si la activación sigue fallando, consulte @proxy-settings para obtener diagnósticos avanzados del proxy. +3. Si el acceso saliente a `api.tabulareditor.com` está bloqueado, utilice la [activación manual](#manual-activation-no-internet). + +> [!TIP] +> La configuración del proxy puede interferir con los cuadros de diálogo de autenticación y otros avisos externos. Después de cambiar el tipo de proxy, cierre siempre Tabular Editor 3 y ábralo de nuevo antes de volver a realizar la prueba. + +## Confirme que usa la versión más reciente -La próxima vez que inicies Tabular Editor 3, se te pedirá una clave de licencia, igual que cuando la herramienta se instaló por primera vez en el equipo. \ No newline at end of file +Los errores relacionados con la activación a veces se corrigen en versiones más recientes de Tabular Editor 3. Confirme que usa la versión más reciente antes de enviar una solicitud de soporte. Compruebe si hay actualizaciones en **Tools > Preferencias > Updates and Feedback**, o descargue el instalador más reciente desde la [página de descargas](xref:downloads). diff --git a/localizedContent/es/content/troubleshooting/locale-not-supported.md b/localizedContent/es/content/troubleshooting/locale-not-supported.md index c0dd1056f..0d6f41d98 100644 --- a/localizedContent/es/content/troubleshooting/locale-not-supported.md +++ b/localizedContent/es/content/troubleshooting/locale-not-supported.md @@ -1,6 +1,6 @@ --- uid: locale-not-supported -title: Configuración regional no admitida +title: Configuración regional no compatible author: Morten Lønskov updated: 2025-09-02 applies_to: @@ -17,20 +17,24 @@ applies_to: full: true --- -# Configuración regional no admitida +# Configuración regional no compatible -Es posible que veas el siguiente mensaje de advertencia en los mensajes: +Es posible que veas alguno de los siguientes mensajes de advertencia: ```plaintext -La configuración regional XXXX no es compatible +The XXXX locale is not supported +``` + +```plaintext +XXXX is an invalid culture identifier ``` en la vista de mensajes de Tabular Editor 3. -![Mensaje de configuración regional no admitida en mensajes](~/content/assets/images/troubleshooting/locale-not-supported-message-view.png) +![Mensaje de configuración regional no admitida](~/content/assets/images/troubleshooting/locale-not-supported-message-view.png) Este problema suele producirse cuando tu equipo usa una **configuración regional que el motor de Analysis Services (SSAS) no admite**. -En la mayoría de los casos, el error se desencadena por otro problema o advertencia subyacente, pero este mensaje se muestra como consecuencia en los mensajes. +En la mayoría de los casos, el error se desencadena por otro problema o advertencia subyacente, pero este mensaje se muestra como consecuencia. --- @@ -38,31 +42,31 @@ En la mayoría de los casos, el error se desencadena por otro problema o adverte ### 1. Conexión a una instancia local de SSAS -Si ejecutas SQL Server Analysis Services (SSAS) localmente en tu equipo: +Si estás ejecutando SQL Server Analysis Services (SSAS) localmente en tu equipo: - **Solución:** Cambia la **cuenta de servicio** que usa la instancia de SSAS. - Actualizar la cuenta suele resolver incompatibilidades de configuración regional no admitida. + Actualizar la cuenta suele resolver incompatibilidades con configuraciones regionales no admitidas. --- -### 2. Conexión a un SSAS remoto, Azure AS o Power BI +### 2. Conexión a una instancia remota de SSAS, Azure AS o Power BI -Al conectarte a una instancia remota, tienes dos posibles soluciones: +Al conectarte a una instancia remota, tienes dos soluciones posibles: -#### Opción A: especificar la configuración regional en la cadena de conexión +#### Opción A: Especificar la configuración regional en la cadena de conexión -Configura explícitamente una configuración regional compatible (p. ej., inglés: 1033) añadiendo `LocaleIdentifier=1033` a tu cadena de conexión. +Establece explícitamente una configuración regional admitida (por ejemplo, inglés – 1033) añadiendo `LocaleIdentifier=1033` a la cadena de conexión. **Ejemplo (Azure AS):** ```plaintext -Data source=asazure://westeurope.asazure.windows.net/instance-name;LocaleIdentifier=1033 +Data Source=asazure://westeurope.asazure.windows.net/instance-name;LocaleIdentifier=1033 ``` -#### Opción B: Cambiar la configuración regional en tu equipo +#### Opción B: Cambiar la configuración regional de tu equipo -Ajusta la configuración regional y de idioma de tu sistema local para que coincida con una configuración regional compatible. +Ajusta la configuración regional y de idioma de tu sistema local para que coincida con una configuración regional admitida. -- **Configuración recomendada:** +- **Ajustes recomendados:** - **Formato regional:** Inglés (Estados Unidos) - - **Idioma de visualización de Windows:** Inglés (Estados Unidos) \ No newline at end of file + - **Idioma para mostrar de Windows:** Inglés (Estados Unidos) \ No newline at end of file diff --git a/localizedContent/zh/content/_ui-strings.json b/localizedContent/zh/content/_ui-strings.json index cfffdf19d..703a84e31 100644 --- a/localizedContent/zh/content/_ui-strings.json +++ b/localizedContent/zh/content/_ui-strings.json @@ -1,48 +1,52 @@ { - "aiTranslationWarning": "本内容由 AI 翻译，尚未经过人工编辑审核。图片和图表仍保留原始语言。", - "header.nav.pricing": "定价", + "aiTranslationWarning": "This content was translated using AI and has not been reviewed by a human editor. Images and charts remain in their original language.", + "header.nav.pricing": "Pricing", "header.nav.download": "下载", - "header.nav.learn": "学习", - "header.nav.resources": "资源", - "header.nav.blog": "博客", - "header.nav.newsletter": "新闻通讯", + "header.nav.learn": "Learn", + "header.nav.resources": "Resources", + "header.nav.blog": "Blog", + "header.nav.newsletter": "Newsletter", "header.nav.publications": "出版物", - "header.nav.documentation": "文档", - "header.nav.supportCommunity": "社区支持", - "header.nav.contactUs": "联系我们", - "header.button1": "免费试用", - "header.button2": "主页", - "footer.heading": "准备开始了吗？", - "footer.button1": "免费试用 Tabular Editor 3", + "header.nav.documentation": "Documentation", + "header.nav.supportCommunity": "Support community", + "header.nav.contactUs": "Contact Us", + "header.button1": "Free trial", + "header.button2": "Main page", + "footer.heading": "Ready to get started?", + "footer.button1": "Try Tabular Editor 3", "footer.button2": "购买 Tabular Editor 3", "footer.aboutUs": "关于我们", + "footer.career": "招贤纳士", + "footer.newsroom": "Newsroom", "footer.contactUs": "联系我们", "footer.technicalSupport": "技术支持", - "footer.privacyPolicy": "隐私与 Cookie 政策", - "footer.termsConditions": "条款与条件", - "footer.licenseTerms": "许可条款", - "appliesTo": "适用于: ", - "availableSince": "自此版本起可用", - "availableIn": "适用范围", - "inThisArticle": "本文内容", - "searchResultsCount": "{count} 条与“{query}”相关的结果", - "searchNoResults": "未找到与“{query}”相关的结果", - "tocFilter": "按标题筛选", - "nextArticle": "下一篇", - "prevArticle": "上一篇", - "themeLight": "浅色", - "themeDark": "深色", - "themeAuto": "自动", - "changeTheme": "切换主题", - "copy": "复制", - "downloadPdf": "下载 PDF", - "search": "搜索文档", - "note": "注意", - "warning": "警告", - "tip": "提示", - "important": "重要", - "caution": "注意事项", - "tableOfContents": "目录", - "selectLanguage": "选择语言", - "copyCode": "复制代码" + "footer.securityTrust": "Security & Trust Center", + "footer.privacyPolicy": "隐私政策", + "footer.cookiePolicy": "Cookie policy", + "footer.siteTerms": "网站条款", + "footer.commercialTerms": "Commercial Terms & Conditions", + "appliesTo": "Applies to: ", + "availableSince": "Available since", + "availableIn": "Available in", + "inThisArticle": "In this article", + "searchResultsCount": "{count} results for \"{query}\"", + "searchNoResults": "No results for \"{query}\"", + "tocFilter": "Filter by title", + "nextArticle": "Next", + "prevArticle": "Previous", + "themeLight": "Light", + "themeDark": "Dark", + "themeAuto": "Auto", + "changeTheme": "Change theme", + "copy": "Copy", + "downloadPdf": "Download PDF", + "search": "Search documentation", + "note": "Note", + "warning": "Warning", + "tip": "Tip", + "important": "Important", + "caution": "Caution", + "tableOfContents": "Table of Contents", + "selectLanguage": "Select language", + "copyCode": "Copy code" } diff --git a/localizedContent/zh/content/features/CSharpScripts/Advanced/script-add-databricks-metadata-descriptions.md b/localizedContent/zh/content/features/CSharpScripts/Advanced/script-add-databricks-metadata-descriptions.md index 57b515550..c5bca6a96 100644 --- a/localizedContent/zh/content/features/CSharpScripts/Advanced/script-add-databricks-metadata-descriptions.md +++ b/localizedContent/zh/content/features/CSharpScripts/Advanced/script-add-databricks-metadata-descriptions.md @@ -15,13 +15,13 @@ applies_to: ## 脚本用途 -本脚本为 Tabular Editor x Databricks 系列的一部分而创建。 在 Unity Catalog 中，可以为表和列添加描述性注释。 此脚本可复用这些信息，自动补全语义模型中的表和列说明。

+该脚本作为 Tabular Editor x Databricks 系列的一部分编写。 在 Unity Catalog 中，可以为表和列添加描述性注释。 此脚本可复用这些信息，自动补全语义模型中的表和列说明。

> [!NOTE] > 此脚本需要 Databricks ODBC 驱动程序。 我们推荐新版 [Databricks ODBC Driver](https://www.databricks.com/spark/odbc-drivers-download)，它将取代旧版 Simba Spark ODBC Driver。 脚本会自动检测已安装的驱动程序，并据此使用相应驱动程序。 每次运行脚本时，都会提示你输入 Databricks 个人访问令牌。 这是用于向 Databricks 进行身份验证所必需的。 -该脚本会使用 Unity Catalog 中的 information_schema 表来检索关系信息，因此你可能需要向 Databricks 管理员再次确认，确保自己有权限查询这些表。

+该脚本会使用 Unity Catalog 中的 information_schema 表来获取关系信息，因此你可能需要与 Databricks 管理员再次确认，确保自己有权限查询这些表。

## 脚本 diff --git a/localizedContent/zh/content/features/CSharpScripts/Advanced/script-create-databricks-relationships.md b/localizedContent/zh/content/features/CSharpScripts/Advanced/script-create-databricks-relationships.md index 8cca4dd29..e3fefe785 100644 --- a/localizedContent/zh/content/features/CSharpScripts/Advanced/script-create-databricks-relationships.md +++ b/localizedContent/zh/content/features/CSharpScripts/Advanced/script-create-databricks-relationships.md @@ -21,7 +21,7 @@ applies_to: > 此脚本需要 Databricks ODBC 驱动程序。 我们推荐使用新版 [Databricks ODBC Driver](https://www.databricks.com/spark/odbc-drivers-download)，它将取代旧版 Simba Spark ODBC Driver。 该脚本会自动检测已安装的驱动程序，并自动使用相应的驱动程序。 每次运行该脚本时，都会提示用户输入 Databricks 个人访问令牌。 这用于对 Databricks 进行身份验证。 -该脚本使用 Unity Catalog 中的 information_schema 表来检索关系信息，因此你可能需要向 Databricks 管理员再次确认，确保自己有权限查询这些表。

+该脚本会使用 Unity Catalog 中的 information_schema 表来检索关系信息，因此您可能需要再与 Databricks 管理员确认一下，确保您有权限查询这些表。

## 脚本 diff --git a/localizedContent/zh/content/features/Command-line-Options.md b/localizedContent/zh/content/features/Command-line-Options.md index 620ca2a89..d5f959313 100644 --- a/localizedContent/zh/content/features/Command-line-Options.md +++ b/localizedContent/zh/content/features/Command-line-Options.md @@ -1,6 +1,6 @@ --- uid: command-line-options -title: 命令行 +title: Command Line (Tabular Editor 2) author: Daniel Otykier updated: 2021-08-26 applies_to: @@ -11,30 +11,33 @@ applies_to: none: true --- -# 命令行 +# Command Line (Tabular Editor 2) -Tabular Editor 可通过命令行执行以执行各种任务，这在自动化构建和部署等场景中可能很有用。 +> [!TIP] +> Looking for the new cross-platform CLI? See @te-cli for the Tabular Editor CLI (Limited Public Preview), a successor that runs on Windows, macOS, and Linux. + +Tabular Editor can be executed from the command-line to perform various tasks, which may be useful in Automated Build and Deployment scenarios, etc. -**注意：** 由于 TabularEditor.exe 是一个 WinForms 应用程序，直接从 Windows 命令提示符执行会导致线程立即返回到提示符。 这可能会在命令脚本等场景中引发问题。 如需等待 TabularEditor.exe 完成其命令行任务，请始终使用以下方式执行：`start /wait TabularEditor ...` +**Note:** Since TabularEditor.exe is a WinForms application, executing it directly from a windows command-prompt will cause the thread to return immediately to the prompt. This may cause issues in command scripts, etc. To wait for TabularEditor.exe to complete its command-line tasks, always execute it using: `start /wait TabularEditor ...` -要查看 Tabular Editor 提供的命令行选项，请运行以下命令： +To view the command-line options available in Tabular Editor, run the following command: -**Windows 命令行：** +**Windows Command line:** ```shell start /wait TabularEditor.exe /? ``` -**PowerShell：** +**PowerShell:** ```powershell $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru -ArgumentList "/?" ``` -输出： +Output: ```cmd -用法: +Usage: TABULAREDITOR ( file | server database | -L [name] ) [-S script1 [script2] [...]] [-SC] [-A [rules] | -AX rules] [(-B | -F | -TMDL) output [id]] [-V | -G] [-T resultsfile] @@ -42,180 +45,185 @@ TABULAREDITOR ( file | server database | -L [name] ) [-S script1 [script2] [...] [-P [-Y]] [-S] [-R [-M]]] [-X xmla_script]] [-W] [-E]] -file 要加载的 Model.bim 文件或 database.json 模型文件夹的完整路径。 -server 用于加载模型的服务器\\实例名称或连接字符串 -database 要加载的模型的数据库 ID。如果为空 (""), 则选择服务器上第一个可用 - 的数据库。 --L / -LOCAL 连接到 Analysis Services 的 Power BI Desktop (本地) 实例。如果未指定 - name，则假定恰好有 1 个实例正在运行。否则，name 应与 Power BI Desktop - 中加载的 .pbix 文件名匹配。 --S / -SCRIPT 在加载后对模型执行指定脚本。 - scriptN 要执行的包含 C# Script 的一个或多个文件的完整路径，或内联 - 脚本。 --SC / -SCHEMACHECK 尝试连接到所有 Provider 数据源，以检测表架构更改。输出... - ...对于数据类型不匹配和未映射的源列的警告 - ...对于未映射的模型列的错误。 --A / -ANALYZE 运行 Best Practice Analyzer 并将结果输出到控制台。 - rules 可选：要分析的附加 BPA 规则文件路径或 URL。如果指定，则不会针对 - 本地用户/本地计算机规则分析模型，但仍会应用模型中定义的规则。 --AX / -ANALYZEX 与 -A / -ANALYZE 相同，但排除在模型注释中指定的规则。 --B / -BIM / -BUILD 将模型 (可选脚本执行后) 保存为 Model.bim 文件。 - output 要保存到的 Model.bim 文件的完整路径。 - id 保存时分配给 Database 对象的可选 id/name。 --F / -FOLDER 将模型 (可选脚本执行后) 保存为文件夹结构。 - output 要保存到的文件夹的完整路径。如果不存在则创建该文件夹。 - id 保存时分配给 Database 对象的可选 id/name。 --TMDL 将模型 (可选脚本执行后) 保存为 TMDL 文件夹结构。 - output 要保存到的 TMDL 文件夹的完整路径。如果不存在则创建该文件夹。 - id 保存时分配给 Database 对象的可选 id/name。 --V / -VSTS 输出 Visual Studio Team Services 日志记录命令。 --G / -GITHUB 输出 GitHub Actions 工作流命令。 --T / -TRX 生成包含执行详细信息的 VSTEST (trx) 文件。 - resultsfile VSTEST XML 文件的文件名。 --D / -DEPLOY 命令行部署 - 如果未指定其他参数，此开关会将模型元数据保存回源 (文件或数据库)。 - server 要部署到的服务器名称或连接字符串到 Analysis Services。 - database 要部署 (创建/覆盖) 的数据库 ID。 - -L / -LOGIN 连接到服务器时禁用集成安全性。指定: - user 用户名 (必须是服务器上具有管理员权限的用户) - pass 密码 - -F / -FULL 部署完整模型元数据，允许覆盖现有数据库。 - -O / -OVERWRITE 允许部署 (覆盖) 现有数据库。 - -C / -CONNECTIONS 部署 (覆盖) 模型中的现有数据源。在 -C 开关之后，您可以 (可选) 指定 - 任意数量的占位符-值对。这样会将模型中每个数据源的连接字符串中出现的 - 指定占位符 (plch1, plch2, ...) 替换为指定的值 (value1, value2, ...)。 - -P / -PARTITIONS 部署 (覆盖) 模型中的现有表分区。 - -Y / -SKIPPOLICY 不要覆盖已定义增量刷新策略的分区。 - -S / -SHARED 部署 (覆盖) 共享表达式。 - -R / -ROLES 部署角色。 - -M / -MEMBERS 部署角色成员。 - -X / -XMLA 不部署。改为生成用于稍后部署的 XMLA/TMSL 脚本。 - xmla_script 新 XMLA/TMSL 脚本输出的文件名。 - -W / -WARN 将有关未处理对象的信息作为警告输出。 - -E / -ERR 如果 Analysis Services 在部署/更新元数据后返回任何错误信息，则返回 - 非零退出代码。 +file Full path of the Model.bim file or database.json model folder to load. +server Server\instance name or connection string from which to load the model +database Database ID of the model to load. If blank (") picks the first available + database on the server. +-L / -LOCAL Connects to a Power BI Desktop (local) instance of Analysis Services. If no + name is specified, this assumes that exactly 1 instance is running. Otherwise, + name should match the name of the .pbix file loaded in Power BI Desktop. +-S / -SCRIPT Execute the specified script on the model after loading. + scriptN Full path of one or more files containing a C# script to execute or an inline + script. +-SC / -SCHEMACHECK Attempts to connect to all Provider Data Sources in order to detect table schema + changes. Outputs... + ...warnings for mismatched data types and unmapped source columns + ...errors for unmapped model columns. +-A / -ANALYZE Runs Best Practice Analyzer and outputs the result to the console. + rules Optional path of file or URL of additional BPA rules to be analyzed. If + specified, model is not analyzed against local user/local machine rules, + but rules defined within the model are still applied. +-AX / -ANALYZEX Same as -A / -ANALYZE but excludes rules specified in the model annotations. +-B / -BIM / -BUILD Saves the model (after optional script execution) as a Model.bim file. + output Full path of the Model.bim file to save to. + id Optional id/name to assign to the Database object when saving. +-F / -FOLDER Saves the model (after optional script execution) as a Folder structure. + output Full path of the folder to save to. Folder is created if it does not exist. + id Optional id/name to assign to the Database object when saving. +-TMDL Saves the model (after optional script execution) as a TMDL folder structure. + output Full path of the TMDL folder to save to. Folder is created if it does not exist. + id Optional id/name to assign to the Database object when saving. +-V / -VSTS Output Visual Studio Team Services logging commands. +-G / -GITHUB Output GitHub Actions workflow commands. +-T / -TRX Produces a VSTEST (trx) file with details on the execution. + resultsfile File name of the VSTEST XML file. +-D / -DEPLOY Command-line deployment + If no additional parameters are specified, this switch will save model metadata + back to the source (file or database). + server Name of server to deploy to or connection string to Analysis Services. + database ID of the database to deploy (create/overwrite). + -L / -LOGIN Disables integrated security when connecting to the server. Specify: + user Username (must be a user with admin rights on the server) + pass Password + -F / -FULL Deploy the full model metadata, allowing overwrite of an existing database. + -O / -OVERWRITE Allow deploy (overwrite) of an existing database. + -C / -CONNECTIONS Deploy (overwrite) existing data sources in the model. After the -C switch, you + can (optionally) specify any number of placeholder-value pairs. Doing so, will + replace any occurrence of the specified placeholders (plch1, plch2, ...) in the + connection strings of every data source in the model, with the specified values + (value1, value2, ...). + -P / -PARTITIONS Deploy (overwrite) existing table partitions in the model. + -Y / -SKIPPOLICY Do not overwrite partitions that have Incremental Refresh Policies defined. + -S / -SHARED Deploy (overwrite) shared expressions. + -R / -ROLES Deploy roles. + -M / -MEMBERS Deploy role members. + -X / -XMLA No deployment. Generate XMLA/TMSL script for later deployment instead. + xmla_script File name of the new XMLA/TMSL script output. + -W / -WARN Outputs information about unprocessed objects as warnings. + -E / -ERR Returns a non-zero exit code if Analysis Services returns any error messages after + the metadata was deployed / updated. ``` > [!WARNING] -> 在 [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases/tag/2.27.0) 中新增 `-S` / `-SHARED` 部署选项标志，这是一次**破坏性变更**。 如果你使用 Tabular Editor CLI 执行部署，并且正在从更早版本的 Tabular Editor 升级，请务必在 CLI 命令中包含该标志，否则**不会部署共享表达式**。 +> The addition of the `-S` / `-SHARED` deployment option flag in [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases/tag/2.27.0) is a **breaking change**. If you're using the Tabular Editor CLI to perform deployments and you are upgrading from an earlier version of Tabular Editor, make sure to include that flag in your CLI commands, as **shared expressions will otherwise not be deployed**. > [!TIP] -> `-F` 标志在 [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases) 中引入。 它用于执行“完整”部署，等同于指定 `-O -C -P -S -R -M`。 +> The `-F` flag was introduced in [Tabular Editor 2.27.0](https://github.com/TabularEditor/TabularEditor/releases). It is used to perform a "full" deployment and is equivalent to specifying `-O -C -P -S -R -M`. -## 连接到 Azure Analysis Services +## Connecting to Azure Analysis Services -在命令中，你可以用任何有效的 SSAS 连接字符串替代服务器名称。 以下命令从 Azure Analysis Services 加载模型，并将其在本地保存为 Model.bim 文件： +You can use any valid SSAS connection string in place of a server name in the command. The following command loads a model from Azure Analysis Services and saves it locally as a Model.bim file: -**Windows 命令行：** +**Windows Command Line:** ```shell start /wait TabularEditor.exe "Provider=MSOLAP;Data Source=asazure://northeurope.asazure.windows.net/MyAASServer;User ID=xxxx;Password=xxxx;Persist Security Info=True;Impersonation Level=Impersonate" MyModelDB -B "C:\Projects\FromAzure\Model.bim" ``` -**PowerShell：** +**PowerShell:** ```powershell $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` -ArgumentList "`"Provider=MSOLAP;Data Source=asazure://northeurope.asazure.windows.net/MyAASServer;User ID=xxxx;Password=xxxx;Persist Security Info=True;Impersonation Level=Impersonate`" MyModelDB -B C:\Projects\FromAzure\Model.bim" ``` -如果你希望使用服务主体（应用程序 ID 和密钥）进行连接，而不是通过 Azure Active Directory 身份验证，可以使用以下连接字符串： +If you prefer to connect using a Service Principal (Application ID and Key) instead of Azure Active Directory authentication, you can use the following connection string: ``` Provider=MSOLAP;Data Source=asazure://northeurope.asazure.windows.net/MyAASServer;User ID=app:@;Password=;Persist Security Info=True;Impersonation Level=Impersonate ``` -## 自动化脚本修改 +## Automating script changes -如果你已在 Tabular Editor 中创建了脚本，并希望在部署前将该脚本应用到 Model.bim 文件，可以使用命令行选项“-S”（Script）： +If you have created a script inside Tabular Editor, and you want to apply this script to a Model.bim file prior to deployment, you can use the command-line option "-S" (Script): -**Windows 命令行：** +**Windows Command Line:** ```shell start /wait TabularEditor.exe "C:\Projects\MyModel\Model.bim" -S "C:\Projects\MyModel\MyScript.cs" -D localhost\tabular MyModel ``` -**PowerShell：** +**PowerShell:** ```powershell $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` -ArgumentList "`"C:\Projects\MyModel\Model.bim`" -S `"C:\Projects\MyModel\MyScript.cs`" -D `"localhost\tabular`" `"MyModel`"" ``` -该命令会在 Tabular Editor 中加载 Model.bim 文件，应用指定脚本，并将修改后的模型作为新数据库“MyModel”部署到“localhost\tabular”服务器。 如果你希望覆盖服务器上已存在的同名数据库，请使用“-O”（Overwrite）开关。 +This command will load the Model.bim file in Tabular Editor, apply the specified script and deploy the modified model to the "localhost\tabular" server as a new database "MyModel". Use the "-O" (Overwrite) switch if you want to overwrite an existing database on the server with the same name. -你也可以用“-B”（Build）开关替代“-D”（Deploy）开关，将修改后的模型输出为新的 Model.bim 文件，而不是直接部署到服务器。 当你想用其他部署工具来部署模型，或希望在部署前先在 Visual Studio 或 Tabular Editor 中检查模型时，这会很有用。 在自动化构建场景中也同样实用：你可以在部署前，将修改后的模型作为发布产物进行保存。 +You can use the "-B" (Build) switch instead of the "-D" (Deploy) switch, to output the modified model as a new Model.bim file, instead of deploying it directly to a server. This is useful if you want to deploy the model using another deployment tool, or if you want to inspect the model in Visual Studio or Tabular Editor prior to deployment. It could also be useful for automated build scenarios, where you want to store the modified model as an artifact of the release, before deploying. -## 在部署期间修改连接字符串 +## Modifying connection strings during deployment -假设你的模型包含一个数据源，其连接字符串如下： +Let's assume you have a model containing a Data Source with the following connection string: ``` Provider=SQLOLEDB.1;Data Source=sqldwdev;Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=DW ``` -在部署期间，你希望修改该字符串，使其指向 UAT 或生产数据库。 最佳做法是：先用脚本将整个连接字符串替换为一个占位符值，然后使用 -C 开关将该占位符替换为实际连接字符串。 +During deployment, you want to modify the string, to point to a UAT or production database. The best way to do this, is to first use a script, that changes the entire connection string into a placeholder value, and then use the -C switch to swap the placeholder with the actual connection string. -将以下脚本放到名为“ClearConnectionStrings.cs”或类似名称的文件中： +Put the following script into a file called "ClearConnectionStrings.cs" or similar: ```csharp -// 这将把模型中所有 Provider（旧版）数据源的连接字符串替换为 -// 基于数据源名称的占位符。例如，如果你的数据源名为 -// "SQLDW"，运行此脚本后，连接字符串将变为 "SQLDW"： +// This will replace the connection string of all Provider (legacy) data sources in the model +// with a placeholder based on the name of the data source. E.g., if your data source is called +// "SQLDW", the connection string after running this script would be "SQLDW": foreach(var ds in Model.DataSources.OfType()) ds.ConnectionString = ds.Name; ``` -我们可以让 Tabular Editor 执行该脚本，然后通过下面的命令进行占位符替换： +We can instruct Tabular Editor to execute the script, and then perform placeholder swapping using the following command: -**Windows 命令行：** +**Windows Command Line:** ```shell start /wait TabularEditor.exe "Model.bim" -S "ClearConnectionStrings.cs" -D localhost\tabular MyModel -C "SQLDW" "Provider=SQLOLEDB.1;Data Source=sqldwprod;Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=DW" ``` -**PowerShell：** +**PowerShell:** ```powershell $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` -ArgumentList "Model.bim -S ClearConnectionStrings.cs -D localhost\tabular MyModel -C SQLDW `"Provider=SQLOLEDB.1;Data Source=sqldwprod;Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=DW`"" ``` -上述命令会将 Model.bim 文件部署为“localhost\\tabular”SSAS 实例上的一个新的 SSAS 数据库“MyModel”。 在部署之前，脚本会先把所有提供程序（旧版）数据源上的连接字符串替换为数据源名称，作为占位符使用。 假设我们只有一个名为“SQLDW”的数据源，那么 -C 开关会更新连接字符串，将“SQLDW”替换为指定的完整字符串。 +The command above, will deploy the Model.bim file as a new SSAS database "MyModel" on the "localhost\tabular" SSAS instance. Before deployment, the script is used to replace all connection strings on provider (legacy) data sources, with the name of the data source, to be used as a placeholder. Assuming we only have a single data source called "SQLDW", the -C switch will then update the connection string, replacing "SQLDW" with the entire string specified. -当你需要将同一个模型部署到多个环境、并让它们从不同（结构相同）的来源处理数据时，这个技巧就很有用——例如生产、预生产或 UAT 数据库。 如果使用 Azure DevOps（见下文），建议用变量来保存实际要使用的连接字符串，而不是把它硬编码在命令里。 +This technique is useful for scenarios, where you want to deploy the same model to multiple environments that should process data from different (identical) sources - for example, a production, pre-prod or UAT database. If using Azure DevOps (see below), consider using a variable to store the actual connection string to be used, instead of hardcoding it in the command. -## 与 Azure DevOps 集成 +## Integration with Azure DevOps -如果你想在 Azure DevOps 管道中使用 Tabular Editor CLI，那么脚本中执行的任何 TabularEditor.exe 命令都应该使用“-V”开关。 该开关会让 Tabular Editor 以 [Azure DevOps 可读取的格式](https://github.com/Microsoft/vsts-tasks/blob/master/docs/authoring/commands.md) 输出日志命令。 这样 Azure DevOps 才能正确响应错误等情况。 +If you want to use the Tabular Editor CLI inside an Azure DevOps pipeline, you should use the "-V" switch on any TabularEditor.exe command executed by your script. This switch will cause Tabular Editor to output logging commands in a [format readable by Azure DevOps](https://github.com/Microsoft/vsts-tasks/blob/master/docs/authoring/commands.md). These allow Azure DevOps to react properly to errors, etc. -通过命令行执行部署时，未处理对象的相关信息会输出到命令提示符中。 在自动化部署场景中，你可能希望构建代理能够对对象变为未处理的情况做出响应，例如新增列、修改计算表格的 DAX 表达式等。 这种情况下，除了上面提到的“-V”开关之外，你还可以使用“-W”开关，将这些信息以警告的形式输出。 这样一来，部署完成后会向 Azure DevOps 返回“SucceededWithIssues”状态。 如果你希望在成功部署后，服务器报告任何 DAX 错误时让部署返回“Failed”状态，也可以使用“-E”开关。 +When performing deployment through the command-line, information about unprocessed objects will be outputted to the prompt. In automated deployment scenarios, you may want your build agent to react to situations where objects become unprocessed, for example when adding new columns, changing the DAX expression of a calculated table, etc. In this case, you can use the "-W" switch in addition to the "-V" switch mentioned above, to output this information as warnings. Doing so, will cause the deployment to return the "SucceededWithIssues" status to Azure DevOps, after deployment is completed. You may also use the "-E" switch if you want the deployment to return status "Failed" in case the server reports any DAX errors back after successful deployment. -在 Azure DevOps 管道的“命令行任务”中执行 TabularEditor.exe 时，不需要使用 `start /wait`。 因为命令行任务会一直等待，直到该任务启动的所有线程都已终止，才会结束。 换句话说，只有在调用 TabularEditor.exe 之后还要执行其他命令时，才需要使用 `start /wait`；并且在这种情况下，请确保使用 `start /B /wait`。 需要使用 `/B` 开关，才能将 TabularEditor.exe 的输出正确地通过管道回传到流水线日志中。 +`start /wait` is not necessary when executing TabularEditor.exe within a Command Line Task in an Azure DevOps pipeline. This is because the Command Line Task will not complete, until all threads spawned by the task have terminated. In other words, you need only use `start /wait` if you have additional commands following the call to TabularEditor.exe, and in this case, make sure to use `start /B /wait`. The `/B` switch is required in order for the output from TabularEditor.exe to be correctly piped back to the pipeline log. ```shell TabularEditor.exe "C:\Projects\My Model\Model.bim" -D ssasserver databasename -O -C -P -S -V -E -W ``` -或者执行多条命令： +Or with multiple commands: ```shell start /B /wait TabularEditor.exe "C:\Projects\Finance\Model.bim" -D ssasserver Finance -O -C -P -S -V -E -W start /B /wait TabularEditor.exe "C:\Projects\Sales\Model.bim" -D ssasserver Sales -O -C -P -S -V -E -W ``` -下图展示了此类构建在 Azure DevOps 中的样子： +The figure below shows what such a build looks like in Azure DevOps: ![image](https://user-images.githubusercontent.com/8976200/27128146-bc044356-50fd-11e7-9a67-b893fc48ea50.png) -如果部署因任何原因失败，Tabular Editor 都会向 Azure DevOps 返回“Failed”状态，无论你是否使用了“-W”开关。 +If the deployment fails for any reason, Tabular Editor returns the "Failed" status to Azure DevOps, regardless of whether or not you are using the "-W" switch. -如需了解 Azure DevOps 与 Tabular Editor 的更多信息，请参阅[这套博客系列](https://tabulareditor.github.io/2019/02/20/DevOps1.html)（尤其是[第 3 章](https://tabulareditor.github.io/2019/10/08/DevOps3.html)及之后的内容）。 +For more information on Azure DevOps and Tabular Editor, [take a look at this blog series](https://tabulareditor.github.io/2019/02/20/DevOps1.html) (especially [chapter 3](https://tabulareditor.github.io/2019/10/08/DevOps3.html) and onward). -### Azure DevOps PowerShell 任务 +### Azure DevOps PowerShell Task -如果你更倾向于使用 PowerShell 任务而不是命令行任务，则必须像上面演示的那样，使用 `Start-Process` cmdlet 来执行 TabularEditor.exe。 此外，请确保在 PowerShell 脚本中将进程退出代码作为 exit 参数传递，这样 Tabular Editor 中发生的错误就会导致 PowerShell 任务失败： +If you prefer to use a PowerShell task instead of a command line task, you must execute TabularEditor.exe using the `Start-Process` cmdlet, as demonstrated above. In addition, make sure to pass the process exit code as the exit parameter in your PowerShell script, so that errors occurring in Tabular Editor will cause the PowerShell task to fail: ```powershell $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` @@ -223,11 +231,11 @@ $p = Start-Process -filePath TabularEditor.exe -Wait -NoNewWindow -PassThru ` exit $p.ExitCode ``` -### 通过环境变量将参数传递给脚本 +### Passing Parameters to Scripts via Environment Variables -在 Azure DevOps 管道中使用 `-S` 选项执行 C# 脚本时，建议通过环境变量而非命令行参数传递参数。 C# 脚本可以使用 `Environment.GetEnvironmentVariable()` 读取环境变量；Azure DevOps 会自动将所有管道变量作为环境变量提供。 +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# 脚本可以使用 `Environment.GetEnvironmentVariable()` 读取环境变量；Azure DevOps 会自动将所有管道变量作为环境变量提供。 -**示例：在 YAML 中设置环境变量：** +**Example - Setting environment variables in YAML:** ```yaml variables: @@ -242,7 +250,7 @@ steps: SERVER_NAME: $(serverName) ``` -**示例：使用环境变量的 PowerShell 任务：** +**Example - PowerShell Task with environment variables:** ```yaml - task: PowerShell@2 @@ -258,7 +266,7 @@ steps: exit $p.ExitCode ``` -**在 C# Script 中（例如 UpdateModel.csx）：** +**In your C# script (e.g., UpdateModel.csx):** ```csharp var deployEnv = Environment.GetEnvironmentVariable("DEPLOY_ENV"); @@ -273,49 +281,49 @@ foreach(var ds in Model.DataSources.OfType()) } ``` -这种方法比在脚本中硬编码值或使用复杂的字符串替换方式更简洁、更易维护。 有关在 C# 脚本中使用环境变量的更多信息，请参阅 [C# Scripts - Accessing Environment Variables](xref:csharp-scripts#accessing-environment-variables)。 +This approach is cleaner and more maintainable than hardcoding values in scripts or using complex string replacement techniques. 有关在 C# 脚本中使用环境变量的更多信息，请参阅 [C# Scripts - Accessing Environment Variables](xref:csharp-scripts#accessing-environment-variables)。 -## 运行 Best Practice Analyzer +## Running the Best Practice Analyzer -你可以使用 "-A" 开关，让 Tabular Editor 扫描模型，找出所有违反最佳实践规则的对象（规则可定义在本机上，位于 %AppData%\..\Local\TabularEditor\BPARules.json 文件中；也可作为注释存储在模型本身中）。 或者，你也可以在 "-A" 开关后指定一个包含最佳实践规则的 .json 文件路径，以使用该文件中定义的规则来扫描模型。 违规的对象将输出到控制台。 +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. -如果你同时使用“-V”开关，则每条规则的严重性级别将决定如何将规则违规情况报告到构建管道： +If you're also using the "-V" switch, the severity level of each rule will determine how the rule violation is reported to the build pipeline: -- Severity = 1 仅作信息提示 -- Severity = 2 会触发 WARNING -- Severity >= 3 会触发 ERROR +- Severity = 1 will be informational only +- Severity = 2 will cause a WARNING +- Severity >= 3 will cause an ERROR -## 执行数据源架构检查 +## Performing a data source schema check -从 [2.8 版本](https://github.com/TabularEditor/TabularEditor/releases/tag/2.8)开始，你可以使用 -SC（-SCHEMACHECK）开关来验证表的源查询。 这相当于调用[刷新表元数据 UI](xref:importing-tables-te2#refreshing-table-metadata)，但不会对模型做任何更改，而是会将架构差异报告到控制台。 数据类型更改以及源中新增的列将以警告形式报告。 源中缺失的列将以错误形式报告。 如果同时指定了 -SC（-SCHEMACHECK）和 -S（-SCRIPT）开关，则架构检查会在脚本成功执行之后运行。这样你就可以在执行架构检查之前修改数据源属性，例如用于指定凭据密码。 +As of [version 2.8](https://github.com/TabularEditor/TabularEditor/releases/tag/2.8), you can use the -SC (-SCHEMACHECK) switch to validate table source queries. This is equivalent to invoking the [Refresh Table Metadata UI](xref:importing-tables-te2#refreshing-table-metadata) except that no changes will be made to the model, but schema differences will be reported to the console. Changed Data Types and columns that were added to the source will be reported as warnings. Missing source columns will be reported as errors. If both the -SC (-SCHEMACHECK) and -S (-SCRIPT) switch are specified, the schema check will run AFTER the script has successfully executed, allowing you to modify Data Source properties before the schema check is performed, for example in order to specify a credential password. -如果你希望架构检查以特定方式处理表和列，也可以为它们添加注释。 [更多信息请参见此处](xref:importing-tables-te2#ignoring-objects)。 +You can also annotate tables and columns if you want the schema check to treat them in a specific way. [More information here](xref:importing-tables-te2#ignoring-objects). -## 命令行输出与退出代码 +## Command Line output and Exit Codes -命令行会根据所使用的开关以及执行过程中遇到的事件，提供各类详细信息。 退出代码在 [2.7.4 版本](https://github.com/TabularEditor/TabularEditor/releases/tag/2.7.4) 中引入。 +The command line provides various details, depending on the switches used and any events encountered during execution. Exit Codes were introduced in [version 2.7.4](https://github.com/TabularEditor/TabularEditor/releases/tag/2.7.4). -| 级别 | 命令 | 信息 | 说明 | -| -- | ------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| 错误 | （任意） | 参数语法无效 | 向 Tabular Editor CLI 提供了无效的参数 | -| 错误 | （任意） | 未找到文件…… | | -| 错误 | （任意） | 加载文件时出错…… | 文件已损坏，或不包含 JSON 格式的有效 TOM 元数据 | -| 错误 | （任意） | 加载模型时出错…… | 无法连接到所提供的 Analysis Services 实例，或找不到数据库，或数据库元数据已损坏，或数据库的兼容级别不受支持 | -| 错误 | -SCRIPT | 未找到指定的脚本文件 | | -| 错误 | -SCRIPT | 脚本编译错误： | 脚本包含无效的 C# 语法。 详细信息将输出在后续几行中。 | -| 错误 | -SCRIPT | 脚本执行错误：…… | 执行脚本时发生未处理的异常。 | -| 信息 | -SCRIPT | 脚本行号 #：…… | 在脚本中使用 `Info(string)` 或 `Output(string)` 方法。 | -| 警告 | -SCRIPT | 脚本警告：…… | 在脚本中使用 `Warning(string)` 方法。 | -| 错误 | -SCRIPT | 脚本错误：…… | 在脚本中使用 `Error(string)` 方法。 | -| 错误 | -FOLDER, -BIM | -FOLDER 和 -BIM 参数互斥。 | Tabular Editor 无法在一次运行中将当前加载的模型同时保存为文件夹结构和 .bim 文件。 | -| 错误 | -ANALYZE | 未找到规则文件：…… | | -| 错误 | -ANALYZE | 无效的规则文件：…… | 指定的 BPA 规则文件已损坏或不包含有效的 JSON。 | -| 信息 | -ANALYZE | …… 违反规则…… | Best Practice Analyzer 针对严重性级别为 1 或以下规则的结果。 | -| 警告 | -ANALYZE | …… 违反规则 …… | Best Practice Analyzer 针对严重性级别 2 的规则的结果。 | -| 错误 | -ANALYZE | …… 违反规则 …… | Best Practice Analyzer 针对严重性级别 3 或更高的规则的结果。 | -| 错误 | -DEPLOY | 部署失败！ …… | 由 Analysis Services 实例直接返回的失败原因（例如：找不到数据库、不允许数据库覆盖等） | -| 信息 | -DEPLOY | 未处理的对象: …… | 成功部署后处于 "NoData" 或 "CalculationNeeded" 状态的对象。 使用 -W 开关将这些按 Level=Warning 处理。 | -| 警告 | -DEPLOY | 对象不处于"Ready"状态: …… | 成功部署后处于 "DependencyError"、"EvaluationError" 或 "SemanticError" 状态的对象。 如果使用 -W 开关，还包括处于“NoData”或“CalculationNeeded”状态的对象。 | -| 警告 | -DEPLOY | X 上发生错误：…… | 成功部署后包含无效 DAX 的对象（度量值、计算列、计算表格、角色）。 使用 -E 选项将这些视为 Level=Error。 | +| Level | Command | Message | Clarification | +| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Error | (Any) | Invalid argument syntax | Invalid arguments were provided to the Tabular Editor CLI | +| Error | (Any) | File not found: ... | | +| Error | (Any) | Error loading file: ... | The file is corrupt or does not contain valid TOM metadata in a JSON format | +| Error | (Any) | Error loading model: ... | Not able to connect to the provided Analysis Services instance, database not found, database metadata corrupt or database not of a supported compatibility level | +| Error | -SCRIPT | Specified script file not found | | +| Error | -SCRIPT | Script compilation errors: | Script contained invalid C# syntax. Details will be outputted on the following lines. | +| Error | -SCRIPT | Script execution error: ... | Unhandled exception when executing the script. | +| Information | -SCRIPT | Script line #: ... | Use of the `Info(string)` or `Output(string)` methods within the script. | +| Warning | -SCRIPT | Script warning: ... | Use of the `Warning(string)` method within the script. | +| Error | -SCRIPT | Script error: ... | Use of the `Error(string)` method within the script. | +| Error | -FOLDER, -BIM | -FOLDER and -BIM arguments are mutually exclusive. | Tabular Editor can not save the currently loaded model to a folder structure and a .bim file in a single execution. | +| Error | -ANALYZE | Rulefile not found: ... | | +| Error | -ANALYZE | Invalid rulefile: ... | The specified BPA rulefile is corrupt or does not contain valid JSON. | +| Information | -ANALYZE | ... violates rule ... | Best Practice Analyzer results for rules of severity level 1 or lower. | +| Warning | -ANALYZE | ... violates rule ... | Best Practice Analyzer results for rules of severity level 2. | +| Error | -ANALYZE | ... violates rule ... | Best Practice Analyzer results for rules of severity level 3 or higher. | +| Error | -DEPLOY | Deployment failed! ... | Failure reason returned directly from Analysis Service instance (for example: Database not found, Database override not allowed, etc.) | +| Information | -DEPLOY | Unprocessed object: ... | Objects that are in state "NoData" or "CalculationNeeded" after successful deployment. Use the -W switch to treat these as Level=Warning. | +| Warning | -DEPLOY | Object not in "Ready" state: ... | 成功部署后处于 "DependencyError"、"EvaluationError" 或 "SemanticError" 状态的对象。 If using the -W switch, also includes objects in state "NoData" or "CalculationNeeded". | +| Warning | -DEPLOY | Error on X:... | Objects containing invalid DAX after successful deployment (measures, calculated columns, calculated tables, roles). Use the -E switch to treat these as Level=Error. | -如果检测到任何级别为“Error”的输出，Tabular Editor 将返回 Exit Code = 1。 否则返回 0。 +If any of the "Error" level outputs are encountered, Tabular Editor will return Exit Code = 1. Otherwise 0. diff --git a/localizedContent/zh/content/features/Semantic-Model/direct-lake-sql-model.md b/localizedContent/zh/content/features/Semantic-Model/direct-lake-sql-model.md index 3c5956055..4e38be0e0 100644 --- a/localizedContent/zh/content/features/Semantic-Model/direct-lake-sql-model.md +++ b/localizedContent/zh/content/features/Semantic-Model/direct-lake-sql-model.md @@ -22,10 +22,10 @@ applies_to: SQL 语义模型上的 Direct Lake 可通过 SQL 端点直接连接到存储在 [Fabric 中的 OneLake](https://learn.microsoft.com/en-us/fabric/onelake/onelake-overview) 中的数据源。 > [!IMPORTANT] -> 自 [Tabular Editor 3.22.0](../../references/release-notes/3_22_0.md) 起，Tabular Editor 3 已支持 OneLake 上的 Direct Lake，并在大多数场景下建议使用。 更多信息请参阅我们的 [Direct Lake 指南](xref:direct-lake-guidance)。 +> 自 [Tabular Editor 3.22.0](../../references/release-notes/3_22_0.md) 起，Tabular Editor 3 支持在 OneLake 上使用 Direct Lake，且在大多数情况下建议采用此方式。 更多信息请参阅我们的 [Direct Lake 指南](xref:direct-lake-guidance)。 -Tabular Editor 3 可以创建并连接此类模型。 如需教程，请参阅我们的博客文章：[Direct Lake 语义模型：如何在 Tabular Editor 中使用](https://blog.tabulareditor.com/2023/09/26/fabric-direct-lake-with-tabular-editor-part-2-creation/)。 -Tabular Editor 3 可以通过 Lakehouse 和 Warehouse 的 SQL 端点创建 Direct Lake 语义模型。 +Tabular Editor 3 可以创建并连接此类模型。 有关本主题的教程，请参阅我们的博客文章：[Direct Lake 语义模型：如何在 Tabular Editor 中使用它们](https://blog.tabulareditor.com/2023/09/26/fabric-direct-lake-with-tabular-editor-part-2-creation/)。 +Tabular Editor 3 可以通过 Lakehouse 和 Warehouse SQL Endpoint 创建 Direct Lake 语义模型。 Tabular Editor 2 可以连接到 Direct Lake 语义模型，但不提供用于创建新表或 Direct Lake 语义模型的内置功能。 这需要手动完成，或使用 C# Script 来实现。 @@ -42,27 +42,27 @@ Tabular Editor 2 可以连接到 Direct Lake 语义模型，但不提供用于 使用该复选框可确保设置 Direct Lake 特有的属性与注释，并将表的导入限制为 Direct Lake 支持的数据源。 > [!NOTE] -> SQL 上的 Direct Lake 模型目前使用的排序规则与常规 Power BI 导入语义模型所用的不同。 这可能会导致在查询模型或在 DAX 代码中引用对象名称时得到不同的结果。 +> 基于 SQL 的 Direct Lake 模型当前使用的排序规则与常规 Power BI 导入语义模型不同。 这可能会导致在查询模型或在 DAX 代码中引用对象名称时得到不同的结果。 > 更多信息见 Kurt Buhler 的这篇博文：[Power BI 中区分大小写的模型：影响与注意事项](https://data-goblins.com/power-bi/case-specific)。 > [!IMPORTANT] -> 从 [Tabular Editor 3.22.0](../../references/release-notes/3_22_0.md) 开始，“新建模型”对话框中已移除 Direct Lake 复选框。 如果在 SQL 上使用 Direct Lake，则必须[手动将模型的排序规则设置为与 Fabric Warehouse 的排序规则一致](xref:direct-lake-guidance#collation)。 +> 从 [Tabular Editor 3.22.0](../../references/release-notes/3_22_0.md) 开始，“新建模型”对话框中已移除 Direct Lake 复选框。 如果在 SQL 上使用 Direct Lake，你必须[手动将模型的排序规则设置为与 Fabric Warehouse 的排序规则一致](xref:direct-lake-guidance#collation)。 ## 为新模型和表导入设定框架 -Tabular Editor 3（3.15.0 或更高版本）会在首次部署时自动对模型执行框架化（刷新）。 这是为了确保 Direct Lake 模式已启用——否则模型会自动回退到 DirectQuery。 +Tabular Editor 3（3.15.0 或更高版本）会在首次部署时自动对模型执行框架化（刷新）。 这是为了确保启用 Direct Lake 模式；否则模型会自动回退到 DirectQuery。 -此外，导入新表后，Tabular Editor 3（3.15.0 或更高版本）会在下一次保存时对模型执行框架化（刷新）。 该首选项位于 **Tools > Preferences > Model Deployment > Data Refresh** 下。 +此外，在导入新表后，Tabular Editor 3（3.15.0 或更高版本）会在你下次保存模型时对模型进行 framing（刷新）。 该首选项位于 **Tools > Preferences > Model Deployment > Data Refresh** 下。 ## 识别 Direct Lake 模型 -Tabular Editor 顶部标题栏会显示该 Tabular Editor 实例当前打开的模型类型。 此外，TOM Explorer 会显示每张表的类型和模式（Import、DirectQuery、Dual 或 Direct Lake）。 如果模型混用了多种表模式，标题栏将显示“混合”。 目前，Direct Lake on SQL 模型无法包含处于 Import、DirectQuery 或 Dual 模式的表。 +Tabular Editor 顶部的标题栏会显示该 Tabular Editor 实例中当前打开的是哪种类型的模型。 此外，TOM Explorer 会显示每张表的类型和模式（Import、DirectQuery、Dual 或 Direct Lake）。 如果模型混用了多种表模式，标题栏将显示“混合”。 目前，Direct Lake on SQL 模型无法包含处于 Import、DirectQuery 或 Dual 模式的表。 ## 将 Direct Lake 模型转换为导入模式 -下面的 C# Script 会将现有模型转换为导入模式。 如果你的模型对数据延迟的要求并不需要 Direct Lake，或者你想避开 Direct Lake 模型的限制，但已经在 Fabric 中开始构建该模型，那么这会很有用。 +下面的 C# Script 会将现有模型转换为导入模式。 如果你的模型对数据延迟的要求不高，无需 Direct Lake，或者你想避开 Direct Lake 模型的限制，但已经在 Fabric 中开始构建 Direct Lake 模型，那么这会很有用。 -当 Tabular Editor 通过 XMLA endpoint 连接到语义模型时，即可运行该脚本。 不过，Microsoft 不支持直接将更改保存回 Power BI/Fabric Workspace。 为规避这一限制，建议使用“Model > Deploy...”选项。 这样就可以将新转换的模型作为 Workspace 中的一个新实体进行部署。 +当 Tabular Editor 通过 XMLA endpoint 连接到语义模型后，即可运行该脚本。 不过，Microsoft 不支持直接将更改保存回 Power BI/Fabric Workspace。 为规避这一限制，建议使用“Model > Deploy...”选项。 这样就可以将新转换的模型作为 Workspace 中的一个新实体进行部署。 > [!NOTE] > 部署新转换的导入模式模型后，你需要指定用于访问 Lakehouse 的凭据，才能将数据刷新到模型中。 diff --git a/localizedContent/zh/content/features/Semantic-Model/semantic-model-types.md b/localizedContent/zh/content/features/Semantic-Model/semantic-model-types.md index 2b1f8b4b1..348341866 100644 --- a/localizedContent/zh/content/features/Semantic-Model/semantic-model-types.md +++ b/localizedContent/zh/content/features/Semantic-Model/semantic-model-types.md @@ -19,7 +19,7 @@ applies_to: # 语义模型类型 -Tabular Editor 可与多种不同的模型类型配合使用。 下面概述了哪些模型类型可与 Tabular Editor 配合使用，以及每种模型类型可用的功能。 +Tabular Editor 支持多种不同的模型类型。 下面概述了哪些模型类型可与 Tabular Editor 一起使用，以及每种模型类型可使用哪些功能。 | 模型类型 | 导入 | DirectQuery | OneLake 上的 Direct Lake | SQL 上的 Direct Lake | .pbix | .pbip | | -------------------------------------- | -- | ----------- | --------------------------------------- | ------------------------------------------ | --------------------- | --------------------- | @@ -60,7 +60,7 @@ Tabular Editor 可与多种不同的模型类型配合使用。 下面概述了 > 2025 年六月发布的 Power BI Desktop 版本已解除对第三方工具的所有建模限制。 在此之前，许多建模操作都不受支持。 见 [Power BI Desktop 限制](xref:desktop-limitations)。 > [!TIP] -> 有关 Direct Lake 模型限制的更多详细信息，请参阅 Microsoft 的 [Direct Lake 文档](https://learn.microsoft.com/en-us/fabric/fundamentals/direct-lake-overview) +> 如需了解 Direct Lake 模型限制的更多详细信息，请参阅 Microsoft 的 [Direct Lake 文档](https://learn.microsoft.com/en-us/fabric/fundamentals/direct-lake-overview) ## 不受支持的语义模型类型 diff --git a/localizedContent/zh/content/features/Useful-script-snippets.md b/localizedContent/zh/content/features/Useful-script-snippets.md index 9057ab04b..c2a1ee247 100644 --- a/localizedContent/zh/content/features/Useful-script-snippets.md +++ b/localizedContent/zh/content/features/Useful-script-snippets.md @@ -19,7 +19,7 @@ applies_to: # 实用脚本片段 -这里汇总了一些简短的脚本片段，帮助你快速上手 Tabular Editor 的 [高级脚本功能](/Advanced-Scripting)。 其中很多脚本都适合保存为 [自定义操作](/Custom-Actions)，这样你就可以通过上下文菜单轻松复用它们。' +这里汇总了一些小脚本片段，帮助你快速上手 Tabular Editor 的 [高级脚本功能](/Advanced-Scripting)。 其中很多脚本都适合保存为 [自定义操作](/Custom-Actions)，这样你就可以通过上下文菜单轻松复用它们。' 另外，也别忘了看看我们的脚本库 @csharp-script-library，里面有更多贴近实际场景的示例，展示了你可以如何利用 Tabular Editor 的脚本功能。 @@ -57,7 +57,7 @@ foreach(var c in Selected.Columns) ## 生成时间智能度量值 -首先，为各个时间智能聚合分别创建自定义操作。 例如： +首先，为每项时间智能聚合创建自定义操作。 例如： ```csharp // 为每个选中的度量值创建一个 TOTALYTD 度量值。 diff --git a/localizedContent/zh/content/features/ai-assistant.md b/localizedContent/zh/content/features/ai-assistant.md index 810693019..848499f35 100644 --- a/localizedContent/zh/content/features/ai-assistant.md +++ b/localizedContent/zh/content/features/ai-assistant.md @@ -20,135 +20,135 @@ applies_to: # AI 助手 -AI 助手是一款基于聊天的界面，面向 AI 辅助的语义模型开发，旨在帮助你更快地创建语义模型。 它采用企业级设计，可让你完全掌控发送给 AI 的内容，并内置同意管理，让你可以放心使用 AI 助手。 AI 助手已通过独立的安全渗透测试。 详情请访问 [Tabular Editor 信任中心](https://trust.tabulareditor.com)。 它可以浏览模型元数据、编写并执行 DAX 查询、生成 C# Script、运行 Best Practice Analyzer 检查、查询 VertiPaq分析器统计信息，并搜索 Tabular Editor 知识库。 +AI 助手是一个用于 AI 辅助语义模型开发的基于聊天的界面，旨在帮助你更快地创建语义模型。 它采用企业级设计，你可以完全控制发送给 AI 的内容，并内置同意管理功能，因此可以放心使用 AI 助手。 AI 助手已接受独立的安全渗透测试。 有关详细信息，请访问 [Tabular Editor 信任中心](https://trust.tabulareditor.com)。 它可以浏览你的模型元数据、编写并执行 DAX 查询、生成 C# Script、运行 Best Practice Analyzer 检查、查询 VertiPaq分析器统计信息，并搜索 Tabular Editor 知识库。 -AI 助手采用自带密钥 BYOK 模式。 你只需从受支持的提供商中选择一个并提供其 API 密钥，助手就会直接通过该提供商的 API 运行。 +AI 助手采用自带密钥 BYOK 模式。 你只需提供某个受支持提供商的 API 密钥，助手就会直接调用该提供商的 API 运行。 > [!NOTE] -> AI 助手自 Tabular Editor 3.26.0 起处于公开预览阶段。 我们欢迎你反馈使用体验，帮助我们持续改进。 +> AI 助手自 Tabular Editor 3.26.0 起进入公开预览。 我们会继续完善这项功能，欢迎你反馈使用体验。 -![AI Assistant First Pane on Open](~/content/assets/images/ai-assistant/ai-assistant-panel-first-open.png) +![AI 助手首次打开时的面板](~/content/assets/images/ai-assistant/ai-assistant-panel-first-open.png) -## 快速入门 +## 开始使用 1. 打开 **工具 > 偏好 > AI 助手** -2. 选择 AI 提供商——全新安装时默认是 **无（AI 已禁用）**——然后输入你的 API 密钥 +2. 选择你的 AI 提供商——全新安装时默认为 **无（AI 已禁用）**——然后输入你的 API 密钥 3. 从 **视图 > AI 助手** 打开 AI 助手面板 -4. 输入一条信息并按 **Enter** 键开始对话 +4. 输入信息后按 **Enter** 开始对话 > [!TIP] > 使用我们的 [AI 助手交互式演示](https://demos.tabulareditor.com/psl/of150vcy?) 了解如何设置和使用它。 > [!NOTE] -> API 密钥会以加密形式存储在你的本地计算机上。 +> API 密钥会以加密形式存储在你的本机上。 -## 支持的提供程序 +## 支持的提供商 -在 **工具 > 偏好 > AI 助手 > AI 提供程序** 下配置 AI 提供程序。 从下拉列表中选择一个提供商——在你完成配置之前，默认是 **无（AI 已禁用）**——输入你的 API 密钥，并可按需替换默认模型。 对于 OpenAI 和 Anthropic，**模型名称** 字段是一个预先填入已知模型的组合框；你也可以输入自定义模型名称。 +在 **工具 > 偏好 > AI 助手 > AI 提供商** 中配置你的 AI 提供商。 从下拉列表中选择一个提供商——在你完成配置之前，默认值为 **无（AI 已禁用）**——输入你的 API 密钥，并可按需覆盖默认模型。 对于 OpenAI 和 Anthropic，**模型名称** 字段是一个预先填充常见模型的可输入下拉框；你也可以手动输入自定义模型名称。 -| 提供程序 | 默认模型 | 需要配置 | +| 提供商 | 默认模型 | 所需配置项 | | -------------- | ----------------- | ------------------------------ | | OpenAI | gpt-4o | API 密钥。 可选：基础 URL、组织 ID 和项目 ID | -| Anthropic | claude-sonnet-4-6 | API 密钥。 可选：基础 URL | -| Azure OpenAI | 视部署而定 | API 密钥、端点 URL 和部署名称 | -| 自定义（兼容 OpenAI） | 由用户指定 | API 密钥和自定义端点 URL | +| Anthropic | claude-sonnet-4-6 | API 密钥。 可选的基础 URL | +| Azure OpenAI | 因部署而异 | API 密钥、端点 URL 和部署名称 | +| 自定义（兼容 OpenAI） | 用户指定 | API 密钥和自定义端点 URL | -![AI 助手提供程序偏好设置选择](~/content/assets/images/ai-assistant/ai-assistant-provider-preferences.png) +![AI 助手提供商偏好设置](~/content/assets/images/ai-assistant/ai-assistant-provider-preferences.png) ### OpenAI -将提供程序选择为 **OpenAI**，然后输入你的 API 密钥。 如果你的 OpenAI 账户使用组织 ID 和项目 ID，也可以选择填写这些信息。 默认模型是 **gpt-4o**，但你可以将其更改为你账户中可用的任意模型。 +选择 **OpenAI** 作为提供商，然后输入你的 API 密钥。 如果你的 OpenAI 账户使用这些 ID，你也可以选择填写 Organization ID 和 Project ID。 默认模型是 **gpt-4o**，但你可以将其更改为你的账户中可用的任何模型。 ![AI 助手 OpenAI 配置](~/content/assets/images/ai-assistant/ai-assistant-openai-config.png) ### Anthropic -选择 **Anthropic** 作为提供商，然后输入你的 API 密钥。 默认模型是 **claude-sonnet-4-6**。 你可以将模型名称更改为你账号下可用的任意 Anthropic 模型。 +选择 **Anthropic** 作为提供方，然后输入你的 API 密钥。 默认模型是 **claude-sonnet-4-6**。 你可以将模型名称更改为你账户中可用的任意 Anthropic 模型。 ![AI 助手 Anthropic 配置](~/content/assets/images/ai-assistant/ai-assistant-anthropic-config.png) > [!IMPORTANT] -> Anthropic 会根据你的账户等级，强制执行每分钟输入 token（ITPM）的速率限制。 新创建的 API 密钥起始为 Tier 1，Claude Sonnet 4.x 的 ITPM 上限为 30,000。 对大型模型发起的一次请求就可能超过此限制。 购买 $40 或以上的 API 额度即可升至第 2 档（450,000 ITPM）。 有关各档位的完整详情，请参阅 [Anthropic 速率限制文档](https://docs.anthropic.com/en/api/rate-limits)。 +> Anthropic 会根据你的账户等级，强制执行每分钟输入 token（ITPM）的速率限制。 新创建的 API 密钥从 Tier 1 起步，Claude Sonnet 4.x 的速率上限为 30,000 ITPM。 对大型模型发起的单次请求就可能超过这个限制。 购买 40 美元及以上的 API 额度，即可达到 Tier 2（450,000 ITPM）。 完整的层级信息请参阅 [Anthropic 速率限制文档](https://docs.anthropic.com/en/api/rate-limits)。 ### Azure OpenAI -选择 **Azure OpenAI** 作为提供商，并配置以下三个字段： +选择 **Azure OpenAI** 作为提供方，并配置以下三个字段： -- **API 密钥** — 用于访问你的 Azure OpenAI 资源的密钥 -- **服务终结点** — 你的资源的终结点 URL，例如 `https://your-resource.openai.azure.com`。 使用资源 URL，而不要使用 `privatelink` 别名；SSL 证书是为 `*.openai.azure.com` 签发的，直接连接到 `*.privatelink.openai.azure.com` 会导致证书验证失败 -- **模型名称** — 填写的是 **部署名称**，不是底层模型名称，也不是资源名称 +- **API 密钥** — 你的 Azure OpenAI 资源的访问密钥 +- **服务端点** — 你的资源的端点 URL，例如 `https://your-resource.openai.azure.com`。 使用资源 URL，而不要使用 `privatelink` 别名；SSL 证书是为 `*.openai.azure.com` 签发的，直接连接到 `*.privatelink.openai.azure.com` 会导致证书验证失败 +- **模型名称** — 指 **部署名称**，不是底层模型名称，也不是资源名称 -Azure OpenAI 要求在每次 API 调用中都提供部署名称。 部署名称是在创建部署时指定的，因此它可以是任意字符串。 部署通常会以其所服务的模型命名（例如 `gpt-4o`），但这只是约定，并非强制要求。 如果你输入的是资源名称，或者一个并未作为部署存在的底层模型名称，请求就会失败。 +Azure OpenAI 要求在每次 API 调用中都提供部署名称。 部署名称是在创建部署时选定的，因此可以是任意字符串。 部署通常会以其提供的模型命名（例如 `gpt-4o`），但这只是约定，不是要求。 如果你输入资源名称，或输入未作为部署存在的原始模型名称，请求将会失败。 #### 查找部署名称 在 [Azure AI Foundry 门户](https://ai.azure.com) 中： 1. 登录并选择你的 Azure OpenAI 资源 -2. 打开 **部署**（如果资源已升级到 Foundry，则为 **模型 + 终结点**） -3. 复制 **名称** 列中的值 +2. 打开 **Deployments**（如果资源已升级到 Foundry，则为 **Models + endpoints**） +3. 复制 **Name** 列中的值 -在你的组织采用 Azure AI Foundry 之前创建的部署，可能不会在门户中显示。 可通过 Azure CLI 列出它们： +在你的组织采用 Azure AI Foundry 之前创建的部署，可能不会在门户中显示。 也可以通过 Azure CLI 列出部署： ```bash az cognitiveservices account deployment list --name "" --resource-group "" --output table ``` -更多详情见 [创建并部署 Azure OpenAI 资源](https://learn.microsoft.com/azure/ai-foundry/openai/how-to/create-resource#deploy-a-model)。 +有关更多详细信息，请参阅 [创建并部署 Azure OpenAI 资源](https://learn.microsoft.com/azure/ai-foundry/openai/how-to/create-resource#deploy-a-model)。 -有关 403 错误、SSL 失败或 "DeploymentNotFound" 响应，请参阅 @azure-openai-connection-errors。 +如果遇到 403 错误、SSL 失败或 "DeploymentNotFound" 响应，请参阅 @azure-openai-connection-errors。 > [!NOTE] -> **Azure OpenAI** 提供程序适用于使用 `api-version` 查询参数的经典 Azure OpenAI 资源。 如果你使用的是新的 **Microsoft Foundry**，请参阅下文的[使用 Microsoft Foundry](#using-microsoft-foundry)。 +> **Azure OpenAI** 提供程序适用于使用 `api-version` 查询参数的经典 Azure OpenAI 资源。 如果你使用的是新的 **Microsoft Foundry**，请参阅下方的 [使用 Microsoft Foundry](#using-microsoft-foundry)。 -### 自定义（OpenAI 兼容） +### 自定义（兼容 OpenAI） -“自定义”提供商选项支持本地或组织内部的 LLM，只要它们提供 OpenAI 兼容的 API 端点即可。 输入你的 API 密钥和自定义端点 URL。 这样你就可以将所有数据保留在自己的基础设施内，以满足数据隐私或合规要求。 +“自定义”提供程序选项支持本地或组织内部的 LLM，只要它们提供与 OpenAI 兼容的 API 端点。 输入你的 API 密钥和自定义端点 URL。 这样一来，出于数据隐私或合规要求，你可以将所有数据保留在自己的基础设施内。 ### 使用本地或组织内部的 LLM -你可以通过“自定义”提供商让 AI 助手对接自托管的 LLM。 这会将所有数据保留在你自己的基础设施内——无论是运行在本机上的模型，还是在组织网络中集中托管的 LLM。 无论哪种方式，都不会将数据发送到第三方云提供商。 +你可以通过“自定义”提供程序，让 AI 助手对接自托管 LLM。 这样可以将所有数据保留在你自己的基础设施内——无论是运行在本地计算机上的模型，还是在你所在组织网络中集中托管的 LLM。 无论采用哪种方式，都不会将数据发送到第三方云提供商。 -以下工具可托管模型并提供 OpenAI 兼容的 API： +有多种工具可以托管模型，并提供与 OpenAI 兼容的 API： -- [Ollama](https://ollama.com) — 轻量级 CLI，用于在本地下载并运行模型 -- [LM Studio](https://lmstudio.ai) — 带图形界面的桌面应用，用于管理并运行本地模型 -- [LocalAI](https://localai.io) — 自托管、社区驱动的替代方案，支持多种模型 +- [Ollama](https://ollama.com) —— 轻量级 CLI，用于在本地下载和运行模型 +- [LM Studio](https://lmstudio.ai) —— 带图形界面的桌面应用，用于管理和运行本地模型 +- [LocalAI](https://localai.io) —— 自托管、社区驱动的替代方案，支持广泛的模型 -这些工具既可以在开发者的工作站上运行供个人使用，也可以部署在组织内的共享服务器上，为你的团队提供集中管理的 LLM 端点。 +这些工具既可以运行在开发人员的工作站上供个人使用，也可以部署在组织内部的共享服务器上，为团队提供集中管理的 LLM 端点。 #### 示例：Ollama 1. [下载并安装 Ollama](https://ollama.com/download) -2. 拉取一个模型（下载），例如：`ollama pull llama3.1` +2. 拉取一个模型，例如：`ollama pull llama3.1` 3. 启动 Ollama 服务器（安装后会自动运行，默认使用端口 11434） -4. 在 Tabular Editor 中，依次点击 **Tools > 偏好 > AI Assistant > AI Provider** -5. 将 **Choose provider** 设置为 **Custom (OpenAI-compatible)** -6. 将 **Service Endpoint** 设置为 `http://localhost:11434/v1` -7. 将 **Model name** 设置为你拉取的模型（例如 `llama3.1`） -8. **API Key** 字段可以设置为任意非空值（例如 `ollama`）——Ollama 不需要身份验证，但该字段不能为空 +4. 在 Tabular Editor 中，依次选择 **工具 > 偏好 > AI 助手 > AI 提供程序** +5. 将 **选择提供程序** 设置为 **自定义（兼容 OpenAI）** +6. 将 **服务端点** 设置为 `http://localhost:11434/v1` +7. 将 **模型名称** 设置为你拉取的模型（例如 `llama3.1`） +8. **API 密钥** 字段可以设置为任何非空值（例如 `ollama`）——Ollama 不要求身份验证，但该字段不能为空 #### 示例：LM Studio 1. [下载并安装 LM Studio](https://lmstudio.ai/download) -2. 拉取一个模型。 可以通过左侧面板的模型搜索页面或 CLI 来完成。 例如：`lms get lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF` -3. 启动 LM Studio 服务器。 可以通过左侧面板的开发者页面或 CLI 来完成。 例如：`lms server start` - 注意：你需要将其配置为 OpenAI 兼容模式。 另外，你可能需要将默认上下文大小调整为 100,000 tokens 以上。 -4. 在 Tabular Editor 中，依次点击 **Tools > 偏好 > AI Assistant > AI Provider** +2. 拉取一个模型。 可通过左侧面板的模型搜索页面或通过 CLI 完成。 例如：`lms get lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF` +3. 启动 LM Studio 服务器。 可通过左侧面板的开发者页面或通过 CLI 完成。 例如：`lms server start` + 注意：你需要将其配置为 OpenAI 兼容模式。 此外，你可能还需要将默认上下文大小调整到 100,000 token 以上。 +4. 在 Tabular Editor 中，转到 **Tools > 偏好 > AI Assistant > AI Provider** 5. 将 **Choose provider** 设置为 **Custom (OpenAI-compatible)** 6. 将 **Service Endpoint** 设置为 `http://localhost:1234/v1` 7. 将 **Model name** 设置为你拉取的模型（例如 `lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF`） -8. **API Key** 字段可以设置为任意非空值（例如 `lms`）——LM Studio 不需要身份验证，但该字段不能为空 +8. **API Key** 字段可设置为任意非空值（例如 `lms`）——LM Studio 不需要身份验证，但该字段不能为空 > [!NOTE] -> 本地模型的响应质量取决于模型规模以及你的硬件配置。 更大的模型通常能产生更好的结果，但需要更多 RAM 和性能更强的 GPU。 AI Assistant 的工具调用能力需要使用支持 OpenAI 兼容格式函数调用的模型。 +> 本地模型的响应质量取决于模型大小和你的硬件。 更大的模型通常能产生更好的结果，但需要更多 RAM 和性能足够的 GPU。 AI 助手的工具调用功能需要模型支持 OpenAI 兼容格式的函数调用。 > [!TIP] -> 我们建议选择参数量_至少_为 30 十亿、理想情况下至少为 100 十亿的模型。 例如，Qwen3.5-122B-A10B 模型在我们的内部测试中表现良好。 +> 我们建议使用参数量 _至少_ 为 30 billion 的模型，理想情况下至少为 100 billion。 例如，Qwen3.5-122B-A10B 模型在我们的内部测试中表现良好。 ### 使用 Microsoft Foundry -[Microsoft Foundry](https://ai.azure.com)（前身为 Azure AI Foundry）可让你在 Azure 环境中部署 OpenAI 和 Anthropic 模型。 在 Tabular Editor 中，这些模型需要通过 **OpenAI** 或 **Anthropic** 提供程序访问——而不是 **Azure OpenAI** 提供程序；后者适用于经典 Azure OpenAI 资源。 +[Microsoft Foundry](https://ai.azure.com)（前身为 Azure AI Foundry）可让你在 Azure 环境中部署 OpenAI 和 Anthropic 模型。 这些模型应通过 Tabular Editor 中的 **OpenAI** 或 **Anthropic** 提供程序访问，而不是 **Azure OpenAI** 提供程序；后者用于经典 Azure OpenAI 资源。 > [!IMPORTANT] > 不要将 **Azure OpenAI** 提供程序用于 Microsoft Foundry 模型。 **Azure OpenAI** 提供程序仅兼容经典 Azure OpenAI 资源。 @@ -157,97 +157,97 @@ az cognitiveservices account deployment list --name "" --resource 要使用部署在 Microsoft Foundry 中的 OpenAI 模型（如 GPT-4o 或 GPT-5.4-mini）： -1. 在 Tabular Editor 中，依次点击 **Tools > 偏好 > AI Assistant > AI Provider** -2. 将 **选择提供程序** 设置为 **OpenAI** -3. 将 **Base URL** 设置为你的 Foundry 资源端点，并在末尾加上 `/openai/v1`。 URL 采用以下任一格式： +1. 在 Tabular Editor 中，转到 **Tools > 偏好 > AI Assistant > AI Provider** +2. 将 **Choose provider** 设置为 **OpenAI** +3. 将 **Base URL** 设置为你的 Foundry 资源端点，并在末尾加上 `/openai/v1`。 URL 采用以下格式之一： - `https://your-resource.services.ai.azure.com/openai/v1` - `https://your-resource.openai.azure.com/openai/v1` 4. 输入 Foundry **API 密钥** -5. 将 **模型名称** 设置为你的部署名称（例如 `gpt-5.4-mini`） +5. 将 **模型名称** 设置为部署名称（例如 `gpt-5.4-mini`） > [!NOTE] -> Microsoft Foundry 门户不会直接显示基础 URL。 门户会显示一个包含完整 API 路径的 **目标 URI**（例如 `https://your-resource.services.ai.azure.com/api/projects/YourProject/openai/v1/responses`）。 基础 URL 只需使用 `https://your-resource.services.ai.azure.com/openai/v1`。 +> 在 Microsoft Foundry 门户中不会直接显示基础 URL。 门户会显示一个包含完整 API 路径的 **目标 URI**（例如 `https://your-resource.services.ai.azure.com/api/projects/YourProject/openai/v1/responses`）。 基础 URL 请仅使用 `https://your-resource.services.ai.azure.com/openai/v1`。 -#### Microsoft Foundry 中的 Anthropic 模型 +#### Microsoft Foundry 上的 Anthropic 模型 -要使用部署在 Microsoft Foundry 中的 Anthropic 模型（例如 Claude Sonnet 4.6）： +若要使用在 Microsoft Foundry 中部署的 Anthropic 模型（例如 Claude Sonnet 4.6）： -1. 在 Tabular Editor 中，依次点击 **Tools > 偏好 > AI Assistant > AI Provider** +1. 在 Tabular Editor 中，依次转到 **工具 > 偏好 > AI 助手 > AI 提供程序** 2. 将 **选择提供程序** 设置为 **Anthropic** -3. 将 **基础 URL** 设置为你的 Foundry 资源端点，并在末尾追加 `/anthropic`，例如 `https://your-resource.services.ai.azure.com/anthropic` -4. 输入你的 Foundry **API 密钥** +3. 将 **基础 URL** 设置为你的 Foundry 资源端点，并在末尾加上 `/anthropic`，例如 `https://your-resource.services.ai.azure.com/anthropic` +4. 输入 Foundry **API 密钥** 5. 将 **模型名称** 设置为模型标识符（例如 `claude-sonnet-4-6`） > [!NOTE] -> 门户会显示一个 **目标 URI**，例如 `https://your-resource.services.ai.azure.com/anthropic/v1/messages`。 基础 URL 只需填写到并包含 `/anthropic` 为止。 +> 门户会显示一个 **目标 URI**，例如 `https://your-resource.services.ai.azure.com/anthropic/v1/messages`。 对于基础 URL，只使用到并包括 `/anthropic` 的部分。 ## 功能 -AI 助手可以访问你的模型上下文，并能执行以下操作： +AI 助手可以访问你的模型上下文，并执行以下操作： - **模型探索**：查询模型元数据，包括表、列、度量值、关系及其属性 -- **DAX 查询编写**：生成 DAX 查询并对你在连接模式下连接的模型执行，结果集会直接在聊天中返回 -- **C# 脚本生成**：生成用于修改模型的 C# Script，并在新的编辑器窗口中打开。 当你在聊天中点击 **Execute** 时，默认会显示 [预览更改](xref:csharp-scripts#running-scripts-with-preview) 对话框，让你在接受前先审阅所有模型元数据更改。 你也可以在编辑器中打开脚本，并从脚本工具栏运行它，可选择是否启用预览。 模型元数据更改可通过 **Ctrl+Z** 撤销 -- **Best Practice Analyzer**：运行 BPA 分析，查看规则违规情况，并创建或修改 BPA 规则 -- **VertiPaq分析器**：查询内存使用统计信息和列的基数 -- **文档访问**：读取并修改已打开的文档，例如 DAX 脚本和 DAX 查询 -- **知识库搜索**：搜索内置的 Tabular Editor 文档以获取答案 -- **UI 导航**：生成 `te3://` 操作链接，用于打开特定的 Tabular Editor 对话框和功能 +- **DAX 查询编写**：生成 DAX 查询，并在连接模式下针对你已连接的模型执行这些查询，结果集会直接返回到聊天中 +- **C# Script 生成**：创建用于修改模型的 C# Script，并在新的编辑器窗口中打开。 当你在聊天中单击 **执行** 时，默认会显示 [预览更改](xref:csharp-scripts#run-c-scripts-with-preview) 对话框，让你在接受更改前查看所有对模型元数据的更改。 你也可以在编辑器中打开该脚本，并通过脚本工具栏运行它，可选择使用或不使用预览。 模型元数据更改可使用 **Ctrl+Z** 撤销 +- **Best Practice Analyzer**：运行 BPA 分析、查看规则违规项，并创建或修改 BPA 规则 +- **VertiPaq分析器**：查询内存使用统计信息和列基数 +- **文档访问**：读取并修改打开的文档，例如 DAX 脚本和 DAX 查询 +- **知识库搜索**：搜索内置的 Tabular Editor 文档以查找答案 +- **UI 导航**：生成 `te3://` 操作链接，用于打开 Tabular Editor 中特定的对话框和功能 > [!NOTE] -> 在处理未连接到 Analysis Services 或 Power BI 的模型文件(例如 `.bim` 文件或 `.tmdl` 文件夹)时，所有需要活动数据库连接的工具——包括 DAX 查询执行和 VertiPaq分析器统计信息——都会自动隐藏。 助手仍会为你编写 DAX 查询，但在建立连接之前，DAX 查询项上的 **执行** 按钮会被禁用。 如果之前已从 `.vpax` 文件加载过，VertiPaq分析器统计信息仍然可用。 +> 在处理未连接到 Analysis Services 或 Power BI 的模型文件(例如 `.bim` 文件或 `.tmdl` 文件夹)时，所有需要活动数据库连接的工具——包括 DAX 查询执行和 VertiPaq分析器统计信息——都会自动隐藏。 AI 助手仍会为你编写 DAX 查询，但在建立连接之前，DAX 查询工件上的 **执行** 按钮将保持禁用状态。 如果之前已从 `.vpax` 文件加载，VertiPaq分析器统计信息仍然可用。 ## 对话 -AI 助手支持多个并行对话。 每个对话都会维护各自的信息历史记录和上下文。 +AI 助手支持同时进行多个对话。 每个对话都维护各自的信息历史记录和上下文。 - 对话会跨会话保留，并存储在本地的 `%LocalAppData%\TabularEditor3\AI\Conversations\` 中 -- 标题会在首次交流后自动生成。 你可以手动重命名对话 -- **自动压缩**：当对话接近上下文窗口限制（约 80%）时，较早的信息会自动总结，以腾出空间。 压缩前会先归档完整对话的快照 +- 首次交互后会自动生成标题。 你可以手动重命名对话 +- **自动压缩**：当对话接近上下文窗口限制（约 80%）时，会自动汇总较早的信息以释放空间。 在压缩前，会先归档完整对话的快照 ## 工件 -当 AI 助手生成代码时，会生成可直接在编辑器窗口中打开的 **工件**： +当 AI 助手生成代码时，会创建可直接在编辑器窗口中打开的 **工件**： -- **C# Script**：在新的 C# Script 编辑器中打开，支持语法高亮、编译和执行 -- **DAX 查询**：在新的 DAX 查询编辑器中打开，支持语法高亮和执行 +- **C# Script**：在新的 C# 脚本编辑器中打开，提供语法高亮、编译和执行支持 +- **DAX 查询**：在新的 DAX 查询编辑器中打开，提供语法高亮和执行支持 -生成物会在 AI 生成过程中实时流式输出。 C# Script 生成物包含安全分析，可标记潜在不安全的代码（例如文件系统访问或网络操作）。 +这些工件会在 AI 生成过程中实时流式呈现。 C# Script 工件包含安全分析，可标记可能不安全的代码（例如文件系统访问或网络操作）。 -![AI Assistant Generate C# Script](~/content/assets/images/ai-assistant/ai-assistant-generate-c-sharp-script.png) +![AI 助手生成 C# Script](~/content/assets/images/ai-assistant/ai-assistant-generate-c-sharp-script.png) -当你在聊天中执行 C# Script 时，**脚本预览**对话框会并排显示该脚本对模型元数据所做的所有更改的差异对比。 你可以接受这些更改，或将其撤销。 详见[使用预览运行脚本](xref:csharp-scripts#run-c-scripts-with-preview)。 +当你从聊天中执行 C# Script 时，**脚本预览**对话框会并排显示该脚本对模型元数据所做全部更改的差异对比。 你可以接受这些更改，也可以将其还原。 详见 [使用预览运行脚本](xref:csharp-scripts#run-c-scripts-with-preview)。 ![脚本预览 - 模型更改](~/content/assets/images/preview-script-changes.png) ## 自定义指令 -自定义指令是一组指令，用于引导 AI 助手在特定任务中的行为。 它们会根据意图识别自动启用，也可以手动调用。 +自定义指令是一组指令，用于在特定任务中引导 AI 助手的行为。 它们会根据意图检测自动激活，也可以手动调用。 ### 内置自定义指令 -AI 助手包含以下内置自定义指令： +AI 助手内置以下自定义指令： -| 自定义指令 | 触发词 | +| 自定义指令 | 触发关键词 | | ------ | ------------------- | | DAX 查询 | DAX、查询、EVALUATE、度量值 | | 模型修改 | 修改、更改、添加、更新、创建 | -| 模型设计 | 设计、架构、模式、最佳实践 | +| 模型设计 | 设计、架构、模式、最佳做法 | | 整理模型 | 整理、清理、文件夹、重命名 | | 优化模型 | 优化、性能、慢、速度 | | 宏 | 宏、自动化、录制 | -| UDF | UDF、函数、用户自定义函数 | -| BPA | BPA、最佳实践、规则、违规 | +| UDFs | UDF、函数、用户定义 | +| BPA | BPA、最佳做法、规则、违规 | -自定义指令会在助手回复上方以指示器形式显示，用于说明哪些指令影响了本次回复。 你可以在 **偏好 > AI Assistant > 偏好 > 显示自定义指令指示器** 中切换该指示器的显示。 +自定义指令会以指示器的形式显示在助手回复上方，用于表明哪些指令对该回复产生了影响。 你可以在 **偏好 > AI 助手 > 偏好 > 显示自定义指令指示器** 中切换是否显示该指示器。 ### 调用自定义指令 -输入 `/` 浏览可用的自定义指令；或在信息开头输入完整的 `/instruction-id`，以明确调用某条特定指令。 例如，`/dax-querying` 会强制使用 DAX 查询指令，无论信息内容如何。 +输入 `/` 以浏览可用的自定义指令，或者在信息开头输入完整的 `/instruction-id`，以显式调用特定指令。 例如，`/dax-querying` 会强制使用 DAX 查询指令，无论信息内容如何。 -### 添加自己的自定义指令 +### 添加自定义指令 -你可以通过将 `.md` 文件放到 `%LocalAppData%\TabularEditor3\AI\CustomInstructions\` 来创建自定义指令。 每个文件都需要包含 YAML front matter，用于定义指令的元数据： +将 `.md` 文件放入 `%LocalAppData%\TabularEditor3\AI\CustomInstructions\` 即可创建自定义指令。 每个文件都需要包含 YAML frontmatter，用于定义指令元数据： ```yaml --- @@ -267,128 +267,128 @@ triggers: - model_loaded --- -你的指令内容写在这里。当该指令被激活时，这段文本会 -注入到 AI 的 system prompt 中。 +Your instruction content goes here. This is the text that will be +injected into the AI's system prompt when the instruction is activated. ``` -| 字段 | 必需 | 默认值 | 说明 | -| --------------------------- | -- | ------------------------------------------------------ | --------------------------------- | -| `id` | 否 | 不含 `.md` 的文件名 | 唯一标识符，也会作为 `/id` 用于显式调用 | -| `name` | 否 | `id` 使用标题式大小写 | 自动完成中的显示名称 | -| `description` | 否 | - | 显示在名称下方的简短说明 | -| `priority` | 否 | 100 | 当匹配到多个自定义指令时，数值越高越优先注入 | -| `always_inject` | 否 | false | 如果为 true，则始终包含在系统提示词中 | -| `hidden` | 否 | false | 如果为 true，则不会在 `/command` 的自动补全中显示 | -| `triggers.keywords` | 否 | [] | 触发该指令的词（不区分大小写） | -| `triggers.patterns` | 否 | [] | 用于复杂匹配的正则表达式 | -| `triggers.context_required` | 否 | [] | 必须满足的条件（例如 `model_loaded`） | +| 字段 | 必填 | 默认值 | 说明 | +| --------------------------- | -- | ------------------------------------------------------ | -------------------------------- | +| `id` | 否 | 不含 `.md` 的文件名 | 唯一标识符，也用作显式调用时的 `/id` | +| `name` | 否 | 标题式大小写的 `id` | 自动补全中显示的名称 | +| `description` | 否 | - | 显示在名称下方的简短说明 | +| `priority` | 否 | 100 | 当多个自定义指令匹配时，数值越高越会先被注入 | +| `always_inject` | 否 | false | 如果为 true，则始终包含在系统提示中 | +| `hidden` | 否 | false | 若为 true，则不会在 `/command` 的自动补全中显示 | +| `triggers.keywords` | 否 | [] | 激活该指令的词语（不区分大小写） | +| `triggers.patterns` | 否 | [] | 用于复杂匹配的正则表达式模式 | +| `triggers.context_required` | 否 | [] | 必须满足的条件（例如 `model_loaded`） | -具有与内置指令相同 `id` 的自定义指令会覆盖内置版本。 +其 `id` 与内置指令相同的自定义指令，会覆盖内置版本。 ## 同意 -AI 助手在向 AI 提供商发送数据之前会先征求你的同意。 同意按特定数据类型进行限定： +AI 助手会在把数据发送给 AI 提供方之前先征求你的同意。 同意的范围仅限于特定数据类型： -| 同意类别 | 说明 | +| 同意类别 | 描述 | | --------- | ------------------------------- | | 查询数据 | DAX 查询结果和数据样本 | -| 读取文档 | 读取打开的文档内容，例如 DAX 脚本和 DAX 查询 | -| 修改文档 | 对打开的文档进行更改 | -| 模型元数据 | 表和列架构、度量值定义以及其他模型元数据 | +| 读取文档 | 读取已打开文档中的内容，例如 DAX 脚本和 DAX 查询 | +| 修改文档 | 修改已打开的文档 | +| 模型元数据 | 表和列的架构、度量值定义及其他模型元数据 | | 编辑 BPA 规则 | 创建或修改 Best Practice Analyzer 规则 | | 读取宏 | 读取宏定义 | -当 AI 助手首次需要访问某种数据类型时，将弹出同意对话框。 你可以选择同意的持续时间： +当 AI 助手首次需要访问某种数据类型时，会弹出授权对话框。 你可以选择授权的有效期限： -| 选项 | 范围 | -| ---- | --------------------------------------------------------- | -| 这次 | 仅限单次请求 | -| 本次会话 | 直到重新启动 Tabular Editor | -| 此模型 | 保存在模型的用户选项 (.tmuo) 文件中 | -| 始终 | 全局偏好，将在所有模型和会话间保留 | +| 选项 | 适用范围 | +| ----- | --------------------------------------------------------- | +| 仅本次 | 仅限单次请求 | +| 本次会话 | 直到重新启动 Tabular Editor | +| 针对此模型 | 保存在模型的用户选项 (.tmuo) 文件中 | +| 始终 | 全局偏好，在所有模型和会话中持续生效 | -![AI Assistant Consent Dialog](~/content/assets/images/ai-assistant/ai-assistant-generate-consent-dialog.png) +![AI 助手同意对话框](~/content/assets/images/ai-assistant/ai-assistant-generate-consent-dialog.png) -### 管理同意项 +### 管理同意设置 -你可以在 **Tools > 偏好 > AI Assistant > AI Consents** 中查看并重置你的同意选项。 每个同意类别都会显示其当前状态。 点击 **Reset** 可撤销处于“Always allowed”状态的同意，并将其恢复为“Ask when needed”。 +你可以在 **工具 > 偏好 > AI 助手 > AI 同意设置** 中查看并重置你的同意选择。 每个同意类别都会显示其当前状态。 点击 **重置** 可撤销“始终允许”的同意，并将其恢复为“需要时询问”。 -![AI Assistant Consent Settings](~/content/assets/images/ai-assistant/ai-assistant-consent-reset.png) +![AI 助手同意设置](~/content/assets/images/ai-assistant/ai-assistant-consent-reset.png) -## 偏好设置 +## 偏好 -在 **Tools > 偏好设置 > AI Assistant > 偏好设置** 中配置 AI Assistant 的显示和行为选项。 +在 **工具 > 偏好 > AI 助手 > 偏好** 中配置 AI 助手的显示和行为选项。 ### 聊天显示 -| 偏好 | 默认值 | 说明 | -| ---------- | ---- | ---------------- | -| 显示选择上下文指示器 | true | 在聊天中显示当前选定的模型对象 | -| 显示自定义指令指示器 | true | 在助手回复上方显示自定义指令标识 | -| 显示知识库搜索指示器 | true | 搜索知识库时显示进度 | +| 偏好 | 默认 | 说明 | +| ---------- | ---- | ------------------- | +| 显示选择上下文指示器 | true | 在聊天中显示当前选中的模型对象 | +| 显示自定义指令指示器 | true | 在助手回复上方显示“自定义指令”指示器 | +| 显示知识库搜索指示器 | true | 搜索知识库时显示进度 | ### 上下文压缩 | 偏好 | 默认值 | 说明 | | -------- | ---- | ------------------ | -| 自动压缩 | true | 接近上下文限制时自动摘要较早的信息 | -| 自动压缩阈值 % | 80 | 令牌使用率达到该百分比时触发自动压缩 | +| 自动压缩 | true | 在接近上下文上限时自动总结较早的信息 | +| 自动压缩阈值 % | 80 | 触发自动压缩的令牌使用百分比 | ### 知识库 -| 偏好 | 默认值 | 说明 | -| ---------- | ---- | --------------------------- | -| 启动时检查知识库更新 | true | Tabular Editor 启动时自动检查知识库更新 | +| 偏好 | 默认值 | 说明 | +| ---------- | ---- | ----------------------------- | +| 启动时检查知识库更新 | true | 在 Tabular Editor 启动时自动检查知识库更新 | ### C# Script -| 偏好 | 默认值 | 说明 | -| ---- | ---- | ------------------------------------- | -| 预览更改 | true | 在聊天中执行 AI 生成的 C# Script 时，显示“预览更改”对话框 | +| 偏好 | 默认值 | 说明 | +| ---- | ---- | ------------------------------------ | +| 预览更改 | true | 执行聊天中 AI 生成的 C# Script 时，显示“预览更改”对话框 | -![AI 助手偏好](~/content/assets/images/ai-assistant/ai-assistant-preferences.png) +![AI 助手偏好设置](~/content/assets/images/ai-assistant/ai-assistant-preferences.png) -## Token 使用量 +## 令牌用量 -每条发给 AI 助手的信息都会消耗输入 token。 单条信息的 token 成本取决于包含了哪些上下文： +发送给 AI 助手的每条信息都会消耗输入令牌。 单条信息的令牌开销取决于包含哪些上下文： -- **系统提示词和自定义说明**：每条信息都会一并发送。 通常为 5,000 到 15,000 个 token，具体取决于启用了哪些自定义说明。 -- **模型元数据**：当助手需要理解你的模型时，会通过工具调用获取元数据。 为了在处理大型模型时不超出提供程序的速率限制，助手会采用渐进式披露的方式——先获取轻量级概览（表和度量值名称、关系），然后按名称、说明或 DAX 表达式搜索相关对象，只有在问题确实需要时，才会深入获取特定表或对象的完整信息。 原本会非常庞大的工具结果会被截断，并附带说明助手如何检索其余数据。 +- **系统提示和自定义指令**：会随每条信息一起发送。 通常为 5,000 到 15,000 个令牌，具体取决于启用了哪些自定义指令。 +- **模型元数据**：当助手需要了解你的模型时，会通过工具调用检索元数据。 为了在处理大型模型时不超出提供商的速率限制，助手会采用渐进式披露的方法——先获取轻量级概览（表和度量值名称、关系），再按名称、说明或 DAX 表达式搜索相关对象，只有在问题确实需要时，才会进一步获取特定表或对象的完整信息。 原本会非常庞大的工具结果会被截断，并附带说明，指导助手如何获取其余数据。 ### 令牌计数器 -聊天输入区域右下角的令牌计数器会显示当前对话的累计令牌用量，其中包括工具往返调用产生的输入。 将鼠标悬停在计数器上可查看明细： +聊天输入区域右下角的令牌计数器会显示当前对话的累计令牌用量，其中包括工具往返调用中的输入。 将鼠标悬停在计数器上可查看明细： -- **输入** — 对话中按全价计费的输入令牌；下面一行会显示其中有多少来自提供程序的提示缓存 -- **缓存写入** — 写入提示缓存的令牌（取决于提供程序） -- **输出** — 模型生成的令牌 -- **上下文压力** — 当前已使用的上下文窗口百分比；也会通过计数器旁边的滑条进行可视化显示 +- **输入** — 对话中按原价计费的输入令牌；下方还会显示其中有多少来自提供商的提示缓存 +- **缓存写入** — 写入提示缓存的令牌（取决于提供商） +- **输出** — 由模型生成的令牌 +- **上下文压力** — 当前上下文窗口的使用比例；也会通过计数器旁边的滑动条直观显示 -### 减少 token 使用量 +### 减少令牌用量 -提问前，先在 **TOM Explorer** 中选择特定对象。 选中对象后，助手会将上下文限定在这些对象上，而不是拉取整个模型的元数据。 这是同时减少 token 使用量和 API 成本的最有效方式。 +提问前，先在 **TOM Explorer** 中选择特定对象。 选择对象后，助手会将上下文范围限定为这些对象，而不是检索整个模型的元数据。 这是同时降低令牌用量和 API 成本的最有效方式。 -其他减少 token 使用量的方法： +减少令牌用量的其他方法： -- 围绕特定的表、度量值或列提出更聚焦的问题，而不是对整个模型提出泛泛的问题。 像 _“为所有度量值设置显示文件夹”_ 这样含糊的提示，会迫使助手检索整个模型的元数据。 像 _“为我选中的度量值设置显示文件夹”_ 这样具体的提示，会将上下文限制在当前选择范围内，并且消耗的 token 少得多 -- 切换话题时开启新对话，避免累积过长的对话历史 -- 进行探索性提问时，使用更小或成本更低的模型 +- 围绕特定的表、度量值或列提问，而不是对整个模型提出宽泛的问题。 像 _"为所有度量值设置显示文件夹"_ 这样含糊的提示，会迫使助手检索整个模型的元数据。 像 _"为我选中的度量值设置显示文件夹"_ 这样具体的提示，会将上下文限制在当前选择范围内，并显著减少令牌用量 +- 切换主题时开始新对话，避免累积过长的对话历史 +- 对于探索性问题，使用更小或成本更低的模型 ## 局限性 -- 需要你自行提供 API 密钥。 不包含内置 API 密钥 -- AI 的响应取决于所选模型及提供商的能力 -- 最大上下文窗口为 200,000 个 token -- AI 助手不能替代你对 DAX 和语义模型设计基础的理解 -- 响应质量会因提供商和模型选择而异 -- AI 助手无法连接到外部文件或服务，也无法搜索网页 -- AI 助手无法添加或充当 MCP 服务器 -- AI 助手无法在聊天中切换到其他模型。 使用 Tabular Editor 的用户界面更改模型连接 +- 需要用户提供 API 密钥。 不包含内置 API 密钥 +- AI 响应取决于所选模型和提供商的能力 +- 最大上下文窗口为 200,000 个令牌 +- AI 助手不能替代对 DAX 和语义模型设计基础的掌握 +- 响应质量会因提供商和所选模型而异 +- AI 助手无法连接外部文件或服务，也无法搜索互联网 +- AI 助手无法添加 MCP 服务器，也无法充当 MCP 服务器 +- AI 助手无法在聊天中连接到其他模型。 使用 Tabular Editor 的用户界面来更改模型连接 - AI 助手无法管理偏好 ## 禁用 AI 助手 -AI 助手是一个可选组件。 该功能目前处于公开预览阶段，安装时默认不会包含，但用户可以选择安装。 你可以再次运行 Tabular Editor 3 安装程序，修改现有的 Tabular Editor 3 安装，以包含或排除 AI 助手组件。 如果你使用的是 Tabular Editor 3 便携版，可以从安装目录中删除名为 `TabularEditor3.AI.dll` 的文件来移除 AI 助手组件。 +AI 助手是一个可选组件。 在该功能处于公开预览阶段期间，安装时默认不包含该组件，但用户可以选择将其包含在内。 重新运行 Tabular Editor 3 安装程序即可修改现有 Tabular Editor 3 安装，以选择包含或排除 AI 助手组件。 如果使用的是 Tabular Editor 3 的便携版本，可以通过从安装目录中删除名为 `TabularEditor3.AI.dll` 的文件来移除 AI 助手组件。 > [!NOTE] -> 无论是否安装 AI 助手组件，系统管理员都可以通过指定 [`DisableAi` 策略](xref:policies) 来禁用 Tabular Editor 3 中的所有 AI 功能。 +> 无论是否安装了 AI 助手组件，系统管理员都可以通过指定 [`DisableAi` 策略](xref:policies) 来禁用 Tabular Editor 3 中的所有 AI 功能。 diff --git a/localizedContent/zh/content/features/code-actions.md b/localizedContent/zh/content/features/code-actions.md index fc9cb88aa..4b7e6b1f7 100644 --- a/localizedContent/zh/content/features/code-actions.md +++ b/localizedContent/zh/content/features/code-actions.md @@ -22,7 +22,7 @@ applies_to: Tabular Editor 3.18.0 引入了一项名为 **代码操作** 的新功能。 该功能默认启用，但你可以在 **工具 > 偏好** 对话框中，依次进入 **文本编辑器 > DAX编辑器 > 代码操作** 将其禁用。 -代码操作是一项提升效率的功能，会在不打扰你的情况下，为你提供改进 DAX 代码的建议。 你只需单击一次即可应用这些建议。 代码操作还让你能轻松执行常见的代码重构操作。 +代码操作是一项提升效率的功能，会以低干扰的方式提供改进 DAX 代码的建议。 你只需单击一次即可应用这些建议。 代码操作还让你能轻松执行常见的代码重构操作。 代码操作分为三个不同的类别： @@ -35,14 +35,14 @@ Tabular Editor 3.18.0 引入了一项名为 **代码操作** 的新功能。 该 - 在可能的情况下简化复杂表达式 - 删除冗余或不必要的代码 - 应用一致的格式和命名规范 -3. **重写**：这些是用于重构 DAX 代码的建议。 它们不一定是改进，但在进行较大规模的代码重构时通常很有用。 示例包括： +3. **重写**：这类建议用于重构你的 DAX 代码。 它们不一定是改进，但在进行较大规模的代码重构时通常很有用。 示例包括： - 将 DAX “语法糖”改写为更冗长但更明确的代码 - 重命名某个变量或扩展列的所有出现位置 - 格式化代码 ## 如何使用代码操作 -新增了 **显示代码操作** 命令及其对应的工具栏/菜单按钮，默认键盘快捷键为 `Ctrl+.`。 这个命令会显示当前光标位置可用的代码操作： +新增了命令 **显示代码操作** 及其对应的工具栏/菜单按钮，默认快捷键为 `Ctrl+.`。 这个命令会显示当前光标位置可用的代码操作： ![代码操作调用菜单](~/content/assets/images/features/code-action-invoke-menu.png) @@ -50,7 +50,7 @@ Tabular Editor 3.18.0 引入了一项名为 **代码操作** 的新功能。 该 ![代码操作重构子菜单](~/content/assets/images/features/code-action-refactor-submenu.png) -最后，当光标位于包含可用操作的代码分段上时，编辑器左侧边距会显示灯泡或螺丝刀图标。 点击该图标也会打开代码操作菜单： +最后，当光标位于有适用操作的代码分段上时，编辑器左侧边距会显示灯泡或螺丝刀图标。 点击该图标也会打开代码操作菜单： ![代码操作边距](~/content/assets/images/features/code-action-margin.png) @@ -60,15 +60,15 @@ Tabular Editor 3.18.0 引入了一项名为 **代码操作** 的新功能。 该 ## 代码操作指示器 -在代码编辑器中，**改进** 和 **可读性** 代码操作也会以视觉标识显示。 这样你就能快速判断代码中哪些部分可以改进，或提升可读性。 +在代码编辑器中，**改进** 和 **可读性** 代码操作也会以视觉标识显示。 这让你可以快速判断代码中哪些部分还能改进，或变得更易读。 -- **改进** 会以橙色圆点显示在代码分段前几个字符的下方（除非该代码分段已显示橙色警告波浪线）。 当光标移到该代码分段上时，左侧边距会显示一个 _灯泡_ 图标。 -- **可读性** 操作会以蓝绿色圆点显示在代码分段前几个字符的下方。 当光标移到该代码分段上时，左侧边距会显示一个 _螺丝刀_ 图标。 +- **改进**会在代码分段开头的前几个字符下方以橙色圆点标示（除非该代码分段已显示橙色警告波浪线）。 当光标移到该代码分段上时，左侧边距会显示一个 _灯泡_ 图标。 +- **可读性**操作会在代码分段前几个字符下方显示蓝绿色圆点。 当光标移到该代码分段上时，左侧边距会显示一个 _螺丝刀_ 图标。 - **重写**本身不会在代码中显示任何视觉标记；但当光标放在包含可用重写的代码分段上时，左侧边距会出现 _螺丝刀_ 图标。 ## 应用到所有出现处 -某些代码操作可应用于当前 DAX 表达式、DAX 脚本或 DAX 查询中的所有出现位置，而不仅仅是光标下的代码分段。 在这种情况下，该代码操作会显示在“代码操作”菜单中，并在操作描述后追加 " (All occurrences)"。 点击该操作后，将把更改应用于文档中的所有出现处。 +某些代码操作可以应用于当前 DAX 表达式、DAX 脚本或 DAX 查询中的所有出现位置，而不只是光标所在的代码分段。 在这种情况下，该代码操作会显示在“代码操作”菜单中，并在操作描述后追加 " (All occurrences)"。 点击该操作后，将把更改应用于文档中的所有出现处。 例如，在下方截图中，**为变量添加“_”前缀**这个操作可以应用到文档中的所有出现位置（即所有变量），而不只是光标所在的 `totalSales` 变量： @@ -84,45 +84,45 @@ Tabular Editor 3.18.0 引入了一项名为 **代码操作** 的新功能。 该 以下代码操作会在适用代码的前两个字符下方显示橙色圆点；当光标位于该代码分段上时，左侧边距还会出现灯泡图标： -| ID | 名称 | 描述 | -| ----- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| DI001 | [删除未使用的变量](xref:DI001) | 应删除未在任何地方被引用的变量。 示例：
`VAR a = 1 VAR b = 2 RETURN a` -> `VAR a = 1 RETURN a` | -| DI002 | [删除所有未使用的变量](xref:DI002) | 应删除 VAR 变量块中在 `RETURN` 部分未被使用的变量（无论直接使用还是通过其他变量间接使用）。 示例：
`VAR a = 1 VAR b = a RETURN 123` -> `123` | -| DI003 | [移除表名](xref:DI003) | 度量值引用中不应包含表名，因为引用度量值时表名是多余的。 此外，这样做也能让度量值引用与列引用更容易区分。 示例：
`Sales[Total Sales]` -> `[Total Sales]` | -| DI004 | [添加表名](xref:DI004) | 列引用应包含表名，以避免歧义，并让列引用与度量值引用更容易区分。 示例：
`SUM([SalesAmount])` -> `SUM(Sales[SalesAmount])` | -| DI005 | [将表筛选 FILTER 重写为标量谓词](xref:DI005) | DAX 中一种常见的反模式是：在 [`CALCULATE`](https://dax.guide/CALCULATE) 的筛选参数中使用 `FILTER` 对整张表进行筛选，而实际上只需筛选该表中的一个或多个列即可。 示例：
`CALCULATE([Total Sales], FILTER(Products, Products[Color] = "Red"))` -> `CALCULATE([Total Sales], KEEPFILTERS(Products[Color] = "Red"))`
此代码操作支持原始表达式的多种变体。 | -| DI006 | [将多列筛选拆分为多个筛选](xref:DI006) | 当使用 `AND`(或等效的 `&&` 运算符)将多个列组合起来筛选表时，通常可通过为每一列分别指定筛选条件来获得更好的性能。 示例：
`CALCULATE(..., Products[Color] = "Red" && Products[Size] = "Large")` -> `CALCULATE(..., Products[Color] = "Red", Products[Size] = "Large")` | -| DI007 | [简化 SWITCH 语句](xref:DI007) | 对于 [`SWITCH`](https://dax.guide/SWITCH) 语句，如果其 **<Expression>** 参数指定为 `TRUE()`，并且所有 **<Value>** 参数都是对同一个 VAR 变量/度量值的简单比较，则可以简化。 示例：
`SWITCH(TRUE(), a = 1, ..., a = 2, ...)` -> `SWITCH(a, 1, ..., 2, ...)` | -| DI008 | [移除多余的 CALCULATE](xref:DI008) | 如果 [`CALCULATE`](https://dax.guide/CALCULATE) 并非必需——例如它不会修改筛选语境，或即使省略也会发生隐式语境转换——则应将其移除。 示例：
`CALCULATE([Total Sales])` -> `[Total Sales]`
`AVERAGEX(Product, CALCULATE([Total Sales]))` -> `AVERAGEX(Product, [Total Sales])`

当 `CALCULATE` / `CALCULATETABLE` 的第一个参数是 DAX 变量时，此规则同样适用，例如：
`VAR x = [Total Sales] RETURN CALCULATE(x, Product[Color] = "Red")` ->
`VAR x = [Total Sales] RETURN x` | -| DI009 | [避免使用 CALCULATE 简写语法](xref:DI009) | 示例：
`[Total Sales](Products[Color] = "Red")` -> `CALCULATE([Total Sales], Products[Color] = "Red")` | -| DI010 | [使用 MIN/MAX 代替 IF](xref:DI010) | 当条件表达式用于返回两个值中的最小值或最大值时，使用 [`MIN`](https://dax.guide/MIN) 或 [`MAX`](https://dax.guide/MAX) 函数会更高效、更简洁。 示例：
`IF(a > b, a, b)` -> `MAX(a, b)` | -| DI011 | [使用 ISEMPTY 代替 COUNTROWS](xref:DI011) | 检查表是否为空时，使用 [`ISEMPTY`](https://dax.guide/ISEMPTY) 函数比统计表的行数更高效。 示例：
`COUNTROWS(Products) = 0` -> `ISEMPTY(Products)` | -| DI012 | [使用 DIVIDE 代替除法](xref:DI012) | 当在除法的分母中使用任意表达式时，建议使用 [`DIVIDE`](https://dax.guide/DIVIDE) 而不是除法运算符，以避免出现除以零错误。 示例：
`x / y` -> `DIVIDE(x, y)` | -| DI013 | [使用除法运算符代替 DIVIDE](xref:DI013) | 当 [`DIVIDE`](https://dax.guide/DIVIDE) 的第 2 个参数是非零常量时，使用除法运算符更高效。 示例：
`DIVIDE(x, 2)` -> `x / 2` | -| DI014 | [用 DIVIDE 代替 IFERROR](xref:DI014) | 当除法的分母为零时，使用 [`DIVIDE`](https://dax.guide/DIVIDE) 函数而不是 [`IFERROR`](https://dax.guide/IFERROR) 来提供替代结果。 示例：
`IFERROR(x / y, 0)` -> `DIVIDE(x, y, 0)` | -| DI015 | [用 DIVIDE 替换 IF](xref:DI015) | 使用 [`DIVIDE`](https://dax.guide/DIVIDE) 函数而不是 [`IF`](https://dax.guide/IF)，可更轻松地检查分母是否为零或空白。 示例：
`IF(y <> 0, x / y)` -> `DIVIDE(x, y)` | -| DI016 | 使用正确的 UDF 语法 | 用户定义函数表达式要使用正确的语法。 示例：
`(x, y) => x + y` | +| ID | 名称 | 描述 | +| ----- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| DI001 | [删除未使用的变量](xref:DI001) | 未在任何地方被引用的变量应删除。 示例：
`VAR a = 1 VAR b = 2 RETURN a` -> `VAR a = 1 RETURN a` | +| DI002 | [删除所有未使用的变量](xref:DI002) | 在 VAR 变量块中，凡是在 `RETURN` 部分未被使用的变量（无论是直接使用，还是通过其他变量间接使用）都应删除。 示例：
`VAR a = 1 VAR b = a RETURN 123` -> `123` | +| DI003 | [移除表名](xref:DI003) | 度量值引用中不应包含表名，因为引用度量值时表名是多余的。 此外，这样做也能让度量值引用与列引用更容易区分。 示例：
`Sales[Total Sales]` -> `[Total Sales]` | +| DI004 | [添加表名](xref:DI004) | 列引用应包含表名，以避免歧义，并更容易将列引用与度量值引用区分开来。 示例：
`SUM([SalesAmount])` -> `SUM(Sales[SalesAmount])` | +| DI005 | [将表筛选 FILTER 重写为标量谓词](xref:DI005) | DAX 中一个常见的反模式是，在 [`CALCULATE`](https://dax.guide/CALCULATE) 的筛选器参数中筛选整张表，而实际上只需筛选该表中的一个或多个列即可。 示例：
`CALCULATE([Total Sales], FILTER(Products, Products[Color] = "Red"))` -> `CALCULATE([Total Sales], KEEPFILTERS(Products[Color] = "Red"))`
此代码操作支持原始表达式的多种变体。 | +| DI006 | [将多列筛选拆分为多个筛选](xref:DI006) | 当使用 `AND`(或等效的 `&&` 运算符)将多个列组合起来筛选表时，通常可通过为每一列分别指定筛选条件来获得更好的性能。 示例：
`CALCULATE(..., Products[Color] = "Red" && Products[Size] = "Large")` -> `CALCULATE(..., Products[Color] = "Red", Products[Size] = "Large")` | +| DI007 | [简化 SWITCH 语句](xref:DI007) | 将 `TRUE()` 指定为 **<Expression>** 参数，且所有 **<Value>** 参数都是对同一 VAR 变量/度量值进行简单比较的 [`SWITCH`](https://dax.guide/SWITCH) 语句，可以简化。 示例：
`SWITCH(TRUE(), a = 1, ..., a = 2, ...)` -> `SWITCH(a, 1, ..., 2, ...)` | +| DI008 | [移除多余的 CALCULATE](xref:DI008) | 如果 [`CALCULATE`](https://dax.guide/CALCULATE) 并非必需——例如它不会修改筛选语境，或即使省略也会发生隐式语境转换——则应将其移除。 示例：
`CALCULATE([Total Sales])` -> `[Total Sales]`
`AVERAGEX(Product, CALCULATE([Total Sales]))` -> `AVERAGEX(Product, [Total Sales])`

如果 `CALCULATE` / `CALCULATETABLE` 的第一个参数是 DAX 变量，也同样适用，例如：
`VAR x = [Total Sales] RETURN CALCULATE(x, Product[Color] = "Red")` ->
`VAR x = [Total Sales] RETURN x` | +| DI009 | [避免使用 CALCULATE 简写语法](xref:DI009) | 示例：
`[Total Sales](Products[Color] = "Red")` -> `CALCULATE([Total Sales], Products[Color] = "Red")` | +| DI010 | [使用 MIN/MAX 代替 IF](xref:DI010) | 当使用条件表达式返回两个值中的较小值或较大值时，使用 [`MIN`](https://dax.guide/MIN) 或 [`MAX`](https://dax.guide/MAX) 函数会更高效，也更简洁。 示例：
`IF(a > b, a, b)` -> `MAX(a, b)` | +| DI011 | [使用 ISEMPTY 代替 COUNTROWS](xref:DI011) | 检查表是否为空时，使用 [`ISEMPTY`](https://dax.guide/ISEMPTY) 函数比统计表的行数更高效。 示例：
`COUNTROWS(Products) = 0` -> `ISEMPTY(Products)` | +| DI012 | [使用 DIVIDE 代替除法](xref:DI012) | 当分母为任意表达式时，应使用 [`DIVIDE`](https://dax.guide/DIVIDE) 而不是除法运算符，以避免除以零错误。 示例：
`x / y` -> `DIVIDE(x, y)` | +| DI013 | [使用除法运算符代替 DIVIDE](xref:DI013) | 当 [`DIVIDE`](https://dax.guide/DIVIDE) 的第 2 个参数是非零常量时，使用除法运算符会更高效。 示例：
`DIVIDE(x, 2)` -> `x / 2` | +| DI014 | [用 DIVIDE 代替 IFERROR](xref:DI014) | 除法的分母为零时，如果要提供替代结果，使用 [`DIVIDE`](https://dax.guide/DIVIDE) 函数，而不是 [`IFERROR`](https://dax.guide/IFERROR)。 示例：
`IFERROR(x / y, 0)` -> `DIVIDE(x, y, 0)` | +| DI015 | [用 DIVIDE 替换 IF](xref:DI015) | 如果想更轻松地检查分母是否为零或空白，使用 [`DIVIDE`](https://dax.guide/DIVIDE) 函数，而不是 [`IF`](https://dax.guide/IF)。 示例：
`IF(y <> 0, x / y)` -> `DIVIDE(x, y)` | +| DI016 | 使用正确的 UDF 语法 | 用户定义函数表达式应使用正确的语法。 示例：
`(x, y) => x + y` | ### 可读性 将光标置于代码分段上时，下面的代码操作会在适用代码的前两个字符下方显示青绿色圆点，并在左侧边距显示螺丝刀图标 -| ID | 名称 | 描述 | -| ----- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| DR001 | [转换为标量谓词](xref:DR001) | 列筛选器可以更简洁地写成标量谓词，而无需显式使用 [`FILTER`](https://dax.guide/FILTER) 函数。 示例：
`FILTER(ALL(Products[Color]), Products[Color] = "Red")` -> `Products[Color] = "Red"`
`FILTER(VALUES(Products[Color]), Products[Color] = "Red")` -> `KEEPFILTERS(Products[Color] = "Red")` | -| DR002 | [使用聚合函数而非迭代器函数](xref:DR002) | 在可能的情况下，使用聚合函数而不是迭代器函数，以简化代码。 示例：
`SUMX(Products, Products[SalesAmount])` -> `SUM(Products[SalesAmount])` | -| DR003 | [使用 VALUES 而非 SUMMARIZE](xref:DR003) | 当 [`SUMMARIZE`](https://dax.guide/SUMMARIZE) 仅指定一列，且该列属于第一个参数指定的表时，可使用 [`VALUES`](https://dax.guide/VALUES) 将代码写得更简洁。 示例：
`SUMMARIZE(Products, Products[Color])` -> `VALUES(Products[Color])` | -| DR004 | [为 VAR 变量添加前缀](xref:DR004) | 变量应使用一致的命名规范。 建议使用前缀，例如下划线。 你可以配置要使用的前缀，以匹配你偏好的风格。 示例：
`VAR totalSales = SUM(Sales[SalesAmount])` -> `VAR _totalSales = SUM(Sales[SalesAmount])` | -| DR005 | [为临时列设置前缀](xref:DR005) | 建议为临时列使用统一的前缀，以便更轻松地将其与基础列或度量值区分开来。 你可以配置要使用的前缀，以符合你偏好的风格。 示例：
`ADDCOLUMNS(Product, "SalesByProd", [Sales])` -> `ADDCOLUMNS(Product, "@SalesByProd", [Sales])` | -| DR006 | [将常量聚合移入 VAR 变量](xref:DR006) | 当聚合函数在迭代器或标量谓词中使用时，该聚合会为迭代中的每一行产生相同的结果。 因此，可以将该聚合移到迭代之外的 DAX VAR 变量中。 示例：
`CALCULATE(..., 'Date'[Date] = MAX('Date'[Date]))` ->
`VAR _maxDate = MAX('Date'[Date]) RETURN CALCULATE(..., 'Date'[Date] = _maxDate)` | -| DR007 | [简化 1 变量块](xref:DR007) | 仅包含一个 VAR 变量的变量块可通过将表达式直接移到该块的 `RETURN` 部分来简化。 这假定该变量只被引用一次，且没有任何上下文修饰符。 示例：
`VAR _result = [Sales] * 1.25 RETURN _result` -> `[Sales] * 1.25` | -| DR008 | [简化多变量 VAR 块](xref:DR008) | 对于包含多个变量的 VAR 变量块，若每个变量都只是对度量值的简单引用，并且每个变量在 `RETURN` 部分仅使用一次且不带任何上下文修饰符，则应简化该变量块。 示例：
`VAR _sales = [Sales] VAR _cost = [Cost] RETURN _sales - _cost` -> `[Sales] - [Cost]` | -| DR009 | [使用 DISTINCTCOUNT 重写](xref:DR009) | 要统计列中不同值的数量，不要使用 `COUNTROWS(DISTINCT(T[c])`，而应使用 [`DISTINCTCOUNT`](https://dax.guide/DISTINCTCOUNT) 函数。 | -| DR010 | [使用 COALESCE 重写](xref:DR010) | 若要在 `RETURN` 中从一组表达式中返回第一个非空白值，不要使用 `IF`，而应使用 [`COALESCE`](https://dax.guide/COALESCE) 函数。 示例：
`IF(ISBLANK([Sales]), [Sales2], [Sales])` -> `COALESCE([Sales], [Sales2])` | -| DR011 | [使用 ISBLANK 重写](xref:DR011) | 不要将表达式与 [`BLANK()`](https://dax.guide/BLANK) 进行比较，而应使用 [`ISBLANK`](https://dax.guide/ISBLANK) 函数。 示例：
`IF([Sales] = BLANK(), [Budget], [Sales])` -> `IF(ISBLANK([Sales], [Budget], [Sales])` | -| DR012 | [移除不必要的 BLANK](xref:DR012) | 某些 DAX 函数，例如 [`IF`](https://dax.guide/IF) 和 [`SWITCH`](https://dax.guide/SWITCH)，在条件不成立时已经会返回 `BLANK()`，因此无需显式指定 `BLANK()`。 示例：
`IF(a > b, a, BLANK())` -> `IF(a > b, a)` | -| DR013 | [简化取反逻辑](xref:DR013) | 对逻辑表达式取反时，通常改用对应的否定运算符来重写，这样更易读。 示例：
`NOT(a = b)` -> `a <> b` | -| DR014 | [使用 IN 简化](xref:DR014) | 使用 [`IN`](https://dax.guide/IN) 运算符来重写复合谓词（即针对同一表达式的相等比较，并通过 [`OR`](https://dax.guide/OR) 或 [`\\|\\|`](https://dax.guide/op/or/) 进行组合）。 示例：
`a = 1 \\|\\| a = 2 \\|\\| a = 100` -> `a IN { 1, 2, 100 }` | +| ID | 名称 | 描述 | +| ----- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| DR001 | [转换为标量谓词](xref:DR001) | 列筛选可以更简洁地写成标量谓词，而无需显式使用 [`FILTER`](https://dax.guide/FILTER) 函数。 示例：
`FILTER(ALL(Products[Color]), Products[Color] = "Red")` -> `Products[Color] = "Red"`
`FILTER(VALUES(Products[Color]), Products[Color] = "Red")` -> `KEEPFILTERS(Products[Color] = "Red")` | +| DR002 | [使用聚合函数而非迭代器函数](xref:DR002) | 在可能的情况下，使用聚合函数而不是迭代器函数，以简化代码。 示例：
`SUMX(Products, Products[SalesAmount])` -> `SUM(Products[SalesAmount])` | +| DR003 | [使用 VALUES 而非 SUMMARIZE](xref:DR003) | 当 [`SUMMARIZE`](https://dax.guide/SUMMARIZE) 只指定一个列，且该列属于第一个参数指定的表时，可改用 [`VALUES`](https://dax.guide/VALUES) 让代码更简洁。 示例：
`SUMMARIZE(Products, Products[Color])` -> `VALUES(Products[Color])` | +| DR004 | [为 VAR 变量添加前缀](xref:DR004) | 变量应使用一致的命名规范。 建议使用前缀，例如下划线。 你可以配置要使用的前缀，以匹配你偏好的风格。 示例：
`VAR totalSales = SUM(Sales[SalesAmount])` -> `VAR _totalSales = SUM(Sales[SalesAmount])` | +| DR005 | [为临时列设置前缀](xref:DR005) | 建议为临时列使用统一的前缀，以便更轻松地将其与基础列或度量值区分开来。 你可以配置要使用的前缀，以符合你偏好的风格。 示例：
`ADDCOLUMNS(Product, "SalesByProd", [Sales])` -> `ADDCOLUMNS(Product, "@SalesByProd", [Sales])` | +| DR006 | [将常量聚合移入 VAR 变量](xref:DR006) | 当聚合函数在迭代器或标量谓词中使用时，该聚合会为迭代中的每一行产生相同的结果。 因此，可以将该聚合移到迭代之外的 DAX VAR 变量中。 示例：
`CALCULATE(..., 'Date'[Date] = MAX('Date'[Date]))` ->
`VAR _maxDate = MAX('Date'[Date]) RETURN CALCULATE(..., 'Date'[Date] = _maxDate)` | +| DR007 | [简化 1 变量块](xref:DR007) | 仅包含一个 VAR 变量的变量块可通过将表达式直接移到该块的 `RETURN` 部分来简化。 这假定该变量只被引用一次，且没有任何上下文修饰符。 示例：
`VAR _result = [Sales] * 1.25 RETURN _result` -> `[Sales] * 1.25` | +| DR008 | [简化多变量 VAR 块](xref:DR008) | 如果一个 VAR 变量块包含多个变量，且每个变量都只是简单的度量值引用，并且在 `RETURN` 部分仅使用一次且不带任何上下文修饰符，则应将该变量块简化。 示例：
`VAR _sales = [Sales] VAR _cost = [Cost] RETURN _sales - _cost` -> `[Sales] - [Cost]` | +| DR009 | [使用 DISTINCTCOUNT 重写](xref:DR009) | 要统计列中不同值的数量，不要使用 `COUNTROWS(DISTINCT(T[c])`，而应使用 [`DISTINCTCOUNT`](https://dax.guide/DISTINCTCOUNT) 函数。 | +| DR010 | [使用 COALESCE 重写](xref:DR010) | 不要使用 `IF` 从一组表达式中返回第一个非空白值，而应使用 [`COALESCE`](https://dax.guide/COALESCE) 函数。 示例：
`IF(ISBLANK([Sales]), [Sales2], [Sales])` -> `COALESCE([Sales], [Sales2])` | +| DR011 | [使用 ISBLANK 重写](xref:DR011) | 与其将表达式同 [`BLANK()`](https://dax.guide/BLANK) 进行比较，不如使用 [`ISBLANK`](https://dax.guide/ISBLANK) 函数。 示例：
`IF([Sales] = BLANK(), [Budget], [Sales])` -> `IF(ISBLANK([Sales], [Budget], [Sales])` | +| DR012 | [移除不必要的 BLANK](xref:DR012) | 某些 DAX 函数（例如 [`IF`](https://dax.guide/IF) 和 [`SWITCH`](https://dax.guide/SWITCH)）在条件为 false 时本身就会返回 `BLANK()`，因此无需显式指定 `BLANK()`。 示例：
`IF(a > b, a, BLANK())` -> `IF(a > b, a)` | +| DR013 | [简化取反逻辑](xref:DR013) | 当逻辑表达式取反时，通常用取反后的运算符重写该表达式会更易读。 示例：
`NOT(a = b)` -> `a <> b` | +| DR014 | [使用 IN 简化](xref:DR014) | 使用 [`IN`](https://dax.guide/IN) 运算符来重写复合谓词（即针对同一表达式的相等比较，并通过 [`OR`](https://dax.guide/OR) 或 [`\\|\\|`](https://dax.guide/op/or/) 进行组合）。 示例：
`a = 1 \\|\\| a = 2 \\|\\| a = 100` -> `a IN { 1, 2, 100 }` | ### 重写 @@ -131,14 +131,14 @@ Tabular Editor 3.18.0 引入了一项名为 **代码操作** 的新功能。 该 | ID | 名称 | 描述 | | ----- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | RW001 | [使用 CALCULATE 重写 TOTALxTD](xref:RW001) | [`TOTALMTD`](https://dax.guide/TOTALMTD)、[`TOTALQTD`](https://dax.guide/TOTALQTD) 和 [`TOTALYTD`](https://dax.guide/TOTALYTD) 等函数都可以使用 [`CALCULATE`](https://dax.guide/CALCULATE) 函数重写。这样表达力更强，也提供了更高的灵活性。 示例：
`TOTALYTD([Total Sales], 'Date'[Date])` -> `CALCULATE([Total Sales], DATESYTD('Date'[Date]))` | -| RW002 | [使用 FILTER 重写](xref:RW002) | `CALCULATE` 的筛选参数中的标量谓词可以使用 `FILTER` 重写。 例如，当你需要添加更复杂的筛选逻辑时，这会很有用。 示例：
`CALCULATE(..., Products[Color] = "Red")` -> `CALCULATE(..., FILTER(ALL(Products[Color]), Products[Color] = "Red"))` | +| RW002 | [使用 FILTER 重写](xref:RW002) | `CALCULATE` 的筛选器参数中的标量谓词可以用 `FILTER` 改写。 例如，当你需要添加更复杂的筛选逻辑时，这会很有用。 示例：
`CALCULATE(..., Products[Color] = "Red")` -> `CALCULATE(..., FILTER(ALL(Products[Color]), Products[Color] = "Red"))` | | RW003 | [反转 IF](xref:RW003) | 为了提高可读性，有时反转 `IF` 语句会很有帮助。 示例：
`IF(a < b, "B is greater", "A is greater")` -> `IF(a > b, "A is greater", "B is greater")` | ## 自定义代码操作 -你可以在 **工具 > 偏好** 对话框中，依次进入 **文本编辑器 > DAX编辑器 > 代码操作**，来自定义代码操作的行为。 在这里，你可以开启或关闭该功能，并为某些代码操作配置其他选项，例如用于变量名和扩展列的前缀。 +你可以在 **工具 > 偏好** 对话框中，依次进入 **文本编辑器 > DAX编辑器 > 代码操作**，自定义代码操作的行为。 在这里，你可以开启或关闭该功能，并为某些代码操作配置其他选项，例如用于变量名和扩展列的前缀。 -我们计划在未来版本中为此界面添加更多配置选项，例如提供单独开启或关闭各个代码操作的选项。 敬请期待！ +我们计划在未来版本中为此界面添加更多配置选项，例如提供可单独启用或禁用各个代码操作的选项。 敬请期待！ ![代码操作偏好](~/content/assets/images/code-actions-preferences.png) diff --git a/localizedContent/zh/content/features/csharp-scripts.md b/localizedContent/zh/content/features/csharp-scripts.md index 7771c1288..6c694cb4e 100644 --- a/localizedContent/zh/content/features/csharp-scripts.md +++ b/localizedContent/zh/content/features/csharp-scripts.md @@ -1,8 +1,8 @@ --- uid: csharp-scripts -title: C# Script +title: C# Scripts author: Daniel Otykier -updated: 2026-03-19 +updated: 2026-05-27 applies_to: products: - product: Tabular Editor 2 @@ -15,68 +15,70 @@ applies_to: full: true - edition: Enterprise full: true + - product: Tabular Editor CLI + full: true --- -# C# Script +# C# Scripts -本文将介绍 Tabular Editor 3 的 C# Script 功能。 本文档中的信息可能会发生变更。 另外，别忘了查看我们的脚本库 @csharp-script-library，里面有更多贴近实际的示例，展示如何使用 Tabular Editor 的脚本功能。 +This is an introduction to the C# Scripting capabilities of Tabular Editor 3. Information in this document is subject to change. Also, make sure to check out our script library @csharp-script-library, for some more real-life examples of what you can do with the scripting capabilities of Tabular Editor. -## 为什么要用 C# Script？ +## Why C# scripting? -Tabular Editor 的 UI 旨在让你在构建表格模型时轻松完成大多数常见任务。 例如，要一次性更改多个度量值的显示文件夹，只需在资源管理器树中选中这些对象，然后拖放到相应位置即可。 资源管理器树的右键菜单提供了更便捷的入口来完成许多任务，例如将对象添加到透视中或从透视中移除、批量重命名对象等。 +Tabular Editor 的界面旨在让你在构建表格模型时，轻松完成大多数常见任务。 For example, changing the Display Folder of multiple measures at once is just a matter of selecting the objects in the explorer tree and then dragging and dropping them around. The right-click context menu of the explorer tree provides a convenient way to perform many of these tasks, such as adding/removing objects from perspectives, renaming multiple objects, etc. -不过，还有不少常见的工作流任务并不容易通过 UI 完成。 因此，Tabular Editor 提供 C# Script，让高级用户可以用 C# 语法编写脚本，更直接地操作已加载的表格模型中的对象。 +There may be many other common workflow tasks, which are not as easily performed through the UI however. For this reason, Tabular Editor offers C# scripting, which lets advanced users write a script using C# syntax, to more directly manipulate the objects in the loaded Tabular Model. ## Code Assist -C# Script 编辑器支持基于 Roslyn 的代码补全和调用提示；从 Tabular Editor 3.23.0 起，补全还支持子字符串匹配和大写首字母缩写匹配。 +The C# script editor supports Roslyn-powered completion and call tips and from Tabular Editor 3.23.0, completion supports substring and capital-letters acronym matching. -## 对象 +## Objects -[scripting API](xref:api-index) 提供对两个顶层对象的访问：`Model` 和 `Selected`。 前者包含用于操作表格模型中所有对象的方法和属性；后者只公开当前在资源管理器树中选中的对象。 +[脚本 API](xref:api-index) 提供对两个顶层对象的访问：`Model` 和 `Selected`。 The former contains methods and properties that allow you to manipulate all objects in the Tabular Model, whereas the latter exposes only objects that are currently selected in the explorer tree. -`Model` 对象是 [Microsoft.AnalysisServices.Tabular.Model](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx) 类的封装，仅公开其部分属性，并额外提供一些方法和属性，方便对翻译、透视和对象集合进行操作。 同样也适用于任何派生对象，例如表、度量值、列等，它们都各自有对应的包装器对象。 请参阅 ，查看 Tabular Editor 包装器库中对象、属性和方法的完整列表。 +The `Model` object is a wrapper of the [Microsoft.AnalysisServices.Tabular.Model](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx) class, exposing a subset of it’s properties, with some additional methods and properties for easier operations on translations, perspectives and object collections. The same applies to any descendant objects, such as Table, Measure, Column, etc. which all have corresponding wrapper objects. Please see for a complete listing of objects, properties and methods in the Tabular Editor wrapper library. -通过此包装器进行操作的主要优势在于：所有更改都可以在 Tabular Editor UI 中撤销。 执行脚本后直接按 CTRL+Z，你会看到脚本所做的所有更改会立即被撤销。 此外，包装器还提供了一些便捷方法，让许多常见任务都能用一行代码完成。 下面我们会提供一些示例。 我们假设你已经对 C# 和 LINQ 有一定了解，因为这里不会讲解 Tabular Editor 脚本功能中的这些内容。 即使你不熟悉 C# 和 LINQ，也应该能跟上下面的示例。 +The main advantage of working through this wrapper is, that all changes will be undoable from the Tabular Editor UI. Simply press CTRL+Z after executing a script, and you will see that all changes made by the script are immediately undone. Furthermore, the wrapper provides convenient methods that turn many common tasks into simple one-liners. We will provide some examples below. It is assumed that the reader is already somewhat familiar with C# and LINQ, as these aspects of Tabular Editors scripting capabilities will not be covered here. Users unfamiliar with C# and LINQ should still be able to follow the examples given below. -## 设置对象属性 +## Setting object properties -如果你只想更改某一个对象的某个属性，最简单的方式当然是直接在 UI 中操作。 不过作为示例，我们来看如何通过脚本实现同样的效果。 +如果你想更改某个特定对象的属性，显然最简单的方式就是直接在 UI 中操作。 But as an example, let us see how we could achieve the same thing through scripting. -假设你想修改 'FactInternetSales' 表中 [Sales Amount] 度量值的格式字符串。 如果你在资源管理器树中找到该度量值，直接将其拖到脚本编辑器即可。 随后 Tabular Editor 会生成如下代码，用于在 Tabular Object Model 中表示这个特定的度量值： +假设你想更改 'FactInternetSales' 表中 [Sales Amount] 度量值的格式字符串。 If you locate the measure in the explorer tree, you can simply drag it onto the script editor. Tabular Editor will then generate the following code, which represents this particular measure in the Tabular Object Model: ```csharp Model.Tables["FactInternetSales"].Measures["Sales Amount"] ``` -再加一个点（.） 在最右侧括号后加上英文句点.，就会弹出自动补全菜单，显示这个度量值有哪些属性和方法。 在菜单中直接选择 "FormatString"，或者输入前几个字母后按 Tab。 然后输入等号，后面接 "0.0%"。 我们也来修改此度量值的显示文件夹。 最终代码应如下所示： +Adding an extra dot (.) after the right-most bracket, should make the autocomplete menu pop up, showing you which properties and methods exist on this particular measure. Simply choose "FormatString" in the menu, or write the first few letters and hit Tab. Then, enter an equal sign followed by "0.0%". Let us also change the Display Folder of this measure. Your final code should look like this: ```csharp Model.Tables["FactInternetSales"].Measures["Sales Amount"].FormatString = "0.0%"; Model.Tables["FactInternetSales"].Measures["Sales Amount"].DisplayFolder = "New Folder"; ``` -**注意：** 记得在每行末尾加上分号（;）。 这是 C# 的要求。 如果忘了加，尝试执行脚本时会收到语法错误信息。 +**Note:** Remember to put the semicolon (;) at the end of each line. This is a requirement of C#. If you forget it, you will get a syntax error message when trying to execute the script. -按 F5 或点击脚本编辑器上方的“播放”按钮来执行脚本。 你会立刻看到该度量值在资源管理器树中移动位置，反映出“显示文件夹”已更改。 如果你在属性网格中查看该度量值，也会看到“格式字符串”属性已相应更改。 +Hit F5 or the "Play" button above the script editor to execute the script. Immediately, you should see the measure moving around in the explorer tree, reflecting the changed Display Folder. If you examine the measure in the Property Grid, you should also see that the Format String property has changed accordingly. -### 同时处理多个对象 +### Working with multiple objects at once -对象模型中的许多对象实际上都是由多个对象组成的集合。 例如，每个表对象都有一个度量值集合。 该封装器在这些集合上提供了一系列便捷的属性和方法，便于你一次性为多个对象设置相同的属性。 下文将对此进行详细说明。 此外，你还可以使用所有标准的 LINQ 扩展方法来筛选和浏览集合中的对象。 +Many objects in the object model, are actually collections of multiple objects. For example, each Table object has a Measures collection. The wrapper exposes a series of convenient properties and methods on these collections, to make it easy to set the same property on multiple objects at once. This is described in detail below. Additionally, you may use all the standard LINQ extension methods to filter and browse the objects of a collection. -下面是一些最常用的 LINQ 扩展方法示例： +Below is a few examples of the most commonly used LINQ extension methods: -- `Collection.First([predicate])` 返回集合中第一个满足可选 [predicate] 条件的对象。 -- `Collection.Any([predicate])` 如果集合包含任何对象（可选：满足 [predicate] 条件），则返回 true。 -- `Collection.Where(predicate)` 返回一个集合，该集合是按 predicate 条件从原集合筛选得到的。 -- `Collection.Select(map)` 根据指定的 map，将集合中的每个对象投影为另一个对象。 -- `Collection.ForEach(action)` 对集合中的每个元素执行指定的 action。 +- `Collection.First([predicate])` Returns the first object in the collection satisfying the optional [predicate] condition. +- `Collection.Any([predicate])` Returns true if the collection contains any objects (optionally satisfying the [predicate] condition). +- `Collection.Where(predicate)` Returns a collection that is the original collection filtered by the predicate condition. +- `Collection.Select(map)` Projects each object in the collection into another object according to the specified map. +- `Collection.ForEach(action)` Performs the specified action on each element in the collection. -在上面的示例中，`predicate` 是一个 lambda 表达式：以单个对象作为输入，并返回一个布尔值作为输出。 例如，如果 `Collection` 是一个度量值集合，一个典型的 `predicate` 可能是： +在上面的示例中，`predicate` 是一个 lambda 表达式：它以单个对象作为输入，并返回一个布尔值作为输出。 For example, if `Collection` is a collection of measures, a typical `predicate` could look like: `m => m.Name.Contains("Reseller")` -该 predicate 仅在度量值的 `Name` 包含字符串“Reseller”时才会返回 true。 如果需要更复杂的逻辑，可以用花括号包裹表达式并使用 `return` 关键字： +仅当该度量值的 Name 属性包含字符串 "Reseller" 时，此 predicate 才会返回 true。 Wrap the expression in curly braces and use the `return` keyword, if you need more advanced logic: ```csharp .Where(obj => { @@ -87,51 +89,51 @@ Model.Tables["FactInternetSales"].Measures["Sales Amount"].DisplayFolder = "New }) ``` -回到上面的示例，`map` 是一个 lambda 表达式：以单个对象作为输入，并返回任意单个对象作为输出。 `action` 是一个 lambda 表达式：以单个对象作为输入，但不返回任何值。 +回到上面的示例，`map` 是一个 lambda 表达式：它以单个对象作为输入，并返回一个对象作为输出。 `action` is a lambda expression that takes a single object as input, but does not return any value. -## 使用 **Model** 对象 +## Working with the **Model** object -要快速引用当前已加载的表格模型中的任意对象，你可以将该对象从资源管理器树拖放到 C# Script 编辑器中： +To quickly reference any object in the currently loaded Tabular Model, you can drag and drop the object from the explorer tree and into the C# script editor: -![将对象拖放到 C# Script 脚本编辑器中](~/content/assets/images/drag-object-to-script.gif) +![Dragging and dropping an object into the C# script editor](~/content/assets/images/drag-object-to-script.gif) -可以参考 [TOM 文档](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx)，了解 Model 及其派生对象上有哪些属性。 另外，也可以查看 ，获取包装对象公开的属性和方法的完整列表。 +如需了解 Model 及其后代对象包含哪些属性，请参阅 [TOM 文档](https://msdn.microsoft.com/en-us/library/microsoft.analysisservices.tabular.model.aspx)。 Additionally, refer to for a complete listing of the properties and methods exposed by the wrapper object. -## 使用 **Selected** 对象 +## Working with the **Selected** object -在某些工作流中，能够显式引用表格模型中的任何对象非常有用；但有时你希望从资源管理器树中挑选对象，然后只对所选对象执行脚本。 这时 `Selected` 对象就派上用场了。 +在某些工作流中，能够显式引用表格模型中的任意对象非常方便；但有时你希望从资源管理器树中挑选一批对象，然后仅对所选对象执行脚本。 This is where the `Selected` object comes in handy. -`Selected` 对象提供了一组属性，便于识别当前选中的内容，同时也可以将选择范围限定为特定类型的对象。 在使用显示文件夹浏览时，如果在资源管理器树中选中了一个或多个文件夹，则其所有子项也会被视为已选中。 -对于单项选择，请使用要访问的对象类型的单数名称。 例如， +The `Selected` object provides a range of properties that make it easy to identify what is currently selected, as well as limiting the selection to objects of a particular type. When browsing with Display Folders, and one or more folders are selected in the explorer tree, all their child items are considered to be selected as well. +For single selections, use the singular name for the type of object you want to access. For example, `Selected.Hierarchy` -它指向树中当前选中的层次结构，前提是只选中了一个层次结构。 如果要处理多选，请使用该类型的复数名称： +它指的是树中当前选中的层次结构，但前提是必须且只能选中一个层次结构。 Use the plural type name, in case you want to work with multiselections: `Selected.Hierarchies` -单数对象上存在的所有属性，在其复数形式上也同样存在，只有少数例外。 这意味着你可以用一行代码一次性为多个对象设置这些属性，而无需使用上面提到的 LINQ 扩展方法。 例如，假设你想把当前选中的所有度量值移动到名为 "Test" 的新显示文件夹中： +All properties that exist on the singular object, also exist on its plural form, with a few exceptions. This means that you can set the value of these properties for multiple objects at once, with just one line of code and without using the LINQ extension methods mentioned above. For example, say you wanted to move all currently selected measures into a new Display Folder called "Test": `Selected.Measures.DisplayFolder = "Test";` -如果树中当前没有选中任何度量值，上面的代码不会执行任何操作，也不会抛出错误。 否则，所有选中的度量值的 DisplayFolder 属性都会被设置为 "Test"（即使这些度量值位于文件夹中也是如此，因为 `Selected` 对象也会包含所选文件夹内的对象）。 如果你使用单数形式 `Measure` 而不是 `Measures`，除非当前选择恰好包含一个度量值，否则会报错。 +If no measures are currently selected in the tree, the above code does nothing, and no error is raised. Otherwise, the DisplayFolder property will be set to "Test" on all selected measures (even measures residing within folders, as the `Selected` object also includes objects in selected folders). If you use the singular form `Measure` instead of `Measures`, you will get an error unless the current selection contains exactly one measure. -虽然没法一次性设置多个对象的 Name 属性，但还是有一些办法。 如果只是想将某个字符串的所有匹配项替换为另一个字符串，可以使用提供的 "Rename" 方法，例如： +Although we cannot set the Name property of multiple objects at once, we still have some options available. 如果你只是想把某个字符串的所有出现位置替换成另一个字符串，可以使用提供的“Rename”方法，如下所示： ```csharp Selected.Measures .Rename("Amount", "Value"); ``` -这会将当前所选所有度量值的名称中出现的“Amount”替换为“Value”。 -或者，也可以按上文所述使用 LINQ 的 ForEach() 方法，以实现更复杂的逻辑： +这会将当前选中的所有度量值名称中的“Amount”全部替换为“Value”。 +Alternatively, we may use the LINQ ForEach()-method, as described above, to include more advanced logic: ```csharp Selected.Measures .ForEach(m => if(m.Name.Contains("Reseller")) m.Name += " DEPRECATED"); ``` -此示例会在所有已选且名称包含“Reseller”的度量值名称后追加文本“ DEPRECATED”。 或者，我们也可以先使用 LINQ 扩展方法 `Where()` 过滤集合，再应用 `ForEach()` 操作，得到的结果完全相同： +This example will append the text " DEPRECATED" to the names of all selected measures where the names contain the word "Reseller". 另外，你也可以在应用 `ForEach()` 操作之前，先用 LINQ 扩展方法 `Where()` 过滤集合，这将得到完全相同的结果： ```csharp Selected.Measures @@ -139,127 +141,127 @@ Selected.Measures .ForEach(m => m.Name += " DEPRECATED"); ``` -### Selected 访问器完整列表 - -下表列出了 `Selected` 对象上所有可用的单数和复数访问器。 如果当前选择中不恰好包含一个该类型的对象，单数访问器会抛出 `SelectionException`。 如果未选择该类型的任何对象，复数访问器会返回空集合。 - -| 单数 | 复数 | 对象类型 | -| ----------------------------------- | ------------------------------------ | ------- | -| `Selected.Measure` | `Selected.Measures` | 度量值 | -| `Selected.Column` | `Selected.Columns` | 所有列类型 | -| `Selected.DataColumn` | `Selected.DataColumns` | 数据列 | -| `Selected.CalculatedColumn` | `Selected.CalculatedColumns` | 计算列 | -| `Selected.CalculatedTableColumn` | `Selected.CalculatedTableColumns` | 计算表格列 | -| `Selected.Hierarchy` | `Selected.Hierarchies` | 层次结构 | -| `Selected.Level` | `Selected.Levels` | 层级 | -| `Selected.Table` | `Selected.Tables` | 表格 | -| `Selected.CalculatedTable` | `Selected.CalculatedTables` | 计算表格 | -| `Selected.Partition` | `Selected.Partitions` | 分区 | -| `Selected.Role` | `Selected.Roles` | 模型角色 | -| `Selected.TablePermission` | `Selected.TablePermissions` | 表格权限 | -| `Selected.KPI` | `Selected.KPIs` | KPI | -| `Selected.Calendar` | `Selected.Calendars` | 日历 | -| `Selected.CalculationItem` | `Selected.CalculationItems` | 计算项 | -| `Selected.Function` | `Selected.Functions` | 用户自定义函数 | -| `Selected.DataSource` | `Selected.DataSources` | 数据源 | -| `Selected.SingleColumnRelationship` | `Selected.SingleColumnRelationships` | 关系 | -| `Selected.Perspective` | `Selected.Perspectives` | 透视 | -| `Selected.Culture` | `Selected.Cultures` | 翻译 | +### Complete list of Selected accessors + +The following table lists all available singular and plural accessors on the `Selected` object. Singular accessors throw a `SelectionException` if the current selection does not contain exactly one object of that type. Plural accessors return an empty collection if no objects of that type are selected. + +| Singular | Plural | Object Type | +| ----------------------------------- | ------------------------------------ | ------------------------ | +| `Selected.Measure` | `Selected.Measures` | Measures | +| `Selected.Column` | `Selected.Columns` | All column types | +| `Selected.DataColumn` | `Selected.DataColumns` | Data columns | +| `Selected.CalculatedColumn` | `Selected.CalculatedColumns` | Calculated columns | +| `Selected.CalculatedTableColumn` | `Selected.CalculatedTableColumns` | Calculated table columns | +| `Selected.Hierarchy` | `Selected.Hierarchies` | Hierarchies | +| `Selected.Level` | `Selected.Levels` | Hierarchy levels | +| `Selected.Table` | `Selected.Tables` | Tables | +| `Selected.CalculatedTable` | `Selected.CalculatedTables` | Calculated tables | +| `Selected.Partition` | `Selected.Partitions` | Partitions | +| `Selected.Role` | `Selected.Roles` | Model roles | +| `Selected.TablePermission` | `Selected.TablePermissions` | Table permissions | +| `Selected.KPI` | `Selected.KPIs` | KPIs | +| `Selected.Calendar` | `Selected.Calendars` | Calendars | +| `Selected.CalculationItem` | `Selected.CalculationItems` | Calculation items | +| `Selected.Function` | `Selected.Functions` | User-defined functions | +| `Selected.DataSource` | `Selected.DataSources` | Data sources | +| `Selected.SingleColumnRelationship` | `Selected.SingleColumnRelationships` | Relationships | +| `Selected.Perspective` | `Selected.Perspectives` | Perspectives | +| `Selected.Culture` | `Selected.Cultures` | Translations | > [!NOTE] -> 在 Tabular Editor 3.26.0 中，新增了 角色、KPI、日历、计算项、表权限、函数、数据源、单列关系、计算列、计算表列、数据列、计算表和分区的访问器。 +> The accessors for Role, KPI, Calendar, CalculationItem, TablePermission, Function, DataSource, SingleColumnRelationship, CalculatedColumn, CalculatedTableColumn, DataColumn, CalculatedTable and Partition were added in Tabular Editor 3.26.0. -## 辅助方法 +## Helper methods -Tabular Editor 提供了一组专用的辅助方法，便于完成某些脚本任务。 注意，其中一些方法也可以以扩展方法的形式调用。 例如，`object.Output();` 与 `Output(object);` 是等价的。 +Tabular Editor provides a set of special helper methods to make certain script tasks easier to achieve. Note that some of these may be invoked as extension methods. For example, `object.Output();` and `Output(object);` are equivalent. -- `void Output(object value)` - 停止脚本执行，并显示所提供对象的信息。 当脚本作为命令行执行的一部分运行时，该方法会将该对象的字符串表示形式写入控制台。 -- `void SaveFile(string filePath, string content)` - 便捷地将文本数据保存到文件。 -- `string ReadFile(string filePath)` - 便捷地从文件加载文本数据。 -- `string ExportProperties(IEnumerable objects, string properties)` - 便捷地将多个对象的一组属性导出为 TSV 字符串。 -- `void ImportProperties(string tsvData)` - 便捷地将 TSV 字符串中的属性加载到多个对象中。 -- `void CustomAction(string name)` - 按名称调用宏。 -- `void CustomAction(this IEnumerable objects, string name)` - 对指定对象调用宏。 -- `string ConvertDax(string dax, bool useSemicolons)` - 在美/英区域设置与非美/英区域设置之间相互转换 DAX 表达式。 如果 `useSemicolons` 为 true（默认），则会将 `dax` 字符串从默认的美/英格式转换为非美/英格式。 也就是说，逗号（列表分隔符）会转换为分号，句点（小数分隔符）会转换为逗号。 如果将 `useSemicolons` 设为 false，则反向转换。 -- `void FormatDax(this IEnumerable objects, bool shortFormat, bool? skipSpace)` - 为所提供集合中的所有对象格式化 DAX 表达式 -- `void FormatDax(this IDaxDependantObject obj)` - 将对象加入队列，在脚本执行完成时，或调用 `CallDaxFormatter` 方法时，对其 DAX 表达式进行格式化。 -- `void CallDaxFormatter(bool shortFormat, bool? skipSpace)` - 格式化截至目前已加入队列的对象上的所有 DAX 表达式 -- `void Info(string)` - 将一条提示信息输出到控制台（仅当脚本在命令行执行过程中运行时）。 -- `void Warning(string)` - 将一条警告信息输出到控制台（仅当脚本在命令行执行过程中运行时）。 -- `void Error(string)` - 将一条错误信息输出到控制台（仅当脚本在命令行执行过程中运行时）。 -- `T SelectObject(this IEnumerable objects, T preselect = null, string label = "Select object") where T: TabularNamedObject` - 向用户显示一个对话框，提示其从指定对象中选择一个。 如果用户取消对话框，此方法将返回 null。 -- `void CollectVertiPaqAnalyzerStats()` - 如果 Tabular Editor 已连接到 Analysis Services 实例，则会运行 VertiPaq分析器统计信息收集器。 -- `long GetCardinality(this Column column)` - 如果当前模型有可用的 VertiPaq分析器统计信息，此方法将返回指定列的基数。 +- `void Output(object value)` - halts script execution and displays information about the provided object. When the script is running as part of a command line execution, this will write a string representation of the object to the console. +- `void SaveFile(string filePath, string content)` - convenient way to save text data to a file. +- `string ReadFile(string filePath)` - convenient way to load text data from a file. +- `string ExportProperties(IEnumerable objects, string properties)` - convenient way to export a set of properties from multiple objects as a TSV string. +- `void ImportProperties(string tsvData)` - convenient way to load properties into multiple objects from a TSV string. +- `void CustomAction(string name)` - invoke a macro by name. +- `void CustomAction(this IEnumerable objects, string name)` - invoke a macro on the specified objects. +- `string ConvertDax(string dax, bool useSemicolons)` - converts a DAX expression between US/UK and non-US/UK locales. If `useSemicolons` is true (default) the `dax` string is converted from the native US/UK format to non-US/UK. That is, commas (list separators) will be converted to semicolons and periods (decimal separators) will be converted to commas. Vice versa if `useSemicolons` is set to false. +- `void FormatDax(this IEnumerable objects, bool shortFormat, bool? skipSpace)` - formats DAX expressions on all objects in the provided collection +- `void FormatDax(this IDaxDependantObject obj)` - queues an object for DAX expression formatting when script execution is complete, or when the `CallDaxFormatter` method is called. +- `void CallDaxFormatter(bool shortFormat, bool? skipSpace)` - formats all DAX expressions on objects enqueued so far +- `void Info(string)` - Writes an informational message to the console (only when the script is executed as part of a command line execution). +- `void Warning(string)` - Writes a warning message to the console (only when the script is executed as part of a command line execution). +- `void Error(string)` - Writes an error message to the console (only when the script is executed as part of a command line execution). +- `T SelectObject(this IEnumerable objects, T preselect = null, string label = "Select object") where T: TabularNamedObject` - Displays a dialog to the user prompting to select one of the objects specified. If the user cancels the dialog, this method returns null. +- `void CollectVertiPaqAnalyzerStats()` - If Tabular Editor is connected to an instance of Analysis Services, this runs the VertiPaq Analyzer statistics collector. +- `long GetCardinality(this Column column)` - If VertiPaq Analyzer statistics are available for the current model, this method returns the cardinality of the specified column. -有关可用帮助方法及其语法的完整列表，请参阅 @script-helper-methods。 +For a full list of available helper methods and their syntax, view @script-helper-methods. -### 调试脚本 +### Debugging scripts -如上所述，你可以使用 `Output(object);` 方法暂停脚本执行，并打开一个对话框来显示所传入对象的信息。 你也可以将此方法作为扩展方法使用，通过 `object.Output();` 来调用。 关闭对话框后，脚本将继续执行。 +如上所述，你可以使用 `Output(object);` 方法来暂停脚本执行，并打开一个对话框来显示传入对象的信息。 You can also use this method as an extension method, invoking it as `object.Output();`. The script is resumed when the dialog is closed. -对话框会根据输出对象的类型，以以下四种方式之一呈现： +The dialog will appear in one of four different ways, depending on the kind of object being output: -- 单个对象（如 string、int 和 DateTime，但不包括任何派生自 TabularNamedObject 的对象）将以简单的信息对话框显示，方法是对该对象调用 `.ToString()`： +- Singular objects (such as strings, ints and DateTimes, except any object that derives from TabularNamedObject) will be displayed as a simple message dialog, by invoking the `.ToString()` method on the object: ![C-sharp Output](~/content/assets/images/c-sharp-script-output-function.png) -- 单个 TabularNamedObject（例如表、度量值，或 Tabular Editor 中提供的任何其他 TOM NamedMetadataObject）将显示在“属性网格”中，类似于在 Tree Explorer 树形资源管理器中选中某个对象时的效果。 你可以在网格中编辑该对象的属性。但请注意：如果脚本在后续执行过程中遇到错误，并且启用了“自动回滚”——"Auto-Rollback"——这些编辑将自动撤销： +- 单个 TabularNamedObject（例如表、度量值，或 Tabular Editor 中提供的任何其他 TOM NamedMetadataObject）会显示在属性网格中，类似于在 Tree Explorer 中选中对象时的效果。 Properties on the object may be edited in the grid, but note that if an error is encountered at a later point in the script execution, the edit will be automatically undone, if "Auto-Rollback" is enabled: ![C-sharp Output](~/content/assets/images/c-sharp-script-auto-rollback.png) -- 任何对象的 IEnumerable（TabularNamedObject 除外）都会以列表形式显示，其中每个列表项都会显示 IEnumerable 中各对象的 `.ToString()` 值及其类型： +- Any IEnumerable of objects (except TabularNamedObjects) will be displayed in a list, where each list item shows the `.ToString()` value and type of the object in the IEnumerable: ![C-sharp Output](~/content/assets/images/c-sharp-script-output-to-string-function.png) -- 任何 TabularNamedObject 的 IEnumerable 都会让对话框左侧显示对象列表，右侧显示属性网格。 属性网格会根据列表中当前选中的对象进行填充，并且属性可编辑方式与输出单个 TabularNamedObject 时相同： +- 任何 TabularNamedObject 的 IEnumerable 都会使对话框左侧显示对象列表，右侧显示属性网格。 The Property Grid will be populated from whatever object is selected in the list, and properties may be edited just as when a single TabularNamedObject is being output: ![C-sharp Output](~/content/assets/images/c-sharp-script-output-function-enumerated.png) -你可以勾选左下角的“不要再显示后续输出”复选框，以避免脚本在之后任何 `.Output()` 调用时暂停。 +You can tick the "Don't show more outputs" checkbox at the lower left-hand corner, to prevent the script from halting on any further `.Output()` invocations. -## 以预览方式运行 C# Script +## Run C# Scripts with Preview -**带预览运行**操作允许你在提交之前，预览 C# Script 对模型元数据所做的所有更改。 在运行不熟悉的脚本或执行批量修改时，这会很有用。 +**带预览运行**操作允许你在提交之前，预览 C# Script 对模型元数据所做的所有更改。 This is useful when running unfamiliar scripts or performing bulk modifications. -要使用此功能，在工具栏或菜单中点击 **脚本 > 带预览运行**。 流程如下： +要使用此功能，在工具栏或菜单中点击 **脚本 > 带预览运行**。 The workflow is: -1. Tabular Editor 会在执行前为模型元数据创建快照 -2. 脚本将运行直至完成 -3. Tabular Editor 会将当前模型的元数据状态与执行前创建的快照进行比较 -4. 如果检测到更改，将弹出预览对话框，以并排的分层差异视图显示模型（执行前与执行后） -5. 更改采用颜色区分：绿色表示新增对象，红色表示已删除对象，橙色表示已修改的属性 -6. 使用 **仅显示更改** 复选框隐藏未更改的项目，将注意力集中在脚本更改的内容上 -7. 单击 **确定** 以接受更改，或单击 **还原** 以撤销所有更改 +1. Tabular Editor takes a snapshot of the model metadata before execution +2. The script runs to completion +3. Tabular Editor compares the current model metadata state to the snapshot taken before execution +4. If changes are detected, a preview dialog appears showing a side-by-side hierarchical diff of the model (before and after) +5. Changes are color-coded: green for added objects, red for deleted and orange for modified properties +6. Use the **Show changes only** checkbox to hide unchanged items and focus on what the script changed +7. Click **OK** to accept the changes, or **Revert** to undo all changes -![脚本预览 - 模型更改](~/content/assets/images/c-sharp-script-preview-changes.png) +![Script Preview - Model Changes](~/content/assets/images/c-sharp-script-preview-changes.png) -如果脚本失败（编译或运行时错误），所有模型元数据更改都会自动回滚，并且不会显示预览对话框。 如果脚本成功但未检测到任何元数据更改，则会改为显示一条信息。 +如果脚本失败（编译或运行时错误），所有模型元数据更改都会自动回滚，并且不会显示预览对话框。 If the script succeeds but makes no detectable metadata changes, an informational message is displayed instead. -脚本执行产生的所有模型元数据更改都会封装在一次撤销事务中。 即使在预览对话框中接受了更改，也仍可通过 **Ctrl+Z** 撤销整个操作。 +All model metadata changes from a script execution are wrapped in a single undo transaction. Even after accepting changes through the preview dialog, you can still undo the entire operation with **Ctrl+Z**. > [!IMPORTANT] -> 预览与撤销功能仅适用于模型元数据更改。 如果脚本执行写入文件、数据库或发起 Web 请求等外部操作，这些操作会立即执行，且无法撤销。 预览对话框不会尝试分析脚本代码——其原理是比较执行前后的模型元数据状态。 +> The preview and undo features only apply to model metadata changes. If a script performs external operations such as writing to files, databases or making web requests, those operations are executed immediately and cannot be reverted. The preview dialog does not attempt to analyze the script code — it works by comparing the model metadata state before and after execution. > [!TIP] -> 当你在聊天中执行 C# Script 时，[AI 助手](xref:ai-assistant)会自动显示更改预览对话框，因此在应用前始终有机会查看 AI 生成的模型更改。 +> The [AI Assistant](xref:ai-assistant) shows the preview changes dialog automatically when you execute C# scripts from the chat, so you always get a chance to review AI-generated model changes before they are applied. -## .NET 引用 +## .NET references -你可以像在普通的 C# 源代码中一样，使用 `using` 关键字来简化类名等写法。 此外，你还可以使用语法 `#r ""` 来包含外部程序集，方式与 Azure Functions 中使用的 .csx 脚本类似。 +You can use the `using` keyword to shorten class names, etc. just like in regular C# source code. In addition, you can include external assemblies by using the syntax `#r ""` similar to .csx scripts used in Azure Functions. -例如，下面这段脚本现在会按预期工作： +For example, the following script will now work as expected: ```csharp -// 程序集引用必须放在文件最顶部： +// Assembly references must be at the very top of the file: #r "System.IO.Compression" -// using 关键字必须位于其他任何语句之前： +// Using keywords must come before any other statements: using System.IO.Compression; using System.IO; var xyz = 123; -// using 语句仍会按预期方式工作： +// Using statements still work the way they're supposed to: using(var data = new MemoryStream()) using(var zip = new ZipArchive(data, ZipArchiveMode.Create)) { @@ -267,7 +269,7 @@ using(var zip = new ZipArchive(data, ZipArchiveMode.Create)) } ``` -默认情况下，Tabular Editor 会自动引入以下 `using` 指令（即使脚本中未显式声明），以便更方便地完成常见任务： +By default, Tabular Editor applies the following `using` keyword (even though they are not specified in the script), to make common tasks easier: ```csharp using System; @@ -279,7 +281,7 @@ using TabularEditor.TOMWrapper.Utils; using TabularEditor.UI; ``` -此外，默认还会加载以下 .NET Framework 程序集： +In addition, the following .NET Framework assemblies are loaded by default: - System.Dll - System.Core.Dll @@ -293,13 +295,13 @@ using TabularEditor.UI; -## 访问环境变量 +## Accessing Environment Variables -通过 Tabular Editor CLI 运行 C# Script 时（尤其是在 CI/CD 流水线中），可以使用环境变量向脚本传递参数。 这是推荐的做法，因为 Tabular Editor CLI 执行的 C# Script 不支持传统的命令行参数。 +通过 Tabular Editor CLI 运行 C# Script 时（尤其是在 CI/CD 流水线中），可以使用环境变量向脚本传递参数。 This is the recommended approach, as C# scripts executed by Tabular Editor CLI don't support traditional command-line arguments. -### 读取环境变量 +### Reading Environment Variables -在脚本中使用 `Environment.GetEnvironmentVariable()` 方法读取环境变量： +Use the `Environment.GetEnvironmentVariable()` method to read environment variables in your script: ```csharp // Read environment variables @@ -320,11 +322,11 @@ foreach(var dataSource in Model.DataSources.OfType()) Info($"Updated connection strings for {environment} environment"); ``` -### Azure DevOps 集成 +### Azure DevOps Integration -环境变量可与 Azure DevOps 流水线无缝集成，因为默认情况下，所有流水线变量都会自动作为环境变量提供。 +Environment variables integrate seamlessly with Azure DevOps pipelines, as all pipeline variables are automatically available as environment variables by default. -**Azure DevOps YAML 流水线示例：** +**Example Azure DevOps YAML Pipeline:** ```yaml variables: @@ -343,80 +345,89 @@ steps: TabularEditor.exe "Model.bim" -S "DeploymentScript.csx" -D "$(targetServer)" "$(targetDatabase)" -O -V -E -W ``` -在此示例中，脚本 `DeploymentScript.csx` 可以通过 `Environment.GetEnvironmentVariable()` 访问 `SERVER_NAME` 和 `DATABASE_NAME`。 +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: -- **动态连接字符串**：根据部署环境（Dev、UAT、Production）更新数据源连接 -- **条件逻辑**：根据目标环境应用不同的转换 -- **部署配置**：基于参数控制要部署或修改的对象 -- **多环境支持**：在不同环境中复用同一脚本，只需使用不同的值 +- **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($"已为 {environment} 环境配置模型"); +Info($"Configured model for {environment} environment"); ``` -## 兼容性 +## Compatibility -Tabular Editor 2 和 Tabular Editor 3 的脚本 API 大多兼容，但在某些情况下，你可能希望根据所使用的版本对代码进行条件编译。 为此，你可以使用预处理器指令，这些指令是在 Tabular Editor 3.10.0 中引入的。 +The scripting APIs for Tabular Editor 2, Tabular Editor 3 (Desktop), and the Tabular Editor CLI are mostly compatible, but there are cases where you want to conditionally compile code depending on which host is running. The CLI host defines a `TECLI` preprocessor symbol; TE3 Desktop defines `TE3` (and version-bracketed symbols like `TE3_3_15_OR_GREATER` for the active minor); TE2 defines neither. Preprocessor directives were introduced in Tabular Editor 3.10.0. Use them to write portable scripts: ```csharp -#if TE3 - // 仅当脚本在 TE3（版本 3.10.0 或更高）中运行时才会编译此代码。 - Info("Hello from TE3!"); +#if TECLI + // CLI host - no UI APIs available + Info($"Running under the CLI on {Environment.OSVersion.Platform}"); +#elif TE3 + // TE3 Desktop - UI APIs are available + ShowMessage("Hello from TE3"); #else - // 在其他所有情况下都会编译此代码。 - Info("Hello from TE2!"); + // TE2 (legacy) - neither TECLI nor TE3 is defined + Info("Hello from TE2"); +#endif + +#if TE3_3_15_OR_GREATER + // Gated on a specific TE3 minor version #endif ``` -如果你想在脚本运行时知道 Tabular Editor 的具体版本，可以查看程序集版本： +One CLI-specific caveat: the TE3-Desktop UI helpers `SelectMeasure()`, `SelectTable()`, `SelectColumn()`, `SelectObject()`, and `SelectObjects()` throw `NotSupportedException` under `te script` since the CLI has no UI to pop up. Wrap such calls in `#if TE3` (or `try/catch`) when sharing scripts across hosts. + +If you need to know the exact version of Tabular Editor at script runtime, you can inspect the assembly version: ```csharp var currentVersion = typeof(Model).Assembly.GetName().Version; Info(currentVersion.ToString()); ``` -公开的产品版本号（例如 "2.20.2" 或 "3.10.1"）可以通过以下代码获取： +The public product version (for example, "2.20.2" or "3.10.1") can be found using this code: ```csharp using System.Diagnostics; var productVersion = FileVersionInfo.GetVersionInfo(Selected.GetType().Assembly.Location).ProductVersion; -productVersion.Output(); // productVersion 是一个字符串（例如 "2.20.2" 或 "3.10.1"） +productVersion.Output(); // productVersion is a string ("2.20.2" or "3.10.1", for example) ``` -如果你只想要主版本号（整数），可以用： +If you just want the major version number (as an integer), use: ```csharp var majorVersion = Selected.GetType().Assembly.GetName().Version.Major; majorVersion.Output(); // majorVersion is an integer (2 or 3) ``` -## 已知问题与限制 +## Known issues and limitations -- 由于脚本的执行方式，某些脚本操作可能导致 Tabular Editor 3 应用程序崩溃或无响应。 例如，包含无限循环（`while(true) {}`）的脚本会导致应用程序卡死。 如果出现这种情况，你需要通过 Windows 任务管理器结束 Tabular Editor 进程。 +- Certain script operations may cause the Tabular Editor 3 application to crash or become unresponsive, due to the way scripts are executed. For example, a script with an infinite loop (`while(true) {}`) will cause the application to hang. If this happens, you will have to end the Tabular Editor process through the Windows Task Manager. -如果你打算将脚本保存为[宏](xref:creating-macros)，请注意以下限制： +If you intend to save the script as a [macro](xref:creating-macros), please be aware of the following limitations: -- 如果脚本主体包含带访问修饰符（`public`、`static` 等）的本地方法，则无法将该脚本保存为宏。 删除这些访问修饰符，或改为将该方法移到一个类中。 -- 目前宏不支持在脚本主体中使用 `await` 关键字。 如果脚本主体调用了异步方法，应使用 `MyAsyncMethod.Wait()` 或 `MyAsyncMethod.Result`，而不是 `await MyAsyncMethod()`。 在脚本中其他位置定义的 `async` 方法里使用 `await` 是可以的。 \ No newline at end of file +- If the script body contains local methods with access modifiers (`public`, `static`, etc.), the script cannot be saved as a macro. Remove the access modifiers, or move the method into a class instead. +- Macros currently do not support the `await` keyword, if used in the script body. If your script body calls into asynchronous methods, you should use `MyAsyncMethod.Wait()` or `MyAsyncMethod.Result` instead of `await MyAsyncMethod()`. It is fine to use `await` in `async` methods that are defined elsewhere in the script. \ No newline at end of file diff --git a/localizedContent/zh/content/features/dax-package-manager.md b/localizedContent/zh/content/features/dax-package-manager.md index d46e2f072..e84eca176 100644 --- a/localizedContent/zh/content/features/dax-package-manager.md +++ b/localizedContent/zh/content/features/dax-package-manager.md @@ -21,15 +21,15 @@ applies_to: ## 概述 -Tabular Editor 中的 **DAX 组件管理器**（DPM）使用户能够直接在应用内轻松发现、安装、更新并管理 [DAX 用户自定义函数（UDF）](xref:udfs) 库（称为 DAX 组件）。 -这些库通过可重用函数扩展你的 DAX 功能，让你更容易构建一致且易于维护的 Power BI 语义模型。 +Tabular Editor 中的 **DAX 组件管理器**（DPM）使用户能够直接在应用程序内轻松发现、安装、更新并管理 [DAX 用户自定义函数（UDF）](xref:udfs) 库（称为 DAX 组件）。 +这些库通过可重用函数扩展了你的 DAX 能力，让你更轻松地构建一致且易于维护的 Power BI 语义模型。 -顾名思义，该功能的工作方式类似于 NuGet 或 npm 等组件管理器，用于帮助开发者管理代码库。 DAX 组件来源于 https://daxlib.org，这是由 [SQLBI](https://sqlbi.com) 创建的开源非营利项目。 +顾名思义，这项功能相当于一个组件管理器，其工作方式类似 NuGet 或 npm 为开发者管理代码库。 DAX 组件的来源是 https://daxlib.org，这是由 [SQLBI](https://sqlbi.com) 发起并维护的开源非营利项目。 -只要模型支持 DAX 用户自定义函数，你就可以使用 DAX 组件管理器；也就是说，模型的兼容级别必须为 1702 或更高。 +你可以在任何支持 DAX 用户自定义函数的模型中使用 DAX 组件管理器，也就是说，模型的兼容级别必须为 1702 或更高。 > [!WARNING] -> DAX 用户自定义函数目前（截至 2025 年十一月）是 Power BI 的预览功能。 使用前请先了解其[限制](https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions#considerations-and-limitations)。 +> DAX 用户自定义函数目前（截至 2025 年十一月）仍是 Power BI 的一项预览功能。 使用前请先了解相关[限制](https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions#considerations-and-limitations)。 --- @@ -37,94 +37,94 @@ Tabular Editor 中的 **DAX 组件管理器**（DPM）使用户能够直接在 ## 界面布局 -### 1。 启动 DAX 组件管理器 +### 1. 启动 DAX 组件管理器 -你可以通过 **视图** 菜单打开 DPM 面板。 你也可以通过 **工具 > 偏好 > 键盘** 为 `View.DaxPackageManager` 命令分配自定义快捷键。 +你可以通过 **视图** 菜单打开 DPM 面板。 你也可以通过 **Tools > Preferences > Keyboard** 为 `View.DaxPackageManager` 命令分配自定义快捷键。 - **菜单：** `视图 → DAX 组件管理器` - **快捷键：** _(如果已在偏好设置中分配)_ --- -### 2。 组件列表 +### 2. 组件列表 -在屏幕左侧，你会看到以下三个选项卡。 每个选项卡旁都会显示一个与该选项卡相关的组件列表： +在屏幕左侧，你会看到以下三个选项卡。 每个选项卡都对应一个相关的组件列表： -| 选项卡 | 说明 | -| ------- | ----------------------------------------------------------- | -| **浏览** | 从提供方 (例如 `api.daxlib.org`) 发现可用的 DAX 组件。 | -| **已安装** | 查看当前已安装的所有组件及其版本。 | -| **更新** | 查看有可用新版本的组件。 | +| 选项卡 | 说明 | +| ------- | --------------------------------------- | +| **浏览** | 从提供程序（例如 `api.daxlib.org`）发现可用的 DAX 组件。 | +| **已安装** | 查看当前已安装的所有组件及其版本。 | +| **更新** | 查看有可用新版本的组件。 | -每个组件条目包含： +每个组件条目都包括： -- **名称和简短说明** +- **名称及简短描述** - **版本号** - **作者或所有者** - **提供方 URL** -- **安装 / 删除 / 更新按钮** -- **热度指标（下载次数）** +- **安装 / 卸载 / 更新按钮** +- **受欢迎程度指标（下载次数）** --- -### 3。 搜索栏 +### 3. 搜索栏 -输入搜索关键词或组件名称（可输入部分名称），即可筛选列表，仅显示与搜索词匹配的项目。 此功能适用于这三个选项卡，即 **浏览**、**已安装** 和 **更新**。 +输入搜索关键词或组件名称（可输入部分名称），即可将列表筛选为仅显示与搜索条件匹配的项目。 这项功能适用于三个选项卡，即 **浏览**、**已安装** 和 **更新**。 > [!NOTE] -> 我们目前只显示与搜索条件匹配的前 20 个组件。 目前还没有分页功能——将在后续更新中加入。 如果需要浏览所有可用的组件，请前往来源网站，例如 https://daxlib.org。 +> 目前我们只显示符合搜索条件的前 20 个组件。 目前还不支持分页；此功能将在后续更新中提供。 如果你需要浏览所有可用组件，请前往源站点，例如 https://daxlib.org。 --- -### 4。 组件详情面板 +### 4. 组件详细信息窗格 -选择某个组件后，会显示详细信息： +选择某个组件后，会显示以下详细信息： | 字段 | 说明 | | ------------------ | ------------------------------------ | -| **已安装 / 版本** | 当前版本及可用更新信息。 | -| **说明** | 该库提供内容的摘要。 | -| **发布说明** | 关于最新版本中新功能或变更的信息。 | +| **已安装 / 版本** | 当前版本以及可用更新。 | +| **说明** | 对该库所提供内容的概述。 | +| **发布说明** | 有关最新版本中新功能或变更的信息。 | | **提供方 / 所有者 / 作者** | 署名元数据。 | -| **标签** | 便于分类和搜索。 | +| **标签** | 有助于分类和搜索。 | | **URL** | 项目文档、API 以及 GitHub repository 的直接链接。 | | **发布日期** | 当前版本发布的时间戳。 | | **下载量** | 所有用户的总安装次数。 | -未安装的组件会显示 **“安装”** 按钮。 点击该按钮会立即将该组件中的 UDF 添加到你的模型中。 +尚未安装的组件会显示 **“安装”** 按钮。 单击此按钮会立即将该组件中的 UDF 添加到你的模型中。 已安装的组件会显示 **“移除”** 按钮。 -有新版本可用的组件会显示 **“更新”** 按钮。 +有较新版本可用的组件会显示 **“更新”** 按钮。 > [!WARNING] -> 如果你移除或更新某个组件，而你曾修改过其中一个或多个 UDF 的 DAX 表达式，你会看到一条警告信息，提示这些更改将会丢失。 +> 如果你移除或更新某个组件，而你已修改过其中一个或多个 UDF 的 DAX 表达式，则会显示警告信息，提示你的更改将丢失。 --- -### 5。 更新通知 +### 5. 更新通知 -打开使用了有可用更新的组件的模型时，你会在 **TOM Explorer** 底部看到更新通知。 +当你打开使用了某个有更新可用的组件的模型时，会在 **TOM Explorer** 底部看到更新通知。 -点击更新通知，或打开 DAX 组件管理器视图，即可查看并安装更新。 +单击更新通知，或打开 DAX 组件管理器视图，查看并安装更新。 --- ## 安装组件 1. 打开 **DAX 组件管理器**。 -2. 在 **浏览** 选项卡中，选择一个组件（例如 `DaxLib.SVG`）。 按需使用搜索栏缩小搜索范围。 -3. 点击 **安装**。 -4. 安装完成后，该组件及其函数会显示在 TOM Explorer 中。 +2. 在 **浏览** 选项卡中，选择一个组件（例如 `DaxLib.SVG`）。 按需使用搜索栏进一步筛选结果。 +3. 单击 **安装**。 +4. 安装完成后，该组件及其函数将显示在 TOM Explorer 中。 -你也可以在安装前选择特定的 **版本**——这对回归测试或确保与旧模型兼容很有用。 +安装前还可以选择特定 **版本**，这对于回归测试或确保与旧模型兼容很有帮助。 --- ## 更新组件 -1. 前往 **更新** 选项卡，或选择一个有新版本可用的组件。 -2. 点击 **全部更新** 以更新所有已安装的组件，或对某个组件点击 **更新**。 +1. 转到 **更新** 选项卡，或选择一个有较新版本可用的组件。 +2. 单击 **全部更新** 以更新所有已安装的组件，或对某个组件单击 **更新**。 3. DPM 会获取最新定义，并自动替换现有函数。 --- @@ -132,71 +132,71 @@ Tabular Editor 中的 **DAX 组件管理器**（DPM）使用户能够直接在 ## 移除组件 1. 转到 **已安装** 选项卡。 -2. 选择你要移除的组件。 +2. 选择要移除的组件。 3. 点击 **移除**。 所有关联的 UDF 都将从模型中移除。 > [!CAUTION] -> 移除 UDF 可能会导致模型中其他位置（度量值、计算列等）的 DAX 表达式 变得无效。 如果发生这种情况，你随时可以按 **撤销**（Ctrl+Z）来撤销移除组件的操作。 在移除组件之前，你可以使用 **显示依赖项**（Shift+F12）功能来查看这些 UDF 在哪些地方被使用。 +> 移除 UDF 可能会导致模型中其他区域（度量值、计算列等）中的 DAX 表达式 变得无效。 如果发生这种情况，你随时可以点击 **撤销**（Ctrl+Z）来撤销移除组件的操作。 在移除组件之前，请先使用 **显示依赖关系**（Shift+F12）功能确定这些 UDF 的使用位置。 --- ## 技术注意事项 -DAX 组件管理器使用 [扩展属性](https://learn.microsoft.com/en-us/dotnet/api/microsoft.analysisservices.tabular.extendedproperty?view=analysisservices-dotnet) 来跟踪已安装的组件。 扩展属性类似于注释，但更适合以 JSON 格式存储自定义元数据。 +DAX Package Manager 使用 [扩展属性](https://learn.microsoft.com/en-us/dotnet/api/microsoft.analysisservices.tabular.extendedproperty?view=analysisservices-dotnet) 来跟踪已安装的组件。 扩展属性与批注类似，但更适合以 JSON 格式存储自定义元数据。 -DAX 组件管理器会在 **Model** 对象上创建以下扩展属性： +DAX Package Manager 会在 **模型** 对象上创建以下扩展属性： -| 属性名称 | 说明 | -| -------------------------------- | -------------------------------------------------------------------- | -| `TabularEditor_ModelDaxPkgTable` | 一个 JSON 字典，每个已安装的组件对应一个条目。 键是按顺序递增的整数，而值包含组件提供方、提供方内的组件 ID，以及组件版本信息。 | -| `TabularEditor_ModelDaxPkgSeq` | 一个整数值，每安装一个组件就会递增。 用于为 `TabularEditor_ModelDaxPkgTable` 属性生成唯一键。 | +| 属性名称 | 说明 | +| -------------------------------- | ------------------------------------------------------------------------ | +| `TabularEditor_ModelDaxPkgTable` | 一个 JSON 字典，每个已安装的组件对应一个条目。 键为按顺序递增的整数；值则包含组件提供程序、该提供程序中的组件 ID 以及组件版本等信息。 | +| `TabularEditor_ModelDaxPkgSeq` | 一个整数值，每次安装组件时都会递增。 这用于为 `TabularEditor_ModelDaxPkgTable` 属性生成唯一键。 | -此外，通过 DAX 组件管理器导入的每个 UDF 都会被赋予以下扩展属性： +此外，通过 DAX Package Manager 导入的每个 UDF 都会被赋予以下扩展属性： -| 属性名称 | 说明 | -| ------------------------------------ | ---------------------------------------------------------------------------------------- | -| `TabularEditor_ObjDaxPkgHandle` | 一个整数值，对应模型上 `TabularEditor_ModelDaxPkgTable` 属性中的键。 这使 Tabular Editor 能够识别某个 UDF 属于哪个组件。 | -| `TabularEditor_ObjDaxPkgContentHash` | 一个哈希值，在安装时根据该 UDF 的 DAX 表达式计算得出。 用于检测 UDF 自安装以来是否被修改——这在更新或移除组件时很重要。 | +| 属性名称 | 说明 | +| ------------------------------------ | ----------------------------------------------------------------------------------------- | +| `TabularEditor_ObjDaxPkgHandle` | 一个整数值，对应于模型上 `TabularEditor_ModelDaxPkgTable` 属性中的键。 这使 Tabular Editor 能够识别某个 UDF 属于哪个组件。 | +| `TabularEditor_ObjDaxPkgContentHash` | 在安装时根据 UDF 的 DAX 表达式计算出的哈希值。 它用于检测 UDF 自安装以来是否被修改过，这在更新或移除组件时非常重要。 | > [!CAUTION] -> 手动修改或删除这些扩展属性可能会导致 DAX 组件管理器出现意外行为。 +> 手动修改或删除这些扩展属性可能会导致 DAX 组件管理器出现异常行为。 ## 处理冲突 -### 修改从组件导入的 UDF +### 修改来自组件的 UDF -如果你修改了从 DAX 组件导入的 UDF 的 DAX 表达式，那么在升级或卸载该组件时，你会看到以下提示： +如果你修改了从 DAX 组件导入的 UDF 的 DAX 表达式，那么在升级或移除该组件时会看到以下提示： ![更新已修改的 UDF](~/content/assets/images/dax-package-manager-update-modified.png) 你有以下选项： -- **是**：将继续更新，并使用 DAX 组件管理器源中的定义覆盖你对该 UDF 所做的更改。 -- **否**：更新将继续进行，但已修改的 UDF(s) 将保持不变；如果此次组件更新包含破坏性更改，可能会引发问题。 +- **是**：将继续更新，并用 DAX 组件管理器源中提供的定义覆盖你对 UDF 所做的更改。 +- **否**：将继续更新，但已修改的 UDF(s) 将保持不变；如果此次组件更新包含破坏性更改，可能会引发问题。 - **取消**：取消更新。 > [!TIP] -> 如果你想将现有 UDF 与 DAX 组件管理器“取消关联”，请从 UDF 对象中删除扩展属性 `TabularEditor_ObjDaxPkgHandle` 和 `TabularEditor_ObjDaxPkgContentHash`。 这样一来，DAX 组件管理器将不再跟踪这些 UDF，它们也不会受到后续组件更新或卸载的影响。 不过，你仍需要留意名称冲突。 +> 如果你想让现有 UDF 与 DAX 组件管理器“取消关联”，请从 UDF 对象中移除扩展属性 `TabularEditor_ObjDaxPkgHandle` 和 `TabularEditor_ObjDaxPkgContentHash`。 这样一来，DAX 组件管理器将不再跟踪这些 UDF，它们也不会受到后续组件更新或移除的影响。 不过，你仍然需要注意名称冲突。 ### 安装存在名称冲突的组件 -如果你尝试安装的组件中包含一个与模型中现有 UDF 同名的 UDF（无论该现有 UDF 是从其他组件导入还是手动创建的），你会看到以下提示： +如果你尝试安装的组件中包含某个 UDF，其名称与模型中现有 UDF 相同（无论该 UDF 是从其他组件导入的还是手动创建的），你会看到以下提示： -![安装组件名称冲突](~/content/assets/images/dax-package-manager-install-conflict.png) +![安装组件时的名称冲突](~/content/assets/images/dax-package-manager-install-conflict.png) 你有以下选项： -- **是**：将继续安装，且组件中的 UDF 会覆盖模型中的现有 UDF。 -- **否**：安装将继续进行，但将跳过组件中存在冲突的 UDF(s)。 +- **是**：将继续安装，组件中的 UDF 会覆盖模型中现有的 UDF。 +- **否**：将继续安装，但会跳过组件中存在冲突的 UDF(s)。 - **取消**：取消安装。 --- -## 更多资源 +## 补充资源 -- [DaxLib 项目站点](https://daxlib.org) +- [DaxLib 项目网站](https://daxlib.org) - [DaxLib GitHub repository](https://github.com/daxlib/daxlib) - [DAX 用户自定义函数（Microsoft Learn）](https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions) - [Tabular Editor 3 中的用户自定义函数](xref:udfs) diff --git a/localizedContent/zh/content/features/pivot-grid.md b/localizedContent/zh/content/features/pivot-grid.md index 35382b59a..8d69ceb23 100644 --- a/localizedContent/zh/content/features/pivot-grid.md +++ b/localizedContent/zh/content/features/pivot-grid.md @@ -2,7 +2,7 @@ uid: pivot-grid title: Pivot Grid author: Daniel Otykier -updated: 2024-05-28 +updated: 2026-05-27 applies_to: products: - product: Tabular Editor 2 @@ -20,49 +20,49 @@ applies_to: # Pivot Grid > [!NOTE] -> 本文信息适用于 Tabular Editor 3.16.0 或更高版本。 请确保你使用的是最新版本的 Tabular Editor 3，以便充分利用新增功能和改进。 +> 本文中的信息适用于 Tabular Editor 3.16.0 或更高版本。 请确保你使用的是最新版本的 Tabular Editor 3，以充分利用新功能和各项改进。 -在开发语义模型时，你经常需要测试 DAX 表达式是否返回了预期值。 传统上，这通常通过 Excel 或 Power BI 等客户端工具来完成。 在 Tabular Editor 3 中，你可以使用 **Pivot Grids**，其行为与 Excel 中广为人知的 PivotTables 非常相似。 Pivot Grid 可让你快速创建模型数据的汇总视图，从而在对不同列和层级进行筛选与切片时，测试 DAX 度量值的行为。 +在开发语义模型时，你可能经常需要测试 DAX 表达式是否返回预期的值。 传统上，这通常是借助 Excel 或 Power BI 等客户端工具来完成的。 在 Tabular Editor 3 中，你可以使用 **Pivot Grid**，其行为与 Excel 中广为人知的数据透视表非常相似。 Pivot Grid 可让你快速为模型中的数据创建汇总视图，从而在按不同列和层次结构进行筛选与切片时，测试 DAX 度量值的表现。 ![Pivot Grid 示例](~/content/assets/images/pivot-grid-example.png) -上面的截图展示了一个 Pivot Grid，其中包含两个度量值 `[Total Net Order Value]` 和 `[Net Orders]`：横向按 Year 切片，并筛选到 2021 和 2022；纵向按 Product Hierarchy 切片。 Tabular Editor 3 用户可以使用此功能，确保度量值背后的 DAX 表达式按预期工作，并快速验证模型中的数据。 +上面的屏幕截图展示了一个 Pivot Grid，其中包含两个度量值 `[Total Net Order Value]` 和 `[Net Orders]`；它在水平方向按 Year 进行切片，并筛选为 2021 和 2022；在垂直方向按 Product Hierarchy 进行切片。 Tabular Editor 3 用户可以使用此功能来确保度量值背后的 DAX 表达式按预期工作，并快速验证模型中的数据。 -默认情况下，每次你保存对语义模型的更改（Ctrl+S）时，Pivot Grid 都会自动更新。 因此，你可以快速迭代 DAX 表达式并在 Pivot Grid 中查看结果：修改度量值并保存模型后，无需等待模型刷新，Pivot Grid 会立即反映新的度量值定义。 一个不错的工作流是：在单独的窗口中打开 Pivot Grid，同时在 **表达式编辑器** 中编写 DAX 表达式，或使用 **DAX脚本**。 +默认情况下，每次保存对语义模型的更改时（Ctrl+S），Pivot Grid 都会自动更新。 因此，你可以快速迭代 DAX 表达式并在 Pivot Grid 中查看结果：只需修改度量值并保存模型，无需等待模型刷新，Pivot Grid 就会立即反映新的度量值定义。 一个不错的工作流是：在 **表达式编辑器** 中编写 DAX 表达式或使用 **DAX脚本** 时，将 Pivot Grid 在单独的窗口中打开。 > [!TIP] -> 关于术语的一些说明： +> 关于术语，这里做几点说明： > -> - **Fields** 指模型度量值、KPI、列和层级。 换句话说，就是任何可以拖到 Pivot Grid 里的内容。 -> - **KPIs** 是一种特殊的度量值类型，可在 Tabular Editor 中创建。 它们在 Pivot Grid 中的显示方式与度量值相同，但会带有一个特殊图标，用于标明它们是 KPI。 每个 KPI 最多可包含 3 个不同的值（目标、趋势和状态），并在 Pivot Grid 中分别显示。 -> - Pivot Grid 中的**列**（例如术语“Column Area”中的列）不要与模型中的列混为一谈。 在 Pivot Grid 中，列用于按水平方向切分数据，而行用于按垂直方向切分数据。 -> - Pivot Grid 中的**单元格**是行与列交叉处的单个数据点。 每个单元格仅包含一个值。该值是在由 _Row Area_ 和 _Column Area_ 中的值所产生的筛选语境下，并结合对 _Filter Area_ 中各字段应用的任何筛选条件，对特定度量值的 DAX 表达式求值得到的结果。 +> - **字段** 指的是模型中的度量值、KPI、列和层次结构。 换句话说，就是任何可以拖入 Pivot Grid 的内容。 +> - **KPI** 是一种可在 Tabular Editor 中创建的特殊度量值。 它们在 Pivot Grid 中的显示方式与度量值相同，但会带有特殊图标，以表明它们是 KPI。 每个 KPI 最多可以有 3 个不同的值（目标、趋势和状态），它们会在 Pivot Grid 中分别显示。 +> - Pivot Grid 中的 **列**（例如术语“列区域”中的“列”）不要与模型中的列混淆。 在 Pivot Grid 中，列用于在水平方向切分数据，而行用于在垂直方向切分数据。 +> - Pivot Grid 中的 **单元格** 是行与列交叉处的单个数据点。 每个单元格都包含一个值。该值是特定度量值的 DAX 表达式在由 _行区域_ 和 _列区域_ 中的值所产生的筛选语境下，并结合应用于 _筛选区域_ 中字段的任何筛选条件计算得到的结果。 > [!NOTE] -> 具有多维模型背景的开发者可能更熟悉 _Dimensions_ 和 _Attributes_ 这两个术语。 在语义模型中，_Dimensions_ 由模型_表_表示，而 _Attributes_ 由模型_列_表示。 语义模型中的 _Hierarchies_ 只是将多列分组在一起的一种方式，例如日历层次结构：Year > Quarter > Month > Day。 在多维模型中，这类层次结构过去称为 _Attribute Hierarchies_ 或 _User-Defined Hierarchies_。 +> 有多维背景的开发人员可能会更熟悉 _Dimensions_ 和 _Attributes_ 这两个术语。 在语义模型中，_Dimensions_ 由模型 _表_ 表示，而 _Attributes_ 由模型 _列_ 表示。 语义模型中的_层次结构_只是将列归为一组的一种方式，例如日历层次结构：年 > 季度 > 月 > 日。 在多维模型中，这类层次结构过去称为_属性层次结构_或_用户定义的层次结构_。 ## 创建 Pivot Grid -你可以通过菜单选项 **File > New > New Pivot Grid** 创建一个新的空 Pivot Grid。 或者，在 **TOM Explorer** 中选择一个或多个度量值，右键点击或打开 **度量值** 菜单并选择 **Add to Pivot Grid**，即可创建一个包含所选度量值的新 Pivot Grid。 +你可以通过 **文件 > 新建 > 新建 Pivot Grid** 菜单创建一个新的空 Pivot Grid。 或者，在 **TOM Explorer** 中选择一个或多个度量值，右键单击，或转到 **度量值** 菜单并选择 **添加到 Pivot Grid**，以创建一个包含所选度量值的新 Pivot Grid。 -![从 TOM Explorer 创建 Pivot Grid](~/content/assets/images/create-pivot-grid-from-TOM-Explorer.png) +![通过 TOM Explorer 创建 Pivot Grid](~/content/assets/images/create-pivot-grid-from-TOM-Explorer.png) -你可以按需创建任意数量的 Pivot Grid。 +你可以根据需要创建任意数量的 Pivot Grid。 > [!IMPORTANT] -> 仅当 Tabular Editor 3 连接到 Analysis Services 实例或 Power BI / Fabric XMLA endpoint 时，才能创建 Pivot Grid。 +> 只有当 Tabular Editor 3 连接到 Analysis Services 实例或 Power BI / Fabric XMLA endpoint 时，才会显示用于创建 Pivot Grid 的选项。 ## Pivot Grid 布局 -Pivot Grid 分为 4 个区域：**Filter Area**、**Column Area**、**Row Area** 和 **Data Area**。 你可以将字段从 **字段列表** 或 **TOM Explorer** 拖入这些区域，来创建 Pivot Grid 布局。 **Data Area** 用于放置度量值或 KPI；**Row Area** 和 **Column Area** 用于按层次结构和列切分数据。 **Filter Area** 用于根据列或层次结构中的值筛选数据。 +Pivot Grid 分为 4 个区域：**筛选区域**、**列区域**、**行区域**和**数据区域**。 你可以将 **字段列表** 或 **TOM Explorer** 中的字段拖到这些区域中，以创建 Pivot Grid 布局。 **数据区域**用于放置度量值或 KPI，而 **行区域** 和 **列区域** 用于按层次结构和列对数据进行切片。 **筛选区域**用于根据列或层次结构中的值筛选数据。 -![突出显示的空 Pivot Grid](~/content/assets/images/empty-pivot-grid-highlighted.png) +![高亮显示的空白 Pivot Grid](~/content/assets/images/empty-pivot-grid-highlighted.png) -上图展示了一个空的 Pivot Grid 布局。 字段列表底部的 4 个空框分别代表 Pivot Grid 的 4 个区域。 你可以将字段从字段列表拖到这些列表框中，以创建 Pivot Grid 的布局。 或者，你也可以直接将字段拖到 Pivot Grid 中。 +上面的屏幕截图显示了一个空白的 Pivot Grid 布局。 字段列表底部的 4 个空框表示 Pivot Grid 的 4 个区域。 你可以将字段从字段列表拖到这些列表框中，以创建 Pivot Grid 布局。 或者，你也可以将字段直接拖到 Pivot Grid 中。 ## Pivot Grid 菜单和工具栏 -默认情况下，在 Tabular Editor 3 中，只要 Pivot Grid 是活动窗口，就会显示 **Pivot Grid** 菜单和工具栏。 这个菜单包含与工具栏相同的操作。 +默认情况下，当 Pivot Grid 是 Tabular Editor 3 中的活动窗口时，会显示 **Pivot Grid** 菜单和工具栏。 该菜单包含与工具栏相同的操作。 ![Pivot Grid 工具栏](~/content/assets/images/pivot-grid-toolbar.png) @@ -70,33 +70,33 @@ Pivot Grid 分为 4 个区域：**Filter Area**、**Column Area**、**Row Area** 这些操作包括： -- **模拟身份...**：显示一个对话框，允许你在 Pivot Grid 中指定要模拟的角色或用户。 当你希望测试模型在不同用户或角色下的行为时，这会很有用，例如模型已应用了 [RLS 或 OLS](xref:data-security-about) 的情况。 -- **刷新**：重新执行 Pivot Grid 生成的查询。 当禁用自动刷新时，或在 Tabular Editor 3 之外对模型进行了更改时，这会很有用。 -- **自动刷新**：开启/关闭自动刷新。 启用自动刷新后，每次保存对模型的更改，或当某个 [数据刷新操作](xref:data-refresh-view) 完成时，Pivot Grid 都会自动刷新。 +- **身份模拟...**：显示一个对话框，可让你指定要在 Pivot Grid 中模拟的角色或用户。 当你想测试模型在不同用户或角色下的行为时，例如在模型已应用 [RLS 或 OLS](xref:data-security-about) 的情况下，这会很有用。 +- **刷新**：重新执行由 Pivot Grid 生成的查询。 在禁用自动刷新时，或在 Tabular Editor 3 之外对模型进行了更改时，这会很有用。 +- **自动刷新**：打开或关闭自动刷新。 启用自动刷新后，每次你保存对模型的更改，或某个 [数据刷新操作](xref:data-refresh-view) 完成时，Pivot Grid 都会自动刷新。 - **清除筛选器**：清除 Pivot Grid 中的所有筛选器。 - **清除**：从 Pivot Grid 中移除所有字段。 -- **在列中显示空值**：切换是否在 Pivot Grid 中显示空值，适用于添加到 Pivot Grid 列区域的字段。 -- **在行中显示空值**：切换是否在 Pivot Grid 中显示空值，适用于添加到 Pivot Grid 行区域的字段。 -- **字段列表**：切换字段列表显示/隐藏。 +- **在列中显示空值**：切换是否要在 Pivot Grid 中显示空值，适用于已添加到 Pivot Grid 列区域的字段。 +- **在行中显示空值**：切换是否要在 Pivot Grid 中显示空值，适用于已添加到 Pivot Grid 行区域的字段。 +- **字段列表**：显示或隐藏字段列表。 ## 字段列表 -默认情况下，字段列表显示在 Pivot Grid 的右侧。 字段列表包含模型中所有可用字段（度量值、KPI、列和层级结构）。 你可以将字段从字段列表拖到 Pivot Grid 中以创建布局。 你还可以在 Pivot Grid 的不同区域之间拖动字段，以重新排列布局。 +默认情况下，字段列表显示在 Pivot Grid 的右侧。 字段列表包含模型中所有可用字段（度量值、KPI、列和层次结构）。 你可以将字段从字段列表拖到 Pivot Grid 中，以创建布局。 你也可以在 Pivot Grid 的不同区域之间拖动字段，以重新排列布局。 -字段列表可以停靠在 Pivot Grid 的左侧、右侧、上方或下方；也可以隐藏；或取消停靠，以独立窗口“浮动”显示。 如果你同时打开了多个 Pivot Grid，每个 Pivot Grid 都有自己的字段列表。 +字段列表本身可以停靠在 Pivot Grid 的左侧或右侧、上方或下方，也可以隐藏，或者取消停靠，使其作为单独窗口“浮动”显示。 如果你同时打开了多个 Pivot Grid，每个 Pivot Grid 都有各自的字段列表。 -如果你希望默认不显示字段列表，请在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 字段列表** 下取消勾选 **始终显示字段列表** 选项。 +如果你不希望默认显示字段列表，请在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 字段列表** 下取消选中 **始终显示字段列表** 选项。 -你可以在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 字段列表 > 布局** 中更改字段列表的默认布局。 你也可以更改任何字段列表的布局：在字段列表的空白处单击右键，然后在快捷菜单中选择所需的布局。 +你可以在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 字段列表 > 布局** 下更改字段列表的默认布局。 你也可以在字段列表的空白区域右键单击，然后从上下文菜单中选择所需布局，以更改任意字段列表的布局。 ![字段列表设置](~/content/assets/images/field-list-settings.png) -默认情况下，你添加到 Pivot Grid 的任何字段都会在字段列表中保持显示。 如果你希望隐藏已添加到 Pivot Grid 的字段，可以在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 字段列表** 下取消勾选 **保持字段可见** 选项（此行为与 Tabular Editor v. 3.16.0 之前的 Pivot Grid 类似）。 +默认情况下，你添加到 Pivot Grid 的任何字段都会在字段列表中保持可见。 如果你希望隐藏已添加到 Pivot Grid 的字段，可以取消选中 **工具 > 偏好 > 数据浏览 > Pivot Grid > 字段列表** 下的 **保持字段可见** 选项（此行为类似于 Tabular Editor v. 3.16.0 之前的 Pivot Grid 工作方式）。 -如果你正在处理大型复杂模型，并且预计 Pivot Grid 中用到的度量值计算会比较慢，你可以勾选字段列表底部的 **延迟更新布局** 选项。 这样可避免 Pivot Grid 在你每次添加或移除字段时都更新布局；如果你打算在更新前对 Pivot Grid 布局做多项修改，这会很有用。 点击 **更新** 按钮，将更改应用到 Pivot Grid。 +如果你正在处理一个大型且复杂的模型，并且预计 Pivot Grid 中使用的度量值计算起来会比较慢，可以勾选字段列表底部的 **延迟布局更新** 选项。 这会阻止 Pivot Grid 在每次添加或移除字段时都更新布局。如果你打算在更新前对 Pivot Grid 布局进行多项更改，这会很有用。 单击 **更新** 按钮，将更改应用到 Pivot Grid。 > [!IMPORTANT] -> 没有属性层次结构（IsAvailableIn MDX = false）的列无法在 Pivot Grid 中使用，也不会显示在字段列表中。 +> 没有属性层次结构的列（IsAvailableIn MDX = false）无法在 Pivot Grid 中使用，也不会显示在字段列表中。 ## 自定义 Pivot Grid @@ -107,63 +107,65 @@ Pivot Grid 分为 4 个区域：**Filter Area**、**Column Area**、**Row Area** **从 TOM Explorer：** - 右键单击一个或多个 _度量值_，然后选择 **添加到 Pivot Grid**。 -- 右键单击 _列_ 或 _层次结构_，然后选择任一 **Add to pivot** 选项（可选择添加到行、列或筛选器）。 -- 如果某个度量值、列或层次结构已经显示在 Pivot Grid 中，右键选项会允许你 **从 Pivot Grid 中移除**。 此外，你还会看到用于在 Pivot Grid 的不同区域之间移动列或层次结构的选项。 -- 当你在 TOM Explorer 中选择了一个或多个此类对象时，上述所有选项也可以分别在 **度量值**、**列** 和 **层次结构** 菜单(分别)中找到。 -- 除了以上方式，你还可以将一个或多个度量值、列或层次结构从 TOM Explorer 拖放到 Pivot Grid 的各个区域。 +- 右键单击某个 _列_ 或 _层次结构_，然后选择任一 **Add to pivot** 选项（可选择添加到行、列或筛选器）。 +- 如果某个度量值、列或层次结构已显示在 Pivot Grid 中，右键菜单中也会显示 **从 Pivot Grid 中移除** 选项。 此外，你还会看到可在 Pivot Grid 不同区域之间移动列或层次结构的选项。 +- 当你在 TOM Explorer 中选择了一个或多个此类对象时，也可以分别通过 **度量值**、**列** 和 **层次结构** 菜单 (分别) 使用上述所有选项。 +- 除了上述方法外，你还可以将一个或多个度量值、列或层次结构从 TOM Explorer 拖放到 Pivot Grid 的各个区域中。 ![通过 TOM Explorer 将层次结构添加到 Pivot Grid](~/content/assets/images/add-through-tom-explorer.png) -**从字段列表中：** +**从字段列表：** -- 将字段从字段列表拖放到 Pivot Grid。 -- 将字段从字段列表拖放到字段列表底部的各个区域列表框中，即可将其添加到 Pivot Grid。 -- 在“字段列表”中右键单击某个字段，即可看到将其添加到 Pivot Grid 的选项。 -- 如果某个字段已显示在 Pivot Grid 中，右键上下文菜单还会提供移除该字段的选项，或将其移动到其他区域（仅列/层级字段）。 -- 双击某个字段会立即将其添加到 Pivot Grid。 度量值/KPI 会添加到“数据区域”，而列和层级字段会添加到“筛选区域”。 +- 将字段从字段列表拖入 Pivot Grid。 +- 将字段从字段列表拖到字段列表底部的各区域列表框中，即可将其添加到 Pivot Grid。 +- 右键单击字段列表中的某个字段，可查看将其添加到 Pivot Grid 的选项。 +- 如果某个字段已显示在 Pivot Grid 中，右键快捷菜单中也会提供移除该字段，或将其移动到其他区域的选项（仅限列/层次结构字段）。 +- 双击某个字段会立即将其添加到 Pivot Grid。 度量值/KPI 会添加到数据区域，而列和层次结构会添加到筛选区域。 ![通过字段列表添加](~/content/assets/images/add-through-field-list.png) ### 调整字段 -将字段添加到 Pivot Grid 后，你可以调整列宽，让内容显示得更合适。 双击列标题分隔线，会自动将列宽调整为适合该列内容的宽度。 你也可以拖动列标题分隔线，手动调整列宽。 最后，你可以在列标题上右键单击，在上下文菜单中使用 **最佳适应** 或 **设置宽度...** 选项。 +将字段添加到 Pivot Grid 后，你可以调整列宽，以便更好地适应其内容。 双击列标题之间的分隔线会自动调整列宽，使其适应该列内容。 你也可以拖动列标题分隔线来手动调整列宽。 最后，你还可以右键单击列标题，在上下文菜单中选择 **最适合** 或 **设置宽度...**。 -![最佳适应列 2](~/content/assets/images/best-fit-columns-2.png) +![最适合列 2](~/content/assets/images/best-fit-columns-2.png) -要同时对 Pivot Grid 中的所有列应用“最佳适应”，或为所有列设置特定的像素宽度，请在“值”标题上右键单击，然后在上下文菜单中选择所需选项。 +若要一次性对 Pivot Grid 中的所有列应用“最适合”或设置指定的像素宽度，请右键单击“值”标题，然后从右键菜单中选择所需选项。 -默认情况下，字段标题会在垂直方向自动扩展，以适应字段名称的内容。 如果你想把字段标题的高度限制为一行，可以在 **工具 > 偏好 > Pivot Grid > 字段标题** 中禁用 **字段标题自动换行** 选项。 +默认情况下，字段标题会在垂直方向自动展开，以容纳字段名称的内容。 如果你希望将字段标题的高度限制为一行，可以在 **工具 > 偏好 > Pivot Grid > 字段标题** 中禁用 **字段标题自动换行** 选项。 -要更改 Pivot Grid 中字段的顺序，你可以在 Pivot Grid 的不同区域之间拖动字段。 你也可以在同一区域内拖动字段来调整顺序。 要从 Pivot Grid 中移除字段，你可以把它拖回“字段列表”，或在该字段上右键单击，然后从上下文菜单中选择 **从 Pivot Grid 中移除**。 +若要更改 Pivot Grid 中字段的顺序，可以在 Pivot Grid 的不同区域之间拖动字段。 你也可以在同一区域内拖动字段来更改其顺序。 若要从 Pivot Grid 中移除字段，可将其拖回“字段列表”，或右键单击该字段，然后在右键菜单中选择 **从 Pivot Grid 中移除**。 -如果你想让度量值显示在行上而不是列上，把“值”字段从“列区域”拖到“行区域”即可。 +如果你希望度量值显示在行而不是列上，请将“值”字段从“列区域”拖到“行区域”。 ### 可视化规则 -你可以为 Pivot Grid 中的单元格添加可视化规则，这有助于根据数值突出显示单元格，例如更容易发现异常值。 要添加可视化规则，在 Pivot Grid 的任意“数据区域”单元格上右键单击，然后从上下文菜单中选择要应用的规则（见下方截图）。 +你可以为 Pivot Grid 中的单元格添加可视化规则，这有助于根据单元格的值突出显示单元格，例如更容易发现异常值。 若要添加可视化规则，请右键单击 Pivot Grid 数据区域中的任意单元格，然后在右键菜单中选择要应用的规则（见下图）。 ![自定义 Pivot Grid](~/content/assets/images/customizing-pivot-grids.png) ## 保存 Pivot Grid 布局 -当你关闭 Pivot Grid 时，Tabular Editor 会提示你保存 Pivot Grid 的布局。 如果你选择保存布局，那么下次打开 Pivot Grid 时，它会恢复到你关闭时的布局。 当 Pivot Grid 窗口处于活动状态时，你也可以按 (Ctrl+S) 或使用 **文件 > 保存** 选项手动保存 Pivot Grid 的布局。 +关闭 Pivot Grid 时，Tabular Editor 会提示你保存该 Pivot Grid 的布局。 如果你选择保存布局，下次打开 Pivot Grid 时，它会恢复到关闭时的相同布局。 当 Pivot Grid 为活动窗口时，你也可以按 (Ctrl+S) 或使用 **文件 > 保存** 选项来手动保存 Pivot Grid 的布局。 -用于保存 Pivot Grid 布局的文件扩展名是 `.te3pivot`。 这是一个简单的 json 文件，用于指定 Pivot Grid 中显示哪些模型对象，以及它们放置在哪些区域。 对象通过名称和 Lineage tag（如有）进行引用，因此即使自保存布局以来模型发生了修改，通常也能恢复 Pivot Grid 布局。 +用于保存 Pivot Grid 布局的文件扩展名是 `.te3pivot`。 这是一个简单的 json 文件，用于指定 Pivot Grid 中显示哪些模型对象，以及它们放置在哪些区域。 对象通过名称和 Lineage tag（如果存在）进行引用，因此即使模型在保存布局后已被修改，Pivot Grid 布局通常仍可恢复。 > [!NOTE] -> 你可以打开在其他模型中创建的 Pivot Grid 布局，不过要注意：该布局中的字段可能在你当前连接的模型中并不存在。 在这种情况下，Pivot Grid 会显示一条警告信息，并将模型中不存在的字段从布局中移除。 你可以在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 如果 Pivot Grid 与模型不匹配则显示警告** 中关闭这条警告信息。 +> 可以打开在其他模型中创建的 Pivot Grid 布局，但请注意，布局中的字段可能在你当前连接的模型中不存在。 在这种情况下，Pivot Grid 会显示警告信息，且模型中不存在的字段会从布局中移除。 你可以在 **工具 > 偏好 > 数据浏览 > Pivot Grid > 如果 Pivot Grid 与模型不匹配则显示警告** 中关闭此警告信息。 ## 其他功能 -Pivot Grid 还有一些值得了解的功能： +Pivot Grid 还有一些值得了解的实用功能： -- 如果你在字段上右键单击，可以选择 **转到** 该字段。 这会将焦点切换到 TOM Explorer，并选中对应的模型对象。 对于度量值和计算列，焦点会切换到 **表达式编辑器**，并显示相应对象的 DAX 表达式。 -- 如果你在 Pivot Grid 的单元格上右键单击，可以选择 **调试此值**。 这将启动 [**DAX Debugger**](xref:dax-debugger)，并以生成该单元格值的特定度量值和筛选语境为起点进行调试。 -- 当 Pivot Grid 正在 **刷新** 时，某些工具栏项会被禁用，上下文菜单操作也会暂时不可用。 +- 如果你右键单击某个字段，可以选择 **转到** 该字段。 这会将焦点切换到 TOM Explorer，并选中对应的模型对象。 对于度量值和计算列，焦点会切换到 **表达式编辑器**，并显示该度量值或列的 DAX 表达式。 +- 如果你右键单击 Pivot Grid 中的某个单元格，可以选择 **调试此值** 选项。 这将启动 [**DAX 调试器**](xref:dax-debugger)，并以生成该单元格值的特定度量值和筛选语境为起点。 +- 当 Pivot Grid 正在**刷新**时，某些工具栏项会被禁用，右键菜单操作也会暂时不可用。 ## 限制与已知问题 -下面列出了 Tabular Editor 3.16.0 中 Pivot Grid 的已知限制与问题，我们正在努力在后续版本中解决： +以下列出了 Tabular Editor 3.16.0 中 Pivot Grid 的已知限制和问题，我们正在后续版本中逐步解决这些问题： -- 格式规则（例如图标集、数据条等） 在将 Pivot Grid 布局保存为 `.te3pivot` 文件时，这些规则无法被正确保留。 -- 如果你在与保存布局时不同的模型上打开 `.te3pivot` 文件，当前模型中不存在的字段会从布局中移除。 按“保存”(Ctrl+S) 会保存该布局，并将已移除的字段也一并从文件中去除。 我们可能会在未来版本中更改此行为，让 `.te3pivot` 文件在你明确确认之前不会被覆盖。 \ No newline at end of file +- 格式规则（如图标集、数据条等） 在将 Pivot Grid 布局保存为 `.te3pivot` 文件时，不会被正确保留。 +- 如果你在与保存该布局时所用模型不同的模型上打开 .te3pivot 文件，当前模型中不存在的字段将从布局中移除。 按下“保存”(Ctrl+S) 后，布局会以移除这些字段后的状态保存。 我们可能会在未来版本中更改此行为，以避免在未明确确认的情况下覆盖 .te3pivot 文件。 +- 使用 **Group By Columns** 属性的列（包括字段参数列）不能单独添加到行区域或列区域。 这样做会产生错误 _“列 X 是复合键的一部分，但表达式或其依赖表达式中并未包含该复合键的所有列”_。 这是 MDX 客户端的通用限制，在 Excel 数据透视表中使用此类列时也会出现相同情况。 要临时解决此问题，请在添加依赖列_之前_，先将相关的 Group By Column 添加到 Pivot Grid。 例如，如果 `[ProductKey]` 被配置为 `[ProductName]` 的 Group By Column，先将 `[ProductKey]` 添加到行区域或列区域，再添加 `[ProductName]`。 +- 对行区域或列区域中的列显式应用升序或降序排序时，无论该列的数据类型如何，值都会按字符串的字典顺序排序。 采用长日期格式的日期（例如“May 4, 2024”）和整数会按字典序排序，而不是按时间顺序或数值大小排序。 这是 MDX 客户端排序方式的限制，连接到该模型的 Excel 数据透视表中也会出现相同的行为。 若要按时间顺序或数值顺序排序，请使用该列的自然排序（不要显式应用排序），或在模型列上使用 **按列排序** 属性，将其指向一个底层值可排序的列。 \ No newline at end of file diff --git a/localizedContent/zh/content/features/semantic-bridge-metric-view-object-model.md b/localizedContent/zh/content/features/semantic-bridge-metric-view-object-model.md index 4b92c9465..a7389e58b 100644 --- a/localizedContent/zh/content/features/semantic-bridge-metric-view-object-model.md +++ b/localizedContent/zh/content/features/semantic-bridge-metric-view-object-model.md @@ -30,17 +30,17 @@ SUMMARY: Overview of the Metric View object model built into the Semantic Bridge > 这里的对象模型明显缺少 TOMWrapper 中提供的许多便捷功能，而这些功能你可能已经在用于操作 Tabular 模型的 C# Script 中用过并熟悉。 > 如[语义桥的限制](xref:semantic-bridge#public-preview-limitations)中所述，我们目前仅支持 Metric View v0.1 的元数据。 -Semantic Bridge 包含一个用于表示 Databricks Metric View 的对象模型。 +Semantic Bridge 包含一个对象模型，用于表示 Databricks Metric View。 这使你可以通过 C# Script 以编程方式处理 Metric View，类似于通过 TOMWrapper 操作 Tabular 模型。 -除 [导入 GUI](xref:semantic-bridge#interface) 外，所有对 Metric View 的访问与交互都需通过 C# Script 进行。 +除 [导入 GUI](xref:semantic-bridge#interface) 之外，对 Metric View 的所有访问与交互都通过 C# Script 完成。 本文档中的所有内容均指你将在 [C# Script](xref:csharp-scripts) 中使用的 C# 代码。 ## 加载并访问 Metric View -你可以使用 [`SemanticBridge.MetricView.Load`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Load_System_String_) 或 [`SemanticBridge.MetricView.Deserialize`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Deserialize_System_String_) 来加载 Metric View。 +你可以通过 [`SemanticBridge.MetricView.Load`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Load_System_String_) 或 [`SemanticBridge.MetricView.Deserialize`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Deserialize_System_String_) 来加载 Metric View。 这会将反序列化后的 Metric View 存储在 [`SemanticBridge.MetricView.Model`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Model) 中。 该属性返回一个 [`View`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.MetricView.View) 对象，它是 Metric View 对象图的根对象。 @@ -53,7 +53,7 @@ var view = SemanticBridge.MetricView.Model; Output($"Metric View version: {view.Version}\r\nSource: {view.Source}"); ``` -与 Tabular 模型类似，但不同于你在 C# Script 中常见的大多数其他对象，Metric View 会在多次脚本执行之间保持持久化。 +与 Tabular 模型类似，但不同于你在 C# Script 中常见的多数其他对象，Metric View 会在多次脚本执行之间保持持久化。 这意味着你只需加载一次指标视图，后续脚本执行时即可引用它，而无需每次都重新加载。 任意时刻只会加载一个指标视图；如上所述，所有脚本都可以通过 `SemanticBridge.MetricView.Model` 访问它。 这种行为类似于 C# Script 中的表格模型，它始终可以直接通过 `Model` 访问。 @@ -71,7 +71,7 @@ Output($"Metric View version: {view.Version}\r\nSource: {view.Source}"); | [`度量值`](xref:TabularEditor.SemanticBridge.Platforms.Databricks.MetricView.Measure) | 表示业务逻辑的聚合定义 | > [!NOTE] -> 在对象模型中，我们遵循 C# 的命名约定，因此对象模型中的所有类型和属性名称都使用 `PascalCase`。 +> 在对象模型中，我们遵循 C# 命名约定，因此对象模型中的所有类型名和属性名均使用 `PascalCase`。 > 指标视图 YAML 规范遵循 `snake_case` 的命名约定。 > 总体而言，我们主要关注作为 Semantic Bridge 组件的 C# 对象模型。 > 除了更改大小写之外，我们不会改变 YAML 中的任何命名约定。 @@ -108,7 +108,7 @@ Output(sb.ToString()); 如果 `Source` 不是一个 3 段式表或视图引用，则会被翻译为一个包含内嵌 SQL 查询的 M 分区，并将整个 `Source` 字符串作为 SQL 查询。 在翻译时会忽略 `Filter` 属性。 -为了评估验证规则，会先检查 `View`，然后按顺序验证各个集合：先是 `Joins`，然后是 `Dimensions`，最后是 `Measures`。 +为评估验证规则，会先检查 `View`，然后按顺序验证各个集合：先是 `Joins`，再是 `Dimensions`，最后是 `Measures`。 事实表 `Source` 的验证是在 `View` 对象的验证规则中完成的。 ### 联接 @@ -140,7 +140,7 @@ Output(sb.ToString()); #### `Join` 翻译与验证 -不支持嵌套的 `Join`，也就是说，只能翻译严格的星型架构。 +不支持嵌套 `Join`，也就是说，只能转换严格的星型架构。 仅支持对使用 `On` 的单字段等值联接进行翻译。 每个 `Join` 都会成为表格模型中的一张表，并且会按照与 `View.Source` 属性相同的规则定义一个 M 分区。 @@ -220,7 +220,7 @@ Output(sb.ToString()); 我们会尝试识别 SQL 表达式中引用的所有字段；如果这些字段尚未作为 Metric View 的 `Dimension` 存在，则将其作为 `DataColumn` 添加到表格模型中。 > [!WARNING] -> SQL 和 DAX 是两种不同的语言，语义也不同。 +> SQL 和 DAX 是不同的语言，语义也不同。 > 自动翻译得到的度量值，可能无法在 Databricks Metric View 和表格模型中表达完全相同的计算逻辑。 > 你需要自己验证所有代码是否按预期工作。 @@ -228,7 +228,7 @@ Output(sb.ToString()); ## Using 指令 -在 C# Script 中使用 Metric View 对象模型时，你可能需要添加 using 指令，以避免与 Tabular Object Model 中名称相同或相近的类型发生命名冲突。 +在 C# Script 中使用 Metric View 对象模型时，你可能需要添加 using 指令，以避免与 Tabular Object Model 中同名或名称相近的类型发生命名冲突。 我们建议为命名空间设置别名： ```csharp diff --git a/localizedContent/zh/content/features/semantic-bridge-metric-view-validation.md b/localizedContent/zh/content/features/semantic-bridge-metric-view-validation.md index 040a232a5..9d4c6c4b9 100644 --- a/localizedContent/zh/content/features/semantic-bridge-metric-view-validation.md +++ b/localizedContent/zh/content/features/semantic-bridge-metric-view-validation.md @@ -41,13 +41,13 @@ SUMMARY: Describes the validation framework for Metric Views in the Semantic Bri 第一阶段和第三阶段是自动的，并且在语义桥内部完成；第二阶段则可以让你提供自己的验证规则。 -验证是一个过程：将一组验证规则逐一应用于 Metric View 中的所有对象，并对其进行评估。 +验证是一个过程：针对 Metric View 中的所有对象，逐一评估一组验证规则。 每条验证规则都只针对一种指标视图对象类型，例如 `Join` 或 `Measure`。 验证完成后，所有由规则违规产生的诊断信息都会返回给你，方便你进行后续处理。 ## 验证规则的构成 -验证规则都是 [`IMetricViewValidationRule`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.Interfaces.IMetricViewValidationRule.html) 的实例。 +所有验证规则都是 [`IMetricViewValidationRule`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.Interfaces.IMetricViewValidationRule.html) 的实例。 与其深入研究那个接口，不如通过这些辅助方法来理解和使用验证规则： - [`MakeValidationRuleForDimension`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService.html#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_MakeValidationRuleForDimension_System_String_System_String_System_String_System_Func_TabularEditor_SemanticBridge_Platforms_Databricks_MetricView_Dimension_System_Boolean__) @@ -56,7 +56,7 @@ SUMMARY: Describes the validation framework for Metric Views in the Semantic Bri - [`MakeValidationRuleForView`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService.html#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_MakeValidationRuleForView_System_String_System_String_System_String_System_Func_TabularEditor_SemanticBridge_Platforms_Databricks_MetricView_View_System_Boolean__) - [`MakeValidationRule`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService.html#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_MakeValidationRule__1_System_String_System_String_System_Func___0_TabularEditor_SemanticBridge_Platforms_Databricks_Validation_IReadOnlyValidationContext_System_Collections_Generic_IEnumerable_TabularEditor_SemanticBridge_Orchestration_DiagnosticMessage___) -前四个都是专门用于为其名称对应的对象类型创建规则的方法。 +前四个都是专用规则，用于为其名称所对应的对象类型创建规则。 它们提供了一个更简化的接口，你只需要提供： - `name`：用于标识该规则的简短唯一名称 @@ -110,7 +110,7 @@ var myRule = SemanticBridge.MetricView.MakeValidationRuleForDimension( Output(SemanticBridge.MetricView.Validate([myRule])); ``` -你可以看到，定义为 Metric View 维度的其中一个字段的名称中带有下划线。 +可以看到，定义为 Metric View 维度的某个字段名称中包含下划线。 运行脚本时，在按照我们定义的规则完成验证后，你会看到一条诊断信息。 你可以查看诊断信息中提供的详细内容： @@ -166,10 +166,10 @@ Output(SemanticBridge.MetricView.Validate([myRule])); 建议创建更多简单规则，而不是更少但更复杂的规则。 验证过程非常轻量，即使规则很多，也无需担心性能问题。 -例如，如果你想确保 Metric View 维度名称不采用 `camelCased`、不采用 `kebab-cased`，也不采用 `snake_cased`，最好分别创建三条规则，而不是试图在一条规则中检查所有这些条件。 +例如，如果你想确保 Metric View 维度名称不是 `camelCased`、不是 `kebab-cased`，也不是 `snake_cased`，最好分别创建三条规则，而不是试图在一条规则中同时检查这些条件。 这样每条规则都能保持简单，信息也会更具体，因此更容易采取相应措施。 -一般来说，一旦某条规则已经能捕获某个特定问题，最好保持不动，而不是去编辑它。 +一般来说，一旦某条规则能够捕获某个特定问题，最好就保持不变，而不是继续编辑它。 如果你发现该规则遗漏了你想捕获的某个条件，只需新增一条小而简单的规则来覆盖这个新条件即可。 你可以在一个 C# Script 中保存许多不同的规则，以便在不同的 Metric View 之间复用。 diff --git a/localizedContent/zh/content/features/semantic-bridge.md b/localizedContent/zh/content/features/semantic-bridge.md index 004a0a336..bf7f70ad2 100644 --- a/localizedContent/zh/content/features/semantic-bridge.md +++ b/localizedContent/zh/content/features/semantic-bridge.md @@ -54,12 +54,12 @@ Semantic Bridge 是一个语义模型编译器，能够将语义模型的结构 2. Databricks 主机名。 用于在为 Databricks 源系统生成的 M 分区中提供正确的参数。 3. Databricks 的 HTTP 路径。 - 这用于在为 Databricks 源系统生成的 M 分区中提供正确的参数。 + 这是为了在为 Databricks 源系统生成的 M 分区中提供正确的参数。 如果你只是测试翻译功能，最后两项可以先用占位值填写，但在将数据刷新到你的 Tabular 模型之前，需要先修正 M 分区定义。 填写完详细信息后，点击 **确定**。 -Semantic Bridge 会将你的 Metric View 转换为 Tabular，并为你创建所有 TOM 对象。 +Semantic Bridge 会将您的 Metric View 转换为 Tabular，并为您创建所有 TOM 对象。 ![导入对话框中的 Databricks 详细信息](~/content/assets/images/features/semantic-bridge/semantic-bridge-metric-view-details.png) @@ -81,7 +81,7 @@ Semantic Bridge 会将你的 Metric View 转换为 Tabular，并为你创建所 ![包含问题的导入成功通知](~/content/assets/images/features/semantic-bridge/semantic-bridge-import-success-with-issues.png) -如果你点击 **查看诊断信息**，就能看到一份信息列表，用于说明翻译过程中出现的问题。 +如果您点击 **查看诊断信息**，就会看到一份信息列表，用于描述翻译中存在的问题。 这些诊断信息也可以在之后通过 C# Script 输出出来查看： ```csharp @@ -104,12 +104,12 @@ SemanticBridge.MetricView.ImportDiagnostics.Output(); 1. 从磁盘读取 YAML 文件 2. 对 YAML 进行反序列化 3. 验证反序列化后的 YAML 是否为有效的 Metric View -4. 如果它是有效的 Metric View，就将其保存为当前已加载的 Metric View，就像你与已加载的 Tabular 模型交互一样。 +4. 如果它是有效的 Metric View，就将其保存为当前加载的 Metric View，类似于您与已加载的 Tabular 模型交互的方式。 如果它不是有效的 Metric View，流程将在此停止，并会提供信息。 5. 分析 Metric View，并尝试将其转换为一种中间表示 6. 尝试将中间表示转换为 Tabular 模型 -上述导入 GUI 会为你处理这一切，但你也可以使用 C# Script 自定义流程中的不同步骤，并以编程方式操作 Metric View，就像你平时操作 Tabular 模型一样。 +上文所述的导入 GUI 会为您处理这些工作；不过，您也可以使用 C# Script 来自定义流程中的不同步骤，并以编程方式操作 Metric View，就像您平时操作 Tabular 模型一样。 具体来说，你可以 - 使用 [`SemanticBridge.MetricView.Load`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService.html#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Load_System_String_) 从磁盘加载 Metric View：加载后可在 C# Script 中通过 [`SemanticBridge.MetricView.Model`](/api/TabularEditor.SemanticBridge.Platforms.Databricks.DatabricksMetricViewService.html#TabularEditor_SemanticBridge_Platforms_Databricks_DatabricksMetricViewService_Model) 访问，但不会将结构导入 Tabular 模型 @@ -139,17 +139,17 @@ SemanticBridge.MetricView.ImportDiagnostics.Output(); - `filter`：用于 Metric View 的 SQL 筛选表达式 公开预览版不支持任何 v1.1 元数据。 -在反序列化 Metric View 时，任何 v1.1 元数据都会被静默忽略，因此在 C# Script 中将不可见，也不会以任何方式影响翻译为 Tabular 的结果。 +在对 Metric View 进行反序列化时，任何 v1.1 元数据都会被静默忽略，因此这些元数据在 C# Script 中不可见，也不会以任何方式影响翻译到 Tabular。 > [!WARNING] -> 由于 v1.1 元数据会被静默忽略，将 Metric View 反序列化后再序列化会导致这些元数据丢失。 +> 由于 v1.1 元数据会被静默忽略，因此你反序列化后再序列化的 Metric View 将缺少这些元数据。 > 注意不要在 C# Script 中覆盖 v1.1 源 YAML 文件，否则会移除所有 v1.1 元数据。 ### 从 SQL 翻译的限制 Metric View 在 SQL 表达式之上提供了一个结构化层，因此翻译 Metric View 的一部分工作是在 Tabular 模型中将 SQL 转换为 DAX 和 M。 -- 不支持在 Metric View 的 `joins` 中嵌套 `joins`。 +- 不支持在 Metric View `joins` 中使用嵌套 `joins`。 换句话说，翻译仅支持严格的星型架构；不支持雪花模型 - 不支持使用 `using` 作为联接条件的 Metric View `joins`；仅支持通过 `on` 属性在单个键字段上进行等值联接。 - 包含 SQL 表达式的 Metric View `dimensions` 不会翻译为 M 或 DAX；它们会以 Tabular 模型计算列的形式呈现，并将其 SQL 表达式注释掉 @@ -159,7 +159,7 @@ Metric View 在 SQL 表达式之上提供了一个结构化层，因此翻译 Me > [!WARNING] > 注意，SQL 和 DAX 是不同的语言，语义也不同。 -> 我们无法保证翻译后的度量值在 Metric View SQL 与我们生成的 Tabular DAX 之间具有完全一致的行为。 +> 我们无法保证转换后的度量值在 Metric View SQL 与我们生成的 Tabular DAX 中的行为完全一致。 > 定义在事实表字段上的基础聚合通常表现一致；而定义在维度表字段上的聚合更可能产生非预期结果。 ### 连接 @@ -169,7 +169,7 @@ Metric View 在 SQL 表达式之上提供了一个结构化层，因此翻译 Me ### C# API -C# 接口的设计旨在优化自动翻译工作流。 +该 C# 接口在设计时针对自动翻译工作流进行了优化。 因此，与当前加载的 Metric View 交互的支持较为有限，某些类型的操作也比较繁琐。 ## 命名法附录 @@ -186,9 +186,9 @@ C# 接口的设计旨在优化自动翻译工作流。 ### 定义 - _语义模型_：单独使用时，始终指通用概念——用于支撑报表与分析的数据、元数据与业务逻辑的集合。 - 只有在其前面紧跟“Fabric”或“Power BI”时，它才指该平台中的那种工件类型：具体而言，是以 TMDL 或 BIM 保存、并使用 M 和 DAX 的 Tabular 模型；为尽可能避免这种混淆，我们通常更倾向于用“Tabular 模型”来指代 Power BI / Fabric 语义模型，因为 Tabular 模型不仅用于 Power BI / Fabric，也用于 Analysis Services Tabular。 + 仅当其前面紧跟“Fabric”或“Power BI”时，它才指该平台中的那种项目类型——具体而言，是以 TMDL 或 BIM 保存、并使用 M 和 DAX 的 Tabular 模型。为尽可能避免混淆，我们通常更倾向于用“Tabular 模型”来指代 Power BI / Fabric 的语义模型，因为 Tabular 模型不仅用于 Power BI / Fabric，也用于 Analysis Services Tabular。 - _平台_：具有语义层、并承载通用语义模型的技术解决方案。 - Databricks Metric Views 代表一个平台；Fabric / Power BI 代表一个平台；Analysis Services Tabular 是一个平台；Analysis Services Multidimensional 也是一个平台——但 Semantic Bridge 目前还不支持它。 + Databricks Metric Views 是一种平台；Fabric / Power BI 是一种平台；Analysis Services Tabular 是一种平台；Analysis Services Multidimensional 也是一种平台，但 Semantic Bridge 目前不支持它。 - _序列化格式_：一种将语义模型以文本形式表示并存储到磁盘上的方式。 TMDL 和 TMSL (.bim) 是 Power BI 语义模型的两种序列化格式；YAML 是 Databricks Metric View 的序列化格式。 - _对象模型_：语义模型在内存中的表示形式。我们通过 Semantic Bridge 在 Tabular Editor 中对它进行操作——既可以通过 GUI 操作，也可以通过 C# Script。 @@ -207,11 +207,11 @@ C# 接口的设计旨在优化自动翻译工作流。 ### Metric Views 与 Tabular 模型中的常见通用术语 对于可能不熟悉 Metric Views 或 Tabular 模型的用户，我们在下方提供了一份不完整的术语对照表。 -我们根据 YAML 中的表示来引用 Metric View 对象的名称；而对 Tabular，我们则以 TMDL/TMSL 中的对象类型名称为准。 +我们对 Metric View 对象的称呼基于它们在 YAML 中的表示；对 Tabular 对象的称呼则基于该对象类型在 TMDL/TMSL 中的名称。 | 通用术语 | Tabular 中的名称 | Metric View 中的名称 | 描述 | 备注 | | ----- | ------------ | ---------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | -| 事实表 | 表 | `source` | 用于存放维度外键以及可聚合的数值字段的表 | 一个 Metric View 只有一个事实表，它没有名称，并在 YAML 中作为根级 `source` 属性来表示。 Tabular 模型不会区分表的类型：某个表是否为事实表只能通过推断才能确定 | +| 事实表 | 表 | `source` | 用于存放维度外键以及可聚合的数值字段的表 | 一个 Metric View 只有一个未命名的事实表，并在 YAML 中表示为根级 `source` 属性。 Tabular 模型不会区分表的类型：某个表是否为事实表只能通过推断才能确定 | | 维度 | 表 | `join` | 用于存放描述性属性以及一个主键的表，事实表通过该主键与其关联 | Tabular 模型同样不会区分，因此“维度”的角色也只能像事实表一样通过推断得出。 | | 分区 | 分区 | `source`（仅用于 `join`） | 用于数据管理的对象，保存表中的一部分数据 | Tabular 模型中的表可以有多个分区，并且至少要有一个分区。 如上所述，Metric View 的事实表完全以 `source` 的形式定义；但 Metric View 的 `join` 也有一个 `source` 属性，其作用大致类似于分区 | | 字段 | 列 | 维度 | 表格中的一列 | | diff --git a/localizedContent/zh/content/features/te-cli/includes/te-cli-preview-notice.md b/localizedContent/zh/content/features/te-cli/includes/te-cli-preview-notice.md new file mode 100644 index 000000000..791c29254 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/includes/te-cli-preview-notice.md @@ -0,0 +1,2 @@ +> [!IMPORTANT] +> The Tabular Editor CLI is in **Limited Public Preview**. It is offered for evaluation with a Tabular Editor account; no license is required during preview. Commands, flags, and outputs may change before general availability. **The preview build stops functioning after 2026-09-30.** We recommend against using the CLI in production CI/CD pipelines during preview. Please refer to our license agreement. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-auth.md b/localizedContent/zh/content/features/te-cli/te-cli-auth.md new file mode 100644 index 000000000..054f1fdb9 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-auth.md @@ -0,0 +1,226 @@ +--- +uid: te-cli-auth +title: Authentication and Connections +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Authentication and Connections + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI authenticates to Power BI Service, Microsoft Fabric, and Azure Analysis Services using the same Power BI Desktop client ID that Tabular Editor 3 uses. Tokens are cached locally so you authenticate once and re-run commands silently until the refresh token expires (typically 90 days). + +## Authentication methods + +The CLI supports the full Azure Identity credential chain: + +| Method | When to use | `--auth` value | +| ---------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- | +| Interactive browser | Local development - opens the system browser | `interactive` (default) | +| Service principal (client secret) | Automation, CI/CD, headless / SSH / WSL | `spn` (with `-u / -p / -t`) or `env` | +| Service principal (certificate) | Automation with certificate-based auth | `spn` (with `-u / -t / --certificate`) | +| Environment variables | `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID` | `env` | +| Managed identity | Azure VMs, Azure Container Apps, Azure Functions | `managed-identity` | + +> [!NOTE] +> `--auth` is a **global** option, available on every `te` command - not just `te auth login`. Pass it to [`te deploy`](xref:te-cli-commands#deploy), [`te refresh`](xref:te-cli-commands#refresh), [`te query`](xref:te-cli-commands#query), [`te connect`](xref:te-cli-commands#connect), or any other command that connects to a remote endpoint, to override the default chain for that invocation. The default (`auto`) tries environment credentials first, then falls back to the cached or interactive browser login. + +For headless, SSH, WSL, or devcontainer scenarios, use a service principal - `te auth login -u -p -t ` (or `--certificate`). The login is cached, so subsequent commands acquire tokens silently with `--auth auto`. + +## `te auth login` + +Authenticate and cache the result for subsequent commands: + +```bash +# Browser-based interactive login (default) +te auth login + +# Service principal with client secret +te auth login -u "$AZURE_CLIENT_ID" -p "$AZURE_CLIENT_SECRET" -t "$AZURE_TENANT_ID" + +# Service principal - read secret from stdin +echo "$AZURE_CLIENT_SECRET" | te auth login -u "$AZURE_CLIENT_ID" -p - -t "$AZURE_TENANT_ID" + +# Service principal with certificate +te auth login -u "$AZURE_CLIENT_ID" -t "$AZURE_TENANT_ID" --certificate ./sp.pfx --certificate-password "$CERT_PASSWORD" + +# Managed identity (Azure-hosted) +te auth login --identity +``` + +After a successful service-principal login the CLI **caches the credentials** so every subsequent `te` command can acquire tokens silently - no need to re-pass `-u / -p / -t` or set the `AZURE_CLIENT_*` environment variables. Pass `--save=false` for a one-shot login that doesn't update the cache, or run `te auth logout` to clear it. + +> [!WARNING] +> Passing secrets directly on the command line exposes them to process listings and shell history. Prefer the `AZURE_CLIENT_SECRET` environment variable, or pipe the secret via stdin with `-p -`. + +## `te auth status` + +Display the current authentication state without opening a browser: + +```bash +te auth status +te auth status --output-format json +``` + +This returns an exit code of `0` when a valid session exists, `1` when not logged in or expired. + +## `te auth logout` + +Clear all cached credentials: + +```bash +te auth logout +``` + +## Credential storage + +The CLI stores access/refresh tokens and service-principal records in the **OS-native secure store** by default. A `0600` file fallback is selected automatically only when the OS keystore is unavailable (e.g., headless Linux without libsecret/D-Bus). + +| Platform | Backend | Storage location | +| --------------------------------- | --------------------------------------------- | -------------------------------------------------------------- | +| Windows | DPAPI | Per-user, managed by MSAL | +| Linux | libsecret (system keyring) | Per-user, managed by MSAL | +| macOS | Keychain | Service `com.tabulareditor.cli.*`, account `te-msal-cache.bin` | +| Any (fallback) | `0600` file | `~/.te-cli/te-msal-cache.bin` and per-key `.bin` blobs | + +Interactive browser and service-principal flows share the same cache; MSAL's account model distinguishes them - there are no separate `auth-record*.json` sidecar files. Run any command with `--debug` to see which backend was selected at startup. + +`te auth logout` clears every cached record (both the MSAL token cache and any SPN blobs) regardless of which backend is in use. + +## `te connect` - set the active connection + +`te connect` persists an active connection for the current terminal session. Subsequent commands that take `-s` / `-d` can omit them: + +```bash +# Remote workspace +te connect my-workspace my-model + +# Local TMDL folder, .bim file, or .SemanticModel container +te connect ./my-model + +# Connect to a running Power BI Desktop instance (Windows only) +te connect --local + +# Show the active connection +te connect + +# Clear the active connection (and any workspace mirror) +te connect --clear +``` + +Active-connection state is per-terminal-session: opening a new terminal starts fresh. + +### Workspace mode (`-w` / `--workspace`) + +`te connect -w ` pairs a primary source with a secondary mirror so every subsequent `--save` writes to both. Use it to keep a local working copy of a remote model in sync, or to push local edits to a workspace as you save: + +```bash +# Mirror remote workspace ↔ local TMDL folder +te connect Finance "Revenue Model" -w ./revenue-model + +# Mirror local source ↔ remote workspace (initial deploy + auto-redeploy on save) +te connect ./revenue-model -w Finance "Revenue Model" +``` + +Save order is always **local first, then remote**, so the on-disk copy reflects the latest user change even if the server push fails. See @te-cli-commands#workspace-mode-w--workspace for `--workspace-format`, overwrite semantics, and clearing the mirror. + +## Connecting to different clouds + +The CLI detects the correct scope from the server URL for: + +- Power BI Service and Fabric (commercial, US Gov, China, Germany clouds) +- Azure Analysis Services (`asazure://...`) +- Local SSAS (`localhost`, named instances - Windows only) + +Pass an XMLA endpoint, workspace name, or `powerbi://` URL as `--server`: + +```bash +te connect "powerbi://api.powerbi.com/v1.0/myorg/Finance" "Revenue Model" +te connect "powerbi://api.powerbi.com/v1.0/SpaceParts/Finance" "Revenue Model" +te connect "asazure://westeurope.asazure.windows.net/myaas" "MyModel" +te connect localhost "AdventureWorks" +``` + +## Connection profiles + +For repeated use of the same connection - especially when you deploy to multiple environments - save named profiles: + +```bash +# Save remote and local profiles +te profile set prod -s my-workspace -d my-model --description "Production" +te profile set dev --model ./model --description "Local dev TMDL" + +# List and inspect +te profile list +te profile show prod + +# Use a profile as the active connection +te connect --profile prod + +# One-shot use without changing the active connection +te deploy ./model --profile staging --force +``` + +Profiles can also carry behavioral overrides that take effect whenever the profile is active: + +```bash +# In dev, disable the BPA gate on deploy and loosen validation +te profile set dev --bpa-on-deploy false --validate-on-mutation false + +# In prod, force auto-format before any mutation +te profile set prod --auto-format true +``` + +See @te-cli-config for the full list of overridable behaviors. + +## Non-interactive authentication + +For CI/CD pipelines, agents, or any unattended context, avoid interactive flows by combining: + +- The `--non-interactive` global flag (fails fast instead of prompting). +- One of the non-interactive auth methods: `env`, `managed-identity`, or explicit service principal credentials. + +Environment-based example for a pipeline: + +```bash +export AZURE_CLIENT_ID="your-app-id" +export AZURE_CLIENT_SECRET="your-client-secret" +export AZURE_TENANT_ID="your-tenant-id" + +te deploy ./model -s my-workspace -d my-model \ + --auth env \ + --non-interactive \ + --force \ + --ci github +``` + +See @te-cli-cicd for complete GitHub Actions and Azure DevOps Pipelines examples. + +## Authentication environment variables + +The CLI honors the standard Azure.Identity environment variables when you use `--auth env` (and as part of the `auto` chain): + +| Variable | Purpose | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AZURE_CLIENT_ID` | Service principal application ID. | +| `AZURE_CLIENT_SECRET` | Service principal client secret. Used together with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. | +| `AZURE_TENANT_ID` | Service principal tenant (directory) ID. | +| `AZURE_CLIENT_CERTIFICATE_PATH` | Path to a PEM or PKCS12 certificate file for certificate-based service principal auth. Used together with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. | +| `AZURE_AUTHORITY_HOST` | Override the authority host for sovereign clouds (e.g., `login.microsoftonline.us`, `login.partner.microsoftonline.cn`, `login.microsoftonline.de`). Defaults to the commercial cloud. | + +For CLI-specific environment variables (config paths, debug logging, TE2 compatibility), see @te-cli-config. + +## Next steps + +- @te-cli-commands - what you can do once connected. +- @te-cli-config - configuration and profile behavior. +- @te-cli-cicd - pipeline examples using service principals and managed identity. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-automation.md b/localizedContent/zh/content/features/te-cli/te-cli-automation.md new file mode 100644 index 000000000..9ff078182 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-automation.md @@ -0,0 +1,193 @@ +--- +uid: te-cli-automation +title: Automation and Scripting +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Automation and Scripting + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI is composable; every command supports structured output, disables interactive prompts on demand, and returns predictable exit codes. The same primitives work equally well for shell pipelines, Python scripts, PowerShell automation, and agent-driven workflows. + +## Structured output + +Use `--output-format` to switch any command between text (human-readable) and machine-readable formats: + +| Format | Use for | Notes | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `text` (default) | Human-readable use | Plain text on stdout regardless of whether the stream is a TTY or piped. | +| `json` | Machine-readable use | Always valid JSON to stdout. Use `--error-format json` if you also want machine-readable errors on stderr. | +| `csv` | Tabular results (`query`, `bpa run`, `bpa rules`, `vertipaq`, `validate`, `test`, `refresh`, `profile list`, `session list`, `find`, `replace`, `get`, `ls`) | RFC 4180 escaping. | +| `tmsl` (alias `bim`) | Whole-object TMSL/BIM serialization | Accepted by `te get` and `te ls`. | +| `tmdl` | Whole-object TMDL serialization | Accepted by `te get` only (single object). | + +```bash +te ls --output-format json +te query -q "EVALUATE VALUES('Date'[Year])" --output-format csv +te bpa run --output-format json +``` + +> [!NOTE] +> `--output-format` and `--error-format` are independent. Setting `--output-format json` does _not_ switch stderr to JSON; pass `--error-format json` for that. There is no automatic format switching when stdout is redirected - the default is always `text` unless you ask otherwise. + +## Non-interactive mode + +Add `--non-interactive` to any command to disable confirmation prompts, credential picklists, and guided wizards. If the command needs input it cannot resolve from flags, environment, or config, it exits non-zero with an actionable error instead of hanging. + +```bash +te deploy ./model --non-interactive --force --ci github +``` + +## Exit codes + +Every `te` command exits with a predictable status code so callers can branch on success or failure without parsing stdout. + +| Exit | Meaning | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `0` | Success. | +| `1` | Generic failure - invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity ≥ error. | +| `2` | Used by `te diff` to indicate models differ (distinct from `0` identical and non-zero errors). | + +Combine exit codes with `--ci ` annotations and `--trx ` to surface rich failure information in CI - see @te-cli-cicd. + +## Errors on stderr + +Errors, warnings, and the preview banner are written to **stderr**; structured data is written to **stdout**. This means you can pipe JSON safely without it being contaminated by progress indicators or diagnostic messages: + +```bash +te ls --output-format json | jq '.[] | .name' +te vertipaq --output-format json > stats.json +``` + +## Python + +Python is a natural host for orchestrating CLI calls from data pipelines, notebooks, or test harnesses. Invoke `te` with `subprocess.run`, request JSON, and parse stdout: + +```python +import json +import subprocess + +def query(server: str, database: str, dax: str) -> list[dict]: + result = subprocess.run( + ["te", "query", + "-s", server, + "-d", database, + "-q", dax, + "--output-format", "json", + "--non-interactive"], + check=True, + capture_output=True, + text=True, + ) + return json.loads(result.stdout) + +rows = query("Finance", "Revenue Model", "EVALUATE TOPN(10, 'Sales')") +for row in rows: + print(row) +``` + +To capture structured errors from stderr: + +```python +import json +import subprocess + +result = subprocess.run( + ["te", "deploy", "./model", + "-s", "Finance", "-d", "Revenue", + "--output-format", "json", "--non-interactive", "--force"], + capture_output=True, text=True, +) + +if result.returncode != 0: + try: + err = json.loads(result.stderr.strip().splitlines()[-1]) + print("Deploy failed:", err.get("error"), "- hint:", err.get("hint")) + except json.JSONDecodeError: + print("Deploy failed:\n", result.stderr) +``` + +## PowerShell + +PowerShell handles JSON natively. `te` is a regular console binary that works directly in PowerShell pipelines (see @te-cli-migrate if you're porting from the older `TabularEditor.exe` CLI): + +```powershell +$rows = te query -s Finance -d Revenue -q "EVALUATE TOPN(10, 'Sales')" --output-format json --non-interactive + | ConvertFrom-Json + +$rows | Format-Table + +# Check exit code after the pipeline +if ($LASTEXITCODE -ne 0) { + Write-Error "Query failed with exit $LASTEXITCODE" + exit $LASTEXITCODE +} +``` + +Read secrets from the environment rather than passing them as plaintext: + +```powershell +$env:AZURE_CLIENT_ID = "your-app-id" +$env:AZURE_CLIENT_SECRET = "your-client-secret" +$env:AZURE_TENANT_ID = "your-tenant-id" + +te deploy ./model ` + -s my-workspace -d my-model ` + --auth env --non-interactive --force --ci vsts +``` + +## Bash + +Compose commands with pipes and `jq`. The CLI's text output is colorized for humans, but switching to `--output-format json` gives you a clean shape to work with: + +```bash +# Count measures per table +te ls --type measure --output-format json \ + | jq -r '.[] | .table' \ + | sort | uniq -c | sort -rn +``` + +```bash +# Fail the shell script if BPA finds any errors +te bpa run --fail-on error --output-format json > bpa.json \ + || { echo "BPA gate failed"; jq '.violations' bpa.json; exit 1; } +``` + +## Composability example + +Generating a refresh TMSL script and version-controlling it is three commands: + +```bash +te connect MyWorkspace MyModel +te refresh --type full --dry-run > refresh.tmsl +cat refresh.tmsl +``` + +The resulting TMSL can be reviewed in a pull request, committed, executed by the CLI (`te refresh --type full`), handed to a DBA, or applied by any XMLA-compatible tool. The CLI becomes a building block rather than a black box. + +## Useful patterns + +A handful of small idioms that come up often when composing `te` commands in scripts or pipelines: + +- **Idempotent creates and removes.** `te add Sales/Marker -t Measure -i "0" --if-not-exists --save` and `te rm Sales/OldMeasure --if-exists --save` both exit `0` whether or not the object existed - safe to re-run in CI. +- **Dry-run diffs.** `te replace` is dry-run by default; add `--save` only when you're satisfied with the preview. +- **Emit TMSL for review.** `te deploy ./model --xmla deploy.tmsl` produces the deployment script without touching the server - useful for DBA review or manual apply. +- **Path-only output.** `te ls --paths-only` and `te find --paths-only` emit one object path per line, ideal for piping to `xargs`, `te get`, or `te set`. The model-level containers (`te ls Measures`, `te ls Columns`) compose well with this for whole-model sweeps. +- **Benchmarking queries.** `te query --trace --cold --runs 5` runs a DAX query with cold cache, five iterations, and captures FE/SE trace events. +- **Step timings in CI logs.** Long-running commands (`te deploy`, `te refresh`, `te script`, `te validate`) include a `durationMs` field in JSON output - useful for surfacing per-step timings in pipeline summaries. + +## Related pages + +- @te-cli-cicd - pipeline-specific patterns and YAML examples. +- @te-cli-commands - full command reference. +- @te-cli-interactive - when interactive mode fits better than scripting. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-cicd.md b/localizedContent/zh/content/features/te-cli/te-cli-cicd.md new file mode 100644 index 000000000..d39da955b --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-cicd.md @@ -0,0 +1,235 @@ +--- +uid: te-cli-cicd +title: CI/CD Integration +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# CI/CD Integration + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI is designed for unattended execution in continuous integration and delivery pipelines. A single binary, structured output, non-interactive mode, native CI annotations for GitHub Actions and Azure DevOps, and VSTEST-compatible test results make it a natural replacement for ad-hoc TE2 invocations. + +> [!WARNING] +> **Do not use the CLI in production pipelines during Limited Public Preview.** Two preview-specific risks apply to pipeline owners: +> +> - **Hard expiry.** The preview binary stops functioning on **2026-09-30** - any pipeline depending on it will fail on that date, regardless of your release calendar. +> - **No backwards-compatibility guarantee.** Commands, flags, output shapes, and exit codes may change between preview builds, so pipeline steps may need updating when you refresh the vendored binary. +> +> Build and evaluate in non-production pipelines, and share feedback in the public [TabularEditor/CLI](https://github.com/TabularEditor/CLI) repository so the GA version matches your needs. + +## What makes the CLI CI-friendly + +- **Single self-contained binary.** No runtime install, no `TabularEditor.exe`, no `start /wait`. +- **`--non-interactive` global flag.** Disables every prompt; fails fast with actionable errors. +- **`--force`** on mutating commands (`te deploy`, `te refresh`) skips confirmation prompts. +- **`--ci vsts` / `--ci github`.** Emit native pipeline annotations to stderr. +- **`--trx `.** Produce VSTEST results consumable by Azure DevOps test publishing. +- **Structured errors.** `--output-format json` emits `{"error": "...", "hint": "..."}` to stderr so pipeline steps can fail with a useful message. + +## Adding the CLI to your repo + +During Limited Public Preview, the CLI is gated behind sign-in on [tabulareditor.com](https://tabulareditor.com/download-tabular-editor-cli), so pipelines cannot fetch the archive from a public URL. The simplest reproducible approach is to commit the binary that matches your runner into your repository and reference it from each pipeline step. + +A common layout: + +``` +your-repo/ +└── tools/ + └── te/ + ├── te # Linux / macOS binary (needs chmod +x at runtime) + └── te.exe # Windows binary +``` + +Place the **extracted** binary - not the archive - so the pipeline can call it directly. Pick the build that matches your runner OS/arch; see @te-cli-install for the filename table. The self-contained binary is ~70 MB; consider Git LFS if your repo is sensitive to size. + +> [!NOTE] +> Committing the binary also pins the CLI version to whatever you checked in, which is desirable for CI reproducibility. To upgrade, replace the binary in `tools/te/` and commit it - the commit message is your version log. Keep in mind that the preview binary still expires on **2026-09-30** regardless of when you committed it, so a vendored copy is not a permanent dependency - plan to refresh it (and re-validate your pipeline against the new API surface) on preview-build cadence. + +## GitHub Actions + +A complete deploy + test workflow. The example assumes the Linux `te` binary is committed at `tools/te/te`, and a service principal is stored in repository secrets (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`). + +```yaml +name: Deploy semantic model + +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + env: + AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }} + AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }} + AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }} + steps: + - uses: actions/checkout@v4 + + - name: Set up Tabular Editor CLI + run: | + chmod +x ./tools/te/te + echo "$GITHUB_WORKSPACE/tools/te" >> $GITHUB_PATH + + - name: Validate + run: te validate ./model --ci github --trx validate.trx + + - name: Best Practice Analyzer (gate) + run: te bpa run ./model --fail-on error --ci github --trx bpa.trx + + - name: Deploy + run: | + te deploy ./model \ + -s "${{ vars.WORKSPACE }}" \ + -d "${{ vars.MODEL }}" \ + --auth env \ + --non-interactive \ + --force \ + --ci github + + - name: Regression tests + run: | + te test run \ + -s "${{ vars.WORKSPACE }}" \ + -d "${{ vars.MODEL }}" \ + --auth env --non-interactive \ + --ci github --trx tests.trx + + - name: Publish test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: trx-results + path: '*.trx' +``` + +## Azure DevOps Pipelines + +The Azure DevOps Pipelines equivalent of the GitHub Actions workflow above. The example assumes `te.exe` is committed at `tools\te\te.exe`. `--ci vsts` emits `##vso[...]` commands that the pipeline interprets as errors, warnings, and task-status updates. + +```yaml +trigger: + - main + +pool: + vmImage: 'windows-latest' + +variables: + - group: 'te-cli-secrets' # Contains AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID + +steps: + - checkout: self + + - powershell: Write-Host "##vso[task.prependpath]$(Build.SourcesDirectory)\tools\te" + displayName: 'Set up Tabular Editor CLI' + + - script: te validate ./model --ci vsts --trx validate.trx + displayName: 'Validate' + + - script: te bpa run ./model --fail-on error --ci vsts --trx bpa.trx + displayName: 'BPA gate' + + - script: | + te deploy ./model ^ + -s "$(WORKSPACE)" -d "$(MODEL)" ^ + --auth env --non-interactive --force --ci vsts + displayName: 'Deploy' + env: + AZURE_CLIENT_ID: $(AZURE_CLIENT_ID) + AZURE_CLIENT_SECRET: $(AZURE_CLIENT_SECRET) + AZURE_TENANT_ID: $(AZURE_TENANT_ID) + + - script: te test run -s "$(WORKSPACE)" -d "$(MODEL)" --auth env --non-interactive --ci vsts --trx tests.trx + displayName: 'Regression tests' + env: + AZURE_CLIENT_ID: $(AZURE_CLIENT_ID) + AZURE_CLIENT_SECRET: $(AZURE_CLIENT_SECRET) + AZURE_TENANT_ID: $(AZURE_TENANT_ID) + + - task: PublishTestResults@2 + condition: always() + inputs: + testResultsFormat: 'VSTest' + testResultsFiles: '*.trx' +``` + +## BPA gate patterns + +`te deploy` and `te save` run the Best Practice Analyzer as a pre-flight gate by default. Three behaviors are worth determining up-front: + +- **Enforce** - the default. Pipeline fails if BPA finds violations at severity ≥ error. Pair with `--fail-on warning` on a standalone `te bpa run` step if you want warnings to fail too. +- **Auto-fix** - `--fix-bpa` applies `fixExpression`s in memory for the deployed artifact. Source files are not modified. Useful when the source of truth lives in the model and you want deploys to normalize style without developer intervention. +- **Bypass** - `--skip-bpa` disables the gate for a single command. Useful for emergency hotfixes; not recommended as a default. + +```bash +# Treat warnings as failures in PR validation +te bpa run ./model --fail-on warning --ci github --trx bpa.trx + +# Auto-fix during deploy (source unchanged) +te deploy ./model -s my-ws -d my-model --fix-bpa --force --ci github + +# Emergency bypass +te deploy ./model -s my-ws -d my-model --skip-bpa --force --ci github +``` + +See @te-cli-config for controlling the BPA gate globally via `bpa.onDeploy` / `bpa.onSave` config keys. + +## Refresh patterns + +Refresh in pipelines is typically a follow-up step after deployment. Use `--non-interactive` and pick a deterministic `--type`: + +```bash +# Full refresh of the whole model after deploy +te refresh -s my-ws -d my-model --type full --non-interactive + +# Refresh a single fact table (e.g., daily incremental pipeline) +te refresh -s my-ws -d my-model --table Sales --type full --non-interactive + +# Recalculate only (useful after calculation-group changes) +te refresh -s my-ws -d my-model --type calculate --non-interactive +``` + +For incremental refresh workflows, combine `--apply-refresh-policy`, `--effective-date `, and `--partition ` flags. See @te-cli-commands for details. + +## Artifact patterns + +Emit TMSL or XMLA as an artifact without deploying, so DBAs or a later job can review or apply it: + +```bash +# Produce the XMLA/TMSL script that would deploy - do not deploy +te deploy ./model -s my-ws -d my-model --xmla deploy.tmsl --force + +# Produce the TMSL refresh command - do not execute +te refresh -s my-ws -d my-model --type full --dry-run > refresh.tmsl +``` + +Commit these artifacts to git, upload them to the pipeline's artifact storage, or pass them between jobs. They're plain text and diff cleanly in pull requests. + +## Secret handling + +| Approach | When to use | Notes | +| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Service principal via env vars (`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`, `--auth env`) | General CI/CD | Map pipeline secrets to environment variables at the step or job level. Never pass secrets in command arguments. | +| Service principal via `te auth login` once per job (`echo $SECRET \| te auth login -u $ID -p - -t $TENANT`) | Multi-step jobs | The login is cached, so subsequent `te` commands acquire tokens silently - no need to set `AZURE_CLIENT_*` for every step or re-pass `-u/-p/-t`. Pipe the secret via stdin rather than interpolating it. | +| Managed identity (`--auth managed-identity`) | Azure VMs, Container Apps, Azure Functions | No secrets to manage. Preferred in Azure-hosted environments. | +| Certificate (`--certificate `) | Enterprise scenarios with cert rotation | Mount the certificate as a secure file step; pass `--certificate-password` via env. | + +> [!WARNING] +> Do not echo secrets or the output of `te auth status` to pipeline logs. The CLI writes warnings to stderr when secrets are passed on the command line - respect those warnings in CI. + +## Related pages + +- @te-cli-auth - authentication methods in detail. +- @te-cli-config - configuration and profile overrides. +- @te-cli-automation - general scripting patterns. +- @te-cli-migrate - migrating an existing TE2-based pipeline. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-commands.md b/localizedContent/zh/content/features/te-cli/te-cli-commands.md new file mode 100644 index 000000000..c8c10b520 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-commands.md @@ -0,0 +1,870 @@ +--- +uid: te-cli-commands +title: Command Reference +author: Peer Grønnerup +updated: 2026-05-12 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Command Reference + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +This page gives a short description and one example per command. Every command accepts `--help` for exhaustive flag documentation: + +```bash +te deploy --help # Help for a single command +te bpa run --help # Help for a command with subcommands +``` + +> [!NOTE] +> During preview, the CLI's `--help` output is the authoritative reference for flags and options. The content on this page is hand-curated and will lag `--help` for anything added between preview releases. + +## Object paths + +Object addressing in the CLI uses a single grammar that's shared across every command. Two flavours of path appear in the reference below: + +- **``** - resolves to **exactly one** object or container. Used by commands that operate on a single target: `te get`, `te set`, `te add`, `te rm`, `te mv`, `te format -p`, `te deps`, `te macro run --on`. +- **``** - resolves to **zero or more** objects, with wildcard support. Used by commands that operate on a set: `te ls`, `te bpa run --path`, and other inspection-style commands. + +Both path forms share the same syntax rules; they differ in only two places: + +- Filter paths allow `*` wildcards; object paths do not. +- Object paths allow DAX bracket-suffix (e.g. `Sales[Amount]`); filter paths do not. + +### Segments and separators + +A path is a slash-separated sequence of **segments**. Each segment names a single step - a table, a child object, or a container keyword. + +- `Sales` — one segment +- `Sales/Revenue` — two segments +- `Roles/Admin/Members/bob` — four segments + +Empty input and `.` both mean "the model root" - the implicit starting point for filter paths and the explicit subject for `te get .`-style queries. + +### Quoting + +Most segment names work as-is. Quote a segment when its name contains spaces, slashes, brackets, or any character that would otherwise be parsed as syntax. The CLI follows DAX quoting conventions, so quoting in `te` paths matches what you'd type inside a DAX expression: + +| Form | Use for | Escape rule | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `'Net Sales'` | Tables, named objects with spaces. | Double the quote (`'Bob''s'` → `Bob's`). | +| `"Net Sales"` | Same as above; cross-shell convenience when single-quote escaping is awkward. | Double the quote (`"He said ""hi"""` → `He said "hi"`). | +| `[Sales Amount]` | DAX bracket-suffix on a table (`'Sales'[Sales Amount]`) or a lone-bracket model-wide reference (`[Total Sales]`). Object paths only. | Double the closing bracket (`[foo]]bar]` → `foo]bar`). | + +Inside quoted segments, `*` is treated as a literal character, not a wildcard. So `'Sa*'` matches a table named exactly `Sa*`. + +### DAX-style references (object paths only) + +Two DAX-shaped forms are accepted anywhere a `` is allowed: + +- **`'Table'[Member]`** - equivalent to `Table/Member`. The bracket-suffix biases ambiguous matches toward columns and measures over hierarchies/partitions. +- **`[Member]`** - a _lone_ measure or column, with no preceding table. Searches the whole model for a measure or column with that name. Measures win when both exist. + +```bash +te get "'Sales'[Amount]" # Same as te get Sales/Amount +te get "'Net Sales'[Sales Amount]" # Spaced names via DAX form +te get "[Total Sales]" # Model-wide measure-or-column lookup +``` + +### Containers and keywords + +Several names act as container keywords. A keyword can stand alone (listing the whole container) or appear inside a path (jumping into that sub-collection on the current parent). + +| Keyword | Scope | Meaning | +| ----------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------- | +| `Tables`, `Measures`, `Columns`, `Hierarchies`, `Partitions` | Model | All objects of that kind across the model. | +| `Relationships`, `Roles`, `Perspectives`, `Cultures`, `DataSources`, `Expressions`, `CalculationGroups`, `Functions`, `Annotations` | Model | Model-level containers. | +| `Measures`, `Columns`, `Hierarchies`, `Partitions`, `Calendars`, `CalculationItems` | Table | Sub-containers under a table. | +| `Levels` | Hierarchy | Levels of a hierarchy. | +| `Members`, `TablePermissions` (alias `Permissions`) | Role | Children of a role. | + +A few examples show how plain and container-scoped paths differ: + +```bash +te get Sales/Revenue # Measure or column on Sales +te get Sales/Measures/Revenue # Same, container-scoped - disambiguates if other kinds share the name +te get Sales/Geography/Levels/Year # Specific level of a hierarchy +te get Roles/Admin/Members/bob@example.com # Role member +te get Sales/refreshPolicy # Refresh-policy sub-object on a table +te get "Measures/Revenue/KPI" # KPI sub-object of a measure +``` + +Quote a segment to force literal-name matching when a real object name happens to coincide with a keyword. The table literally named `Tables` is `'Tables'`, addressed by `te get "'Tables'"`. + +### Wildcards in filter paths + +Filter paths add a single wildcard character - `*` - that matches any run of characters within one segment (greedy, single-segment). Wildcards are how `te ls` and similar commands narrow their results. + +```bash +te ls 'Sa*' # Tables whose name starts with Sa +te ls 'Sales/*Amount' # Children of Sales whose name ends with Amount +te ls '*/Amount' # An Amount column/measure across every table +te ls 'Roles/Re*/Members' # Members of every role matching Re* +``` + +A filter path with **N segments** produces **N-level-deep** results - wildcards never auto-expand a level beyond what you typed. The single-segment shortcut `te ls Sales` is the exception: an unqualified, non-wildcarded table name expands to the table's direct children to match the "show me what's in Sales" intent. `te ls Sa*`, in contrast, returns just the matching tables - no expansion. + +DAX bracket-suffix is rejected in filter paths; quote names containing `[` and `]` if you need to match them literally. + +### Errors and hints + +Misspelled segments emit a contextual error with a "did you mean" hint when the CLI can guess what you meant. Missing-parent paths fail before the leaf check, so the message points at the segment that's actually wrong. Empty containers (e.g., `te ls Hierarchies` on a model without hierarchies) emit a simply "nothing here" hint rather than an error. + +## Global options + +These flags are available on every command and can be used before or after the subcommand name. + +| Option | Description | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-m, --model ` | Path to semantic model (TMDL folder, `.bim` file, or TE folder). | +| `-s, --server ` | Workspace name or endpoint (e.g., `MyWorkspace`, `powerbi://...`, `asazure://...`, `localhost`). | +| `-d, --database ` | Semantic model name on the workspace. | +| `--local` | Connect to a locally running Power BI Desktop instance (Windows only). | +| `--auth ` | Auth method: `auto`, `interactive`, `spn`, `env`, `managed-identity` (default: `auto`). | +| `--output-format ` | Stdout format: `text` (default), `json`, `csv`, `tmsl` (alias `bim`), `tmdl`. `csv` is honored by commands that emit tabular data; `tmsl`/`tmdl` only by `te get` and `te ls` for whole-object serialization. Commands reject formats they don't support. | +| `--error-format ` | Stderr format for errors, warnings, and hints: `text` (default) or `json`. Other values fall back to text. Independent of `--output-format`, so you can pair JSON stdout with plain-text errors (or vice versa). | +| `--recent [N]` | Use a recently used model. No value = interactive picker; `N` = Nth most recent (1 = last used). | +| `--non-interactive` | Disable all interactive prompts. Fail with an actionable error if required input is missing. | +| `--debug` | Enable debug logging to stderr (connection strings, auth flow, timing). | + +For commands that read a model, the resolution order is: + +positional `` argument → `--model` global flag → `--server`/`--database` (remote) → active connection from `te connect` → `--recent`. + +## Model I/O + +### load + +Load a semantic model and display a summary of the model — name, compatibility level, and high-level object counts (tables, measures, columns). + +```bash +te load ./model # TMDL folder +te load model.bim # BIM file +te load -s MyWorkspace -d MyModel # Remote workspace +``` + +### save + +Save a model to disk. Use it to write a remote workspace model to local files, convert formats, or persist edits back to the source. + +`te save` accepts: + +- `-o, --output-path ` - target file or folder. **Optional** - when omitted, `te save` writes back to the source location, preserving the original format. +- `--serialization ` - `tmdl`, `bim`, `te-folder`, `pbip`, `database.json`. Defaults to inferring from the loaded model (BIM source → BIM, TMDL `SemanticModel/` → TMDL under `definition/`). +- `--force` - skip validation and overwrite existing output. Some refusals (ambiguous containers, multi-`SemanticModel` project roots) fire even under `--force`. +- `--skip-bpa` - bypass the BPA gate entirely. +- `--fix-bpa` - auto-fix BPA violations where rules define a fix expression. +- `--bpa-rules ` - repeatable; override `bpa.rules` from your CLI config for this single save. Built-in rules still apply unless `bpa.builtInRules` is `false`. +- `--skip-validation` - skip DAX semantic analysis and validation for fast passthrough downloads. +- `--supporting-files` - generate Fabric supporting files (`.platform`, `definition.pbism`). + +```bash +te save # Save back to source (no -o needed) +te save ./model.bim -o ./tmdl-out # Convert BIM to TMDL +te save -o ./project --serialization pbip # Save as a PBIP project +te save -o ./out -s my-workspace -d my-model --skip-validation # Fast download +``` + +> [!TIP] +> Use `te save -o -s -d ` to download a remote model to disk. Pair with `--skip-validation` for the fastest passthrough when you only need the bytes (no DAX semantic analysis). + +### open + +Open a model in Tabular Editor 3 Desktop. **Windows only** (requires TE3 to be installed). + +```bash +te open ./my-model +``` + +### init + +Create a new empty semantic model at the given path. + +```bash +te init ./new-model +``` + +## Model editing + +### set + +Set a property on a model object. Accepts a ``. + +`te set` accepts: + +- `-q ` - property name (e.g., `expression`, `formatString`, `description`, `isHidden`). +- `-i ` - value (use `-` to read from stdin). +- `--save` / `--save-to ` - persist changes. + +```bash +te set Sales/Amount -q expression -i "SUM(Sales[Amt])" --save +te set "'Net Sales'[Sales Amount]" -q formatString -i "#,0" --save # DAX form with spaced names +te set Sales -q isHidden -i true --save +``` + +### add + +Add an object to the model. Pass a `` for the new object (the parent must already exist; the leaf segment is the new name) and the type via `-t` / `--type`. Relationships keep their shorthand syntax (`Sales[Key]->Dim[Key]`). + +`te add` accepts: + +- `-t, --type ` - object type. Common values: `Table`, `Measure`, `Column`, `CalculatedColumn`, `Hierarchy`, `Role`, `Perspective`, `Culture`, `CalculationGroup`, `CalculationItem`. Tab-completion is supported; the full list can be retrieved by running `te add --help`. +- `--if-not-exists` - exit `0` without error if the object already exists. Use this for idempotent CI/CD pipelines. + +```bash +te add Sales/Revenue -t Measure -i "SUM(Sales[Amount])" --save +te add Sales -t Table --save +te add "Sales[ProdKey]->Product[ProdKey]" --save # Relationship shorthand +te add Sales/MarketingFlag -t CalculatedColumn -i "Sales[Amount] > 1000" --if-not-exists --save +te add Perspectives/Default/Sales --save # Include Sales in the Default perspective +te add Roles/Reader -t Role --save # New role at the model level +``` + +For data-bound tables, `te add` also supports schema detection from SQL, Lakehouse, or Warehouse sources. See `te add --help` for `--source`, `--endpoint`, `--source-table`, `--columns`, etc. + +### rm + +Remove an object. Checks dependents by default to prevent breaking existing references. + +`te rm` accepts: + +- `` — positional argument: the object to remove. +- `--force` — bypass the dependents check. +- `--if-exists` — exit `0` without error if the object doesn't exist. Use this for idempotent CI/CD pipelines. +- `--dry-run` — preview the removal without applying it. +- `--save` — persist the change to the loaded model. + +```bash +te rm Sales/Revenue --save +te rm "'Sales'[Revenue]" --save # DAX form +te rm Sales/Revenue --dry-run # Preview only +te rm Sales/OldMeasure --if-exists --save # Idempotent +``` + +### mv + +Move or rename a model object. Both source and destination are `` arguments. + +```bash +te mv Sales/Revenue Finance/Revenue --save # Move measure to another table +te mv Sales/Revenue Sales/TotalRevenue --save # Rename measure +``` + +### replace + +Find and replace text across model objects. Dry-run by default; add `--save` to apply. + +`te replace` accepts: + +- `--in ` - scope: `names`, `expressions`, `descriptions`, `displayFolders`, `formatStrings`, `annotations`, `all` (default: `all`). +- `--regex` - treat the find pattern as a regular expression. +- `--case-sensitive` - enable case-sensitive matching. +- `--dry-run` - preview changes without applying. Default behavior. +- `--save` - persist the mutation to the source location. Mutually exclusive with `--revert` and `--stage`. +- `--save-to ` - save to a different path (implies `--save`). +- `--serialization ` - model serialization: `tmdl`, `bim`, `te-folder`. +- `--force` - save even if the replacement introduces DAX validation errors. + +`--in expressions` walks every expression-bearing property: + +- **Measure**: `Expression`, `DetailRowsExpression` +- **KPI**: `TargetExpression`, `StatusExpression`, `TrendExpression` +- **Partition**: source M, polling M +- **Table permission**: `FilterExpression` +- **Calculation group**: selection expressions +- **Calculated column**: DAX expression + +Adding new expression-shaped properties to the model surfaces them automatically. + +```bash +te replace "OldTable" "NewTable" --in expressions --save +te replace "SUM" "SUMX" --regex --in expressions --save +``` + +## Inspection + +### ls + +List objects with filesystem-like navigation. Takes a `` argument supporting wildcards. Both model-level containers (`Tables`, `Measures`, `Columns`, `Hierarchies`, `Relationships`, `Roles`, `Perspectives`, `Cultures`) and table-scoped containers (`Sales/Measures`, `Sales/Columns`, …) are supported. + +`te ls` accepts: + +- `--type ` - narrow to one object kind (`table`, `measure`, `column`, `hierarchy`, `partition`, `relationship`, `role`, `perspective`, `culture`). With no `` this is equivalent to typing the matching container keyword. +- `--paths-only` - emit one object path per line, suitable for piping to `xargs`, `te get`, or `te set`. +- `--no-multiline` - collapse multi-line cells (typically DAX or M expressions) to a single line and truncate, so rows stay scannable in wide tables. Text output only; JSON/CSV/TMSL output is unaffected. +- `--output-format tmsl` (alias `bim`) - emit the matching objects as a TMSL/BIM script. Useful for `te ls Tables --output-format bim > tables.json`. `--output-format tmdl` is not supported by `ls` (TMDL is single-object only - use `te get`). + +```bash +te ls # All tables in the model +te ls Sales # All children of Sales (columns + measures + hierarchies + partitions) +te ls Sales/Measures # Just Sales's measures +te ls 'Sales/*Amount' # Children of Sales whose name ends with Amount +te ls 'Sa*' # Tables whose name starts with Sa (no auto-expansion) +te ls '*/Amount' # An Amount column/measure across every table +te ls 'Roles/Re*/Members' # Members of every role matching Re* +te ls Sales/Geography/Levels # All levels of the Geography hierarchy +te ls "'Net Sales'/'Sales Amount'" # Quote names containing spaces +te ls Measures --paths-only # One Table/Measure per line for piping +te ls --type measure # Same as `te ls Measures` +te ls Measures --no-multiline # Wide table with column dividers, single-line DAX +te ls Tables --output-format bim > tables.json # All tables emitted as TMSL/BIM +``` + +### get + +Get properties of a model object. Takes a ``. + +`te get` accepts: + +- `-q, --query ` - fetch a single property (e.g. `expression`, `formatString`). +- `-t, --type ` - disambiguate when the path matches multiple table-children (e.g. a column and a hierarchy with the same name). Values: `Measure`, `Column`, `CalculatedColumn`, `Hierarchy`, `Calendar`, `Partition`, `CalculationItem`. +- `--output-format tmsl` (alias `bim`) - emit the resolved object as TMSL/BIM JSON. +- `--output-format tmdl` - emit the resolved object as TMDL (named objects only). + +`te get` and `te ls` share a single descriptor catalog, so every property surfaces the same way across formats - the text table, JSON, and CSV all see the same set, and adding a new property to the model exposes it everywhere. + +```bash +te get Sales/Amount -q expression # Print DAX +te get "'Sales'[Amount]" # DAX form: same as Sales/Amount +te get "[Total Sales]" # Lone-bracket: model-wide measure-or-column +te get "'Net Sales'[Sales Amount]" -q expression # DAX form with spaced names +te get "Sales/Revenue/KPI" # KPI sub-object of a measure +te get Sales --output-format tmdl # Emit the table as TMDL +te get Sales --output-format bim # Emit the table as TMSL/BIM +te get Model -q description +``` + +### find + +Search for text across model objects. + +`te find` accepts: + +- `--in ` - as per `te replace` (default `all`). +- `--regex`, `--case-sensitive`, `--paths-only`. +- `--no-multiline` - collapse multi-line match context to a single line. Text output only. + +`--in expressions` covers every `IExpressionObject` in the model - including KPI `TargetExpression` / `StatusExpression` / `TrendExpression`, measure `DetailRowsExpression`, partition source/polling M, table-permission `FilterExpression`, and calculation-group `MultipleOrEmptySelection` / `NoSelection` expressions - so a literal like `123` set on a KPI's target turns up the same way a measure body would. + +```bash +te find "CALCULATE" --in expressions +te find "Revenue" --in names +te find "CALCULATE" --in expressions --paths-only | xargs -I{} te get {} -q expression +``` + +### diff + +Compare two models for structural differences. Returns the following exit codes: `0` = identical, `1` = differences found, `2` = error. + +```bash +te diff ./model-v1 ./model-v2 +te diff old.bim new.bim +``` + +### deps + +Analyze an object's upstream and downstream dependencies, or surface unused objects across the model. The single-object form takes a ``. + +`te deps` accepts: + +- `--unused` - list measures, calculated columns, and **all data columns** that no DAX references and that aren't used in any relationship, hierarchy level, sort-by, variation, AlternateOf base, or calendar time role. Each result shows `(hidden)` in text mode and an `isHidden` field in JSON. +- `--hidden` - narrow `--unused` to hidden objects only. Hidden, unused objects are the safest prune candidates because nothing user-facing depends on them. + +```bash +te deps Sales/Revenue # Upstream + downstream for one object +te deps "'Sales'[Revenue]" # DAX form is accepted everywhere a is +te deps --unused # All unused measures and columns +te deps --unused --hidden # Only hidden, unused objects +``` + +## Analysis and quality + +### validate + +Validate model expressions, schema integrity, and TOM errors. + +`te validate` accepts: + +- `--ci ` - emit CI annotations to stderr: `vsts` or `github`. +- `--trx ` - write results as a VSTEST `.trx` file. + +```bash +te validate ./model +te validate --ci github --trx results.trx +``` + +### bpa run + +Run Best Practice Analyzer rules against a model. + +`te bpa run` accepts: + +- `` - positional argument: path to model (alternative to the `--model` global flag). +- `-r, --rules ` - path(s) or URL(s) to additional BPA rule file(s) in JSON format. Repeatable. +- `--no-model-rules` - exclude BPA rules embedded in the model's annotations. +- `--no-defaults` - exclude built-in default BPA rules. +- `--vpax ` - load VertiPaq Analyzer stats from a `.vpax` file to enable VPA-aware rules. +- `--vpa-rules` - include built-in VPA-aware rules (requires `--vpax` or a pre-annotated model). +- `--allow-external-rules` - allow fetching BPA rule files from URLs embedded in model annotations. +- `--rule ` - run only specific rule(s) by ID. Repeatable. +- `--path ` - limit analysis to the tables containing the matched objects. Accepts literal names, container keywords, and wildcards (e.g., `'Sales'`, `'Sa*'`, `'Sales/Measures'`, `'*/Amount'`). +- `--fix` - apply fix expressions to auto-fix violations where possible. +- `--save` - save the model back to source after applying fixes. +- `--save-to ` - save the model to a different path after applying fixes. +- `--serialization ` - model serialization: `tmdl`, `bim`, `te-folder`. +- `--fail-on ` - failure threshold: `error` (default) or `warning`. Exits with code `1` when violations meet the threshold. +- `--ci ` - emit CI logging commands to stderr: `vsts` (Azure DevOps), `github` (GitHub Actions). +- `--trx ` - write results as a VSTEST `.trx` file to the specified path. +- `--no-multiline` - collapse multi-line cell content in the violations table to a single line. Text output only. + +```bash +te bpa run --fail-on error --ci github +te bpa run --fix --save +te bpa run --rule PERF_UNUSED_HIDDEN_COLUMN +te bpa run --path Sales # Tables touched by the Sales filter only +te bpa run --path 'Sa*' # Wildcard - every table starting with Sa +te bpa run --path Sales/Measures # Path filter applied to the matched tables +``` + +### bpa rules + +Manage BPA rule collections — list, inspect, initialize, and toggle rules in your local rules file or in model annotations. Built-in rules are read-only - to skip one without losing the rest, use `te bpa rules disable` (do not edit the built-in set directly). + +Subcommands: + +| Subcommand | Purpose | +| ------------------------------- | -------------------------------------------------------------------- | +| `add [model]` | Add a new BPA rule. | +| [`disable`](#bpa-rules-disable) | Disable a built-in BPA rule for the current user. | +| [`enable`](#bpa-rules-enable) | Re-enable a previously disabled built-in BPA rule. | +| `ignore [model]` | Add a rule to the model's ignore list. | +| [`init`](#bpa-rules-init) | Create an empty BPA rules file at the resolved path. | +| [`list`](#bpa-rules-list) | List BPA rules from all sources with status. | +| `rm [model]` | Remove a BPA rule. | +| `set [model]` | Update a BPA rule's properties. | +| `unignore [model]` | Remove a rule from the model's ignore list. | + +All `te bpa rules` subcommands accept: + +- `--rules-file ` - path to a BPA rules JSON file. Defaults to the first existing entry of `bpa.rules` in your CLI config (`~/.config/te/config.json`), or the `TE_BPA_RULES` environment variable. +- `--model-rules` - operate on rules embedded in the model annotation instead of a file. + +> [!IMPORTANT] +> `te bpa rules set` and `te bpa rules rm` refuse to mutate built-in rule IDs. Attempting to do so exits with code `1` and points at `te bpa rules disable`. To customize a built-in rule's behavior, disable the built-in and add a custom copy with a different ID: +> +> ```bash +> te bpa rules disable TE3_BUILT_IN_DATE_TABLE_EXISTS +> te bpa rules add MY_DATE_TABLE_EXISTS +> ``` + +#### bpa rules list + +List rules from all sources (built-in, user, model). + +`te bpa rules list` accepts: + +- (default) Active rules only. +- `--all` - include disabled and ignored rules. +- `--disabled` - only built-in rule IDs the user has disabled via `te bpa rules disable`. +- `--ignored` - only rules whose IDs appear in `BestPracticeAnalyzer_IgnoreRules` on the model. +- `--no-defaults` - exclude built-in rules from output. + +```bash +te bpa rules list # Active rules +te bpa rules list --all # Include disabled and ignored rules +te bpa rules list --ignored +``` + +Disabled built-in rules are flagged with a `[disabled]` marker next to the rule ID. + +#### bpa rules init + +Create an empty BPA rules file (`[]`) at the configured path. Use this once before invoking `te bpa rules set` / `te bpa rules rm` against a path that does not yet exist. + +`te bpa rules init` accepts: + +- `--force` - overwrite an existing file with `[]`. Required if the target file exists. +- `--rules-file ` - target file path. Can appear before or after the `init` subcommand. + +Path resolution (first match wins): `--rules-file` → `TE_BPA_RULES` env var → first entry of `bpa.rules[]` in your CLI config → `./BPARules.json` (current working directory). + +```bash +te bpa rules init +te bpa rules init --rules-file ./MyRules.json +te bpa rules init --force +``` + +#### bpa rules disable + +Disable an individual built-in BPA rule. The rule ID is added to `bpa.disabledBuiltInRuleIds` in your CLI config. Subsequent gate runs (deploy, save, mutation) and `te bpa run` skip the disabled rule. + +The command is idempotent — running `disable` against an already-disabled rule succeeds without modifying the config. It exits with code `1` if `` is not a built-in rule; use `te bpa rules list` to see valid built-in IDs. + +```bash +te bpa rules disable TE3_BUILT_IN_DATE_TABLE_EXISTS +``` + +#### bpa rules enable + +Re-enable a previously disabled built-in BPA rule by removing the rule ID from `bpa.disabledBuiltInRuleIds`. Exits with code `1` if the rule isn't currently disabled. + +```bash +te bpa rules enable TE3_BUILT_IN_DATE_TABLE_EXISTS +``` + +### vertipaq + +Analyze VertiPaq storage statistics. + +`te vertipaq` accepts: + +- `--columns`, `--relationships`, `--partitions`, `--all`. +- `--export ` - export VertiPaq stats to a `.vpax` file for offline analysis. +- `--import ` - load a previously exported `.vpax` file and analyze it offline. +- `--obfuscate` - obfuscate names and expressions in exported VPAX. +- `--top `, `--stats`, `--annotate`, `--save`. + +```bash +te vertipaq # Columns by size (default) +te vertipaq --all # Tables, columns, relationships, partitions +te vertipaq --export stats.vpax +te vertipaq --import stats.vpax # Analyze offline +``` + +### format + +Format DAX or M/Power Query expressions. + +`te format` accepts: + +- `-e, --expression ` - format a single inline expression. +- `-p, --path ` - format a specific measure/column. +- `--lang ` - default `dax`. +- `--save` / `--save-to` - persist formatted expressions. + +```bash +te format --save # Format all DAX +te format -p Sales/Amount --save # Single measure +te format -e "SUM ( Sales[Amount] )" # Inline +te format --lang m --save # Format M +``` + +## Execution + +### query + +Execute a DAX query against a deployed model. + +`te query` accepts: + +- `-q, --query ` - inline query. +- `--file ` - query from file. +- `--limit ` - default 100. +- `-o, --output-file ` - write results to file (`.csv`, `.tsv`, `.json`, `.dax`). +- `--trace`, `--cold`, `--plan`, `--runs ` - performance tracing and benchmarking. +- `--no-validate` - skip pre-execution DAX semantic validation. + +```bash +te query -q "EVALUATE TOPN(5, 'Sales')" -s my-ws -d my-model +te query --file query.dax --output-format json +``` + +### script + +Execute one or more C# scripts against a semantic model. The CLI uses the same scripting host as Tabular Editor 3 Desktop, so a script that runs in TE3 runs unchanged here. + +`te script` accepts: + +- `-S, --script ` - `.cs` / `.csx` file (repeatable). +- `-e, --expression ` - inline C# (use `-` for stdin). +- `--save` / `--save-to` / `--serialization`. +- `--dry-run`, `--timeout `. + +```bash +te script --script fix.cs --save +te script -e "Info(Model.Tables.Count)" +echo "Info(Model.Name);" | te script -e - +``` + +> [!IMPORTANT] +> Two behavioral details to know if you're porting an older script: +> +> - **No interactive selection in CLI scripts.** The TE3 Desktop helpers `SelectMeasure()`, `SelectTable()`, `SelectColumn()`, `SelectObject()`, and `SelectObjects()` throw `NotSupportedException` when called from `te script` - the CLI has no UI to pop up. Pre-resolve the object(s) outside the script and pass them in, or wrap the call in `try/catch` if the script is shared with TE3. +> - **Default `using` directives match TE3 Desktop.** Scripts that use `DataTable`, `File`, `StringBuilder`, or `Regex` must include the corresponding `using System.Data;` / `using System.IO;` / `using System.Text;` / `using System.Text.RegularExpressions;` directive explicitly. + +> [!NOTE] +> **Preprocessor symbols for cross-host scripts.** Scripts compiled by `te script` have the symbol `TECLI` defined. TE3 Desktop scripts have `TE3` defined instead, plus version-bracketed symbols like `TE3_3_10_OR_GREATER` ... `TE3_3_X_OR_GREATER` for the current TE3 minor version. TE2 defines neither symbol. Use these to write portable scripts: +> +> ```csharp +> #if TECLI +> // CLI-only code - no UI calls +> Info($"Running under the CLI on {Environment.OSVersion.Platform}"); +> #elif TE3 +> // TE3 Desktop-only code - UI APIs available +> ShowMessage("Hello from TE3"); +> #else +> // TE2 (legacy) - neither TECLI nor TE3 is defined +> Info("Hello from TE2"); +> #endif +> +> #if TE3_3_15_OR_GREATER +> // Gated on a specific TE3 minor version +> #endif +> ``` +> +> See @csharp-scripts for the broader cross-version scripting story. + +### macro + +Manage and run macros from a macros JSON file (typically `MacroActions.json`). The macros file is resolved in this order: `--macros ` → `TE_MACROS_PATH` env var → `macros` in CLI config → `./MacroActions.json`. + +Subcommands: + +| Subcommand | Purpose | +| -------------------------------- | ----------------------------------------------------------------- | +| `list` | List macros. | +| [`run `](#macro-run) | Run a macro. | +| `add ` | Add a macro. | +| `set ` | Update macro properties. | +| `rm ` | Remove a macro. | +| `sort` | Sort and re-assign IDs. | +| [`init`](#macro-init) | Create an empty macros file at the resolved path. | + +#### macro init + +Create an empty macros file (`{"Actions":[]}`) at the configured path. Use this once when the resolved macros file does not yet exist. + +`te macro init` accepts: + +- `--force` - overwrite an existing file. Required if the target exists. +- `--macros ` - target file path. Can appear before or after the `init` subcommand. + +```bash +te macro init +te macro init --macros ./project-macros.json +te macro init --force +``` + +#### macro run + +Run a macro. Macros that emit tables via `dataTable.Output()` render formatted output in the terminal, so DAX-style query macros work the same in `te macro run` as they do in TE3. + +`te macro run` accepts: + +- `--on ` - set the macro's selection context to a single named object (a table, measure, column, …). Equivalent to right-clicking that object in TE3 and invoking the macro from the context menu. +- `--save` / `--save-to` - persist any changes the macro makes. + +```bash +te macro run "Hide all measures" +te macro run "Format DAX" --on Sales/Revenue --save +te macro run "Format DAX" --on "'Net Sales'[Sales Amount]" --save # DAX form works in --on too +``` + +## Deployment and refresh + +### deploy + +Deploy a semantic model to Power BI, Fabric, or Azure Analysis Services. + +`te deploy` accepts: + +- `-s, --server` / `-d, --database` - target workspace and model. +- `--deploy-full` - overwrite + connections + partitions + shared expressions + roles + role members. +- `--deploy-connections` +- `--deploy-partitions` +- `--skip-refresh-policy` +- `--deploy-roles` +- `--deploy-role-members` +- `--deploy-shared-expressions` +- `--create-only` +- `--xmla ` - generate XMLA/TMSL script instead of deploying (`-` for stdout). +- `--skip-bpa` - bypass the BPA gate entirely. +- `--fix-bpa` - auto-fix BPA violations where rules define a fix expression. +- `--bpa-rules ` - repeatable; override `bpa.rules` from your CLI config for this single deploy. Built-in rules still apply unless `bpa.builtInRules` is `false`. +- `--force` - skip interactive confirmation (required for CI). +- `--ci ` - `vsts` or `github`. +- `--profile ` - one-shot use of a saved @te-cli-auth profile. + +```bash +te deploy ./model -s my-workspace -d my-model --force --ci github +te deploy ./model --xmla script.tmsl # Generate TMSL only +te deploy ./model --profile staging --force +``` + +> [!IMPORTANT] +> `te deploy` runs the Best Practice Analyzer as a gate before executing. In interactive mode, a summary + confirmation prompt is shown with **`n` as the safe default**. In CI, pass `--force` to skip the prompt. See @te-cli-config for BPA gate configuration. + +### refresh + +Trigger a data refresh on a deployed model. + +`te refresh` accepts: + +- `--type ` - `full`, `dataonly`, `automatic`, `calculate`, `clearvalues`, `defragment`, `add` (default: `automatic`). +- `--table ` - refresh specific table(s); repeatable. +- `--partition ` - refresh specific partition(s). +- `--apply-refresh-policy` - apply the incremental refresh policy to determine which partitions are refreshed. +- `--effective-date ` - set the effective date used by the refresh policy. +- `--max-parallelism ` - set the maximum number of partitions to refresh in parallel. +- `--dry-run` - output the TMSL script without executing. +- `--no-progress`, `--trace [path]`. + +```bash +te refresh --type full # Full refresh +te refresh --table Sales --type full # Single table +te refresh --type full --dry-run > refresh.tmsl # Emit TMSL only +``` + +### incremental-refresh + +Manage incremental refresh policies on tables. + +```bash +te incremental-refresh show
+``` + +Additional subcommands (`set`, `remove`, `apply`) are documented via `te incremental-refresh --help`. + +## Testing + +### test run + +Run a suite of DAX assertion tests against a deployed model. + +`te test run` accepts: + +- `--suite ` - test-suite directory (default: `.te-tests/`). +- `--tag ` - only tests with this tag. +- `--fail-on ` - `error` (default) or `warning`. +- `--ci `, `--trx ` - CI annotations and TRX output. + +```bash +te test run --ci github --trx results.trx +te test run --tag revenue +``` + +### test init / spec / use / list / snapshot / compare + +Additional subcommands scaffold tests, print the assertion spec format, switch the active suite, list suites, capture snapshots, and compare models. See `te test --help` for details. + +```bash +te test init --example # Scaffold an example suite +te test spec # Print the full assertion format reference +te test init --from-model --model ./my-model # Generate stubs from your measures +``` + +## Connection and authentication + +### connect + +Set (or display) the active connection for the current terminal session. See @te-cli-auth. + +```bash +te connect # Show current active connection +te connect my-workspace my-model # Remote +te connect ./model # Local +te connect --local # Power BI Desktop (Windows) +te connect --profile prod # Activate a saved profile +te connect --clear # Clear the active connection (and any workspace mirror) +``` + +#### Workspace mode (`-w` / `--workspace`) + +Pair a primary source with a secondary target so every subsequent `--save` mirrors the model between the two. Useful for keeping a local working copy of a remote workspace, or pushing local edits to a workspace as you save. + +- `te connect -w ./src` - primary is remote; `./src` receives an initial TMDL export and mirrors every save. +- `te connect ./src -w ` - primary is local; an initial deploy pushes the model to the workspace, and subsequent saves re-deploy automatically. +- `--workspace-format ` - choose the on-disk format when mirroring to a folder/file (e.g., `-w ./model.bim` infers BIM). +- `--force` - required when the target already exists (non-empty folder, existing database). Without it, `te connect` shows an interactive `y/n` prompt with `n` as the safe default. + +Once active, `te set --save`, `te rm --save`, `te script --save`, etc. all dual-save transparently. Save order is always **local first, then remote** so the on-disk copy reflects the latest user change even if the server push fails. Clear the mirror with `te connect --clear`. + +```bash +te connect Finance "Revenue Model" -w ./revenue-model # Mirror remote → local TMDL +te connect ./revenue-model -w Finance "Revenue Model" # Mirror local → remote +``` + +### auth login / status / logout + +Manage cached authentication. See @te-cli-auth. + +### profile list / show / set / remove + +Manage named connection profiles. See @te-cli-auth. + +## Configuration + +### config show / paths / init / set + +View and manage CLI configuration and TE3 path overrides. See @te-cli-config. + +```bash +te config show # Display all settings +te config paths # Resolved TE3 file paths +te config init # Create default config +te config set autoFormat true +``` + +### license + +`te license` is reserved for the GA release and is not available in this preview build. The command is still wired up to the parser - so existing scripts that invoke it won't blow up at parse time - but every subcommand exits with status `1` and a "not available in this preview build" message. See the [Preview notice](xref:te-cli#preview-notice) on the overview page for the broader licensing outlook. + +### migrate + +Reference guide showing how legacy Tabular Editor 2 CLI flags map to the new CLI. Useful as a live lookup while porting a TE2-based pipeline. See @te-cli-migrate for the full migration guide. + +```bash +te migrate # Full flag mapping table +te migrate -A # Look up a single TE2 flag +te migrate --output-format json # Machine-readable mapping +``` + +## Shell + +### interactive + +Start a guided REPL session with a model-aware prompt. See @te-cli-interactive. + +```bash +te interactive # Connect later +te interactive ./model # Start with a local model +te interactive -s MyWorkspace -d MyModel # Start with a remote model +``` + +Quoting and DAX-style references work the same as outside the session - see the [Object paths](#object-paths) section above and @te-cli-interactive for details on bracket-aware argv splitting inside the REPL. + +### completion + +Generate a shell completion script. See @te-cli-install. + +```bash +te completion bash +te completion zsh +te completion pwsh +``` + +## Exit codes + +| Exit | Meaning | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0` | Success. | +| `1` | Generic failure (invalid arguments, command failed, validation errors, auth failure, BPA gate failed at severity ≥ error). | +| `2` | Non-zero diff (`te diff`) - models differ. | + +For fine-grained control in CI pipelines, combine exit codes with `--ci ` annotations and `--trx` results files - see @te-cli-cicd. + +## Related pages + +- @te-cli - overview and framing. +- @te-cli-install - install and set up the CLI. +- @te-cli-auth - authenticate and manage connections. +- @te-cli-config - configuration file, BPA gate, post-mutation behavior. +- @te-cli-migrate - TE2 → TE3 flag mapping. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-config.md b/localizedContent/zh/content/features/te-cli/te-cli-config.md new file mode 100644 index 000000000..bcda9ee41 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-config.md @@ -0,0 +1,258 @@ +--- +uid: te-cli-config +title: Custom Configuration +author: Peer Grønnerup +updated: 2026-04-20 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Custom Configuration + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI reads optional configuration from a JSON file. Configuration controls three things: + +- **File paths** — where the CLI reads macros, BPA rules, and (optionally) the TE3 Desktop executable, and where to write the query log. +- **Behavioral defaults** — BPA gates, auto-format, validation. +- **Saved connection profiles** — the list of named profiles you can switch between. + +The CLI is self-contained - it does not read from or write to any Tabular Editor 3 desktop install path. BPA rules and macros files must be set explicitly via this config (or initialized on demand with `te bpa rules init` / `te macro init`). + +Most users don't need to edit the config file directly - `te config show`, `te config set `, and `te profile set` cover the common operations. + +## Config file location + +The following locations are checked in this order: + +1. `$TE_CONFIG` environment variable (if set and the file exists). +2. `~/.config/te/config.json` (on Windows, `%USERPROFILE%\.config\te\config.json`). +3. No config file - the CLI uses built-in defaults. + +`TE_CONFIG` is honored consistently by every config-file operation - `te config show`, `te config set`, `te config init`, and `te config paths` all read and write at the resolved path. This is primarily intended for testing, scripted installs, and per-environment configuration. + +To create a default config: + +```bash +te config init # Create config at TE_CONFIG (or ~/.config/te/config.json) +te config init --force # Overwrite existing config +``` + +## Viewing configuration + +```bash +te config show # Display all settings +te config show --output-format json # Machine-readable +te config paths # Show resolved macros and BPA rule paths +``` + +Use `te config paths` to see which files the CLI will actually use for macros and BPA rules. It's handy when debugging missing data files. The output shows two rows: `macros` (the resolved macros file path or `[not set]`) and `bpa.rules` (the first existing BPA rules file resolved by the path resolver, or `[not set]`). + +> [!NOTE] +> `te config paths` emits `null` fields explicitly in `--output-format json` mode (e.g., `{"macros": null, "bpa": {"rules": null}}`). Reporting resolution outcomes is the command's whole purpose, so `null` is a meaningful "tried but resolved to nothing" answer. `te config show --output-format json` strips null fields by default, so consumers should parse it tolerantly. + +## Setting values + +```bash +te config set autoFormat true +te config set bpa.onDeploy false +te config set hidePreviewNotice true +te config set macros null # Clear a path override +``` + +Unknown keys fail with exit code `1` and an error that lists the valid keys. + +If no config file exists, `te config set` auto-creates one at the resolved path (`$TE_CONFIG` if set, otherwise `~/.config/te/config.json`) before applying the change. + +> [!NOTE] +> Every key in the schema is settable via `te config set`, including nested keys via dotted paths (`bpa.onDeploy`, `formatOptions.useSqlBiDaxFormatter`, etc.). The only exception is `formatVersion`, which the CLI manages automatically. Run `te config paths` to find the config file if you'd rather edit the JSON directly. + +## Full schema + +The complete JSON config schema with all keys at their default values. Use this as a reference when editing the config file directly, or when looking up the dotted path for a `te config set` call. + +```json +{ + "formatVersion": 1, + "macros": null, + "autoFormat": false, + "validateOnMutation": true, + "vertipaqOnRefresh": false, + + "bpa": { + "rules": null, + "onDeploy": true, + "onSave": true, + "onMutation": false, + "builtInRules": true, + "disabledBuiltInRuleIds": null + }, + + "interactiveEditMode": "stage", + + "formatOptions": { + "useSemicolons": false, + "shortFormat": false, + "skipSpaceAfterFunction": false, + "useSqlBiDaxFormatter": false + }, + + "hidePreviewNotice": false, + "spinner": true, + "debug": false, + "disableTelemetry": false, + + "queryLog": null, + "te3ExePath": null, + + "profiles": {} +} +``` + +### File paths + +Set these in your config to avoid passing the same paths on every command. Per-command flags and environment variables override config values; see [Path resolution priority](#path-resolution-priority) below. + +| Key | Meaning | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `macros` | Explicit path to a macros JSON file (typically `MacroActions.json`). Resolved by every `te macro` command. Point at a shared file (network share, repo-local, or even the TE3 desktop file) to reuse the same set of macros across machines and between the CLI and TE3 Desktop. | +| `bpa.rules` | Ordered list of paths or URLs to BPA rule files. The deploy/save gate loads **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. | +| `te3ExePath` | Explicit path to the Tabular Editor 3 Desktop executable (`TabularEditor.exe`). Used **only** by `te open` to launch the desktop app; safe to leave unset on Linux/macOS or when you don't use `te open`. If unset, `te open` falls back to a `PATH` lookup. | +| `queryLog` | Path to a log file where every `te query` invocation appends its query text and execution metadata. Useful for audit trails or analyzing query patterns over time. Supports `~` for the home directory (e.g., `~/.config/te/queries.log`). | + +### Path resolution priority + +For each user-provided file (macros, BPA rules), the CLI resolves the path in this order: + +1. **Command-line flag** - `--macros ` for macro commands; `--bpa-rules ` for the deploy/save gate; `--rules-file ` for `te bpa rules` subcommands. +2. **Environment variable** - `TE_MACROS_PATH` for macros, `TE_BPA_RULES` for BPA rules. +3. **CLI config** - `macros` for macros, the first existing entry of `bpa.rules[]` for BPA rules. + +The CLI does not auto-detect any TE3 install location - configure these explicitly. To start from a default file in the current working directory, run `te macro init` (creates `./MacroActions.json`) or `te bpa rules init` (creates `./BPARules.json`). + +Run `te config paths` to see which file the CLI actually resolved. + +### Behavioral defaults + +All BPA-related settings live under the `bpa` object and are addressed via dotted keys on `te config set`. + +| Key | Default | Description | +| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `autoFormat` | `false` | Run the DAX Formatter on modified expressions after `te add` / `te set` / `te mv` / `te macro run`. Uses the in-house formatter by default; opt into the SQL BI web service via `formatOptions.useSqlBiDaxFormatter`. | +| `validateOnMutation` | `true` | After a mutating command (`add`, `set`, `mv`, `replace --save`, `macro run`), check that every `Table[Column]` reference in the model still resolves. Catches dangling references introduced by renames or removals before they reach deploy. | +| `bpa.onMutation` | `false` | Run a scoped BPA analysis after each mutating command (`set`, `add`, `mv`, `rm`, `macro run`). Only the affected table's objects are checked, not the whole model - useful for fast feedback during iterative edits. | +| `bpa.onDeploy` | `true` | Run the BPA gate before `te deploy` executes. The deploy is aborted if any rule fires at severity ≥ error. Bypass per-invocation with `--skip-bpa`, or auto-fix with `--fix-bpa`. | +| `bpa.onSave` | `true` | Run the BPA gate before `te save -o` writes to disk. Bypass per-invocation with `--skip-bpa` or `--force`. | +| `bpa.builtInRules` | `true` | Include the curated built-in BPA rule set whenever the gate runs. Set to `false` to ignore built-ins entirely; the gate then runs only the rules configured via `bpa.rules` and any model-embedded rules. | +| `bpa.disabledBuiltInRuleIds` | `null` | IDs of individual built-in rules to exclude from the gate. Mutated by `te bpa rules disable ` / `te bpa rules enable ` - prefer those over editing the array directly. | +| `vertipaqOnRefresh` | `false` | After a successful refresh (`full`, `dataonly`, `automatic`, or `add`), automatically run VertiPaq analysis to show storage stats for the refreshed tables. Useful for catching unexpected cardinality or memory regressions immediately. | +| `interactiveEditMode` | `stage` | Default behavior for in-memory mutations inside `te interactive`. `stage` keeps mutations in memory until `save` is invoked (safest); `save` writes to source after every mutating command (use with care on remote sources - every `set` triggers an XMLA write); `revert` discards mutations after each command unless `--save` or `--stage` was passed. Per-command `--save` / `--revert` / `--stage` flags always override. | +| `disableTelemetry` | `false` | Opt out of anonymous usage telemetry. The CLI collects coarse-grained command usage data (command name, exit code, duration) to inform feature priority. The CLI never collects model content, paths, or query text. | + +```bash +te config set bpa.rules "/etc/te/team.json,/etc/te/strict.json" +te config set bpa.onDeploy true +te config set bpa.builtInRules false +te config set bpa.disabledBuiltInRuleIds "TE3_BUILT_IN_DATE_TABLE_EXISTS,TE3_BUILT_IN_HIDE_FOREIGN_KEYS" +``` + +### Format options + +Applied whenever the CLI invokes a DAX formatter (for `te format` and, when enabled, `autoFormat` on mutations). The CLI ships with an in-house formatter that works fully offline; opt into the SQL BI [daxformatter.com](https://www.daxformatter.com) web service via `formatOptions.useSqlBiDaxFormatter` if you need that style or want to match the behavior of TE2 or TE3 with "Use daxformatter.com..." enabled. + +| Key | Default | Description | +| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `formatOptions.useSemicolons` | `false` | Use `;` as the list separator (European/EU locale convention). The default `,` matches the en-US locale. | +| `formatOptions.shortFormat` | `false` | Prefer short, single-line formatting where possible instead of the default multi-line layout. | +| `formatOptions.skipSpaceAfterFunction` | `false` | Omit the space between a function name and its opening parenthesis (e.g. `SUM(x)` instead of `SUM (x)`). | +| `formatOptions.useSqlBiDaxFormatter` | `false` | Format DAX via the [SQL BI daxformatter.com](https://www.daxformatter.com) web service instead of the in-house formatter. Requires internet access. The in-house formatter (default) works offline and matches the Tabular Editor 3 Desktop default. | + +### Display + +Settings that control the CLI's terminal output and diagnostic verbosity. + +| Key | Default | Description | +| ------------------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `hidePreviewNotice` | `false` | Suppress the yellow preview banner. **Ignored within 14 days of expiry.** | +| `spinner` | `true` | Show animated progress indicators in the terminal. Disable for CI. | +| `debug` | `false` | Always enable debug logging (same as passing `--debug`). | + +### Profiles + +Saved connection profiles live under the `profiles` key. Don't edit them by hand - use `te profile set / remove / list`. See @te-cli-auth for profile management. + +Profiles can carry **overrides** that override the behavioral defaults above whenever the profile is active. This is how a dev profile can relax validation and BPA while a prod profile keeps them strict: + +```bash +te profile set dev --validate-on-mutation false --bpa-on-deploy false +te profile set prod --auto-format true +``` + +## BPA gate + +The BPA gate is the safety net that prevents a model with rule violations from being saved or deployed. It runs automatically when the following commands are executed: + +- `te deploy` runs the gate unless `--skip-bpa` is passed or `bpa.onDeploy` is `false`. +- `te save` runs the gate unless `--skip-bpa` (or `--force`) is passed or `bpa.onSave` is `false`. +- `te add`, `te set`, `te mv`, `te macro run` run the gate only when `bpa.onMutation` is `true`. + +The gate loads BPA rules from `bpa.rules` and, by default, the built-in rule set (controlled by `bpa.builtInRules`). Built-in rules can be individually excluded via `bpa.disabledBuiltInRuleIds` - managed with `te bpa rules disable ` / `te bpa rules enable `. + +When the gate fires and finds violations at severity ≥ `error`, the command fails with exit code `1` and a summary of the violations. Options to resolve: + +- `--fix-bpa` - apply the rule's `fixExpression` in memory for the deploy/save artifact; source files are not modified. +- `--skip-bpa` - disable the gate for this one command. +- `--bpa-rules ` - repeatable; override `bpa.rules` for this single `te deploy` or `te save` invocation. Built-in rules still apply unless `bpa.builtInRules` is `false`. + +Run `te bpa run` independently to preview the gate's behavior without deploying: + +```bash +te bpa run ./model --fail-on error +te bpa run ./model --fix --save # Apply fixes to the source +``` + +### Built-in BPA rules + +The CLI ships a single canonical set of built-in BPA rules embedded as a JSON resource. Built-in rules are read-only - `te bpa rules set` and `te bpa rules rm` refuse to mutate built-in IDs and point users at `te bpa rules disable` instead. To customize a built-in rule's behavior, copy it into your local rules file as a new rule with a different ID and disable the built-in. + +Both `bpa.builtInRules` and `bpa.disabledBuiltInRuleIds` apply consistently to the deploy/save/mutation gate **and** the manual `te bpa run` command - disabling a rule once via `te bpa rules disable` excludes it everywhere. + +## Post-mutation behavior + +When you run a mutating command (`te add`, `te set`, `te mv`, `te replace --save`, `te macro run`), the CLI performs these checks automatically: + +1. **TOM errors** are always surfaced. Invalid DAX or M in measures, columns, partitions, or calculation items always fails the command. +2. **Schema validation** (`validateOnMutation`, default `true`) verifies that `Table[Column]` references in DAX still resolve, cross-checking metadata consistency. +3. **DAX auto-format** (`autoFormat`, default `false`) formats any expressions touched by the mutation via the built-in DAX Formatter when enabled. +4. **BPA on mutation** (`bpa.onMutation`, default `false`) runs BPA after the mutation when enabled, warning or failing based on `--fail-on`. + +Disable a check with `te config set false`, or scope the relaxation to a specific environment via a profile. + +## Environment variables + +Use the following CLI-specific environment variables for paths, behavior, and diagnostics. For Azure authentication variables (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_CERTIFICATE_PATH`, etc.), see @te-cli-auth. + +| Variable | Purpose | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TE_CONFIG` | Path to an alternative config file. Honored by every `te config` operation (`show`, `set`, `init`, `paths`). | +| `TE_MACROS_PATH` | Override the macros file path (second in resolution order - see above). Read by `te macro` commands. | +| `TE_BPA_RULES` | Override the BPA rules file/URL list used by `te bpa run` and `te bpa rules` subcommands. | +| `TE_BPA_CONFIG` | Override the path to the BPA gate config (`.te-bpa.json`) the deploy/save gate reads. | +| `TE3_EXE_PATH` | Path to the Tabular Editor 3 desktop binary. Used **only** by `te open`; safe to leave unset on Linux/macOS or when you don't use `te open`. Falls back to `PATH` lookup. | +| `TE_DEBUG` | Set to `1` to enable debug logging globally (same as `--debug` or `debug: true` in config). | +| `NO_SPINNER` | Set to `1` or `true` to disable animated progress indicators (alternative to `spinner: false` in config). | +| `CI` | Auto-detected. When `1` or `true`, the CLI disables the spinner and switches to plain output. Most CI runners set this automatically. | +| `TE_SESSION` | Override the per-terminal session ID used for active-connection state. Useful for running multiple isolated CLI sessions inside the same shell, e.g. in parallel CI matrix jobs. | +| `TE_COMPAT` | Set to `te2` to force TE2-compatibility mode - see @te-cli-migrate. | + +## Related pages + +- @te-cli-auth - profiles, authentication, and credential storage. +- @te-cli-commands - `te config` subcommands. +- @te-cli-cicd - configuring the BPA gate for pipelines. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-install.md b/localizedContent/zh/content/features/te-cli/te-cli-install.md new file mode 100644 index 000000000..dfb89c1a7 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-install.md @@ -0,0 +1,201 @@ +--- +uid: te-cli-install +title: Installation and Setup +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Installation and Setup + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +The Tabular Editor CLI ships as a single self-contained executable named `te` (`te.exe` on Windows). It has no external runtime dependencies. + +## 下载 + +1. Sign in at [tabulareditor.com](https://tabulareditor.com/download-tabular-editor-cli) with a Tabular Editor account. +2. Download the archive for your platform and architecture: + + | Platform | 64-bit (Intel/AMD) | ARM64 | Archive | + | -------- | ---------------------------------------------- | -------------------------------------------------------- | --------- | + | Windows | `te-win-x64.zip` | `te-win-arm64.zip` | `.zip` | + | macOS | `te-osx-x64.tar.gz` (Intel) | `te-osx-arm64.tar.gz` (Apple Silicon) | `.tar.gz` | + | Linux | `te-linux-x64.tar.gz` | `te-linux-arm64.tar.gz` | `.tar.gz` | + + Pick the ARM64 build on Apple Silicon Macs (M1 and newer), Windows on ARM devices, and ARM-based Linux servers (including AWS Graviton, Azure Ampere, and Raspberry Pi 64-bit). Pick the `x64` build on everything else. + +## Install + +Unzip the archive into a folder of your choice and add that folder to `PATH` so you can invoke `te` from any working directory. + +### Windows (PowerShell) + +#### x64 + +```powershell +Expand-Archive te-win-x64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\te" +[Environment]::SetEnvironmentVariable( + "PATH", + [Environment]::GetEnvironmentVariable("PATH", "User") + ";$env:LOCALAPPDATA\Programs\te", + "User") +``` + +#### ARM64 + +```powershell +Expand-Archive te-win-arm64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\te" +[Environment]::SetEnvironmentVariable( + "PATH", + [Environment]::GetEnvironmentVariable("PATH", "User") + ";$env:LOCALAPPDATA\Programs\te", + "User") +``` + +### macOS + +#### Apple Silicon (ARM64) + +```bash +mkdir -p ~/.local/bin +tar -xzf te-osx-arm64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc +``` + +#### Intel (x64) + +```bash +mkdir -p ~/.local/bin +tar -xzf te-osx-x64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc +``` + +On macOS, the binary is signed with our Apple Developer ID and notarized by Apple, so the first run completes without a "cannot verify developer" Gatekeeper warning. Network access on first run is recommended so Gatekeeper can fetch the notarization ticket; offline first-runs may briefly prompt before being unblocked once network returns. + +### Linux + +#### x64 + +```bash +mkdir -p ~/.local/bin +tar -xzf te-linux-x64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc +``` + +#### ARM64 + +```bash +mkdir -p ~/.local/bin +tar -xzf te-linux-arm64.tar.gz -C ~/.local/bin +chmod +x ~/.local/bin/te +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc +``` + +> [!NOTE] +> The PATH change takes effect in **new** shell sessions. To run `te` in the shell where you ran the install, open a new terminal, or reload your profile: `source ~/.bashrc` / `source ~/.zshrc` on macOS/Linux, or close and reopen PowerShell on Windows. + +## Verify + +Check the installed version and list available commands: + +```bash +te --version +te --help +``` + +`te --help` prints a colorized help index grouping commands by family. Every subcommand accepts `--help` for detailed usage: + +```bash +te deploy --help +te bpa run --help +``` + +## Hide the preview banner + +The CLI prints a yellow preview banner on stderr by default. To suppress it run: + +```bash +te config set hidePreviewNotice true +``` + +> [!WARNING] +> The banner reappears on every command within **14 days of the preview end date** (2026-09-30), regardless of `hidePreviewNotice`. This ensures you have visible warning before the CLI stops functioning. + +## Shell completion + +The CLI provides tab-completion scripts for **Bash**, **Zsh**, and **PowerShell**. Pick the block that matches your shell — each one installs the completion persistently for new shell sessions. + +### Bash (macOS/Linux) + +```bash +mkdir -p ~/.local/share/bash-completion/completions +te completion bash > ~/.local/share/bash-completion/completions/te +``` + +### Zsh (macOS/Linux) + +```zsh +mkdir -p ~/.zfunc +te completion zsh > ~/.zfunc/_te +echo 'fpath=(~/.zfunc $fpath); autoload -U compinit; compinit' >> ~/.zshrc +``` + +### PowerShell (Windows/macOS/Linux) + +```powershell +Add-Content $PROFILE 'te completion pwsh | Out-String | Invoke-Expression' +``` + +Open a new shell session for completion to take effect. + +Completion covers subcommands, global flags, and model paths (where tab-completion against the filesystem is meaningful). + +## Cross-platform feature matrix + +Most features are identical across platforms. A handful depend on Windows-only transports: + +| Feature | Windows | macOS / Linux | +| ---------------------------------------------------------------------------------------------- | ------- | ------------- | +| Load/save BIM and TMDL | Yes | Yes | +| Deploy to Power BI / Fabric / Azure Analysis Services | Yes | Yes | +| Best Practice Analyzer and VertiPaq Analyzer | Yes | Yes | +| C# scripting | Yes | Yes | +| DAX queries against cloud models | Yes | Yes | +| Authentication: browser, device-code, service principal, env, managed identity | Yes | Yes | +| Connect to local SSAS instance (TCP transport) | Yes | **No** | +| Connect to Power BI Desktop (named-pipe transport) | Yes | **No** | + +> [!IMPORTANT] +> Local SSAS and Power BI Desktop connections rely on Windows-only transport protocols. All cloud-based workflows (Power BI Service, Fabric, Azure Analysis Services) work on every platform. + +## Updating + +To update to a newer preview build, download the latest archive and overwrite the previous installation. Configuration and cached credentials are stored outside the install folder (see and ) and are preserved across updates. + +## Uninstalling + +1. Delete the install folder. +2. Remove the PATH entry. +3. (Optional) Clear cached credentials and config: + - Run `te auth logout` first - it removes all cached tokens and SPN records from the active backend (OS keystore or file fallback). + - Delete `~/.config/te/` (config and saved profiles). + - Delete `~/.te-cli/` (residual cache files; only present when the file fallback was in use, or as legacy from older CLI builds). + - To also purge the OS-native keystore entries - usually unnecessary, since `te auth logout` already clears them - see: + - **Windows:** Credential Manager → Windows Credentials → entries named `com.tabulareditor.cli...` or `te-cli`. + - **Linux:** `secret-tool search Component te-cli` and `secret-tool clear ...`, or use seahorse. + - **macOS:** Keychain Access → search for `com.tabulareditor.cli`. + +## Next steps + +- @te-cli-auth - authenticate to Power BI, Fabric, or Azure Analysis Services. +- @te-cli-commands - full command reference. +- @te-cli-interactive - guided REPL mode. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-interactive.md b/localizedContent/zh/content/features/te-cli/te-cli-interactive.md new file mode 100644 index 000000000..c264d93f0 --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-interactive.md @@ -0,0 +1,98 @@ +--- +uid: te-cli-interactive +title: Interactive Mode +author: Peer Grønnerup +updated: 2026-05-12 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Interactive Mode + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +Interactive mode is a guided read-eval-print loop (REPL) for exploring a model from the terminal. It's the gentlest on-ramp for users who are new to command lines, and a convenient workspace for ad-hoc sessions against a single model. + +## Starting a session + +To Start a session run any of these commands: + +```bash +te interactive # Start and connect to a model later +te interactive ./model # Start with a local model +te interactive -s MyWorkspace -d MyModel # Start with a remote model +``` + +The session prints a welcome banner, shows the active model, and opens you at a model-aware prompt: + +![Tabular Editor CLI interactive mode session](~/content/assets/images/features/cli/cli-interactive-mode.png) + +If no model is set, the prompt is just `te>` - simply use `connect` for connection picker, `connect ` or `connect ` to connect to one. + +## Commands inside the session + +Once a REPL has started, every `te` subcommand is available **without the `te` prefix**: + +``` +ls tables +get "Sales/Revenue" -q expression +query -q "EVALUATE TOPN(5, 'Sales')" +bpa run --fail-on error +``` + +Each command accepts `--help` the same way it does outside the session: + +``` +deploy --help +``` + +## Quoting and DAX-style paths + +The REPL line splitter recognises the same quoting forms as [object paths](xref:te-cli-commands#object-paths) so DAX-shaped references are interpreted as a single argument: + +- `'...'` and `"..."` - single- and double-quoted segments. The quote characters are stripped, doubled quotes escape a literal occurrence. +- `[...]` - bracketed segment. **Brackets are preserved** in the resulting argument so a path like `'Internet Sales'[Sales Amount]` reaches the command as one token that the path parser can re-interpret as a DAX reference. Doubled closing brackets (`]]`) stay verbatim for the same reason. + +``` +get 'Internet Sales'[Sales Amount] # One argument, DAX form +get [Total Sales] # Lone-bracket model-wide lookup +ls 'Net Sales'/'Sales Amount' # Quoted segments with a slash separator +``` + +Unterminated groups absorb to end of line, so a stray opening quote or bracket fails with an explicit error rather than splitting silently. + +## Built-in REPL commands + +These are handled by the REPL itself, not the regular command tree: + +| Command | Purpose | +| ---------------------- | ------------------------------------------------- | +| `help` or `?` | List available commands. | +| `status` or `pwd` | Show the active model/connection. | +| `clear` or `cls` | Clear the screen. | +| `exit`, `quit`, or `q` | Exit interactive mode. | + +## Guided prompts + +When interactive mode is active, commands that need missing input prompt for it instead of failing. Running `auth` without a subcommand opens a picker for Login / Status / Logout; running `deploy` without `--force` shows a summary and asks for confirmation (`n` is the safe default). + +To disable prompts for a single command inside the session, pass `--non-interactive`. + +## When to use interactive vs. non-interactive + +- **Interactive mode** is best for exploration, learning the CLI, one-off bulk edits against a single model, and demos. +- **Non-interactive mode** (the default outside `te interactive`) is what you reach for when scripting, automating, or running in CI. See @te-cli-automation and @te-cli-cicd. + +The two share the same command tree - anything you run inside `te interactive` can be pasted into a shell script by prefixing it with `te`. + +## Related pages + +- @te-cli-commands - full command reference. +- @te-cli-auth - connect to workspaces and manage profiles. +- @te-cli-automation - when to leave interactive mode. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-limitations.md b/localizedContent/zh/content/features/te-cli/te-cli-limitations.md new file mode 100644 index 000000000..d7d378f8d --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-limitations.md @@ -0,0 +1,90 @@ +--- +uid: te-cli-limitations +title: Known Limitations +author: Peer Grønnerup +updated: 2026-05-20 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Known Limitations + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +This page lists known limitations of the Tabular Editor CLI (`te`) so you can plan around them and avoid common pitfalls. It is updated with each release; if you find an issue that is not listed here, please file it in the public [TabularEditor/CLI](https://github.com/TabularEditor/CLI) repository. + +> [!NOTE] +> Limitations are grouped by area. Each entry describes the constraint and, where one exists, a workaround or the recommended CLI-friendly alternative. + +## Scripting + +The CLI runs C# scripts (`te script`) against the same `Model` object you use in Tabular Editor 2 and 3, but it is a headless console host. Anything that depends on a Windows Forms UI, on the TOM Explorer selection, or on a live UI-side service (macro registry, online DAX Formatter, live VertiPaq Analyzer) behaves differently - usually by being empty, no-op, or returning an error. + +| Limitation | Notes / Workaround | +| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`System.Windows.Forms` not loaded** | The CLI uses a cross-platform `TOMWrapper` build that strips all WinForms-coupled code; the WinForms assembly is never loaded into the AppDomain. Scripts that reference `System.Windows.Forms` types (`MessageBox`, `Form`, file pickers, custom dialogs, …) fail to compile. Refactor any UI interaction into script arguments, environment variables, or stdin. | +| **`Selected.` returns an empty enumerable** | `Selected.Tables`, `Selected.Measures`, `Selected.Columns`, `Selected.Hierarchies`, etc. iterate to nothing in the CLI - no compile or runtime error, just no rows. Replace with explicit lookups: `Model.AllMeasures.Where(...)`, `Model.Tables["Sales"].Measures`, or pass object paths via `te script --args`. | +| **`Selected.` throws an error at runtime** | `Selected.Table`, `Selected.Measure`, `Selected.Column`, `Selected.Hierarchy`, etc. return an error because they require exactly one selected object of that type and the CLI selection is always empty. Reference the object directly - e.g. `Model.Tables["Sales"]`. | +| **`Selected.ActivePerspectives` and `Selected.ActiveCulture`** | Always return an empty collection and `null` respectively. Set the perspective or culture explicitly in the script if needed. | +| **`Select` dialogs throw `NotSupportedException`** | `SelectTable`, `SelectColumn`, `SelectMeasure`, `SelectObject`, `SelectObjects` (and all overloads) return the following error: _"Object selection dialogs … are not available in CLI scripts. Pre-select the object by name or path before scripting."_ Resolve targets up front from script arguments, config, or by querying the model. | +| **`Info` / `Warning` / `Error` / `Output` write to the console** | These still work, but route to stdout/stderr instead of opening a dialog. They never block and never offer an "ignore further popups" prompt. Safe to use in CI. | +| **`ShowPrompt(...)` always returns `Cancel`** | No interactive confirmation is possible. Pre-decide the answer via script arguments or configuration. | +| **`SuspendWaitForm` / `WaitFormVisible` are no-ops** | The "Please wait" spinner is a TE3 UI element. `WaitFormVisible` is a settable flag with no visual effect, and `SuspendWaitForm` is silently ignored - existing scripts continue to compile. | +| **`host.Macro(...)` / `CustomAction(...)` throws and error** | The CLI does not load `%APPDATA%/TabularEditor3/MacroActions.json`, so invoking a macro from inside a script returns an error. Inline the macro logic, or call the macro's underlying script file directly. | +| **`table.GetCardinality()` / `column.GetTotalSize()` return 0** | The in-script VertiPaq cardinality helpers have no live VPA in the CLI host. For VPA statistics, load a VPAX explicitly and use `host.Vpa.*`, or run [`te vertipaq`](xref:te-cli-commands#vertipaq). | + +## Best Practice Analyzer + +| Limitation | Notes / Workaround | +| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **BPA rule sources must be HTTPS URLs or local file paths** | Only `https://` URLs and bare local file paths are accepted. `http://` is recognized but deliberately rejected at load time with a clear error - BPA rules are executable rule expressions, and fetching them over an unauthenticated channel would be a tampering risk. Other URL schemes (`file://`, `ftp://`, …) are not supported. Applies to both `te bpa run --rules` and the rule list configured via [`te config set`](xref:te-cli-commands#config-show--paths--init--set). | +| **Rule-URL validation runs at gate time, not on `te config set`** | A typo such as `http://` is accepted by `te config set` and only surfaces when BPA actually runs. After editing the configured rule sources, run `te bpa run` (or `te validate`) once to verify each URL loads. | +| **`--rules` does not suppress built-in rules** | When `te bpa run --rules ` is passed, the supplied rules replace the entries in [`bpa.rules`](xref:te-cli-commands#config-show--paths--init--set) and `TE_BPA_PATH` for that invocation, but the built-in defaults still load alongside. To run only the explicit rule file, also pass `--no-defaults`. | +| **No per-invocation flag to skip `bpa.rules` config** | Once `bpa.rules` is configured, every `te bpa run` loads those rules in addition to the built-ins. There is currently no flag to skip the configured rule files for a single run. Workaround: pass `--rules ` explicitly - the flag fully replaces `bpa.rules` and `TE_BPA_PATH` for that invocation. | + +## Validation + +| Limitation | Notes / Workaround | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`te validate` cannot auto-fix Code Action violations** | `te validate` reports Code Action violations but offers no CLI flag to apply the suggested fix. Apply the fix in Tabular Editor 3, or use `te bpa run --fix` for the subset of Code Actions that overlap with BPA rules. | + +## Model I/O + +| Limitation | Notes / Workaround | +| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **`--serialization` cannot combine a serialization with a PBIP container** | The `--serialization` option on [`te save`](xref:te-cli-commands#save) treats `bim`, `tmdl`, `te-folder`, and `pbip` as mutually exclusive, so you cannot currently produce a PBIP container around a TMSL-serialized (`.bim`) model. Save TMDL inside PBIP, or save `.bim` outside a PBIP wrapper. | + +## Authentication + +| Limitation | Notes / Workaround | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Only one cached identity per auth method** | The CLI caches one UPN (interactive) identity and one SPN (service principal) identity at a time. Switching to a different user or tenant under the same auth method requires `te auth logout` followed by `te auth login` again, which invalidates the previous cache. | + +## Command-line input + +| Limitation | Notes / Workaround | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **DAX object paths with spaces must be enclosed in shell quotes** | When a table or column name contains spaces, the entire DAX object reference must be wrapped in shell quotes from the terminal: `te get "'My Table'[My Column]"`. Without the outer quotes, the shell splits the path into multiple arguments and parsing fails. Inside [`te interactive`](xref:te-cli-interactive) no shell quoting is needed because the REPL receives the raw input before the shell breaks it into arguments. | + +## TE2 parity + +| Limitation | Notes / Workaround | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`te schemacheck` is not yet implemented** | The TE2 `-SC` / `-SCHEMACHECK` flag has no `te` equivalent today; schema-drift detection against source data sources is planned for a future release. See @te-cli-migrate for the full TE2-to-`te` flag-mapping table. | + +## Reporting a missing limitation + +If a behavior surprises you and it's not listed here, please open an issue at [TabularEditor/CLI](https://github.com/TabularEditor/CLI/issues) with the command you ran, the output you saw, and the output you expected. Confirmed limitations are added to this page in the next release. + +## Related pages + +- @csharp-scripts - full C# scripting reference (UI and CLI). +- @script-helper-methods - list of `ScriptHost` helper methods and how they behave in the CLI. +- @te-cli-commands - full CLI command reference. +- @te-cli-automation - patterns for using the CLI in scripts and pipelines. diff --git a/localizedContent/zh/content/features/te-cli/te-cli-migrate.md b/localizedContent/zh/content/features/te-cli/te-cli-migrate.md new file mode 100644 index 000000000..6ae97fa4f --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli-migrate.md @@ -0,0 +1,111 @@ +--- +uid: te-cli-migrate +title: Migrating from the TE2 Command Line +author: Peer Grønnerup +updated: 2026-05-06 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Migrating from the TE2 Command Line + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +Teams with existing build pipelines that invoke `TabularEditor.exe` with TE2-style flags (`-S`, `-A`, `-D`, `-O`, `-C`, etc.) can adopt the new CLI incrementally. The Tabular Editor CLI accepts both command shapes: the new subcommand-based form (`te deploy`, `te bpa run`, …) and the legacy TE2 flag syntax, via a built-in compatibility layer. + +For the legacy TE2 Windows command-line reference, see @command-line-options. + +## How TE2 compatibility works + +TE2 compatibility mode is activated in any of three ways: + +1. **Binary name.** Rename `te` to `te2` (or symlink it) and the CLI runs in TE2-exact mode. This is the drop-in replacement path: swap `TabularEditor.exe` for `te2` in your existing pipeline and the same arguments work. +2. **Environment variable.** Set `TE_COMPAT=te2` before invoking `te` to force TE2 mode. +3. **Auto-detection.** If the first argument isn't a `te` subcommand (`load`, `deploy`, …) and at least one recognized TE2 flag appears somewhere in the argument list, the CLI auto-routes to TE2 mode. This means most existing TE2 invocations work without any changes. + +```bash +# All three are equivalent - each runs in TE2 mode +./te2 Model.bim -S fix.csx -D "localhost\tabular" MyDB -O +TE_COMPAT=te2 te Model.bim -S fix.csx -D "localhost\tabular" MyDB -O +te Model.bim -S fix.csx -D "localhost\tabular" MyDB -O +``` + +> [!NOTE] +> TE2 mode runs the same `Load → Scripts → Schema Check → Save → BPA → Deploy → TRX` pipeline as `TabularEditor.exe`, including context-sensitive flag behavior (e.g., `-S` after `-D` means `-SHARED`, not `-SCRIPT`). + +## The migrate command + +Use `te migrate` as a live reference for how TE2 flags map to the new CLI. It prints a colorized table of every known TE2 flag, its status (supported, renamed, planned), and the equivalent `te` command. + +```bash +te migrate # Full flag mapping table +te migrate -A # Look up a single flag +te migrate --output-format json # Machine-readable mapping +``` + +Refer to the output of the `te migrate` command for the current mapping that reflects the CLI version you have installed. + +## Flag mapping (curated subset) + +A non-exhaustive summary of the most commonly used flags. Run `te migrate` for the full list. + +| TE2 flag | New CLI equivalent | Notes | +| ------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `file` (positional) | `te ` or global `--model` | First positional arg on most commands. | +| `server`, `database` | `te connect ` or `te deploy ` | Server is no longer a global positional. | +| `-L` / `-LOCAL` | `te connect --local` | Windows only. | +| `-S` / `-SCRIPT` | `te script -s ` or `-e "code"` | Supports multiple scripts, inline code, and stdin. | +| `-A` / `-ANALYZE` | `te bpa run --rules ` | Supports `--fail-on`, `--fix`, multiple rule files. | +| `-AX` / `-ANALYZEX` | `te bpa run --rules ` (without `--model-rules`) | Excluding model-embedded rules is the new default. | +| `-B` / `-BIM` | `te save -o --serialization bim` | | +| `-F` / `-FOLDER` | `te save -o --serialization te-folder` | After `-D`, TE2's `-F` means `-FULL` - see `--deploy-full`. | +| `-TMDL` | `te save -o --serialization tmdl` | TMDL is the default save format. | +| `-D` / `-DEPLOY` | `te deploy ` | Separate command with named options. | +| `-O` / `-OVERWRITE` | (default) or `--create-only` to opt out | Overwrite is the default in the new CLI. | +| `-C` / `-CONNECTIONS` | `te deploy --deploy-connections` | | +| `-P` / `-PARTITIONS` | `te deploy --deploy-partitions` | | +| `-Y` / `-SKIPPOLICY` | `te deploy --deploy-partitions --skip-refresh-policy` | Requires `--deploy-partitions`. | +| `-SHARED` | `te deploy --deploy-shared-expressions` | After `-D`, TE2's `-S` means `-SHARED`. | +| `-R` / `-ROLES` | `te deploy --deploy-roles` | | +| `-M` / `-MEMBERS` | `te deploy --deploy-role-members` | | +| `-FULL` (after `-D`) | `te deploy --deploy-full` | Equivalent to overwrite + connections + partitions + shared + roles + role-members. | +| `-X` / `-XMLA ` | `te deploy ... --xmla ` | Use `-` for stdout. | +| `-V` / `-VSTS` | `--ci vsts` on `validate`, `bpa run`, `deploy` | Emits `##vso[...]` annotations to stderr. | +| `-G` / `-GITHUB` | `--ci github` | Emits `::error::` / `::warning::` annotations. | +| `-T` / `-TRX ` | `--trx ` on `validate`, `bpa run`, `test run` | VSTEST `.trx` file for Azure DevOps test publishing. | +| `-W` / `-WARN` | (default) | Warnings always reported in deploy results. | +| `-E` / `-ERR` | (default) | Deploy returns non-zero exit on DAX errors. | +| `-SC` / `-SCHEMACHECK` | _Not yet implemented._ | TE2 schema check connects to actual data sources. Different from `te validate` (DAX semantic validation, no data source connection). | +| `-L` / `-LOGIN ` (after `-D`) | `te auth login -u -p -t ` | Use service principal or env-based credentials. The login is cached, so subsequent commands acquire tokens silently - see @te-cli-auth. | + +## Migration playbook + +The recommended path from a TE2-based pipeline to the new CLI: + +1. **Drop-in replacement.** Replace `TabularEditor.exe` with `te` (or `te2`) in your existing pipeline. Verify the pipeline still runs - TE2 compatibility handles most invocations unchanged. +2. **Replace flags incrementally.** Convert one flag group at a time: + - Start with `-A` / `-AX` → `te bpa run` to pick up richer BPA output (`--fail-on`, `--fix`, `--trx`). + - Then `-D` → `te deploy` for fine-grained deploy control. + - Finally `-V` / `-G` → `--ci vsts` / `--ci github`. +3. **Switch to non-interactive CI flags.** Add `--non-interactive --ci ` to every `te` command and remove any `start /wait` wrappers - the new CLI is a regular console binary and doesn't need them. +4. **Adopt service principal auth.** Replace `-D -L ` with `te auth login -u ... -p ... -t ...` or an environment-credential pipeline step. See @te-cli-auth. + +## Important differences + +- **BPA gate on deploy.** `te deploy` now runs BPA as a pre-flight gate by default. Use `--skip-bpa` to preserve the old behavior, or `--fix-bpa` to auto-fix violations before deploy. See @te-cli-config. +- **Interactive confirmation on deploy.** `te deploy` prompts for confirmation by default (with `n` as the safe default answer). CI pipelines must pass `--force`. +- **Structured output.** Every command supports `--output-format json` for machine-readable output - see @te-cli-automation. +- **No `start /wait` needed.** The new CLI is a regular console binary; invoke it directly in shell scripts, PowerShell, and CI tasks. +- **Cross-platform.** The CLI runs on Windows, macOS, and Linux. Local SSAS and Power BI Desktop connections remain Windows-only. + +## Related pages + +- @command-line-options - the legacy TE2 command-line reference. +- @te-cli-commands - the new CLI's full command reference. +- @te-cli-cicd - pipeline examples for GitHub Actions and Azure DevOps. diff --git a/localizedContent/zh/content/features/te-cli/te-cli.md b/localizedContent/zh/content/features/te-cli/te-cli.md new file mode 100644 index 000000000..c3c43e33c --- /dev/null +++ b/localizedContent/zh/content/features/te-cli/te-cli.md @@ -0,0 +1,112 @@ +--- +uid: te-cli +title: Tabular Editor CLI (Limited Public Preview) +author: Peer Grønnerup +updated: 2026-05-12 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + none: true + - product: Tabular Editor CLI + full: true +--- + +# Tabular Editor CLI (Limited Public Preview) + +The Tabular Editor CLI (`te`) is a cross-platform command-line interface for Power BI and Analysis Services semantic models. It runs on Windows, macOS, and Linux as a single self-contained executable and is based on the same foundation that powers Tabular Editor 3. + +With the Tabular Editor CLI you can inspect, edit, validate, deploy, refresh, and test semantic models from a terminal - against local TMDL or BIM files, Power BI Desktop, or semantic models in Fabric and Power BI Service workspaces. + +Unlike the Windows-only `TabularEditor.exe` command-line options (TE2) - which was designed primarily to automate C# scripts and macros from a desktop binary - `te` is a purpose-built, cross-platform CLI with structured output, predictable exit codes, and an interactive shell. This unlocks scenarios that our existing [TE2 CLI](xref:command-line-options) can't cover well: terminal-driven model work on macOS and Linux, AI agents driving model changes directly, and clean drop-in for any modern CI runner. + +[!INCLUDE [te-cli-preview-notice](includes/te-cli-preview-notice.md)] + +## Built for three audiences + +Three design pillars run through every command: + +- **Structured output** — JSON, CSV, TMDL, TMSL alongside default human-readable text. +- **Non-interactive mode** — a global `--non-interactive` flag that disables prompts and fails fast. +- **Clear errors** — written to stderr with predictable exit codes. + +Together they make the same binary work well for three very different audiences: + +- **Humans** - scripting bulk edits, exploring a model from the terminal, composing commands in shell pipelines. +- **AI agents** - token-lean JSON, machine-parseable error shapes, exit codes that signal success or failure without parsing stdout. +- **CI/CD pipelines** - non-interactive execution, GitHub Actions and Azure DevOps annotations, VSTEST-compatible test results. + +## What the CLI can do + +The CLI organizes more than 50 commands into 10 families. Each family maps to a concrete stage of the semantic-model lifecycle. + +See @te-cli-commands for a full command reference with syntax, options, and examples for each command. Click any example command in the table to jump straight to its reference entry. + +| Family | What it does | Example commands | +| ------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Model I/O](xref:te-cli-commands#model-io) | Load, save, convert, initialize models | [`te load`](xref:te-cli-commands#load), [`te save`](xref:te-cli-commands#save), [`te init`](xref:te-cli-commands#init) | +| [Model Editing](xref:te-cli-commands#model-editing) | Get/set properties, add/remove/move objects | [`te set`](xref:te-cli-commands#set), [`te add`](xref:te-cli-commands#add), [`te rm`](xref:te-cli-commands#rm), [`te mv`](xref:te-cli-commands#mv) | +| [Inspection](xref:te-cli-commands#inspection) | List objects, search, diff, dependency analysis | [`te ls`](xref:te-cli-commands#ls), [`te find`](xref:te-cli-commands#find), [`te diff`](xref:te-cli-commands#diff), [`te deps`](xref:te-cli-commands#deps) | +| [Analysis & Quality](xref:te-cli-commands#analysis-and-quality) | Validate, run BPA, format DAX, analyze storage | [`te validate`](xref:te-cli-commands#validate), [`te bpa run`](xref:te-cli-commands#bpa-run), [`te format`](xref:te-cli-commands#format), [`te vertipaq`](xref:te-cli-commands#vertipaq) | +| [Execution](xref:te-cli-commands#execution) | Run DAX queries, C# scripts, macros | [`te query`](xref:te-cli-commands#query), [`te script`](xref:te-cli-commands#script), [`te macro`](xref:te-cli-commands#macro) | +| [Deployment & Refresh](xref:te-cli-commands#deployment-and-refresh) | Deploy to workspace, trigger refresh, incremental refresh | [`te deploy`](xref:te-cli-commands#deploy), [`te refresh`](xref:te-cli-commands#refresh), [`te incremental-refresh`](xref:te-cli-commands#incremental-refresh) | +| [Testing](xref:te-cli-commands#testing) | Assertion tests, snapshots, A/B comparison | [`te test run`](xref:te-cli-commands#test-run) | +| [Connection & Authentication](xref:te-cli-commands#connection-and-auth) | Connect to workspaces, manage authentication and profiles | [`te connect`](xref:te-cli-commands#connect), [`te auth`](xref:te-cli-commands#auth-login--status--logout), [`te profile`](xref:te-cli-commands#profile-list--show--set--remove) | +| [Configuration](xref:te-cli-commands#configuration) | Settings and licensing | [`te config`](xref:te-cli-commands#config-show--paths--init--set) | +| [Shell](xref:te-cli-commands#shell) | Interactive mode, shell completions | [`te interactive`](xref:te-cli-commands#interactive), [`te completion`](xref:te-cli-commands#completion) | + +## Getting started + +1. **Sign up or sign in** at [tabulareditor.com](https://tabulareditor.com/download-tabular-editor-cli) with a Tabular Editor account. +2. **Download and install** - see @te-cli-install for Windows, macOS, and Linux instructions. +3. **Authenticate** - run `te auth login` to connect to Power BI or Fabric. See @te-cli-auth. +4. **Run your first command** - `te --help` lists every command; `te --help` shows detailed options. + +A first look at a live model takes two commands: + +```bash +te auth login +te ls -s MyWorkspace -d MyModel +``` + +![Tabular Editor CLI te ls example output](~/content/assets/images/features/cli/cli-command-ls.png) + +## Preview notice + +Every command prints a yellow preview banner on stderr by default: + +![Tabular Editor CLI preview notice banner](~/content/assets/images/features/cli/cli-preview-notice.png) + +To hide the preview notice, simply run: + +```bash +te config set hidePreviewNotice true +``` + +> [!WARNING] +> The banner reappears on every command within **14 days of the preview end date** (2026-09-30), regardless of `hidePreviewNotice`. This ensures you have visible warning before the CLI stops functioning. + +## License outlook + +During Limited Public Preview, the CLI does not require a license; you only need a Tabular Editor account to download it. At General Availability (GA) the CLI will require a license; pricing is still being finalized and will be announced ahead of GA. + +## Feedback and community + +During the preview, bug reports, feature requests, and general discussion happen in the public [TabularEditor/CLI](https://github.com/TabularEditor/CLI) repository on GitHub: + +- **Issues** - report bugs, request features, and track known problems. +- **Discussions** - ask questions, share feedback, and swap usage tips with other early adopters. + +The repository does not host the CLI source code; it exists to give the community a public place to reach us during the preview. + +## Next steps + +- @te-cli-install - download, install, verify. +- @te-cli-auth - authenticate to Power BI, Fabric, and Azure Analysis Services. +- @te-cli-commands - full command reference. +- @te-cli-config - configuration file and path overrides. +- @te-cli-interactive - guided REPL mode for new users. +- @te-cli-automation - structured output, scripting patterns for Python, PowerShell, and Bash. +- @te-cli-cicd - GitHub Actions and Azure DevOps pipeline examples. +- @te-cli-migrate - migrating from the Tabular Editor 2 command line. diff --git a/localizedContent/zh/content/features/views/tom-explorer-view.md b/localizedContent/zh/content/features/views/tom-explorer-view.md index b3133e8bd..aeabeb456 100644 --- a/localizedContent/zh/content/features/views/tom-explorer-view.md +++ b/localizedContent/zh/content/features/views/tom-explorer-view.md @@ -10,11 +10,11 @@ applies_to: note: "它的工作方式与本文所示不同" - product: Tabular Editor 3 editions: - - edition: Desktop + - edition: 桌面版 full: true - - edition: Business + - edition: 商业版 full: true - - edition: Enterprise + - edition: 企业版 full: true --- diff --git a/localizedContent/zh/content/getting-started/editions.md b/localizedContent/zh/content/getting-started/editions.md index 89ccbaeb1..d9dc0c1a6 100644 --- a/localizedContent/zh/content/getting-started/editions.md +++ b/localizedContent/zh/content/getting-started/editions.md @@ -1,6 +1,6 @@ --- uid: editions -title: 比较版本 +title: 版本对比 author: Søren Toft Joensen updated: 2025-02-07 applies_to: @@ -13,61 +13,61 @@ applies_to: # Tabular Editor 3 各版本 -本文档概述并对比 Tabular Editor 3 的不同版本。 +本文档概述并比较了 Tabular Editor 3 的不同版本。 > [!NOTE] -> Tabular Editor 3 的许可证为**按开发者授权**。 换句话说，只有实际使用 Tabular Editor 3 产品的人才需要许可证。 +> Tabular Editor 3 的许可证按**每位开发者**授权。 换句话说，只有使用 Tabular Editor 3 的人员才需要许可证。 ## 支持的 Data model 建模场景 -Tabular Editor 3 各版本的主要区别在于它们支持哪些类型的表格 Data model 建模场景。 要理解这一差异，可以把 Analysis Services（Tabular）看作有多种不同的“形态”： +Tabular Editor 3 各版本之间的主要区别在于，它们支持的表格 Data model 建模场景类型不同。 要理解这一差异，需要先了解 Analysis Services (Tabular) 有多种不同的“形态”： -- Power BI Desktop（请确保您了解[限制](xref:desktop-limitations)） -- 通过 XMLA 终结点使用的 Power BI Premium（Premium Per User、**Premium 容量 [A、EM 或 P SKUs]**、**Fabric 容量 [F SKUs]**） -- SQL Server（2016+）Analysis Services（版本：开发人员版、标准版、**企业版**） -- Azure Analysis Services（层级：开发者层、基本层、**标准层**） +- Power BI Desktop（请务必了解其[限制](xref:desktop-limitations)） +- 通过 XMLA 终结点访问的 Power BI Premium（Premium Per User、**Premium Capacity [A、EM 或 P SKUs]**、**Fabric Capacity [F SKUs]**） +- SQL Server（2016+）Analysis Services（版本：Developer、Standard、**Enterprise**） +- Azure Analysis Services（层级：Developer、Basic、**Standard**） -我们将 Analysis Services 中**突出显示**的这些形态视为企业级，因此只能在 Tabular Editor 3 企业版中使用。 +我们将**加粗标示**的 Analysis Services 形态视为企业级，因此这些形态只能与 Tabular Editor 3 企业版配合使用。 > [!IMPORTANT] -> Tabular Editor 只允许编辑兼容级别为 1200 或更高的 Data model。 自 SQL Server 2016 起，Analysis Services 的所有实例默认都是如此。 出于同样的原因，Tabular Editor 不支持 Excel PowerPivot，因为它使用更早的兼容级别。 +> Tabular Editor 仅允许编辑兼容级别为 1200 或更高版本的 Data model。 自 SQL Server 2016 起，Analysis Services 的任何实例默认都是如此。 出于同样的原因，Tabular Editor 不支持 Excel PowerPivot，因为它使用更早的兼容级别。 -支持的场景完整概览见下方矩阵： +完整的受支持场景概览请参见下方矩阵： -| 场景 / 版本 | 桌面版 | 商业版 | 企业版 | +| 场景 / 版本 | Desktop | Business | Enterprise | | ---------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------- | -| Power BI Desktop 外部工具 | ✔ | ✔ | ✔ | +| Power BI Desktop 的外部工具 | ✔ | ✔ | ✔ | | 将模型元数据加载/保存到磁盘\*\* | ❌ | ✔\* | ✔ | | 工作区模式\*\*\* | ❌ | ✔\* | ✔ | | Power BI Premium 按用户 | ❌ | ✔ | ✔ | | SQL Server 开发者版 | ❌ | ✔\* | ✔ | | SQL Server 标准版 | ❌ | ✔ | ✔ | | SQL Server 企业版 | ❌ | ❌ | ✔ | -| Azure AS 开发者层 | ❌ | ✔\* | ✔ | -| Azure AS 基础层 | ❌ | ✔ | ✔ | -| Azure AS 标准层 | ❌ | ❌ | ✔ | +| Azure AS 开发者层级 | ❌ | ✔\* | ✔ | +| Azure AS 基础层级 | ❌ | ✔ | ✔ | +| Azure AS 标准层级 | ❌ | ❌ | ✔ | | Power BI Premium 容量（P SKU） | ❌ | ❌ | ✔ | | Power BI Embedded 容量（A/EM SKU） | ❌ | ❌ | ✔ | | Fabric 容量（F SKU） | ❌ | ❌ | ✔ | -| Semantic Bridge（Databricks） | ❌ | ❌ | ✔ | +| 语义桥接（Databricks） | ❌ | ❌ | ✔ | | [高级刷新对话框](xref:advanced-refresh) | ❌ | ✔ | ✔ | | [免费 DAX优化器许可证](xref:dax-optimizer-integration) | ❌ | ❌ | ✔ | -\*\*\*注意：\*\*如果 Analysis Services Data model 包含透视，或者某个表包含多个分区，则需要企业版（不适用于 Power BI Desktop 或 Power BI Premium Per User 模型）。 +\***注意：** 如果 Analysis Services Data model 包含透视或带有多个分区的表，则需要企业版（不适用于 Power BI Desktop 或 Power BI Premium Per User 模型）。 -\*\***注意：** 支持的文件格式包括：**.pbip**（Power BI Project）、**.pbit**（Power BI 模板）、**.bim**（Analysis Services 模型元数据）、**.vpax**（VertiPaq分析器）以及**Database.json**（Tabular Editor 文件夹结构）、**TMDL**（Tabular Model Definition Language，表格模型定义语言）。 +\*\***注意：** 支持的文件格式包括：**.pbip**（Power BI Project）、**.pbit**（Power BI 模板）、**.bim**（Analysis Services 模型元数据）、**.vpax**（VertiPaq分析器）以及 **Database.json**（Tabular Editor 文件夹结构）和 **TMDL**（表格模型定义语言）。 -\*\*\*\*\*注意：\*\*工作区模式允许 Tabular Editor 3 同时将模型元数据保存到磁盘，并让数据库与所购买的 Tabular Editor 3 版本支持的任意 Analysis Services 或 Power BI 版本保持同步。 +\*\*\***注意：** 工作区模式允许 Tabular Editor 3 将模型元数据同时保存到磁盘，并与所购买的 Tabular Editor 3 版本支持的任一 Analysis Services 或 Power BI 版本上的数据库保持同步。 ## 建模限制 我们也会在 Tabular Editor 3 中限制部分 Data model 建模操作，以与 Microsoft 某些服务层级（Azure Analysis Services _Basic Tier_、SQL Server Analysis Services _Standard Edition_，以及 Power BI _Premium-Per-User_）的限制保持一致。 -具体来说，[Azure AS Basic 层级和 SQL Server Analysis Services 标准版不支持透视、多个分区或 DirectQuery](https://azure.microsoft.com/en-us/pricing/details/analysis-services/)。因此，使用这些功能的 SSAS/Azure AS 模型需要 TE3 企业版。 +具体而言，[Azure AS Basic 层和 SQL Server 标准版不支持透视、多个分区或 DirectQuery](https://azure.microsoft.com/en-us/pricing/details/analysis-services/)，因此，使用这些功能的 SSAS/Azure AS 模型需要 TE3 企业版。 -同样地，[Power BI Premium-Per-User Workspace 不支持 Direct Lake Dataset](https://learn.microsoft.com/en-us/power-bi/enterprise/directlake-overview#prerequisites)，所以使用该功能的 Power BI 模型也需要 TE3 企业版。 +同样，[Power BI Premium-Per-User Workspace 不支持 Direct Lake Dataset](https://learn.microsoft.com/en-us/power-bi/enterprise/directlake-overview#prerequisites)，因此，使用此功能的 Power BI 模型也需要 TE3 企业版。 -| 模型类型 | 功能 | 商务版 | 企业版 | +| 模型类型 | 功能 | Business | Enterprise | | --------------- | ------------- | ------------------------------------------------------- | ------------------------------------------------------- | | Azure AS / SSAS | 透视 | ❌ | ✔ | | Azure AS / SSAS | 多个分区 | ❌ | ✔ | @@ -78,64 +78,64 @@ Tabular Editor 3 各版本的主要区别在于它们支持哪些类型的表格 | Power BI | DirectQuery | ✔ | ✔ | | Power BI | Direct Lake | ❌ | ✔ | -\***注意：** SQL Server 2019 之前的标准版 Analysis Services 不支持 DirectQuery。 Azure AS 基本层也同样不支持 DirectQuery。 [了解更多](https://learn.microsoft.com/en-us/analysis-services/analysis-services-features-by-edition?view=asallproducts-allversions#tabular-models)。 +\***注意：** SQL Server Standard Edition 2019 之前的版本中的 Analysis Services 不支持 DirectQuery。 Azure AS Basic 层也不支持。 [了解详细信息](https://learn.microsoft.com/en-us/analysis-services/analysis-services-features-by-edition?view=asallproducts-allversions#tabular-models)。 -\*\***注意：** 在商业版中，Power BI 模型支持透视和多个分区，但模型的 `CompatibilityMode` 必须设置为 `PowerBI`。 有关操作说明，请参阅 [更改兼容模式](xref:change-compatibility-mode)。 +\*\***注意：** 在商业版中，Power BI 模型支持透视和多个分区，但模型的 `CompatibilityMode` 必须设置为 `PowerBI`。 有关说明，请参阅[更改兼容模式](xref:change-compatibility-mode)。 -如果您在使用 TE3 商业版许可证时尝试打开一个应用了上述一项或多项建模限制的模型，将会看到以下错误信息： +如果你在使用 TE3 商业版许可证时尝试打开使用了上述一项或多项建模限制的模型，将会看到以下错误信息： ![此版本的 Tabular Editor 3 不支持企业级语义模型](https://github.com/TabularEditor/TabularEditorDocs/assets/8976200/7ef69593-ea4b-4a16-a8df-543f5c31ac65) -除了上面列出的内容之外，Tabular Editor 3 各版本之间没有其他功能差异。 +除上文列出的内容外，Tabular Editor 3 各版本之间没有其他功能差异。 > [!NOTE] -> 请注意，Power BI Desktop [目前并不支持所有 Data model 建模操作](xref:desktop-limitations)。 因此，Tabular Editor 3 默认会阻止 Power BI Desktop 不支持的操作。 不过，你可以在“工具 > 偏好 > Power BI”中解除该限制。 +> 请注意，Power BI Desktop [目前不支持所有数据建模操作](xref:desktop-limitations)。 因此，Tabular Editor 3 默认会阻止 Power BI Desktop 不支持的操作。 不过，你可以在“工具 > 偏好 > Power BI”中取消此限制。 > [!IMPORTANT] -> 仅当 Power BI Report（.pbix、.pbip 或 .pbit）文件包含 Data model（导入、DirectQuery 或复合模式）时，Tabular Editor 才能作为 Power BI Desktop 的外部工具使用。 **不支持使用 Live connection 的 Report**，因为这些 Report 不包含 Data model。 [更多信息](xref:desktop-limitations)。 +> 只有当 Power BI Report（.pbix、.pbip 或 .pbit）文件包含 Data model（Import、DirectQuery 或 Composite）时，Tabular Editor 才能作为 Power BI Desktop 的外部工具使用。 **使用实时连接的 Report 不受支持**，因为这类 Report 不包含 Data model。 [更多信息](xref:desktop-limitations)。 ## 个人许可证与可转让许可证 -我们的桌面版和商业版采用**个人**许可模式。 这意味着每位用户都会获得自己的个人许可证密钥，该密钥无法与其他用户共享或转让。 当用户不再需要该产品时，应取消订阅，以避免产生续费。 +我们的桌面版和商业版都采用**个人**许可模式。 这意味着，每位用户都会获得自己的专属许可证密钥，且不得共享或转让给其他用户。 当用户不再需要该产品时，应取消其订阅，以避免持续扣费。 -我们的企业版采用**可转让**许可模式。 许可证管理员会收到一个许可证密钥，该密钥对一定数量的具名用户有效，数量上限为购买的席位数。 用户通过其电子邮件地址进行识别；该地址需要在用户首次激活 Tabular Editor 3 安装时输入。 用户首次使用许可证密钥激活 Tabular Editor 3 安装时，会在该许可证下被“锁定”30 天。 30 天锁定期结束后，可随时将用户从许可证中移除，从而释放许可证名额供其他用户使用。 许可证管理员可通过我们的[自助门户](https://tabulareditor.com/my-account)查看和管理用户。 你也可以联系支持团队获取帮助。 +我们的企业版采用**可转让**许可模式。 许可证管理员会收到一个许可证密钥，该密钥最多可供不超过购买数量的指定用户使用。 系统会通过电子邮件地址识别用户；用户首次激活 Tabular Editor 3 时需要输入该地址。 用户首次使用许可证密钥激活某个 Tabular Editor 3 安装时，会在 30 天内“绑定”到该许可证。 30 天绑定期结束后，可随时将某位用户从许可证中移除，从而释放该许可证席位供其他用户使用。 许可证管理员可通过我们的[自助门户](https://tabulareditor.com/my-account)查看和管理用户。 你也可以联系支持团队获取帮助。 -## 多台设备安装 +## 多设备安装 -每位 Tabular Editor 3 用户可根据所持许可证类型，在多台设备上安装该工具： +每位 Tabular Editor 3 用户都可以根据所持许可证类型，在多台计算机上安装该工具： -| | 桌面版 | 商业版 | 企业版 | -| --------- | --- | --- | --- | -| 可同时激活的安装数 | 1 | 2 | 3 | +| | Desktop | Business | Enterprise | +| ------ | ------- | -------- | ---------- | +| 可同时安装数 | 1 | 2 | 3 | > [!NOTE] -> 在多位用户之间共享同一个许可证违反我们的[许可条款](https://tabulareditor.com/license-terms)。 +> 多个用户共用同一许可证违反我们的 [许可条款](https://tabulareditor.com/license-terms)。 -你可以随时在工具中停用现有安装：在“帮助 > 关于 Tabular Editor”中选择“更改许可证密钥...”选项。 你也可以通过我们的[自助门户](https://tabulareditor.com/sign-in)停用安装：进入“Licenses”选项卡。 +你可以随时在工具中停用现有安装：依次选择“帮助 > 关于 Tabular Editor”，然后点击“更改许可证密钥...”即可。 你也可以通过我们的[自助服务门户](https://tabulareditor.com/sign-in)切换到“许可证”选项卡来停用某个安装。 -如果您需要的 Tabular Editor 3 并发安装数量超过上述范围，请联系 [licensing@tabulareditor.com](mailto:licensing@tabulareditor.com)。 +如需的 Tabular Editor 3 同时安装数量超过上表所列，请联系[licensing@tabulareditor.com](mailto:licensing@tabulareditor.com)。 ## 企业版批量折扣 -我们的企业版采用分级定价，具体如下表所示（按月承诺也适用类似的折扣率）： +我们的企业版采用分级定价，具体如下表所示（按月承诺也适用类似折扣）： -| 档位 | 每席年度价格 | -| -------------- | --------------------------- | -| 前 5 个席位 | $950.00 USD | -| 接下来的 6-10 个席位 | $900.00 USD | -| 接下来的 11-20 个席位 | $850.00 USD | -| 接下来的 21-50 个席位 | $800.00 USD | -| 51 个席位及以上 | $750.00 USD | +| 档位 | 每席位年费 | +| ----------- | --------------------------- | +| 前 5 个席位 | $950.00 USD | +| 第 6–10 个席位 | $900.00 USD | +| 第 11–20 个席位 | $850.00 USD | +| 第 21–50 个席位 | $800.00 USD | +| 51 个席位及以上 | $750.00 USD | -例如，如果您需要 12 个席位，价格构成如下： +举例来说，如果您需要 12 个席位，价格明细如下： ```text -席位 1-5： 5 x 950.00 = $ 4,750.00 -席位 6-10： 5 x 900.00 = $ 4,500.00 -席位 11-12： 2 x 850.00 = $ 1,700.00 +Seats 1-5: 5 x 950.00 = $ 4,750.00 +Seats 6-10: 5 x 900.00 = $ 4,500.00 +Seats 11-12: 2 x 850.00 = $ 1,700.00 -------------------------------------- -总计 $ 10,950.00 +Total $ 10,950.00 ====================================== ``` -如果您需要超过 100 个席位，请 联系销售 获取报价。 +如果您需要超过 100 个席位，请 联系销售团队索取报价。 diff --git a/localizedContent/zh/content/getting-started/getting-started.md b/localizedContent/zh/content/getting-started/getting-started.md index 114a4225d..617d5b998 100644 --- a/localizedContent/zh/content/getting-started/getting-started.md +++ b/localizedContent/zh/content/getting-started/getting-started.md @@ -1,8 +1,8 @@ --- uid: getting-started -title: 安装与激活 +title: 安装和激活 author: Morten Lønskov -updated: 2026-03-27 +updated: 2026-05-19 applies_to: products: - product: Tabular Editor 2 @@ -17,148 +17,122 @@ applies_to: full: true --- -# 快速入门 +# 入门 ## 安装 -从我们的[下载页面](xref:downloads)下载最新版本的 Tabular Editor 3。 +请从我们的[下载页面](xref:downloads)下载 Tabular Editor 3 的最新版本。 -## 先决条件 +我们建议在大多数情况下使用 64 位 MSI 安装程序。 下载完成后，双击 MSI 文件，并按安装向导的提示完成安装。 + +![安装](~/content/assets/images/getting-started/install.png) + +### 先决条件 无。 -## 系统要求 +### 系统要求 - **操作系统：** Windows 10、Windows 11、Windows Server 2016、Windows Server 2019 或更高版本 -- **体系结构：** x64、ARM64（自 3.23.0 起提供原生支持） -- **.NET 运行时：** [.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) +- **架构：** x64、ARM64（自 3.23.0 起原生支持） +- **.NET 运行时：**[.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) -有关各运行时当前支持的 Windows 版本，请参阅 .NET 支持的 OS 策略。 +有关每个运行时当前支持的 Windows 版本，请参阅 .NET 支持的操作系统策略。 ## 激活安装 Tabular Editor 3 是商业软件。 访问我们的[主页](https://tabulareditor.com)，了解定价详情和购买选项。 如果你之前未使用过 Tabular Editor 3，即可获得 30 天免费试用。 -首次在新设备上启动 Tabular Editor 3 时，系统会提示进行产品激活。 +首次在新计算机上启动 Tabular Editor 3 时，系统会提示你激活产品。 ![产品激活](~/content/assets/images/getting-started/product-activation.png) -### 使用现有许可证密钥进行激活 +### 使用现有许可证密钥激活 -购买 Tabular Editor 3 许可证后，您将收到一封电子邮件，其中包含一串 25 个字符的代码，也就是您的许可证密钥。 按提示输入许可证密钥，然后点击“下一步 >”以激活产品。 +购买 Tabular Editor 3 的许可证后，你会收到一封电子邮件，其中包含一段 25 个字符的字符串，这就是你的许可证密钥。 出现提示时，输入许可证密钥，然后点击 **下一步 >** 以激活产品。 ![输入许可证密钥](~/content/assets/images/getting-started/enter-license-key.png) > [!NOTE] -> 对于多用户许可证类型，除了许可证密钥之外，您还需要输入电子邮件地址。 如果您输入的许可证密钥对应多用户许可证，Tabular Editor 3 会提示您输入电子邮件地址。 - -请注意，Tabular Editor 3 的安装是**按用户**激活的。 换句话说，如果多个用户共用同一台计算机，则每个用户都必须在各自的 Windows 用户配置文件中激活产品。 - -### 申请试用许可证 - -如果你之前未使用过 Tabular Editor 3，即可获得 30 天免费试用。 选择此选项时，系统会提示您输入电子邮件地址。 我们会使用该电子邮件地址来验证您是否已经激活过 Tabular Editor 3。 - -> [!NOTE] -> 在申请 30 天试用许可证时，Tabular Editor ApS 不会发送未经请求的电子邮件，也不会将你的电子邮件地址提供给第三方。 查看我们的 @privacy-policy 以了解更多信息。 - -### 更改许可证密钥 +> 对于多用户许可证类型，除了许可证密钥之外，你还需要输入电子邮件地址。 当许可证密钥对应的是多用户许可证时，Tabular Editor 3 会提示你这样做。 -Tabular Editor 3 激活后，您可以在“帮助”菜单中选择“关于 Tabular Editor”来更改许可证密钥。 +Tabular Editor 3 的安装是按 **用户** 激活的。 如果多个用户共享同一台计算机，则每位用户都需要在各自的 Windows 用户配置文件中激活产品。 -![关于 Te3](~/content/assets/images/getting-started/about-te3.png) +### Windows 帐户与 Power BI / Entra 帐户 -在对话框中，选择“更改许可证密钥”。 请注意，只有在 Tabular Editor 中未加载任何模型时，此选项才可用。 如果您已加载模型，可以通过“文件 > 关闭模型”将其关闭。 单击“更改许可证密钥”后，Tabular Editor 会询问您是否要删除当前许可证： +安装 Tabular Editor 3 的 Windows 帐户，与用于登录 Power BI / Fabric Workspace 的 Microsoft Entra 帐户彼此独立。 -![图片](https://user-images.githubusercontent.com/8976200/146754154-e691810b-342d-4311-8278-33da240d8d08.png) +- **许可证激活** 信息存储在 Windows 注册表中，即激活该产品的 Windows 用户的 `HKEY_CURRENT_USER` 下。 许可证不与任何云身份绑定。 +- **Workspace 身份验证**会在连接时于 **从数据库加载语义模型** 对话框中完成。 你需要使用对该 Workspace 具有权限的 Microsoft Entra 帐户登录。 -确认后，将删除当前许可证，并且您必须重新输入许可证密钥才能使用产品。 +即使你使用单独的 Entra 帐户（例如未启用邮箱的管理员帐户）来管理 Power BI Workspace，也不需要仅因为这一点就通过 **以其他用户身份运行** 在其他 Windows 帐户下启动 Tabular Editor 3。 在你平常使用的 Windows 帐户下启动 Tabular Editor 3，在该帐户下使用许可证密钥激活，然后在连接对话框中提供管理员 Entra 凭据。 -> [!IMPORTANT] -> 按上述方式删除许可证密钥后，在该计算机上的当前用户重新输入新的许可证密钥之前，将无法使用该产品。 - - - -#### 注册表详细信息 - -Tabular Editor 3 使用 Windows 注册表来存储激活详细信息。 - -要查看分配给该计算机的当前许可证密钥，请在 Windows 命令提示符（开始 > 运行 > cmd.exe）中运行以下命令： +有关 Tabular Editor 如何对 XMLA endpoint 进行身份验证，以及如何选择正确的身份验证模式的详细信息（例如，当你的 Windows 登录与 Power BI 帐户不一致时使用 **Microsoft Entra MFA**），请参阅 @xmla-as-connectivity。 -```cmd -REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey -``` +### 申请试用许可证 -你也可以使用 `regedit.exe`（Windows 注册表编辑器），前往 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`，查看并修改 **LicenseKey** 和 **User** 的值。 +如果你之前未使用过 Tabular Editor 3，即可获得 30 天免费试用。 选择此选项时，系统会提示你输入电子邮件地址。 我们会使用该电子邮件地址来验证你是否已有 Tabular Editor 3 的激活记录。 -系统管理员也可以在每个用户的 `SOFTWARE\Kapacity\Tabular Editor 3` 注册表键下指定 **LicenseKey** 和 **User** 的值，提前为某台计算机分配 Tabular Editor 3 许可证。 +> [!NOTE] +> 在申请 30 天试用许可证时，Tabular Editor ApS 不会发送未经请求的电子邮件，也不会将你的电子邮件地址提供给第三方。 更多信息见我们的 @privacy-policy。 -![注册表编辑器](~/content/assets/images/troubleshooting/registry-editor.png) +### 更改许可证密钥 -### 通过注册表更改许可证密钥 +激活 Tabular Editor 3 后，你可以在“帮助”菜单中选择 **关于 Tabular Editor** 来更改许可证密钥。 -如果出于任何原因，你无法按上述流程更改许可证密钥，也可以随时通过注册表编辑器重置分配给 Tabular Editor 3 的许可证： +![About Te3](~/content/assets/images/getting-started/about-te3.png) -1. 关闭所有 Tabular Editor 3 实例。 -2. 在 Windows 中打开注册表编辑器（开始 > 运行 > regedit.msc）。 -3. 定位到 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`（见上方截图）。 -4. 删除该项下的所有值。 -5. 关闭注册表编辑器，然后重新启动 Tabular Editor 3。 +在该对话框中，选择 **更改许可证密钥**。 此选项仅在 Tabular Editor 中未加载任何模型时可用。 如果某个模型已打开，先通过 **文件 > 关闭模型** 将其关闭。 点击 **更改许可证密钥** 后，Tabular Editor 会提示你是否要删除当前许可证： -或者，在 Windows 命令提示符中运行以下命令（开始 > 运行 > cmd.exe）： +![image](https://user-images.githubusercontent.com/8976200/146754154-e691810b-342d-4311-8278-33da240d8d08.png) -```cmd -REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va -``` +如果你确认，当前许可证将被删除，你需要重新输入许可证密钥才能使用该产品。 -下次启动 Tabular Editor 3 时，系统会提示你输入许可证密钥，就像该工具首次安装到此计算机上时一样。 +> [!IMPORTANT] +> 删除许可证密钥后，在该计算机上，当前用户将无法使用该产品，直到输入新的许可证密钥为止。 -### 静默安装与许可证预配置 +## 安装后配置 -你可以以静默方式部署 Tabular Editor，并通过 Windows 注册表预先配置许可证。 +Tabular Editor 3 提供了许多配置选项。 默认设置已足以满足大多数开发场景，但仍建议查看以下选项。 -1. **静默安装**（无 UI，不重启）： +### 启动时检查更新 - ```powershell - msiexec /i TabularEditor..x64.Net8.msi /qn /norestart /l*v C:\Temp\TE3_install.log - ``` +默认情况下，每次启动 Tabular Editor 3 时，工具都会联机检查是否有新版本可用。 你可以在 **工具 > 偏好 > 更新和反馈** 中控制更新检查的执行方式。 - 要包含 **AI Assistant** 功能，请在 `ADDLOCAL` 属性中指定它。 AI Assistant 默认不安装。 +> [!NOTE] +> 请始终使用最新版本的 Tabular Editor 3。 在提交 Bug Report 之前，我们的支持团队会默认你使用的是最新版本。 - ```powershell - msiexec /i TabularEditor..x64.Net8.msi /qn /norestart ADDLOCAL=MainFeature,AIAssistant /l*v C:\Temp\TE3_install.log - ``` +### 退出遥测数据收集 - | MSI 功能 | 说明 | 默认安装 | - | ------------- | ----------------------------------- | ----- | - | `MainFeature` | Tabular Editor 3 的核心应用程序 | 是（必需） | - | `AIAssistant` | 适用于 Tabular Editor 3 的 AI Assistant | 否 | +Tabular Editor 3 会收集匿名使用数据和遥测信息，用来帮助我们改进产品。 你可以随时启动 Tabular Editor 3，并依次前往 **工具 > 偏好 > 更新和反馈** 以选择退出。 如需退出，请取消选中 **通过收集匿名使用数据帮助改进 Tabular Editor** 复选框。 - > [!NOTE]> 使用 `ADDLOCAL` 时，除任何可选功能外，还必须包含 `MainFeature`。 只指定 `AIAssistant` 而不包含 `MainFeature` 会导致安装不完整。 +![收集遥测数据](~/content/assets/images/getting-started/collect-telemetry.png) -你也可以使用 `/package` 替代 `/i`。 将 `` 替换为实际的版本字符串。 如适用，请使用 ARM64 MSI。 +### 代理设置 -有关可用的 MSI 命令行选项的详细信息，请参阅 Microsoft 官方文档： -[Microsoft Standard Installer command-line options - Win32 apps | Microsoft Learn](https://learn.microsoft.com/windows/win32/msi/command-line-options) +如果你所在的网络互联网连接受限，请在 **工具 > 偏好 > 代理设置** 中指定代理服务器的地址、用户名和密码。 在 Tabular Editor 3 使用任何依赖出站 Web 请求的功能之前，必须先完成此设置。 具体包括： -2. **在应用程序首次启动之前**，**将许可证写入注册表**： +- 检查更新 +- 产品激活 +- DAX 格式化 +- 从外部 URL 下载最佳实践规则 - ```bat - REM Per-user license key (HKCU) - REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey /t REG_SZ /d YOUR-25-CHAR-KEY /f - ``` +> [!TIP] +> 代理设置有时会影响身份验证对话框或其他外部提示。 尝试在 **System** 和 **None** 之间切换代理设置，然后关闭并重新打开 Tabular Editor 3 以进行验证。 - 如果你使用的是 **企业版** 许可证密钥，还需要设置获授权用户的电子邮件： +### 其他偏好设置 - ```bat - REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v User /t REG_SZ /d user@example.com /f - ``` +Tabular Editor 3 还包含许多用于控制应用程序行为的设置。 若要了解详细信息，请参阅 @preferences。 -**备注** +## 高级场景 -- 安装程序**不**接受许可证参数；许可证通过上述注册表项进行处理。 -- 注册表项存储在 **HKCU** 下（每用户）。 请确保这些命令在目标用户的上下文中运行（例如通过登录脚本等方式），以便将值写入正确的用户配置文件。 -- 有关更多键和值，请参阅[注册表详细信息](#registry-details)。 +有关手动（无互联网）激活、基于注册表的许可证管理、静默部署和 Enterprise 席位管理，请参阅 @installation-activation-basic。 ## 后续步骤 -- [Tabular Editor 3 用户界面概览](xref:user-interface) +- [Tabular Editor 3 用户界面概述](xref:user-interface) +- @xmla-as-connectivity +- @migrate-from-vs +- @migrate-from-desktop +- @migrate-from-te2 +- @installation-activation-basic diff --git a/localizedContent/zh/content/getting-started/index.md b/localizedContent/zh/content/getting-started/index.md index 05149ee12..8eb234514 100644 --- a/localizedContent/zh/content/getting-started/index.md +++ b/localizedContent/zh/content/getting-started/index.md @@ -1,7 +1,8 @@ --- uid: onboarding-te3 title: 欢迎 -author: Daniel Otykier +author: Morten Lønskov +updated: 2026-05-19 --- # 欢迎 @@ -10,59 +11,72 @@ author: Daniel Otykier
--> -**感谢你选择 Tabular Editor 3！** +**感谢您选择 Tabular Editor 3！** -为了帮助你充分发挥该工具的价值，我们已将所有入门资料汇总在本“快速开始”部分中，希望你会喜欢。 我们建议所有 Tabular Editor 3 的新用户通读本指南，跳过你已经熟悉的内容。 +为了帮助您充分利用该工具，我们已将所有入门资料汇总在本“快速入门”章节中。 我们建议 Tabular Editor 3 的所有新用户通读本指南，已熟悉的内容可略过。 > [!NOTE] -> 本指南中的部分文章会引用 Tabular Editor 2，尤其是其命令行界面 (CLI)，用于自动化部署和测试。 我们计划在稍后发布一款可与 Tabular Editor 3 配套使用的独立 CLI 应用程序。 +> 本指南中的部分文章会引用 Tabular Editor 2，尤其是其命令行界面 (CLI)，用于自动化部署和测试。 配套 Tabular Editor 3 的独立 CLI 应用计划在后续发布。 -由于本培训资料侧重于 Tabular Editor 产品，我们假设你已对表格数据建模有基本了解（例如使用 Power BI Desktop、Visual Studio 或 Tabular Editor 2.x 进行建模）。 如果你刚开始接触表格数据建模，我们强烈建议你参考一些第三方提供的培训资料和课程，例如 [sqlbi.com](https://sqlbi.com)。 +由于本培训资料侧重于 Tabular Editor 产品，我们假设您已对表格数据建模有基本了解（使用 Power BI Desktop、Visual Studio 或 Tabular Editor 2.x）。 如果您刚接触表格数据建模，我们建议学习由 [sqlbi.com](https://sqlbi.com) 等第三方提供的培训资料和课程。 **本指南涵盖的主题：** -- @general-introduction - - @installation-activation-basic - - @migrate-from-vs - - @migrate-from-desktop - - @migrate-from-te2 +**Tabular Editor 3 入门** +- @general-introduction - @getting-started - - @editions - - @training-telearn +- @installation-activation-basic +- @migrate-from-vs +- @migrate-from-desktop +- @migrate-from-te2 +- @azure-marketplace +- @editions +- @training-telearn + +**Tabular Editor 2** - @getting-started-te2 +**Power BI Desktop 与 Tabular Editor** + - @desktop-integration - - @desktop-limitations +- @desktop-limitations -- @user-interface - - @bpa-view - - @数据刷新视图 - - @查找和替换 - - @宏视图 - - @消息视图 - - @属性视图 - - @tom-explorer-view - - @图表视图 +**用户界面** -- @并行开发 - - @在工作区模式下优化工作流程 +- @user-interface-reference +- @bpa-view-reference +- @data-refresh-view-reference +- @find-replace-reference +- @macros-view-reference +- @messages-view-reference +- @properties-view-reference +- @tom-explorer-view-reference +- @diagram-view-reference -- @boosting-productivity-te3 - - @导入表并进行数据建模 - - @刷新、预览与查询 - - @creating-and-testing-dax - - @dax-script-introduction - - @bpa - - @C# 脚本和宏 - - @personalizing-te3 +**并行开发** + +- @parallel-development +- @optimizing-workflow-workspace-mode -**更多资源：** +**使用 Tabular Editor 更快构建模型** -- [TE3 参考文档](xref:getting-started) +- @boosting-productivity-te3 +- @importing-tables-data-modeling +- @refresh-preview-query +- @creating-and-testing-dax +- @dax-script-introduction +- @bpa +- @cs-scripts-and-macros +- @personalizing-te3 + +**其他资源：** + +- [开始使用 Tabular Editor 3](xref:getting-started) +- [高级安装与激活](xref:installation-activation-basic) - [下载 Tabular Editor](https://tabulareditor.com/download) -- [Tabular Editor Learn 学习中心](https://tabulareditor.com/learn) +- [Tabular Editor 学习](https://tabulareditor.com/learn) - [专属支持（仅限企业版客户）](mailto:support@tabulareditor.com) - [社区支持](https://github.com/TabularEditor/TabularEditor3/issues) -- [社区讨论](https://github.com/TabularEditor/TabularEditor3/discussions) \ No newline at end of file +- [社区讨论](https://github.com/TabularEditor/TabularEditor3/discussions) diff --git a/localizedContent/zh/content/getting-started/installation.md b/localizedContent/zh/content/getting-started/installation.md index 8b2738d70..36d1b2e97 100644 --- a/localizedContent/zh/content/getting-started/installation.md +++ b/localizedContent/zh/content/getting-started/installation.md @@ -1,8 +1,8 @@ --- uid: installation-activation-basic -title: 安装、激活与基础配置 -author: Daniel Otykier -updated: 2021-09-30 +title: 高级安装与激活 +author: Morten Lønskov +updated: 2026-05-19 applies_to: products: - product: Tabular Editor 2 @@ -17,97 +17,119 @@ applies_to: full: true --- -## 安装 +## 概述 -要安装 Tabular Editor 3，请从我们的 [下载页面](xref:downloads) 下载最新版本。 +本页介绍 Tabular Editor 3 的高级安装和激活场景：手动（离线）激活、基于注册表的许可证管理、静默部署，以及企业版席位管理。 -建议下载 64 位 MSI 安装程序，它适用于大多数场景。 下载完成后，双击 MSI 文件，然后按照安装向导的提示完成安装。 +有关标准的激活流程，请参阅 @getting-started。 -![安装](~/content/assets/images/getting-started/install.png) + + +## 手动激活（无网络） + +如果你无法访问互联网，例如由于代理限制，Tabular Editor 会提示你进行手动激活。 + +![手动激活提示](~/content/assets/images/getting-started/Activation_manual_firstprompt.png) + +输入电子邮件地址后，会弹出一个对话框，其中包含指向激活密钥的链接。 复制该 URL，并在可连接互联网的 Web 浏览器中打开它。 + +该 URL 会返回一个 JSON 对象： -## 激活此安装 +![手动激活 JSON 对象](~/content/assets/images/getting-started/activation_manual_jsonobject.png) -当你首次在新机器上启动 Tabular Editor 3 时，系统会提示你激活产品。 +复制完整的 JSON 对象，并将其粘贴到对话框中。 完成后，手动激活对话框会像下图这样。 -![产品激活](~/content/assets/images/getting-started/product-activation.png) +![已填写的手动激活信息](~/content/assets/images/getting-started/activation_manual_dialogbox_filled.png) -### 使用现有许可证密钥激活 +随后会验证你的 Tabular Editor 3 许可证。 -购买 Tabular Editor 3 的许可证后，你会收到一封电子邮件，其中包含一段 25 个字符的字符串，这就是你的许可证密钥。 出现提示时，输入许可证密钥并点击“下一步 >”以激活产品。 +## 更换企业版席位 -![输入许可证密钥](~/content/assets/images/getting-started/enter-license-key.png) +要更换企业版席位，先通过 [Tabular Editor 自助服务门户](https://tabulareditor.com/my-account/) 取消该席位上现有用户的注册。 订阅所有者或许可证管理员可以创建账户，或使用现有账户登录，以管理许可证席位。 > [!NOTE] -> 对于多用户许可证类型，除了许可证密钥之外，你还需要输入电子邮件地址。 如果你输入的许可证密钥对应多用户许可证，Tabular Editor 3 会提示你这样做。 +> 仅企业版支持更换用户。 - + -#### 手动激活（无网络） +## 注册表详细信息 -如果你无法访问互联网，例如由于代理，Tabular Editor 会提示你进行手动激活。 +Tabular Editor 3 使用 Windows 注册表存储激活信息。 -![手动激活提示](~/content/assets/images/getting-started/Activation_manual_firstprompt.png) +要查看当前分配给这台计算机的许可证密钥，可在 Windows 命令提示符中运行以下命令（开始 > 运行 > cmd.exe）： -输入邮箱后，会弹出一个对话框，其中包含指向激活密钥的链接。 -复制该 URL，并在已连接互联网的网页浏览器中打开。 +```cmd +REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey +``` -该 URL 会返回一个 JSON 对象： +你也可以使用 `regedit.exe`（Windows 注册表编辑器），并导航到 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`，以查看和修改 **LicenseKey** 和 **User** 的值。 -![手动激活 JSON 对象](~/content/assets/images/getting-started/activation_manual_jsonobject.png) +![注册表编辑器](~/content/assets/images/troubleshooting/registry-editor.png) -复制返回的完整 JSON 对象，并将其粘贴到对话框中。 -你的手动激活对话框最后会像下面这样。 +系统管理员还可以在每个用户的 `SOFTWARE\Kapacity\Tabular Editor 3` 注册表项下指定 **LicenseKey** 和 **User** 值，从而提前为计算机分配 Tabular Editor 3 许可证。 完整部署流程请参阅 [静默安装和许可证预配](#silent-installation-and-license-pre-provisioning)。 -![已填写的手动激活](~/content/assets/images/getting-started/activation_manual_dialogbox_filled.png) +## 通过注册表更改许可证密钥 -这样即可验证你的 Tabular Editor 3 许可证。 +如果由于某种原因，你无法通过 **关于 Tabular Editor** 对话框中的标准 **更改许可证密钥** 选项修改许可证密钥，请通过注册表编辑器重置许可证： -### 更改许可证密钥 +1. 关闭所有正在运行的 Tabular Editor 3 实例。 +2. 在 Windows 中打开注册表编辑器（开始 > 运行 > regedit.msc）。 +3. 找到 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`（见上方屏幕截图）。 +4. 删除此注册表项中的所有值。 +5. 关闭注册表编辑器并重新启动 Tabular Editor 3。 -Tabular Editor 3 激活完成后，你可以在“帮助”菜单中选择“关于 Tabular Editor”，以更改许可证密钥。 +或者，在 Windows 命令提示符中运行以下命令（开始 > 运行 > cmd.exe）： -![关于 Te3](~/content/assets/images/getting-started/about-te3.png) +```cmd +REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va +``` -在该对话框中，选择“更改许可证密钥”。 注意：只有在 Tabular Editor 中没有加载任何模型时，这个选项才可用。 如果你已经加载了模型，可以通过“文件 > 关闭模型”将其关闭。 +下次启动 Tabular Editor 3 时，系统会提示你输入许可证密钥，就像该工具首次安装到这台计算机上时一样。 -有关管理许可证密钥的更多详细信息，请参阅[注册表详细信息](xref:getting-started#registry-details)。 +## 静默安装和许可证预配 -## 基本配置 +你可以静默部署 Tabular Editor，并通过 Windows 注册表预配许可证。 -Tabular Editor 3 激活后，我们建议花几分钟熟悉一下[基本界面](xref:user-interface)。 此外，Tabular Editor 3 还提供了许多不同的配置选项。 默认设置足够应对大多数开发场景，但有几个重要的配置选项你最好都检查一下。 +1. **静默安装**（无界面，无需重启）： -### 启动时检查更新 + ```powershell + msiexec /i TabularEditor..x64.Net8.msi /qn /norestart /l*v C:\Temp\TE3_install.log + ``` -默认情况下，每次启动 Tabular Editor 3 时，工具都会联机检查是否有新版本可用。 你可以在 **工具 > 偏好 > 更新和反馈** 中设置更新检查的方式。 + 要包含 **AI Assistant** 功能，请在 `ADDLOCAL` 属性中指定它。 默认不会安装 AI Assistant。 -> [!NOTE] -> 我们建议始终使用最新版本的 Tabular Editor 3。 在提交 bug Report 时，我们的支持团队通常会默认你使用的是最新版本。 + ```powershell + msiexec /i TabularEditor..x64.Net8.msi /qn /norestart ADDLOCAL=MainFeature,AIAssistant /l*v C:\Temp\TE3_install.log + ``` -### 选择不参与遥测数据收集 + | MSI 功能 | 说明 | 默认安装 | + | ------------- | ------------------------ | ----- | + | `MainFeature` | Tabular Editor 3 核心应用程序 | 是（必填） | + | `AIAssistant` | Tabular Editor 3 的 AI 助手 | 否 | -Tabular Editor 3 会收集匿名使用数据和遥测信息，用来帮助我们改进产品。 你可以随时退出：启动 Tabular Editor 3，依次进入 **工具 > 偏好 > 更新和反馈**。 取消选中 **通过收集匿名使用数据帮助改进 Tabular Editor** 复选框即可选择退出。 + > [!NOTE]> 使用 `ADDLOCAL` 时，除可选功能外，还必须同时包含 `MainFeature`。 如果仅指定 `AIAssistant` 而不指定 `MainFeature`，将导致安装不完整。 -![Collect Telemetry](~/content/assets/images/getting-started/collect-telemetry.png) +你也可以使用 `/package` 替代 `/i`。 将 `` 替换为实际版本字符串。 如适用，请使用 ARM64 MSI。 -### 代理设置 +有关可用 MSI 命令行选项的详细信息，参见 Microsoft 官方文档： +[Microsoft Standard Installer 命令行选项 - Win32 应用 | Microsoft Learn](https://learn.microsoft.com/windows/win32/msi/command-line-options) -如果你的网络连接受限，可以在 **工具 > 偏好 > 代理设置** 下指定代理服务器的地址、用户名和密码。 在 Tabular Editor 3 使用任何依赖出站 Web 请求的功能之前，必须先完成此设置。 具体包括： +2. **在首次启动应用程序之前**，**将许可证写入注册表**： -- 检查更新 -- 产品激活 -- DAX 格式化 -- 从外部 URL 下载最佳实践规则 + ```bat + REM Per-user license key (HKCU) + REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey /t REG_SZ /d YOUR-25-CHAR-KEY /f + ``` -> [!TIP] -> 代理设置有时会干扰身份验证对话框或其他外部提示。 -> 尝试在“System”和“None”之间切换代理设置，关闭并重新打开 Tabular Editor 3 进行验证。 + 如果你使用的是 **企业版** 许可证密钥，还需要设置授权用户的电子邮件地址： -### 其他偏好设置 + ```bat + REG ADD "HKCU\Software\Kapacity\Tabular Editor 3" /v User /t REG_SZ /d user@example.com /f + ``` -除上述设置外，Tabular Editor 3 还提供许多其他设置，用于控制应用程序的各种行为，让你可以更贴合自身需求地定制该工具。 要了解这些其他偏好设置的更多信息，请参阅 @preferences。 +**说明** -## 后续步骤 +- 安装程序不接受许可证参数；授权通过上述注册表项完成。 +- 这些键存储在 **HKCU** 下（按用户）。 确保以目标用户的身份运行这些命令（例如通过登录脚本），这样这些值会写入正确的用户配置文件。 +- 有关其他键和值，请参阅 [注册表详细信息](#registry-details)。 -- @migrate-from-vs -- @migrate-from-desktop -- @migrate-from-te2 \ No newline at end of file diff --git a/localizedContent/zh/content/how-tos/scripting-check-object-types.md b/localizedContent/zh/content/how-tos/scripting-check-object-types.md index 5f9349f48..3bb738e26 100644 --- a/localizedContent/zh/content/how-tos/scripting-check-object-types.md +++ b/localizedContent/zh/content/how-tos/scripting-check-object-types.md @@ -99,7 +99,7 @@ foreach (var col in Model.AllColumns) > > - `Column` 是抽象类型，但你无需进行类型转换，也可以访问基类型上定义的所有属性（`Name`、`DataType`、`FormatString`、`IsHidden`、`Description`、`DisplayFolder`）。 只有在你需要子类型特有的属性（例如 `CalculatedColumn` 上的 `Expression`）时，才将其转换为该子类型。 > - `OfType()` 会同时进行筛选和类型转换。 `Where(x => x is T)` 只会筛选，结果仍然是基类型。 当你需要访问子类型属性时，优先使用 `OfType()`。 -> - 计算表格的列会自动维护。 要添加或更改列，就编辑计算表格的 `Expression`。 你不能直接添加这些列。 +> - 计算表格的列会自动管理。 要添加或更改列，就编辑计算表格的 `Expression`。 你不能直接添加这些列。 ## 另见 diff --git a/localizedContent/zh/content/how-tos/scripting-perspectives-translations.md b/localizedContent/zh/content/how-tos/scripting-perspectives-translations.md index 9b8f45bb2..a5f6564d9 100644 --- a/localizedContent/zh/content/how-tos/scripting-perspectives-translations.md +++ b/localizedContent/zh/content/how-tos/scripting-perspectives-translations.md @@ -13,7 +13,7 @@ applies_to: # 如何使用透视和翻译 -透视用于控制哪些对象会显示在特定的客户端视图中。 翻译（区域设置）提供本地化的名称、描述和显示文件夹。 两者都使用 TOM 对象上的索引器属性。 有关访问 TOM 对象及其索引器的详细信息，请参阅 @how-to-navigate-tom-hierarchy。 +透视用于控制哪些对象会显示在特定的客户端视图中。 翻译（区域设置）提供本地化的名称、描述和显示文件夹。 两者都使用 TOM 对象上的索引器属性。 有关如何访问 TOM 对象及其索引器的详细信息，请参阅 @how-to-navigate-tom-hierarchy。 ## 快速参考 diff --git a/localizedContent/zh/content/how-tos/scripting-ui-helpers.md b/localizedContent/zh/content/how-tos/scripting-ui-helpers.md index 4b4195643..c4fad3b7a 100644 --- a/localizedContent/zh/content/how-tos/scripting-ui-helpers.md +++ b/localizedContent/zh/content/how-tos/scripting-ui-helpers.md @@ -68,7 +68,7 @@ Info("Updated " + Selected.Measures.Count() + " measures."); | 字符串或基本类型 | 简单的信息对话框 | > [!NOTE] -> 字符串输出使用 Windows 行结束符。 使用 `\r\n` 或 `Environment.NewLine` 来插入换行符。 单独的 `\\n` 会渲染为一行。 这常让使用 M 表达式的用户出错：M 表达式使用 `\n`，但在 `Output()` 中会作为单行输出。 +> 字符串输出使用 Windows 行结束符。 使用 `\r\n` 或 `Environment.NewLine` 来插入换行符。 单独的 `\\n` 会渲染为一行。 这会让使用 M 表达式的用户很容易踩坑：它们使用 `\\n`，但在 `Output()` 中会被打印成一行。 ### 用于结构化输出的 DataTable diff --git a/localizedContent/zh/content/how-tos/scripting-work-with-expressions.md b/localizedContent/zh/content/how-tos/scripting-work-with-expressions.md index 47eaf3cd9..0b62006f8 100644 --- a/localizedContent/zh/content/how-tos/scripting-work-with-expressions.md +++ b/localizedContent/zh/content/how-tos/scripting-work-with-expressions.md @@ -72,7 +72,7 @@ m.FormatString = "#,##0.00"; | `DaxTableName` | `'Sales'` | `'Sales'` | `'Sales'` | > [!NOTE] -> 对于度量值，`DaxObjectFullName` 返回与 `DaxObjectName`（不带限定符）相同的值。 在 DAX 中，度量值不需要表名限定。 对于列，`DaxObjectFullName` 包含表前缀。 +> 对于度量值，`DaxObjectFullName` 返回的值与 `DaxObjectName`（不带限定符）相同。 在 DAX 中，度量值不需要表名限定。 对于列，`DaxObjectFullName` 包含表前缀。 生成 DAX 时，请使用以下属性以避免引号错误： diff --git a/localizedContent/zh/content/how-tos/update-compatibility-level.md b/localizedContent/zh/content/how-tos/update-compatibility-level.md index 451fe15c2..c37d96dd2 100644 --- a/localizedContent/zh/content/how-tos/update-compatibility-level.md +++ b/localizedContent/zh/content/how-tos/update-compatibility-level.md @@ -22,7 +22,7 @@ applies_to: 模型的 **兼容级别** 决定你可以使用哪些 Tabular Object Model (TOM) 功能。 当 Microsoft 引入自定义日历或 DAX 用户定义函数等新功能时，这些功能通常需要在较新的兼容级别下才会开放。 你需要先升级，这些功能才会出现在 Tabular Editor 中。 > [!WARNING] -> 兼容级别升级是不可逆的。 你可以升级，但无法可靠地降级。 将其视为一次架构升级，并先验证你的部署目标。 +> 兼容性升级是不可逆的。 你可以升级，但无法可靠地降级。 将其视为一次架构升级，并先验证你的部署目标。 ## 兼容级别与兼容模式 diff --git a/localizedContent/zh/content/references/downloads.md b/localizedContent/zh/content/references/downloads.md index d8dde3792..8ad847ace 100644 --- a/localizedContent/zh/content/references/downloads.md +++ b/localizedContent/zh/content/references/downloads.md @@ -23,7 +23,7 @@ Tabular Editor 3.26.1 **.NET 8** 下载： ## 安装说明 1. 下载 .exe 安装程序文件。 -2. 运行此 .exe 安装程序。 安装向导将引导你完成安装。 +2. 运行.exe 安装程序。 安装向导将引导你完成安装。 3. 有关如何激活产品或更换许可证密钥的说明，请参阅我们的[入门指南](xref:getting-started)。 升级到更新版本的 Tabular Editor 3 时，无需卸载之前安装的版本。 diff --git a/localizedContent/zh/content/security/index.md b/localizedContent/zh/content/security/index.md index df0e45fce..009834ed9 100644 --- a/localizedContent/zh/content/security/index.md +++ b/localizedContent/zh/content/security/index.md @@ -1,14 +1,14 @@ # 安全 -本节包含有关安全、隐私和许可的信息。 +This section contains information about security, privacy, and licensing. -## 本节内容 +## In this section -- @security-privacy - Tabular Editor 3 的安全与隐私注意事项 -- @privacy-policy - 隐私政策与数据处理 -- @gdpr-delete - 用户数据删除 -- @te3-eula - 我们最新版本的许可条款 -- @third-party-notices - 第三方组件许可证与声明 +- @security-privacy - Security and privacy considerations of Tabular Editor 3 +- @privacy-policy - Privacy policy and data handling +- @gdpr-delete - User Data Deletion +- @terms - The latest version of our Terms & Conditions +- @third-party-notices - Third-party component licenses and notices --- diff --git a/localizedContent/zh/content/security/terms.md b/localizedContent/zh/content/security/terms.md new file mode 100644 index 000000000..6e2982460 --- /dev/null +++ b/localizedContent/zh/content/security/terms.md @@ -0,0 +1,22 @@ +--- +uid: terms +title: 条款与条件 +author: Søren Toft Joensen +updated: 2026-05-29 +applies_to: + products: + - product: Tabular Editor 2 + none: true + - product: Tabular Editor 3 + full: true + - product: TE CLI + full: true +--- + +# 条款与条件 + +请参阅以下最新版本的条款与条件： + +- [商业条款与条件](https://tabulareditor.com/commercial-terms) +- [Tabular Editor 3 最终用户许可协议 EULA](https://tabulareditor.com/eula-te3) +- [Tabular Editor CLI 最终用户许可协议 EULA](https://tabulareditor.com/eula-cli) diff --git a/localizedContent/zh/content/troubleshooting/databricks-column-comments-length.md b/localizedContent/zh/content/troubleshooting/databricks-column-comments-length.md index ec03e7107..8e192d460 100644 --- a/localizedContent/zh/content/troubleshooting/databricks-column-comments-length.md +++ b/localizedContent/zh/content/troubleshooting/databricks-column-comments-length.md @@ -22,7 +22,7 @@ applies_to: > [!TIP] > Databricks 已发布新的 ODBC 驱动程序，用于替代旧版 Simba Spark ODBC Driver。 新版 [Databricks ODBC Driver](https://www.databricks.com/spark/odbc-drivers-download) 可能没有下文所述的 `MaxCommentLen` 限制。 如果你遇到此问题，建议切换到新驱动程序，Tabular Editor 3.26.0 及更高版本已支持该驱动程序。 -使用“导入表向导”从 Databricks 导入表时，如果列注释（描述）超过 512 个字符，可能会出现连接错误。 这一限制来自 Simba Spark ODBC Driver，尽管 Databricks Unity Catalog 允许更长的列注释。 +使用“导入表向导”从 Databricks 导入表时，如果列注释（说明）超过 512 个字符，可能会遇到连接错误。 这一限制来自 Simba Spark ODBC Driver，尽管 Databricks Unity Catalog 允许更长的列注释。 典型的错误信息如下： @@ -34,7 +34,7 @@ applies_to: ## 了解问题 -Tabular Editor 使用 Simba Spark ODBC Driver 连接到 Databricks，而该驱动对列注释的默认长度限制是 512 个字符。 无论 Databricks Unity Catalog 允许的长度是多少，这个限制都会被强制执行。 +Tabular Editor 通过 Simba Spark ODBC Driver 连接到 Databricks，该驱动对列注释的默认长度限制为 512 个字符。 无论 Databricks Unity Catalog 允许的长度是多少，这个限制都会被强制执行。 ### 为什么会这样 @@ -204,13 +204,13 @@ Tabular Editor 使用 Simba Spark ODBC Driver 连接到 Databricks，而该驱 如果以上步骤未能解决你的问题： -1. **验证 ODBC 驱动程序版本**：确保已安装最新版本的 Simba Spark ODBC Driver。 你可以从 [Microsoft Azure Databricks ODBC 下载页面](https://learn.microsoft.com/azure/databricks/integrations/odbc/download) 下载。 +1. **检查 ODBC 驱动程序版本**：确保已安装最新版本的 Simba Spark ODBC Driver。 你可以从 [Microsoft Azure Databricks ODBC 下载页面](https://learn.microsoft.com/azure/databricks/integrations/odbc/download) 下载该驱动程序。 2. **检查 ODBC 数据源配置**：打开 Windows 的 ODBC 数据源管理器 (odbcad32.exe)，确认你的 Databricks 连接已正确配置。 3. **用更简单的表测试**：尝试导入一张你确定列注释很短（或没有注释）的 Databricks 表，先确认连接本身是否正常。 -4. **查看 ODBC 驱动程序日志**：Simba Spark ODBC Driver 可以生成详细日志。 参考驱动程序文档，按说明启用日志记录；日志可能会提供更多诊断信息。 +4. **查看 ODBC 驱动程序日志**：Simba Spark ODBC Driver 可以生成详细的日志。 参考驱动程序文档，按说明启用日志记录；日志可能会提供更多诊断信息。 5. **联系支持**：联系 Tabular Editor 支持团队，并提供： - 完整的错误信息文本 diff --git a/localizedContent/zh/content/troubleshooting/licensing-activation.md b/localizedContent/zh/content/troubleshooting/licensing-activation.md index c3b4f5853..ee9dbc90e 100644 --- a/localizedContent/zh/content/troubleshooting/licensing-activation.md +++ b/localizedContent/zh/content/troubleshooting/licensing-activation.md @@ -1,7 +1,8 @@ --- uid: licensing-activation title: 安装并激活 Tabular Editor 3 -author: Daniel Otykier +author: Morten Lønskov +updated: 2026-05-19 applies_to: products: - product: Tabular Editor 2 @@ -16,90 +17,124 @@ applies_to: full: true --- -# Tabular Editor 3 +# 安装并激活 Tabular Editor 3 -## 安装 +本页介绍 Tabular Editor 3 常见的安装和激活问题，以及相应的解决方法。 有关标准激活流程，请参见 @getting-started。 有关高级部署场景（静默安装、许可证预配置、安装后配置），请参见 @installation-activation-basic。 -请从我们的[下载页面](xref:downloads)下载 Tabular Editor 3 的最新版本。 +## 检查系统要求 -## 先决条件 +在继续排查之前，先确认你的计算机满足以下要求： -无。 +- **操作系统：** Windows 10、Windows 11、Windows Server 2016、Windows Server 2019 或更高版本 +- **架构：** x64、ARM64（自 3.23.0 起提供原生支持） +- **.NET Runtime：** [.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) -## 系统要求 +从 [下载页](xref:downloads) 下载与你的系统架构匹配的 MSI 安装包。 安装程序与系统架构不匹配，是安装失败以及首次启动时出现依赖项缺失错误的常见原因。 -- **操作系统：** Windows 7、Windows 8、Windows 10、Windows Server 2016、Windows Server 2019 或更高版本 -- **.NET Framework：** [4.7.2](https://dotnet.microsoft.com/download/dotnet-framework) + -## 激活你的安装 +## 检查已激活的许可证 -Tabular Editor 3 是商业软件。 访问我们的[主页](https://tabulareditor.com)查看价格详情和购买选项。 如果你之前没有使用过 Tabular Editor 3，则可免费试用 30 天。 +Tabular Editor 3 会将激活信息存储在 Windows 注册表的 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3` 下。 -在新设备上首次启动 Tabular Editor 3 时，系统会提示你激活产品。 +要查看当前 Windows 登录用户的许可证密钥，在 Windows 命令提示符（开始 > 运行 > cmd.exe）中运行以下命令： -![产品激活](~/content/assets/images/getting-started/product-activation.png) +```cmd +REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey +``` + +你也可以直接使用 `regedit.exe` 查看和编辑 **LicenseKey** 与 **User** 的值。 -### 使用现有许可证密钥激活 +![注册表编辑器](~/content/assets/images/troubleshooting/registry-editor.png) -购买 Tabular Editor 3 许可证后，你会收到一封电子邮件，其中包含一段 25 个字符的字符串，即你的许可证密钥。 出现提示时，输入许可证密钥，然后点击“下一步 >”激活产品。 +## 激活对话框反复出现 -![输入许可证密钥](~/content/assets/images/getting-started/enter-license-key.png) +Tabular Editor 3 会在启动时以及之后定期连接 `https://api.tabulareditor.com` 以验证许可证。 如果由于防火墙或代理而无法访问这个端点，应用每 30 天都需要重新激活一次。 有关所使用端点的完整列表，请参阅 @policies。 -> [!NOTE] -> 对于多用户许可证类型，除了许可证密钥外，还需要输入电子邮件地址。 如果你输入的许可证密钥对应多用户许可证，Tabular Editor 3 会提示你输入电子邮件地址。 +如果激活提示反复出现： -#### 企业版更换席位 +1. 确认受影响的计算机可以访问 `api.tabulareditor.com`。 +2. 在 **工具 > 偏好 > 代理设置** 中配置代理。 如需进行代理相关的故障排除，请参阅 @proxy-settings，其中包括用于启用外部 MSAL 代理支持的 **AnalysisServices.AppSettings.json** 覆盖配置。 +3. 如果网络阻止向激活端点发起出站流量，请使用下方的[手动激活](#manual-activation-no-internet)。 -要更换企业版席位，必须先通过 [Tabular Editor 自助服务门户](https://tabulareditor.com/my-account/) 将现有用户从该席位取消注册。 订阅所有者或许可证管理员可以创建账号，或使用现有账号登录，以管理许可证席位。 + -> [!NOTE] -> 仅企业版支持更换用户。 +## 手动激活（无网络连接） -### 申请试用许可证 +如果运行 Tabular Editor 的计算机无法访问激活端点，激活提示会提供手动激活流程。 -如果你之前没有使用过 Tabular Editor 3，你可以免费试用 30 天。 选择此选项后，系统会提示你输入电子邮件地址。 我们会使用该电子邮件地址来验证你是否已激活过 Tabular Editor 3。 +![Manual Activation Prompt](~/content/assets/images/getting-started/Activation_manual_firstprompt.png) -> [!NOTE] -> 注册 30 天试用许可证时，Tabular Editor ApS 不会发送未经请求的电子邮件，也不会将你的电子邮件地址转交给第三方。 更多信息请查看我们的 @privacy-policy。 +1. 输入您的电子邮件地址。 此时会弹出一个对话框，其中包含指向激活密钥的链接。 -### 更改许可证密钥 +2. 复制该 URL，然后在另一台能上网的计算机上打开。 该 URL 会返回一个 JSON 对象。 -激活 Tabular Editor 3 后，你可以在“帮助”菜单中选择“关于 Tabular Editor”，来更换许可证密钥。 + ![Manual Activation JSON Object](~/content/assets/images/getting-started/activation_manual_jsonobject.png) -![关于 Te3](~/content/assets/images/getting-started/about-te3.png) +3. 复制完整的 JSON 对象，并将其粘贴到离线计算机上的对话框中。 -在对话框中，选择“更改许可证密钥”。 注意：只有在 Tabular Editor 中未加载任何模型时，此选项才可用。 如果你已经加载了模型，可以通过“文件”>“关闭模型”将其关闭。 + ![Manual Activation Filled In](~/content/assets/images/getting-started/activation_manual_dialogbox_filled.png) -#### 注册表信息 +随后，Tabular Editor 3 会验证许可证。 -Tabular Editor 3 使用 Windows 注册表来存储激活详细信息。 +## 无法在 UI 中更改许可证密钥 -要查看分配给此计算机的当前许可证密钥，请在 Windows 命令提示符中运行以下命令（开始 > 运行 > cmd.exe）： +只有在未加载任何模型时，**帮助 > 关于 Tabular Editor** 下的 **更改许可证密钥** 按钮才会启用。 如果该按钮是灰色的，先通过 **文件 > 关闭模型** 关闭当前打开的模型，然后再试一次。 + +如果 UI 选项还是不起作用，就通过注册表编辑器重置许可证： + +1. 关闭所有正在运行的 Tabular Editor 3。 +2. 打开注册表编辑器（开始 > 运行 > regedit.msc）。 +3. 定位到 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`。 +4. 删除此键下的所有值。 +5. 重新启动 Tabular Editor 3。 + +或者，在 Windows 命令提示符中运行以下命令： ```cmd -REG QUERY "HKCU\Software\Kapacity\Tabular Editor 3" /v LicenseKey +REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va ``` -你也可以使用 `regedit.exe`（Windows 注册表编辑器），并导航到 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`，以查看和修改 **LicenseKey** 与 **User** 值。 +下次启动时，会像首次安装该应用一样提示输入许可证密钥。 -系统管理员也可以通过在每个用户的 `SOFTWARE\Kapacity\Tabular Editor 3` 注册表项下指定 **LicenseKey** 和 **User** 值，提前为某台机器分配 Tabular Editor 3 许可证。 +> [!IMPORTANT] +> 一旦移除许可证密钥，在输入新的许可证密钥之前，该计算机上的当前 Windows 用户将无法使用该产品。 -![注册表编辑器](~/content/assets/images/troubleshooting/registry-editor.png) +## 许可证激活在错误的 Windows 用户帐户下 -### 通过注册表更改许可证密钥 +Tabular Editor 3 的激活信息会 **按用户分别** 存储在 `HKEY_CURRENT_USER` 下。 如果多位用户共用一台计算机，则每位用户都需要在自己的 Windows 用户配置文件下激活该产品。 在某个 Windows 帐户下激活的许可证，对同一台计算机上的其他 Windows 帐户不可见。 -如果由于某些原因你无法按上述流程更改许可证密钥，你也可以使用注册表编辑器重置分配给 Tabular Editor 3 的许可证： +若要检查哪个 Windows 帐户拥有该许可证，以该用户身份登录，并运行 [检查已激活的许可证](#inspect-the-activated-license) 中的注册表查询命令。 -1. 关闭所有 Tabular Editor 3 实例。 -2. 在 Windows 中打开“注册表编辑器”（开始 > 运行 > regedit.msc）。 -3. 找到 `HKEY_CURRENT_USER\SOFTWARE\Kapacity\Tabular Editor 3`（见上方屏幕截图）。 -4. 删除此键下的所有值。 -5. 关闭“注册表编辑器”，然后重新启动 Tabular Editor 3。 +### Windows 帐户与 Power BI / Entra 帐户 -或者，你也可以在 Windows 命令提示符（开始 > 运行 > cmd.exe）中运行以下命令： +一个常见的困惑点是：运行 Tabular Editor 3 的 Windows 帐户，与用于对 Power BI / Fabric Workspace 进行身份验证的 Microsoft Entra 帐户是相互独立的。 -```cmd -REG DELETE "HKCU\Software\Kapacity\Tabular Editor 3" /va -``` +- **许可证激活信息** 存储在激活该产品的 Windows 用户的 `HKEY_CURRENT_USER` 下。 它不与任何云身份绑定。 +- **Workspace 身份验证**会在 **从数据库加载语义模型** 对话框中建立连接时进行。 在这里使用对 Workspace 有权限的 Microsoft Entra 帐户登录。 + +即使你使用单独的 Entra 帐户连接到 Power BI（例如未启用邮件的管理员帐户），也无需通过 **以其他用户身份运行** 使用不同的 Windows 帐户启动 Tabular Editor 3。 在你常用的 Windows 帐户下启动，在该帐户下激活许可证，并在连接对话框中提供管理员 Entra 凭据。 + +关于如何选择正确的身份验证模式的详细信息（例如，当你的 Windows 登录与 Power BI 帐户不一致时使用 **Microsoft Entra MFA**），请参阅 @xmla-as-connectivity。 + +## 企业版席位正被另一位用户使用 + +企业版许可证按席位授权。 要在所有席位都已占用时为新用户激活 Tabular Editor 3，必须先通过 [Tabular Editor 自助服务门户](https://tabulareditor.com/my-account/) 将现有用户从某个席位取消注册。 此操作需由订阅所有者或许可证管理员执行。 + +> [!NOTE] +> 仅企业版支持重新分配席位。 + +## 通过代理激活 + +Tabular Editor 3 会发起出站 Web 请求，用于产品激活、检查更新、DAX 格式化，以及下载外部最佳实践规则。 如果你在代理服务器后面： + +1. 在 **工具 > 偏好 > 代理设置** 中进行配置。 将 **代理类型** 在 `System` 和 `None` 之间切换，重启 Tabular Editor 3，然后再次尝试激活。 +2. 如果激活仍然失败，请参阅 @proxy-settings 进行高级代理诊断。 +3. 如果对 `api.tabulareditor.com` 的出站访问被阻止，请使用 [手动激活](#manual-activation-no-internet)。 + +> [!TIP] +> 代理设置可能会干扰身份验证对话框和其他外部提示。 更改代理类型后，重新测试前务必先关闭并重新打开 Tabular Editor 3。 + +## 确认你已使用最新版本 -下次启动 Tabular Editor 3 时，系统会像该工具首次安装到此计算机时那样，提示你输入许可证密钥。 \ No newline at end of file +与激活相关的问题有时会在较新的 Tabular Editor 3 版本中得到修复。 提交支持请求前，先确认你使用的是最新版本。 在 **工具 > 偏好 > 更新和反馈** 中检查更新，或从 [下载页面](xref:downloads) 下载最新安装程序。 diff --git a/localizedContent/zh/content/troubleshooting/locale-not-supported.md b/localizedContent/zh/content/troubleshooting/locale-not-supported.md index 6b3b158ff..2c441f438 100644 --- a/localizedContent/zh/content/troubleshooting/locale-not-supported.md +++ b/localizedContent/zh/content/troubleshooting/locale-not-supported.md @@ -19,50 +19,54 @@ applies_to: # 区域设置不受支持 -你可能会看到以下警告信息： +你可能会看到以下任一条警告信息： ```plaintext -不支持 XXXX 区域设置 +The XXXX locale is not supported +``` + +```plaintext +XXXX is an invalid culture identifier ``` 在 Tabular Editor 3 的“信息视图”中。 -![区域设置不受支持信息](~/content/assets/images/troubleshooting/locale-not-supported-message-view.png) +![“区域设置不受支持”信息](~/content/assets/images/troubleshooting/locale-not-supported-message-view.png) 当你的本地计算机使用 **Analysis Services (SSAS) 引擎不支持的区域设置** 时，通常会出现此问题。 -在大多数情况下，该错误由其他潜在问题或警告触发，但最终会表现为这条信息。 +大多数情况下，这个错误是由其他潜在问题或警告触发的，因此才会显示这条信息。 --- ## 场景与解决方案 -### 1。 连接到本地 SSAS 实例 +### 1. 连接到本地 SSAS 实例 -如果你在本地计算机上运行 SQL Server Analysis Services (SSAS)： +如果你是在本机本地运行 SQL Server Analysis Services (SSAS)： - **解决方案：** 更改 SSAS 实例使用的 **服务账户**。 - 更新该账户通常可以解决由于区域设置不受支持而导致的不匹配问题。 + 更新账户通常可以解决因区域设置不受支持而导致的不匹配问题。 --- -### 2。 连接到远程 SSAS、Azure AS 或 Power BI +### 2. 连接到远程 SSAS、Azure AS 或 Power BI 连接到远程实例时，有两种可行的解决方案： -#### 选项 A：在连接字符串中指定区域设置 +#### 方案 A：在连接字符串中指定区域设置 -在连接字符串中添加 `LocaleIdentifier=1033`，即可显式设置受支持的区域设置(例如：英语 – 1033)。 +在连接字符串中添加 `LocaleIdentifier=1033`，以显式设置受支持的区域设置 (例如英语 – 1033)。 **示例（Azure AS）：** ```plaintext -数据源=asazure://westeurope.asazure.windows.net/instance-name;LocaleIdentifier=1033 +Data Source=asazure://westeurope.asazure.windows.net/instance-name;LocaleIdentifier=1033 ``` -#### 选项 B：更改计算机上的区域设置 +#### 方案 B：更改本机的区域设置 -将本地系统的区域和语言设置调整为受支持的区域设置。 +调整你本地系统的区域和语言设置，使其与受支持的区域设置一致。 -- **推荐设置：** - - **区域格式：** 英语（美国） - - **Windows 显示语言：** 英语（美国） \ No newline at end of file +- **建议设置：** + - \*\*区域格式：\*\*英语（美国） + - \*\*Windows 显示语言：\*\*英语（美国） \ No newline at end of file diff --git a/localizedContent/zh/content/tutorials/connecting-to-azure-databricks.md b/localizedContent/zh/content/tutorials/connecting-to-azure-databricks.md index f2c787dfd..2bf82561e 100644 --- a/localizedContent/zh/content/tutorials/connecting-to-azure-databricks.md +++ b/localizedContent/zh/content/tutorials/connecting-to-azure-databricks.md @@ -51,9 +51,9 @@ Tabular Editor 使用 Power Query `Databricks.Catalogs()` 函数连接到 Databr 连接到 Azure Databricks 时，您可以使用以下几种身份验证方法： -### 1。 Microsoft Entra ID（原 Azure AD）身份验证 +### 1。 Microsoft Entra ID（前身为 Azure AD）身份验证 -如果你的组织使用 Microsoft Entra ID，建议采用这种方式连接到 Azure Databricks。 这种方法可提供无缝的单点登录，并通过托管身份提升安全性。 +如果你的组织使用 Microsoft Entra ID，这是连接到 Azure Databricks 的推荐方法。 这种方法可提供无缝的单点登录，并通过托管身份提升安全性。 #### 关于 Tabular Editor 企业应用 @@ -62,18 +62,18 @@ Tabular Editor 使用 Power Query `Databricks.Catalogs()` 函数连接到 Databr 此企业应用需要以下 API 权限： - **Microsoft Graph** (`00000003-0000-0000-c000-000000000000`) - - `offline_access`（委托）- 此权限允许 Tabular Editor 即使在你未主动使用该应用时，也能持续访问你已授权其访问的数据。 这是维持与 Databricks 持续连接所必需的。 + - `offline_access`（委托）- 此权限允许 Tabular Editor 在你未主动使用应用程序时，仍能持续访问你已授权给它的数据。 这是维持与 Databricks 持续连接所必需的。 - `openid`（委托）- 允许用户使用其工作或学校账户登录该应用，并允许该应用查看基本的用户个人资料信息。 - `profile`（委托）- 允许该应用查看基本个人资料信息，例如姓名、电子邮件地址、照片和用户名。 - `User.Read`（委托）- 允许该应用读取您的个人资料，并在访问 Databricks API 时识别您的身份。 - **Azure Databricks API** (`2ff814a6-3304-4ab8-85cb-cd0e6f879c1d`) - - `user_impersonation`（委托）- 代表已登录用户访问 Azure Databricks。 这样，Tabular Editor 就能使用你的凭据连接到 Databricks Workspace。 + - `user_impersonation`（委托）- 代表已登录用户访问 Azure Databricks。 这使 Tabular Editor 能够使用你的凭据连接到你的 Databricks Workspace。 有关 Microsoft Entra ID 权限的更多信息，请参阅 [Microsoft 关于权限类型的文档](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent) 和 [应用同意体验](https://learn.microsoft.com/en-us/azure/active-directory/develop/application-consent-experience)。 > [!IMPORTANT] -> Tabular Editor 需要这些权限，才能通过您的 Microsoft Entra ID 凭据安全访问您的 Azure Databricks 数据。 如果没有这些权限，Tabular Editor 将无法在你的 Azure Databricks Workspace 中正确完成身份验证。 +> Tabular Editor 需要这些权限，才能通过您的 Microsoft Entra ID 凭据安全访问您的 Azure Databricks 数据。 如果没有这些权限，Tabular Editor 将无法对你的 Azure Databricks Workspace 正确进行身份验证。 #### Microsoft Entra ID 身份验证的同意流程 @@ -88,7 +88,7 @@ Tabular Editor 使用 Power Query `Databricks.Catalogs()` 函数连接到 Databr 3. 点击 **Accept** 以授予同意 > [!NOTE] -> 是否需要管理员同意取决于你所在组织的 Microsoft Entra ID 策略，而不一定取决于所请求的具体 API 权限。 许多组织允许用户自行同意委托权限，而另一些组织则要求所有第三方应用程序无论权限级别如何都必须由管理员批准。 +> 是否需要管理员同意取决于你所在组织的 Microsoft Entra ID 策略，不一定取决于所请求的具体 API 权限。 许多组织允许用户自行同意委托权限，而另一些组织则要求所有第三方应用程序无论权限级别如何都必须由管理员批准。 ##### 需要管理员同意 @@ -180,7 +180,7 @@ https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=ea0f ## 查找你的 HTTP Path -HTTP Path 参数对于连接到 Databricks SQL Warehouse 至关重要。 查找该值的方法： +HTTP Path 参数对于连接到你的 Databricks SQL Warehouse 至关重要。 查找该值的方法： 1. 前往你的 Databricks Workspace 2. 依次选择 **SQL** > **SQL Warehouse** @@ -241,7 +241,7 @@ HTTP Path 参数对于连接到 Databricks SQL Warehouse 至关重要。 查找 2. 请他们将 Tabular Editor 企业应用程序（ID：`ea0fc0fe-ed02-40d7-a29a-cc0a59d8b42c`）添加到你组织的允许应用程序列表中 > [!TIP] -> 在某些组织中，IT 部门在批准新的企业应用程序之前，可能需要提交正式申请或进行安全审查。 你需要准备好说明：此应用由 Tabular Editor 3 使用，借助组织现有的 Microsoft Entra ID 身份验证基础架构，安全连接到 Azure Databricks 资源。 +> 在某些组织中，IT 部门在批准新的企业应用程序之前，可能需要提交正式申请或进行安全审查。 请准备好解释：此应用程序由 Tabular Editor 3 使用，借助你所在组织现有的 Microsoft Entra ID 身份验证基础设施，安全连接到 Azure Databricks 资源。 ## 在 Databricks 中使用“更新表架构”