diff --git a/data-explorer/kusto/functions-library/functions-library.md b/data-explorer/kusto/functions-library/functions-library.md index b1340945ca..0a12ed400c 100644 --- a/data-explorer/kusto/functions-library/functions-library.md +++ b/data-explorer/kusto/functions-library/functions-library.md @@ -39,6 +39,7 @@ The following section contains functions for rendering interactive [Plotly chart | Function Name | Description | |--|--| | [plotly_anomaly_fl()](plotly-anomaly-fl.md) | Render anomaly chart using a Plotly template. | +| [plotly_gauge_fl()](plotly-gauge-fl.md) | Render gauge chart using a Plotly template. | | [plotly_scatter3d_fl()](plotly-scatter3d-fl.md) | Render 3D scatter chart using a Plotly template. | ## PromQL functions diff --git a/data-explorer/kusto/functions-library/media/plotly-gauge-fl/plotly-gauge-chart.png b/data-explorer/kusto/functions-library/media/plotly-gauge-fl/plotly-gauge-chart.png new file mode 100644 index 0000000000..a30297455a Binary files /dev/null and b/data-explorer/kusto/functions-library/media/plotly-gauge-fl/plotly-gauge-chart.png differ diff --git a/data-explorer/kusto/functions-library/plotly-anomaly-fl.md b/data-explorer/kusto/functions-library/plotly-anomaly-fl.md index 05359d126a..aeb9d8fc79 100644 --- a/data-explorer/kusto/functions-library/plotly-anomaly-fl.md +++ b/data-explorer/kusto/functions-library/plotly-anomaly-fl.md @@ -12,7 +12,12 @@ monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || micro The function `plotly_anomaly_fl()` is a [user-defined function (UDF)](../query/functions/user-defined-functions.md) that allows you to customize a [plotly](https://plotly.com/python/) template to create an interactive anomaly chart. +::: moniker range="azure-data-explorer" The function accepts a table containing the source and the baseline time series, lists of positive and negative anomalies with their respective sizes, and chart labeling string. The function returns a single cell table containing [plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). Optionally, you can render the data in an [Azure Data Explorer dashboard](/azure/data-explorer/azure-data-explorer-dashboards) tile. For more information, see [Plotly (preview)](../query/visualization-plotly.md). +::: moniker-end +::: moniker range="microsoft-fabric" +The function accepts a table containing the source and the baseline time series, lists of positive and negative anomalies with their respective sizes, and chart labeling string. The function returns a single cell table containing [plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). Optionally, you can render the data in a [Real-Time dashboard](/fabric/real-time-intelligence/dashboard-real-time-create) tile. For more information, see [Plotly (preview)](../query/visualization-plotly.md). +::: moniker-end :::moniker range="azure-data-explorer" > [!NOTE] @@ -205,7 +210,12 @@ demo_make_series2 **Output** +::: moniker range="azure-data-explorer" The output is a Plotly JSON string that can be rendered using '| render plotly' or in an Azure Data Explorer dashboard tile. For more information on creating dashboard tiles, see [Visualize data with Azure Data Explorer dashboards ](/azure/data-explorer/azure-data-explorer-dashboards). +::: moniker-end +::: moniker range="microsoft-fabric" +The output is a Plotly JSON string that can be rendered in a Real-Time dashboard tile. For more information on creating dashboard tiles, see [Real-Time dashboards](/fabric/real-time-intelligence/dashboard-real-time-create). +::: moniker-end The following image shows a sample anomaly chart using the above function: diff --git a/data-explorer/kusto/functions-library/plotly-gauge-fl.md b/data-explorer/kusto/functions-library/plotly-gauge-fl.md new file mode 100644 index 0000000000..7c0285b3dd --- /dev/null +++ b/data-explorer/kusto/functions-library/plotly-gauge-fl.md @@ -0,0 +1,162 @@ +--- +title: plotly_gauge_fl() +description: Learn how to use the plotly_gauge_fl() user-defined function. +ms.reviewer: adieldar +ms.topic: reference +ms.date: 11/12/2024 +monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || microsoft-sentinel" +--- +# plotly_gauge_fl() + +>[!INCLUDE [applies](../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../includes/applies-to-version/azure-data-explorer.md)] [!INCLUDE [monitor](../includes/applies-to-version/monitor.md)] [!INCLUDE [sentinel](../includes/applies-to-version/sentinel.md)] + +The function `plotly_gauge_fl()` is a [user-defined function (UDF)](../query/functions/user-defined-functions.md) that allows you to customize a [plotly](https://plotly.com/python/) template to create a [gauge chart](https://plotly.com/python/gauge-charts/). + +::: moniker range="azure-data-explorer" +The function accepts few parameters to customize the gauge chart and returns a single cell table containing [plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). Optionally, you can render the data in an [Azure Data Explorer dashboard](/azure/data-explorer/azure-data-explorer-dashboards) tile. For more information, see [Plotly (preview)](../query/visualization-plotly.md). +::: moniker-end +::: moniker range="microsoft-fabric" +The function accepts few parameters to customize the gauge chart and returns a single cell table containing [plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). Optionally, you can render the data in a [Real-Time dashboard](/fabric/real-time-intelligence/dashboard-real-time-create) tile. For more information, see [Plotly (preview)](../query/visualization-plotly.md). +::: moniker-end + +## Prerequisite + +Extract the required 'gauge' template from the publicly available `PlotlyTemplate` table. Copy this table from the Samples database to your database by running the following KQL command from your target database: + +```kusto +.set PlotlyTemplate <| cluster('help.kusto.windows.net').database('Samples').PlotlyTemplate +``` + +## Syntax + +`T | invoke plotly_gauge_fl(`*value*`,` *max_range*`,` *mode*`,` *chart_title*`,` *font_color*`,` *bar_color*`,` *bar_bg_color*`,` *tick_color*`,` *tick_width*`)` + +[!INCLUDE [syntax-conventions-note](../includes/syntax-conventions-note.md)] + +## Parameters + +| Name | Type | Required | Description | +|--|--|--|--| +| *value* | `real` | :heavy_check_mark: | The number to be displayed.| +| *max_range* | `range` | | The maximum range of the gauge.| +| *mode* | `string` | | Specifies how the value is displayed on the graph. Default is 'gauge+number'.| +| *chart_title* | `string` | | The chart title. The default is empty title.| +| *font_color* | `string` | | The chart's font color. Default is 'black'.| +| *bar_color* | `string` | | The gauge's filled bar color. Default is 'green'.| +| *bar_bg_color* | `string` | | The gauge's not filled bar color. Default is 'lightgreen'.| +| *tick_color* | `string` | | The gauge's ticks color. Default is 'darkblue'.| +| *tick_width* | `int` | | The gauge's ticks width. Default is 1.| + +Plotly gauge charts support many parameters, still this function exposes only the above ones. For more information, see [indicator traces reference](https://plotly.com/python/reference/indicator/). + +## Function definition + +You can define the function by either embedding its code as a query-defined function, or creating it as a stored function in your database, as follows: + +### [Query-defined](#tab/query-defined) + +Define the function using the following [let statement](../query/let-statement.md). No permissions are required. + +> [!IMPORTANT] +> A [let statement](../query/let-statement.md) can't run on its own. It must be followed by a [tabular expression statement](../query/tabular-expression-statements.md). To run a working example of `plotly_gauge_fl()`, see [Example](#example). + +```kusto +let plotly_gauge_fl=(value:real, max_range:real=real(null), mode:string='gauge+number', chart_title:string='',font_color:string='black', + bar_color:string='green', bar_bg_color:string='lightgreen', tick_color:string='darkblue', tick_width:int=1) +{ + let gauge_chart = toscalar(PlotlyTemplate | where name == "gauge" | project plotly); + print plotly = gauge_chart + | extend plotly=replace_string(plotly, '$VALUE$', tostring(value)) + | extend plotly=replace_string(plotly, '$MAX_RANGE$', iff(isnull(max_range), 'null', tostring(max_range))) + | extend plotly=replace_string(plotly, '$MODE$', mode) + | extend plotly=replace_string(plotly, '$TITLE$', chart_title) + | extend plotly=replace_string(plotly, '$FONT_COLOR$', font_color) + | extend plotly=replace_string(plotly, '$BAR_COLOR$', bar_color) + | extend plotly=replace_string(plotly, '$BAR_BG_COLOR$', bar_bg_color) + | extend plotly=replace_string(plotly, '$TICK_COLOR$', tick_color) + | extend plotly=replace_string(plotly, '$TICK_WIDTH$', tostring(tick_width)) + | project plotly +}; +// Write your query to use your function here. +``` + +### [Stored](#tab/stored) + +Define the stored function once using the following [`.create function`](../management/create-function.md). [Database User permissions](../access-control/role-based-access-control.md) are required. + +> [!IMPORTANT] +> You must run this code to create the function before you can use the function as shown in the [Example](#example). + +```kusto +.create-or-alter function with (folder = "Packages\\Plotly", docstring = "Render gauge chart using plotly template") +plotly_gauge_fl(value:real, max_range:real=real(null), mode:string='gauge+number', chart_title:string='',font_color:string='black', + bar_color:string='green', bar_bg_color:string='lightgreen', tick_color:string='darkblue', tick_width:int=1) +{ + let gauge_chart = toscalar(PlotlyTemplate | where name == "gauge" | project plotly); + print plotly = gauge_chart + | extend plotly=replace_string(plotly, '$VALUE$', tostring(value)) + | extend plotly=replace_string(plotly, '$MAX_RANGE$', iff(isnull(max_range), 'null', tostring(max_range))) + | extend plotly=replace_string(plotly, '$MODE$', mode) + | extend plotly=replace_string(plotly, '$TITLE$', chart_title) + | extend plotly=replace_string(plotly, '$FONT_COLOR$', font_color) + | extend plotly=replace_string(plotly, '$BAR_COLOR$', bar_color) + | extend plotly=replace_string(plotly, '$BAR_BG_COLOR$', bar_bg_color) + | extend plotly=replace_string(plotly, '$TICK_COLOR$', tick_color) + | extend plotly=replace_string(plotly, '$TICK_WIDTH$', tostring(tick_width)) + | project plotly +} +``` + +--- + +## Example + +The following example uses the [invoke operator](../query/invoke-operator.md) to run the function. + +### [Query-defined](#tab/query-defined) + +To use a query-defined function, invoke it after the embedded function definition. + +```kusto +let plotly_gauge_fl=(value:real, max_range:real=real(null), mode:string='gauge+number', chart_title:string='',font_color:string='black', + bar_color:string='green', bar_bg_color:string='lightgreen', tick_color:string='darkblue', tick_width:int=1) +{ + let gauge_chart = toscalar(PlotlyTemplate | where name == "gauge" | project plotly); + print plotly = gauge_chart + | extend plotly=replace_string(plotly, '$VALUE$', tostring(value)) + | extend plotly=replace_string(plotly, '$MAX_RANGE$', iff(isnull(max_range), 'null', tostring(max_range))) + | extend plotly=replace_string(plotly, '$MODE$', mode) + | extend plotly=replace_string(plotly, '$TITLE$', chart_title) + | extend plotly=replace_string(plotly, '$FONT_COLOR$', font_color) + | extend plotly=replace_string(plotly, '$BAR_COLOR$', bar_color) + | extend plotly=replace_string(plotly, '$BAR_BG_COLOR$', bar_bg_color) + | extend plotly=replace_string(plotly, '$TICK_COLOR$', tick_color) + | extend plotly=replace_string(plotly, '$TICK_WIDTH$', tostring(tick_width)) + | project plotly +}; +plotly_gauge_fl(value=180, chart_title='Speed', font_color='purple', tick_width=5) +| render plotly +``` + +### [Stored](#tab/stored) + +> [!IMPORTANT] +> For this example to run successfully, you must first run the [Function definition](#function-definition) code to store the function. + +```kusto +plotly_gauge_fl(value=180, chart_title='Speed', font_color='purple', tick_width=5) +| render plotly +``` + +--- + +**Output** + +::: moniker range="azure-data-explorer" +The output is a Plotly JSON string that can be rendered in an Azure Data Explorer dashboard tile. For more information on creating dashboard tiles, see [Visualize data with Azure Data Explorer dashboards](/azure/data-explorer/azure-data-explorer-dashboards). +::: moniker-end +::: moniker range="microsoft-fabric" +The output is a Plotly JSON string that can be rendered in a Real-Time dashboard tile. For more information on creating dashboard tiles, see [Real-Time dashboards](/fabric/real-time-intelligence/dashboard-real-time-create). +::: moniker-end + +![Screenshot of gauge chart with random data.](media/plotly-gauge-fl\plotly-gauge-chart.png) diff --git a/data-explorer/kusto/functions-library/plotly-scatter3d-fl.md b/data-explorer/kusto/functions-library/plotly-scatter3d-fl.md index e336b3125e..3dcb68b7da 100644 --- a/data-explorer/kusto/functions-library/plotly-scatter3d-fl.md +++ b/data-explorer/kusto/functions-library/plotly-scatter3d-fl.md @@ -12,7 +12,12 @@ monikerRange: "microsoft-fabric || azure-data-explorer || azure-monitor || micro The function `plotly_scatter3d_fl()` is a [user-defined function (UDF)](../query/functions/user-defined-functions.md) that allows you to customize a [plotly](https://plotly.com/python/) template to create an interactive 3D scatter chart. +::: moniker range="azure-data-explorer" The function accepts a table containing the records to be rendered, the names of the x, y, z & aggregation columns, and the chart title string. The function returns a single cell table containing [plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). Optionally, you can render the data in an [Azure Data Explorer dashboard](/azure/data-explorer/azure-data-explorer-dashboards) tile. For more information, see [Plotly (preview)](../query/visualization-plotly.md). +::: moniker-end +::: moniker range="microsoft-fabric" +The function accepts a table containing the records to be rendered, the names of the x, y, z & aggregation columns, and the chart title string. The function returns a single cell table containing [plotly JSON](https://plotly.com/chart-studio-help/json-chart-schema/). Optionally, you can render the data in a [Real-Time dashboard](/fabric/real-time-intelligence/dashboard-real-time-create) tile. For more information, see [Plotly (preview)](../query/visualization-plotly.md). +::: moniker-end ## Prerequisite @@ -175,7 +180,13 @@ Iris **Output** + +::: moniker range="azure-data-explorer" The output is a Plotly JSON string that can be rendered in an Azure Data Explorer dashboard tile. For more information on creating dashboard tiles, see [Visualize data with Azure Data Explorer dashboards](/azure/data-explorer/azure-data-explorer-dashboards). +::: moniker-end +::: moniker range="microsoft-fabric" +The output is a Plotly JSON string that can be rendered in a Real-Time dashboard tile. For more information on creating dashboard tiles, see [Real-Time dashboards](/fabric/real-time-intelligence/dashboard-real-time-create). +::: moniker-end ![Screenshot of 3D scatter chart of a sample dataset.](media/plotly-scatter3d-fl\plotly-scatter3d-chart.png) diff --git a/data-explorer/kusto/functions-library/toc.yml b/data-explorer/kusto/functions-library/toc.yml index 4d398af574..39788a2261 100644 --- a/data-explorer/kusto/functions-library/toc.yml +++ b/data-explorer/kusto/functions-library/toc.yml @@ -74,6 +74,9 @@ items: - name: plotly_anomaly_fl() displayName: functions library, Plotly, anomaly, chart, render href: plotly-anomaly-fl.md +- name: plotly_gauge_fl() + displayName: functions library, Plotly, gauge, speed, chart, render + href: plotly-gauge-fl.md - name: plotly_scatter3d_fl() displayName: functions library, Plotly, scatter, chart, render href: plotly-scatter3d-fl.md diff --git a/data-explorer/kusto/management/create-ingestion-mapping-command.md b/data-explorer/kusto/management/create-ingestion-mapping-command.md index 172b945d7b..a56c65eca1 100644 --- a/data-explorer/kusto/management/create-ingestion-mapping-command.md +++ b/data-explorer/kusto/management/create-ingestion-mapping-command.md @@ -3,7 +3,7 @@ title: .create ingestion mapping command description: Learn how to use the `.create ingestion mapping` command to create an ingestion mapping. ms.reviewer: orspodek ms.topic: reference -ms.date: 08/11/2024 +ms.date: 11/13/2024 --- # .create ingestion mapping command @@ -11,7 +11,7 @@ ms.date: 08/11/2024 Creates an ingestion mapping that can be associated with a specific format and a specific table or database. -If a mapping with same name in the given scope already exists, `.create` will fail. Use [`.create-or-alter`](create-or-alter-ingestion-mapping-command.md) instead. +If a mapping with same name in the given scope already exists, `.create` fails. Use [`.create-or-alter`](create-or-alter-ingestion-mapping-command.md) instead. ## Permissions @@ -38,11 +38,15 @@ At least [Database Ingestor](../access-control/role-based-access-control.md) per > [!NOTE] > > * Once created, the mapping can be referenced by its name in ingestion commands, instead of specifying the complete mapping as part of the command. -> * If a mapping with the same name is created in both the table scope and the database scope, the mapping in the table scope will have a higher priority. +> * If a mapping with the same name is created in both the table scope and the database scope, the mapping in the table scope will have higher priority. > * When ingesting into a table and referencing a mapping whose schema does not match the ingested table schema, the ingest operation will fail. ## Examples +### Create a table and database with CSV ingestion mapping + +The following example creates a table, `MyTable` with CSV ingestion mapping `Mapping1` and a database, `MyDatabase` with CSV ingestion mapping `Mapping2`. + ```kusto .create table MyTable ingestion csv mapping "Mapping1" '[' @@ -64,7 +68,9 @@ At least [Database Ingestor](../access-control/role-based-access-control.md) per | mapping1 | CSV | `[{"Name":"rownumber","DataType":"int","CsvDataType":null,"Ordinal":0,"ConstValue":null},{"Name":"rowguid","DataType":"string","CsvDataType":null,"Ordinal":1,"ConstValue":null}]` | MyDatabase | MyTable | | mapping2 | CSV | `[{"Name":"rownumber","DataType":"int","CsvDataType":null,"Ordinal":0,"ConstValue":null},{"Name":"rowguid","DataType":"string","CsvDataType":null,"Ordinal":1,"ConstValue":null}]` | MyDatabase | | -### Example: .create ingestion mapping with escape characters +### Create ingestion mapping with escape characters + +The following example creates a table, `test_table` with JSON ingestion mapping `test_mapping_name`. To avoid errors, backslashes are used to escape single quotes in the JSON path strings. ```kusto .create table test_table ingestion json mapping "test_mapping_name" @@ -75,4 +81,5 @@ At least [Database Ingestor](../access-control/role-based-access-control.md) per ## Related content -* For detailed descriptions of various ingestion mapping formats such as CSV, JSON, Avro, Parquet, and Orc, see [Data mappings](mappings.md). +* For detailed descriptions of various ingestion mapping formats, such as CSV, JSON, Avro, Parquet, and Orc, see [Data mappings](mappings.md). +* To learn more about JSON mapping as an ingestion source, see [JSON mapping](json-mapping.md) diff --git a/data-explorer/kusto/management/update-policy-with-managed-identity.md b/data-explorer/kusto/management/update-policy-with-managed-identity.md index 1fe684106e..75d73c4f64 100644 --- a/data-explorer/kusto/management/update-policy-with-managed-identity.md +++ b/data-explorer/kusto/management/update-policy-with-managed-identity.md @@ -3,7 +3,7 @@ title: Run an update policy with a managed identity description: This article describes how to use a managed identity for update policy. ms.reviewer: atefsawaed ms.topic: reference -ms.date: 08/11/2024 +ms.date: 11/13/2024 monikerRange: "azure-data-explorer" --- # Use a managed identity to run an update policy @@ -12,8 +12,8 @@ monikerRange: "azure-data-explorer" The update policy must be configured with a [managed identity](/azure/data-explorer/managed-identities-overview) in the following scenarios: -* When the update policy query references tables in other databases. -* When the update policy query references tables with an enabled [row level security policy](row-level-security-policy.md). +* When the update policy query references tables in other databases +* When the update policy query references tables with an enabled [row level security policy](row-level-security-policy.md) An update policy configured with a managed identity is performed on behalf of the managed identity. @@ -38,11 +38,11 @@ Select one of the following tabs to set up your preferred managed identity type. 1. Follow the steps to [Add a user-assigned identity](/azure/data-explorer/configure-managed-identities-cluster#add-a-user-assigned-identity). -1. In the Azure portal, in the left menu of your managed identity resource, select **Properties**. Copy and save the **Tenant Id** and **Principal Id** for use in the following steps. +1. In the Azure portal, in the left menu of your managed identity resource, select **Properties**. Copy and save the **Tenant Id** and **Principal ID** for use in the following steps. - :::image type="content" source="media/updatepolicy/managed-identity-ids.png" alt-text="Screenshot of Azure portal area with managed identity ids." lightbox="media/updatepolicy/managed-identity-ids.png"::: + :::image type="content" source="media/updatepolicy/managed-identity-ids.png" alt-text="Screenshot of Azure portal area with managed identity IDs." lightbox="media/updatepolicy/managed-identity-ids.png"::: -1. Run the following [.alter-merge policy managed_identity](alter-merge-managed-identity-policy-command.md) command, replacing `` with the managed identity object ID from the previous step. This command sets a [managed identity policy](../management/managed-identity-policy.md) on the cluster that allows the managed identity to be used with the update policy. +1. Run the following [.alter-merge policy managed_identity](alter-merge-managed-identity-policy-command.md) command, replacing `` with the managed identity **Principal ID** from the previous step. This command sets a [managed identity policy](../management/managed-identity-policy.md) on the cluster that allows the managed identity to be used with the update policy. ````kusto .alter-merge cluster policy managed_identity ```[ @@ -62,13 +62,13 @@ Select one of the following tabs to set up your preferred managed identity type. .add database viewers ('aadapp=;') ``` - Replace `` with the relevant database, `` with the managed identity **Principal Id** from step 2, and `` with the Microsoft Entra ID **Tenant Id** from step 2. + Replace `` with the relevant database, `` with the managed identity **Principal ID** from step 2, and `` with the Microsoft Entra ID **Tenant Id** from step 2. ### [System-assigned](#tab/system-assigned) 1. Follow the steps to [Add a system-assigned identity](/azure/data-explorer/configure-managed-identities-cluster#add-a-system-assigned-identity). -1. Copy and save the **Object (principal) ID** for use in a later step. +1. Copy and save the **Object ID** for use in a later step. 1. Run the following [.alter-merge policy managed_identity](alter-merge-managed-identity-policy-command.md) command. This command sets a [managed identity policy](../management/managed-identity-policy.md) on the cluster that allows the managed identity to be used with the update policy. @@ -90,13 +90,13 @@ Select one of the following tabs to set up your preferred managed identity type. .add database viewers ('aadapp=') ``` - Replace `` with the relevant database and `` with the managed identity **Object (principal) ID** from step 2. + Replace `` with the relevant database and `` with the managed identity **Object ID** you saved earlier. --- ## Create an update policy -Select one of the following tabs to create an update policy that will run on behalf of a user-assigned or system-assigned managed identity. +Select one of the following tabs to create an update policy that runs on behalf of a user-assigned or system-assigned managed identity. ### [User-assigned](#tab/user-assigned)