diff --git a/data-explorer/includes/kusto-emulator-limitations.md b/data-explorer/includes/kusto-emulator-limitations.md index c390177e4f..56a9d21349 100644 --- a/data-explorer/includes/kusto-emulator-limitations.md +++ b/data-explorer/includes/kusto-emulator-limitations.md @@ -1,7 +1,7 @@ --- ms.service: azure ms.topic: include -ms.date: 08/14/2022 +ms.date: 02/05/2025 --- ## Limitations @@ -21,7 +21,7 @@ In general, this offering isn't suited for production workloads. - No support for ingestion endpoints, including Kusto.Ingest SDKs - No streaming ingestion - Although ingested data can be stored externally to the container, we don't recommend persisting data for long periods of time for the following reasons: - - There's no guarantee the [extent](/kusto/management/extents-overview?view=azure-data-explorer&preserve-view=true) format will be compatible between versions of the Kusto emulator + - There's no guarantee the [extent](/kusto/management/extents-overview?view=azure-data-explorer&preserve-view=true) format is compatible between versions of the Kusto emulator - Extents aren't [merged](/kusto/management/merge-policy?view=azure-data-explorer&preserve-view=true) and therefore can become fragmented as data get ingested - - Retention policies can be set but won't be honored + - Retention and partitioning policies can be set but aren't honored - The [Python plugin](/kusto/query/python-plugin?view=azure-data-explorer&preserve-view=true?view=azure-data-explorer&preserve-view=true) isn't supported diff --git a/data-explorer/kusto-emulator-install.md b/data-explorer/kusto-emulator-install.md index b8e05f21f3..0d6c13fbd0 100644 --- a/data-explorer/kusto-emulator-install.md +++ b/data-explorer/kusto-emulator-install.md @@ -1,21 +1,21 @@ --- title: Install the Azure Data Explorer Kusto emulator -description: In this article, you'll learn how to install the Azure Data Explorer Kusto emulator and run your first query. +description: In this article, you learn how to install the Azure Data Explorer Kusto emulator and run your first query. ms.reviewer: vplauzon ms.topic: how-to -ms.date: 12/05/2023 +ms.date: 02/09/2025 --- # Install the Azure Data Explorer Kusto emulator You can install the Azure Data Explorer Kusto emulator in the following ways: -- On your own device: Consider using this option if you need to provision a local development environment -- On a CI/CD agent virtual machine (VM): Use this option if you require a CI/CD pipeline for running automated tests +- **On your own device**: Consider using this option if you need to provision a local development environment +- **On a CI/CD agent virtual machine (VM)**: Use this option if you require a CI/CD pipeline for running automated tests -The emulator is available as a *Windows* or *Linux* Docker container image. +The emulator is available as a *Linux* and *Windows* Docker container image. -In this article, you'll learn how to: +In this article, you learn how to: - [Install the Kusto emulator](#install-the-kusto-emulator) - [Connect to the emulator](#connect-to-the-emulator) @@ -23,6 +23,8 @@ In this article, you'll learn how to: - [Ingest data](#ingest-data) - [Query data](#query-data) +This article focuses on how to install the Linux Docker container on a Windows client. + ## Prerequisites - The host operating system must be one of: @@ -35,25 +37,35 @@ In this article, you'll learn how to: > Linux distros only support Linux container images. - 2 gigabytes (GB) of RAM minimum; we recommend using 4 GB or more -- Docker Client for [Windows](https://docs.docker.com/desktop/windows/install/) or [Linux](https://docs.docker.com/desktop/install/linux-install/) +- Docker Client for [Linux](https://docs.docker.com/desktop/install/linux-install/) or [Windows](https://docs.docker.com/desktop/windows/install/) ## Install the Kusto emulator The following steps are for using PowerShell to start the emulator using the [Kusto emulator container image](https://aka.ms/adx.emulator.image). For other options, see [Run emulator options](#run-emulator-options). -1. For Windows only, switch Docker to run with Windows containers. You may need to enable the feature in the Docker settings. +1. **For Windows container only**: Switch Docker to run with Windows containers. You might need to enable the feature in the Docker settings. :::image type="content" source="media/kusto-emulator/kusto-emulator-docker-windows-container.png" alt-text="Screenshot of the Docker settings, showing the Switch to Windows containers option."::: 1. Run the following command to start the emulator. > [!IMPORTANT] - > The Kusto emulator container image is a free offering under the [Microsoft Software License Terms](https://aka.ms/adx.emulator.license). Since the emulator runs in a container, you must accept the license terms by passing the `ACCEPT_EULA` environment variable to the container with its value set to `Y` indicating. + > The Kusto emulator container image is a free offering under the [Microsoft Software License Terms](https://aka.ms/adx.emulator.license). Since the emulator runs in a container, you must accept the license terms by passing the `ACCEPT_EULA` environment variable to the container with its value set to `Y`. > [!NOTE] > - > - The first time this command is run, Docker pulls the container image which is several GBs in size and may take several minutes to download. Once downloaded, the image is cached and available for subsequent runs without having to download it again. - > - (For Windows container only) The container must be run in process-isolation mode. This is the default on some versions of Docker. For other versions, you can start the container in Hyper-V isolation mode by adding `--isolation=hyperv` to the run command. + > - The first time this command is run, Docker pulls the container image which is several GBs in size and might take several minutes to download. Once downloaded, the image is cached and available for subsequent runs without having to download it again. + > - **For Windows container only**: The container must run in process-isolation mode. This is the default on some versions of Docker. For other versions, you can start the container in Hyper-V isolation mode by adding `--isolation=hyperv` to the run command. + + # [Linux container](#tab/linux-container) + + To start the Linux container, make sure you use the `latest` or `stable` tag: + + ```powershell + docker run -e ACCEPT_EULA=Y -m 4G -d -p 8080:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer-linux:latest + ``` + + # [Windows container](#tab/windowscontainer) - To start the Windows container on Windows Server operating system, make sure you use the `latest` or `stable` tag: @@ -67,11 +79,7 @@ The following steps are for using PowerShell to start the emulator using the [Ku docker run -e ACCEPT_EULA=Y -m 4G -d -p 8080:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer:windows11 ``` - - To start the Linux container: - - ```powershell - docker run -e ACCEPT_EULA=Y -m 4G -d -p 8080:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer-linux:latest - ``` + --- 1. Run the following command to verify that the container is running. @@ -114,24 +122,35 @@ The following steps are for using PowerShell to start the emulator using the [Ku RawContentLength : 988 ``` -### Run emulator options +## Run emulator options You can use any of the following options when running the emulator: - Mount a local folder to the container: Use this option to mount a folder in the host environment into the container. Mounting a host folder enables your queries to interact with local files, which is useful for [creating a database persistent between container runs](#create-a-database) and [ingesting data](#ingest-data). - For example, to mount the folder "D:\host\local" on the host to the folder "c:\kustodatadata" in the container, use the next command on Windows Server: + # [Linux container](#tab/linux-container) + + For example, to mount the folder "D:\host\local" on the host to the folder "/kustodatadata" in the container, use the following command on Windows Server: + + ```powershell + docker run -v d:\host\local:/kustodata -e ACCEPT_EULA=Y -m 4G -d -p 8080:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer-linux:latest + ``` + + # [Windows container](#tab/windowscontainer) + For example, to mount the folder "D:\host\local" on the host to the folder "c:\kustodata" in the container, use the following command on Windows Server: ```powershell docker run -v d:\host\local:c:\kustodata -e ACCEPT_EULA=Y -m 4G -d -p 8080:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer:latest ``` + --- + - Run on a different port: The Kusto emulator exposes access to the Kusto Query Engine on port 8080; hence in other examples you mapped the host port 8080 to the emulator port 8080. You can use this option to map a different host to the engine. For example, to map port 9000 on the host to the engine, use the following command on Windows Server: ```powershell - docker run -e ACCEPT_EULA=Y -m 4G -d -p 9000:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer:latest + docker run -e ACCEPT_EULA=Y -m 4G -d -p 9000:8080 -t mcr.microsoft.com/azuredataexplorer/kustainer-linux:latest ``` ## Connect to the emulator @@ -142,19 +161,19 @@ You can use any of the following tools to connect to and interact with the emula - [Kusto.CLI](/kusto/tools/kusto-cli?view=azure-data-explorer&preserve-view=true) - [Kusto.Data SDKs](/kusto/api/netfx/about-kusto-data?view=azure-data-explorer&preserve-view=true) -In the following sections, you'll use Kusto.Explorer to create a database, ingest data, and query it. To learn more, see [Using Kusto.Explorer](/kusto/tools/kusto-explorer-using?view=azure-data-explorer&preserve-view=true). +In the following sections, you use Kusto.Explorer to create a database, ingest data, and query it. To learn more, see [Using Kusto.Explorer](/kusto/tools/kusto-explorer-using?view=azure-data-explorer&preserve-view=true). > [!IMPORTANT] > The Kusto Emulator doesn't support HTTPS or Microsoft Entra authentication. > > You must first allow unsafe connections in **Tools** > **Options** > **Connections** > **Allow unsafe connections**. -> +> > :::image type="content" source="media/kusto-emulator/unsafe-connections.png" alt-text="Screenshot of Kusto Explorer connection options."::: -> +> > The following image highlights the affected fields in the **Add connection** properties. > > - The **Cluster connection** must begin with `http://` and not `https://`. -> - In **Security** > **Advanced: Connection String**, you'll need to remove the `AAD Federated Security=True` portion of the connection string to disable Microsoft Entra authentication. +> - In **Security** > **Advanced: Connection String**, you need to remove the `AAD Federated Security=True` portion of the connection string to disable Microsoft Entra authentication. > > :::image type="content" source="media/kusto-emulator/kusto-emulator-connection.png" alt-text="Screenshot of Kusto Explorer single connection setup."::: @@ -162,27 +181,30 @@ In the following sections, you'll use Kusto.Explorer to create a database, inges To store data and run queries, create a database or attach the emulator to an existing database. -A database can be persisted in a container folder or on a [mounted folder](#run-emulator-options). The former's lifetime is bound to the container, so restarting the container loses any changes. Also, the container virtual storage is less efficient than native one. Mounted folder enables you to keep the data between container runs. +A database can be persisted in a container folder or on a [mounted folder](#run-emulator-options). The former's lifetime is bound to the container, so restarting the container loses any changes. Also, the container virtual storage is less efficient than native one. Mounted folder enables you to keep the data between container runs. In this example, we keep the data on the container. -In the [Kusto.Explorer Query mode](/kusto/tools/kusto-explorer-using?view=azure-data-explorer&preserve-view=true#query-mode), run the following command to create a persistent database if using a Windows container image: +In the [Kusto.Explorer Query mode](/kusto/tools/kusto-explorer-using?view=azure-data-explorer&preserve-view=true#query-mode), run the following command to create a persistent database: + +# [Linux container](#tab/linux-container) ```kusto .create database persist ( - @"c:\kustodata\dbs\\md", - @"c:\kustodata\dbs\\data" + @"/kustodata/dbs//md", + @"/kustodata/dbs//data" ) ``` -The equivalent command for a Linux container image is: +# [Windows container](#tab/windowscontainer) ```kusto .create database persist ( - @"/kustodata/dbs//md", - @"/kustodata/dbs//data" + @"c:\kustodata\dbs\\md", + @"c:\kustodata\dbs\\data" ) ``` +--- This command requires that the folders don't already exist, to prevent over-writing existing information. To attach to an existing database, use the following command instead, specifying the path that ends with `md`: @@ -190,7 +212,7 @@ This command requires that the folders don't already exist, to prevent over-writ .attach database from @"" ``` -It's also possible to detach the database from the emulator, which will keep all the database metadata and data intact (so you could reattach to it in the future): +It's also possible to detach the database from the emulator, which will keep all the database metadata and data intact so you can reattach to it in the future: ```kusto .detach database @@ -200,7 +222,7 @@ It's also possible to detach the database from the emulator, which will keep all To ingest data, you must first create an external table linked to a file and then ingest the data into a table in the database. -Use the steps in the following example to create an external table and ingest data into it. For the example, in the local folder *c:\kustodata*, create a file called `sample.csv` with the following data: +Use the steps in the following example to create an external table and ingest data into it. As part of the example, create a file called `sample.csv` in the local folder *d:\host\local*, with the following data: ```text Alice, 1 @@ -217,7 +239,7 @@ Carl, 3 1. Run the following command to [ingest the file into the table](/kusto/management/data-ingestion/ingest-from-storage?view=azure-data-explorer&preserve-view=true): ```kusto - .ingest into table MyIngestedSample(@"c:\kustodata\sample.csv") + .ingest into table MyIngestedSample(@"/kustodata/sample.csv") ``` ## Query data diff --git a/data-explorer/kusto-emulator-overview.md b/data-explorer/kusto-emulator-overview.md index 154376cdb6..e9193c77f4 100644 --- a/data-explorer/kusto-emulator-overview.md +++ b/data-explorer/kusto-emulator-overview.md @@ -1,9 +1,9 @@ --- title: Azure Data Explorer Kusto emulator overview -description: In this article, you'll learn about the Azure Data Explorer Kusto emulator +description: In this article, you learn about the Azure Data Explorer Kusto emulator. ms.reviewer: vplauzon ms.topic: conceptual -ms.date: 05/08/2023 +ms.date: 02/06/2025 --- # Azure Data Explorer Kusto emulator @@ -13,11 +13,11 @@ The Kusto emulator is a local environment that encapsulates the query engine. Yo > > - The emulator is provided *as-is*, without any support or warranties. > - The emulator isn't intended for use in production environments. -> - The [license terms](https://aka.ms/adx.emulator.license) explicitly prohibit benchmark tests using the emulator as it is not intended or optimized for that purpose. The emulator has a very different performance profile compared to the Azure Data Explorer service. +> - The [license terms](https://aka.ms/adx.emulator.license) explicitly prohibit benchmark tests using the emulator as it isn't intended or optimized for that purpose. The emulator has a different performance profile compared to the Azure Data Explorer service. ## Architecture -The emulator is available as a *Windows* or *Linux* Docker container image. It exposes a query endpoint over HTTP that can be used with any client including [Kusto.Explorer](/kusto/tools/kusto-explorer-using?view=azure-data-explorer&preserve-view=true), [Kusto.CLI](/kusto/tools/kusto-cli?view=azure-data-explorer&preserve-view=true), or [Kusto.Data SDKs](/kusto/api/netfx/about-kusto-data?view=azure-data-explorer&preserve-view=true). +The emulator is available as a *Linux* and *Windows* Docker container image. It exposes a query endpoint over HTTP that can be used with any client including [Kusto.Explorer](/kusto/tools/kusto-explorer-using?view=azure-data-explorer&preserve-view=true), [Kusto.CLI](/kusto/tools/kusto-cli?view=azure-data-explorer&preserve-view=true), or [Kusto.Data SDKs](/kusto/api/netfx/about-kusto-data?view=azure-data-explorer&preserve-view=true). ![Schematic representation of Kusto emulator architecture.](media/kusto-emulator/kusto-emulator-architecture.png) @@ -34,7 +34,7 @@ The main scenarios for the emulator are: ## Kusto emulator vs. free cluster -There are some overlaps between the Kusto emulator and the [free cluster](start-for-free.md) offerings. The following table contrasts the features of the offerings. +There are some overlaps between the Kusto emulator and the [free cluster](start-for-free.md) offerings. The following table contrasts the features of the offerings. | Item | Kusto emulator | Free cluster | |--|--|--| @@ -49,10 +49,10 @@ There are some overlaps between the Kusto emulator and the [free cluster](start- | Long term data management | No extent merge capability | Full support | | Internet requirement | No connectivity required | Cloud service | -When choosing the best option for your use case, you should consider the following: +When choosing the best option for your use case, you should consider: - **Local development**: The best fit for local development depends on the features you require. For instance, if your scenario requires the use of managed pipelines, the free cluster offering works best. On the other hand, if your scenario requires local development in a disconnected environment, the Kusto emulator would be a better fit. -- **Automated testing**: In general, the Kusto emulator is more suited to automated testing than the free cluster offering. It's faster to provision and doesn't require any Azure principal to set up. +- **Automated testing**: In general, the Kusto emulator is more suited to automated testing than the free cluster offering. It's faster to provision and doesn't require any Azure principal to set up. [!INCLUDE [kusto-emulator-limitations](includes/kusto-emulator-limitations.md)] diff --git a/data-explorer/kusto/includes/help-cluster-note-data-explorer-only.md b/data-explorer/kusto/includes/help-cluster-note-data-explorer-only.md new file mode 100644 index 0000000000..f968e9b4dc --- /dev/null +++ b/data-explorer/kusto/includes/help-cluster-note-data-explorer-only.md @@ -0,0 +1,8 @@ +--- +ms.topic: include +ms.date: 01/22/2025 +--- + +:::moniker range="azure-data-explorer" +> The examples in this article use publicly available tables in the [help cluster](https://dataexplorer.azure.com/clusters/help/), such as the `StormEvents` table in the *Samples* database. +::: moniker-end \ No newline at end of file diff --git a/data-explorer/kusto/management/alter-merge-managed-identity-policy-command.md b/data-explorer/kusto/management/alter-merge-managed-identity-policy-command.md index 496856341e..19f41a73a3 100644 --- a/data-explorer/kusto/management/alter-merge-managed-identity-policy-command.md +++ b/data-explorer/kusto/management/alter-merge-managed-identity-policy-command.md @@ -32,16 +32,18 @@ You must have [AllDatabasesAdmin](../access-control/role-based-access-control.md |Name|Type|Required|Description| |--|--|--|--| |*DatabaseName*| `string` | :heavy_check_mark:|The name of the database.| -|*ArrayOPolicyObjects*|array| :heavy_check_mark:|A serialized array with zero or more [ManagedIdentity policy](managed-identity-policy.md#the-managedidentity-policy-object) objects defined.| +|*ArrayOfPolicyObjects*|array| :heavy_check_mark:|A serialized array with zero or more [ManagedIdentity policy](managed-identity-policy.md#the-managedidentity-policy-object) objects defined, each defined with only the *ObjectId* and *AllowedUsages* properties.| > [!NOTE] > > * Policy objects must define the *ObjectId* and *AllowedUsages* properties. Other properties are automatically populated. > -> * For every item in `ArrayOfManagedIdentityPolicyObjects`: +> * For every item in *ArrayOfPolicyObjects*: > -> * If the ObjectId *doesn't exist* in the ManagedIdentity policy, the item will be added to the policy. -> * If the ObjectId *already exists* in the ManagedIdentity policy, the identity's AllowedUsages property will be added to the relevant item in the policy. For example, if the current policy has AllowedUsages="NativeIngestion" for a specific managed identity, then if `ArrayOfManagedIdentityPolicyObjects` has an item for this managed identity with AllowedUsages="ExternalTables", then the AllowedUsages for this managed identity in the Managed Identity policy will become "NativeIngestion, ExternalTables". +> * If the *ObjectId* doesn't exist in the ManagedIdentity policy, the item is added to the policy. +> * If the *ObjectId* already exists in the ManagedIdentity policy: +> * The identity's *AllowedUsages* property is added to the relevant item in the policy. For example, if the current policy has AllowedUsages="NativeIngestion" for a specific managed identity, then if *ArrayOfPolicyObjects* has an item for this managed identity with AllowedUsages="ExternalTables", then the AllowedUsages for this managed identity in the ManagedIdentity policy becomes "NativeIngestion, ExternalTables". +> * The latest information about the managed identity, such as the *DisplayName*, is retrieved from Microsoft Entra and updated in the policy. ### Getting the managed identity object ID diff --git a/data-explorer/kusto/query/project-rename-operator.md b/data-explorer/kusto/query/project-rename-operator.md index 6fde356267..f17d06cb85 100644 --- a/data-explorer/kusto/query/project-rename-operator.md +++ b/data-explorer/kusto/query/project-rename-operator.md @@ -35,16 +35,16 @@ If you have a table with columns a, b, and c, and you want to rename a to new_a :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] -> Run the query +> Run the query ::: moniker-end ```kusto -print a='a', b='b', c='c' -| project-rename new_b=b, new_a=a +print a='alpha', b='bravo', c='charlie' +| project-rename new_a=a, new_b=b, new_c=c ``` **Output** -| new_a | new_b | c | +|new_a|new_b|new_c| |--|--|--| -| a | b | c | +|alpha|bravo|charlie| diff --git a/data-explorer/kusto/query/visualization-piechart.md b/data-explorer/kusto/query/visualization-piechart.md index e7569d24f7..1c36f3d3b7 100644 --- a/data-explorer/kusto/query/visualization-piechart.md +++ b/data-explorer/kusto/query/visualization-piechart.md @@ -3,8 +3,7 @@ title: Pie chart visualization description: This article describes the pie chart visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 08/11/2024 -monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || microsoft-sentinel" +ms.date: 01/28/2025 --- # Pie chart @@ -31,7 +30,7 @@ The pie chart visual can also be used in the context of [Geospatial visualizatio | Name | Type | Required | Description | | -- | -- | -- | -- | -| *T* | `string` | :heavy_check_mark: | Input table name. +| *T* | `string` | :heavy_check_mark: | Input table name.| | *propertyName*, *propertyValue* | `string` | | A comma-separated list of key-value property pairs. See [supported properties](#supported-properties).| ### Supported properties @@ -43,7 +42,7 @@ All properties are optional. |*PropertyName*|*PropertyValue* | |--------------|----------------------------------------------------------------------------------| |`accumulate` |Whether the value of each measure gets added to all its predecessors. (`true` or `false`)| -|`kind` |Further elaboration of the visualization kind. For more information, see [`kind` property](#kind-property). | +|`kind` |Further elaboration of the visualization kind. For more information, see [`kind` property](#kind-property). | |`legend` |Whether to display a legend or not (`visible` or `hidden`). | |`series` |Comma-delimited list of columns whose combined per-record values define the series that record belongs to.| |`title` |The title of the visualization (of type `string`). | @@ -77,6 +76,10 @@ The supported values of this property are: ## Example +[!INCLUDE [help-cluster-note](../includes/help-cluster-note.md)] + +This query provides a visual representation of the top 10 states with the highest number of storm events, displayed as a pie chart + :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] > Run the query @@ -90,4 +93,4 @@ StormEvents | render piechart with(title="Storm Events by State") ``` -:::image type="content" source="media/visualization-piechart/pie-chart.png" alt-text="Screenshot of pie chart visualization output." lightbox="media/visualization-piechart/pie-chart.png"::: \ No newline at end of file +:::image type="content" source="media/visualization-piechart/pie-chart.png" alt-text="Screenshot of pie chart visualization output." lightbox="media/visualization-piechart/pie-chart.png"::: diff --git a/data-explorer/kusto/query/visualization-pivotchart.md b/data-explorer/kusto/query/visualization-pivotchart.md index 5b3506670b..6bec9c572a 100644 --- a/data-explorer/kusto/query/visualization-pivotchart.md +++ b/data-explorer/kusto/query/visualization-pivotchart.md @@ -3,7 +3,7 @@ title: Pivot chart visualization description: This article describes the pivot chart visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 08/11/2024 +ms.date: 01/21/2025 monikerRange: "azure-data-explorer" --- # Pivot chart @@ -15,7 +15,7 @@ Displays a pivot table and chart. You can interactively select data, columns, ro > [!NOTE] > > * This visualization can only be used in the context of the [render operator](render-operator.md). -> * This visualization can be used in Kusto.Explorer but is not available in the Azure Data Explorer web UI. +> * This visualization can be used in Kusto.Explorer but isn't available in the Azure Data Explorer web UI. ## Syntax @@ -31,6 +31,10 @@ Displays a pivot table and chart. You can interactively select data, columns, ro ## Example +This query provides a detailed analysis of sales for Contoso computer products within the specified date range, visualized as a pivot chart. + +[!INCLUDE [help-cluster-note-data-explorer-only](../includes/help-cluster-note-data-explorer-only.md)] + ```kusto SalesFact | join kind= inner Products on ProductKey @@ -40,4 +44,6 @@ SalesFact | render pivotchart ``` +**Output** + :::image type="content" source="media/visualize-pivotchart/pivotchart.png" alt-text="Screenshot of query result showing a pivot chart visualization." lightbox="media/visualize-pivotchart/pivotchart.png"::: diff --git a/data-explorer/kusto/query/visualization-plotly.md b/data-explorer/kusto/query/visualization-plotly.md index 11c5cd265a..bbf8e6caf4 100644 --- a/data-explorer/kusto/query/visualization-plotly.md +++ b/data-explorer/kusto/query/visualization-plotly.md @@ -3,8 +3,7 @@ title: Plotly visualization description: This article describes how to visualize data using the Plotly graphics library. ms.reviewer: adieldar ms.topic: reference -ms.date: 08/11/2024 -monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || microsoft-sentinel" +ms.date: 01/28/2025 --- # Plotly (preview) @@ -12,7 +11,7 @@ monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || micro ::: moniker range="microsoft-fabric || azure-data-explorer" -The Plotly graphics library supports ~80 chart types that are useful for advanced charting including geographic, scientific, machine learning, 3d, animation, and many other chart types. For more information, see [Plotly](https://plotly.com/python/). +The Plotly graphics library supports ~80 chart types that are useful for advanced charting including geographic, scientific, machine learning, 3d, animation, and many other chart types. For more information, see [Plotly](https://plotly.com/python/). To render a Plotly visual in Kusto Query Language, the query must generate a table with a single string cell containing [Plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). This Plotly JSON string can be generated by one of the following two methods: @@ -23,14 +22,14 @@ To render a Plotly visual in Kusto Query Language, the query must generate a tab In this method, you dynamically create the Plotly JSON string in Python using the [Plotly package](https://plotly.com/python/getting-started/). This process requires use of the [python() plugin](python-plugin.md). The Python script is run on the existing nodes using the inline python() plugin. It generates a Plotly JSON that is rendered by the client application. -Using this method, all types of Plotly visualizations are supported. +All types of Plotly visualizations are supported. > [!NOTE] -> For best performance, make sure that the python plugin image contains the latest version of the Python engine (currently 3.10.8). This can be checked with the [get_packages_version_fl()](../functions-library/get-packages-version-fl.md) function. To upgrade the Python image see [Change the Python language extensions image on your cluster](/azure/data-explorer/language-extensions#change-the-python-language-extensions-image-on-your-cluster). +> For best performance, make sure that the python plugin image contains the latest version of the Python engine (currently 3.10.8). Check the latest version with the [get_packages_version_fl()](../functions-library/get-packages-version-fl.md) function. To upgrade the Python image, see [Change the Python language extensions image on your cluster](/azure/data-explorer/language-extensions#change-the-python-language-extensions-image-on-your-cluster). ### Example -The following KQL query uses inline Python to create a 3D scatter chart: +The following query uses inline Python to create a 3D scatter chart: ~~~kusto OccupancyDetection @@ -54,7 +53,7 @@ OccupancyDetection The Plotly graphics library supports ~80 chart types including basic charts, scientific, statistical, financial, maps, 3D, animations, and more. To render a Plotly visual in KQL, the query must generate a table with a single string cell containing [Plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). -Since python is not available in this service, you create this Plotly JSON using a preprepared template. +Since python isn't available in this service, you create this Plotly JSON using a preprepared template. ::: moniker-end diff --git a/data-explorer/kusto/query/visualization-scatterchart.md b/data-explorer/kusto/query/visualization-scatterchart.md index 930a5cd1fa..6f970230c2 100644 --- a/data-explorer/kusto/query/visualization-scatterchart.md +++ b/data-explorer/kusto/query/visualization-scatterchart.md @@ -3,8 +3,7 @@ title: Scatter chart visualization description: This article describes the scatter chart visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 08/11/2024 -monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || microsoft-sentinel" +ms.date: 01/28/2025 --- # Scatter chart @@ -38,7 +37,7 @@ All properties are optional. |*PropertyName*|*PropertyValue* | |--------------|----------------------------------------------------------------------------------| |`accumulate` |Whether the value of each measure gets added to all its predecessors. (`true` or `false`)| -|`kind` |Further elaboration of the visualization kind. For more information, see [`kind` property](#kind-property). | +|`kind` |Further elaboration of the visualization kind. For more information, see [`kind` property](#kind-property). | |`legend` |Whether to display a legend or not (`visible` or `hidden`). | |`series` |Comma-delimited list of columns whose combined per-record values define the series that record belongs to.| |`ymin` |The minimum value to be displayed on Y-axis. | @@ -63,7 +62,6 @@ All properties are optional. ::: moniker-end - #### `kind` property This visualization can be further elaborated by providing the `kind` property. @@ -75,6 +73,10 @@ The supported values of this property are: ## Example +This query provides a scatter chart that helps you analyze the correlation between state populations and the total property damage caused by storm events. + +[!INCLUDE [help-cluster-note](../includes/help-cluster-note.md)] + :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] > Run the query @@ -88,4 +90,4 @@ StormEvents | render scatterchart with (xtitle="State population", title="Property damage by state", legend=hidden) ``` -:::image type="content" source="media/visualization-scatterchart/scatter-chart.png" alt-text="Screenshot of scatter chart visualization output." lightbox="media/visualization-scatterchart/scatter-chart.png"::: \ No newline at end of file +:::image type="content" source="media/visualization-scatterchart/scatter-chart.png" alt-text="Screenshot of scatter chart visualization output." lightbox="media/visualization-scatterchart/scatter-chart.png"::: diff --git a/data-explorer/kusto/query/visualization-stackedareachart.md b/data-explorer/kusto/query/visualization-stackedareachart.md index 6830d19cf9..d0ea958a9d 100644 --- a/data-explorer/kusto/query/visualization-stackedareachart.md +++ b/data-explorer/kusto/query/visualization-stackedareachart.md @@ -3,7 +3,7 @@ title: Stacked area chart visualization description: This article describes the stacked area chart visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 11/27/2024 +ms.date: 01/21/2025 monikerRange: "microsoft-fabric || azure-data-explorer" --- # Stacked area chart @@ -51,6 +51,8 @@ All properties are optional. The following query summarizes data from the `nyc_taxi` table by number of passengers and visualizes the data in a stacked area chart. The x-axis shows the pickup time in two day intervals, and the stacked areas represent different passenger counts. +[!INCLUDE [help-cluster-note](../includes/help-cluster-note.md)] + :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] > Run the query diff --git a/data-explorer/kusto/query/visualization-table.md b/data-explorer/kusto/query/visualization-table.md index bd264e0db3..8c4080e3ed 100644 --- a/data-explorer/kusto/query/visualization-table.md +++ b/data-explorer/kusto/query/visualization-table.md @@ -3,8 +3,7 @@ title: Table visualization description: This article describes the table visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 08/11/2024 -monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || microsoft-sentinel" +ms.date: 01/28/2025 --- # Table @@ -62,6 +61,10 @@ All properties are optional. ## Example +This query outputs a snapshot of the first 10 storm event records, displayed in a table format. + +[!INCLUDE [help-cluster-note](../includes/help-cluster-note.md)] + :::moniker range="azure-data-explorer" > [!div class="nextstepaction"] > Run the query @@ -73,4 +76,4 @@ StormEvents | render table ``` -:::image type="content" source="media/visualization-table/table-visualization.png" alt-text="Screenshot of table visualization output." lightbox="media/visualization-table/table-visualization.png"::: \ No newline at end of file +:::image type="content" source="media/visualization-table/table-visualization.png" alt-text="Screenshot of table visualization output." lightbox="media/visualization-table/table-visualization.png"::: diff --git a/data-explorer/kusto/query/visualization-timechart.md b/data-explorer/kusto/query/visualization-timechart.md index 2f29f57bc4..b668f3791c 100644 --- a/data-explorer/kusto/query/visualization-timechart.md +++ b/data-explorer/kusto/query/visualization-timechart.md @@ -3,8 +3,7 @@ title: Time chart visualization description: This article describes the time chart visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 11/13/2024 -monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || microsoft-sentinel" +ms.date: 01/21/2025 --- # Time chart @@ -62,6 +61,10 @@ This visualization supports splitting into multiple y-axis values: ## Examples +The example in this section shows how to use the syntax to help you get started. + +[!INCLUDE [help-cluster](../includes/help-cluster-note.md)] + ### Render a timechart The following example renders a timechart with a title "Web app. traffic over a month, decomposing" that decomposes the data into baseline, seasonal, trend, and residual components. @@ -89,7 +92,7 @@ demo_make_series2 ### Label a timechart -The following example renders a timechart that depicts crop damage grouped by week. The timechart x axis is labeled "Date" and the y axis is labeled "Crop damage." +The following example renders a timechart that depicts crop damage grouped by week. The timechart x axis label is "Date" and the y axis label is "Crop damage." ::: moniker-end ::: moniker range="azure-data-explorer" diff --git a/data-explorer/kusto/query/visualization-timepivot.md b/data-explorer/kusto/query/visualization-timepivot.md index d0389a5e53..cd78f6709a 100644 --- a/data-explorer/kusto/query/visualization-timepivot.md +++ b/data-explorer/kusto/query/visualization-timepivot.md @@ -3,7 +3,7 @@ title: Time pivot visualization description: This article describes the time pivot visualization. ms.reviewer: alexans ms.topic: reference -ms.date: 08/11/2024 +ms.date: 01/21/2025 monikerRange: "azure-data-explorer" --- # Time pivot @@ -15,7 +15,7 @@ The time pivot visualization is an interactive navigation over the events time-l > [!NOTE] > > * This visualization can only be used in the context of the [render operator](render-operator.md). -> * This visualization can be used in Kusto.Explorer but is not available in the Azure Data Explorer web UI. +> * This visualization can be used in Kusto.Explorer but isn't available in the Azure Data Explorer web UI. ## Syntax @@ -27,7 +27,7 @@ The time pivot visualization is an interactive navigation over the events time-l | Name | Type | Required | Description | | -- | -- | -- | -- | -| *T* | `string` | :heavy_check_mark: | Input table name. +| *T* | `string` | :heavy_check_mark: | Input table name.| | *propertyName*, *propertyValue* | `string` | | A comma-separated list of key-value property pairs. See [supported properties](#supported-properties).| ### Supported properties @@ -51,6 +51,10 @@ All properties are optional. ## Example +This query outputs a visualization of flood events in the specified Midwestern states, displayed as a time pivot chart. + +[!INCLUDE [help-cluster-note-data-explorer-only](../includes/help-cluster-note-data-explorer-only.md)] + ```kusto let midwesternStates = dynamic([ "ILLINOIS", "INDIANA", "IOWA", "KANSAS", "MICHIGAN", "MINNESOTA", @@ -61,4 +65,6 @@ StormEvents | render timepivot with (xcolumn=State) ``` +**Output** + :::image type="content" source="media/visualization-timepivot/time-pivot-visualization.jpg" lightbox="media/visualization-timepivot/time-pivot-visualization.jpg" alt-text="Screenshot of timepivot in Kusto.Explorer."::: diff --git a/data-explorer/kusto/query/visualization-treemap.md b/data-explorer/kusto/query/visualization-treemap.md index 1fa3847daf..ffc759abc3 100644 --- a/data-explorer/kusto/query/visualization-treemap.md +++ b/data-explorer/kusto/query/visualization-treemap.md @@ -3,7 +3,7 @@ title: Treemap visualization description: Learn how to use the treemap visualization to visualize data. ms.reviewer: alexans ms.topic: reference -ms.date: 08/11/2024 +ms.date: 01/28/2025 monikerRange: "azure-data-explorer" --- # Treemap @@ -15,7 +15,7 @@ Treemaps display hierarchical data as a set of nested rectangles. Each level of > [!NOTE] > > * This visualization can only be used in the context of the [render operator](render-operator.md). -> * This visualization can be used in Kusto.Explorer but is not available in the Azure Data Explorer web UI. +> * This visualization can be used in Kusto.Explorer but isn't available in the Azure Data Explorer web UI. ## Syntax @@ -26,9 +26,9 @@ Treemaps display hierarchical data as a set of nested rectangles. Each level of ## Parameters | Name | Type | Required | Description | -| -- | -- | -- | -- | -| *T* | `string` | :heavy_check_mark: | Input table name. -| *propertyName*, *propertyValue* | `string` | | A comma-separated list of key-value property pairs. See [supported properties](#supported-properties).| +|--|--|--|--| +| *T* | `string` | :heavy_check_mark: | Input table name. | +| *propertyName*, *propertyValue* | `string` | | A comma-separated list of key-value property pairs. See [supported properties](#supported-properties). | ### Supported properties @@ -40,6 +40,10 @@ All properties are optional. ## Example +This query counts the number of storm events for each type and state, sorts them in descending order, limits the results to the top 30, and then visualizes the data as a treemap. + +[!INCLUDE [help-cluster-note-data-explorer-only](../includes/help-cluster-note-data-explorer-only.md)] + ```kusto StormEvents | summarize StormEvents=count() by EventType, State