diff --git a/data-explorer/create-cluster-database.md b/data-explorer/create-cluster-database.md index 45bd72f1e1..37948ae1a2 100644 --- a/data-explorer/create-cluster-database.md +++ b/data-explorer/create-cluster-database.md @@ -4,14 +4,14 @@ description: Learn how to create an Azure Data Explorer cluster and database. ms.reviewer: lugoldbe ms.topic: how-to ms.custom: devx-track-azurepowershell -ms.date: 09/28/2025 +ms.date: 05/13/2026 --- # Create an Azure Data Explorer cluster and database Azure Data Explorer is a fast, fully managed data analytics service for real-time analysis on large volumes of data streaming from applications, websites, IoT devices, and more. To use Azure Data Explorer, you first create a cluster, and create one or more databases in that cluster. Then, you can ingest (load) data into a database and run queries against it. -In this article, you'll learn how to create a cluster and a database using either C#, Python, Go, the Azure CLI, PowerShell, or an Azure Resource Manager (ARM) template. To learn how to create a cluster and database using the Azure portal, see [Quickstart: Create an Azure Data Explorer cluster and database](create-cluster-and-database.md). +In this article, you'll learn how to create a cluster and a database using either C#, Python, Go, the Azure CLI, PowerShell, Bicep, or an Azure Resource Manager (ARM) template. To learn how to create a cluster and database using the Azure portal, see [Quickstart: Create an Azure Data Explorer cluster and database](create-cluster-and-database.md). > For code samples based on previous SDK versions, see the [archived article](/previous-versions/azure/data-explorer/create-cluster-database). @@ -19,6 +19,18 @@ In this article, you'll learn how to create a cluster and a database using eithe Prerequisites by method of cluster and database creation: +### [ARM template](#tab/arm) + +* An Azure subscription. Create a [free Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). + +### [Bicep](#tab/bicep) + +* An Azure subscription. Create a [free Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). + +### [PowerShell](#tab/powershell) + +* Set up your environment using the instructions in [Use Kusto cmdlets in Azure PowerShell](/kusto/api/powershell/azure-powershell?view=azure-data-explorer&preserve-view=true). + ### [C#](#tab/csharp) * An Azure subscription. Create a [free Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). @@ -42,6 +54,9 @@ Prerequisites by method of cluster and database creation: ### [Azure CLI](#tab/azcli) +> [!IMPORTANT] +> The Kusto extension for Azure CLI is outdated and not maintained. We recommend using PowerShell or ARM/Bicep templates for cluster and database creation. If you choose to use Azure CLI, make sure to install the [Kusto extension](/cli/azure/kusto/cluster?view=azure-cli-latest&preserve-view=true) to ensure you have the latest CLI commands for Azure Data Explorer. + * An Azure subscription. Create a [free Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). * You can use [Azure Cloud Shell](https://shell.azure.com) to run the code in this article without having to install anything on your local environment. * If you choose to install and use the Azure CLI locally, follow the steps in [Configure parameters](#configure-the-cli-parameters). This article requires the Azure CLI version 2.0.4 or later. Run `az --version` to check your version. If you need to install or upgrade, see [Install the Azure CLI](/cli/azure/install-azure-cli). @@ -74,23 +89,136 @@ The following steps aren't required if you're running commands in Azure Cloud Sh az group create --name testrg --location westus ``` -### [PowerShell](#tab/powershell) - -* Set up your environment using the instructions in [Use Kusto cmdlets in Azure PowerShell](/kusto/api/powershell/azure-powershell?view=azure-data-explorer&preserve-view=true). +--- -### Configure parameters +## Create an Azure Data Explorer cluster -The following steps aren't required if you're running commands in Azure Cloud Shell. If you're running the CLI locally, follow these steps to set up the environment: +This section guides you through the process of creating an Azure Data Explorer cluster. Choose the relevant tab for your preferred method to create the cluster. ### [ARM template](#tab/arm) -* An Azure subscription. Create a [free Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn). +### ARM template ---- +Below is an example of an ARM template that creates an Azure Data Explorer cluster and a database within that cluster with minimal configuration. For full details and supported properties, see [ARM template cluster reference](/azure/templates/microsoft.kusto/clusters?pivots=deployment-language-arm-template) and [ARM template database reference](/azure/templates/microsoft.kusto/clusters/databases?pivots=deployment-language-arm-template). -## Create an Azure Data Explorer cluster +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "clusters_kustocluster_name": { + "type": "string", + "defaultValue": "[concat('kusto', uniqueString(resourceGroup().id))]", + "metadata": { + "description": "Name of the cluster to create" + } + }, + "databases_kustodb_name": { + "type": "string", + "defaultValue": "kustodb", + "metadata": { + "description": "Name of the database to create" + } + }, + "location": { + "type": "string", + "defaultValue": "[resourceGroup().location]", + "metadata": { + "description": "Location for all resources." + } + } + }, + "variables": {}, + "resources": [ + { + "name": "[parameters('clusters_kustocluster_name')]", + "type": "Microsoft.Kusto/clusters", + "apiVersion": "2025-02-14", + "location": "[parameters('location')]", + "sku": { + "name": "Standard_E8ads_v5", + "tier": "Standard", + "capacity": 2 + } + }, + { + "name": "[concat(parameters('clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'))]", + "type": "Microsoft.Kusto/clusters/databases", + "apiVersion": "2025-02-14", + "location": "[parameters('location')]", + "dependsOn": [ + "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_name'))]" + ], + "kind": "ReadWrite", + "properties": { + "softDeletePeriod": "P365D", + "hotCachePeriod": "P31D" + } + } + ] +} +``` -This section guides you through the process of creating an Azure Data Explorer cluster. Choose the relevant tab for your preferred method to create the cluster. +### [Bicep](#tab/bicep) + +Below is an example of a Bicep template that creates an Azure Data Explorer cluster and a database within that cluster with minimal configuration. For full details and supported properties, see [Bicep cluster reference](/azure/templates/microsoft.kusto/clusters?pivots=deployment-language-bicep) and [Bicep database reference](/azure/templates/microsoft.kusto/clusters/databases?pivots=deployment-language-bicep). + +``` bicep + @description('Name of the cluster to create') + param clusterName string = 'kusto${uniqueString(resourceGroup().id)}' + + @description('Name of the database to create') + param databaseName string = 'kustodb' + + @description('Location for all resources.') + param location string = resourceGroup().location + + resource cluster 'Microsoft.Kusto/clusters@2025-02-14' = { + name: clusterName + location: location + sku: { + name: 'Standard_E8ads_v5' + tier: 'Standard' + capacity: 2 + } + } + + + resource database 'Microsoft.Kusto/clusters/databases@2025-02-14' = { + parent: cluster + name: databaseName + location: location + kind: 'ReadWrite' + properties: { + softDeletePeriod: 'P365D' + hotCachePeriod: 'P31D' + } + } +``` + +### [PowerShell](#tab/powershell) + +1. Create your cluster by using the following command: + + ```azurepowershell-interactive + New-AzKustoCluster -ResourceGroupName testrg -Name mykustocluster -Location westus2 -SkuTier Standard -SkuCapacity 2 -SkuName 'Standard_E8ads_v5' + ``` + + |**Setting** | **Suggested value** | **Field description**| + |---|---|---| + | Name | *mykustocluster* | The desired name of your cluster.| + | Sku | *Standard_E8ads_v5* | The SKU that will be used for your cluster. | + | ResourceGroupName | *testrg* | The resource group name where the cluster will be created. | + + There are other optional parameters that you can use, such as the capacity of the cluster. + +1. Run the following command to check whether your cluster was successfully created: + + ```azurepowershell-interactive + Get-AzKustoCluster -Name mykustocluster -ResourceGroupName testrg + ``` + +1. Confirm the successful creation of the cluster by verifying the result contains `provisioningState` as `Succeeded`. ### [C#](#tab/csharp) @@ -354,6 +482,9 @@ The following code shows how to create a cluster. ### [Azure CLI](#tab/azcli) +> [!IMPORTANT] +> The Kusto extension for Azure CLI is outdated and not maintained. We recommend using PowerShell or ARM/Bicep templates for cluster and database creation. If you choose to use Azure CLI, make sure to install the [Kusto extension](/cli/azure/kusto/cluster?view=azure-cli-latest&preserve-view=true) to ensure you have the latest CLI commands for Azure Data Explorer. + 1. Create your cluster by using the following command: ```azurecli-interactive @@ -377,172 +508,42 @@ The following code shows how to create a cluster. 1. Confirm the successful creation of the cluster by verifying the result contains `provisioningState` as `Succeeded`. -### [PowerShell](#tab/powershell) - -1. Create your cluster by using the following command: - - ```azurepowershell-interactive - New-AzKustoCluster -ResourceGroupName testrg -Name mykustocluster -Location westus2 -SkuTier Standard -SkuCapacity 2 -SkuName 'Standard_E8ads_v5' - ``` - - |**Setting** | **Suggested value** | **Field description**| - |---|---|---| - | Name | *mykustocluster* | The desired name of your cluster.| - | Sku | *Standard_E8ads_v5* | The SKU that will be used for your cluster. | - | ResourceGroupName | *testrg* | The resource group name where the cluster will be created. | - - There are other optional parameters that you can use, such as the capacity of the cluster. - -1. Run the following command to check whether your cluster was successfully created: +--- - ```azurepowershell-interactive - Get-AzKustoCluster -Name mykustocluster -ResourceGroupName testrg - ``` +## Create an Azure Data Explorer database -1. Confirm the successful creation of the cluster by verifying the result contains `provisioningState` as `Succeeded`. +In this section, you'll create a database within the cluster created in the previous section. ### [ARM template](#tab/arm) -To learn how to deploy the following ARM template using PowerShell, see [Use the ARM template](#use-the-arm-template). Alternatively, you can [deploy the template in the Azure portal](/samples/azure/azure-quickstart-templates/kusto-cluster-database/) by selecting **Deploy to Azure**. +The cluster and database are created together with the ARM template in the previous section. -### ARM template +### [Bicep](#tab/bicep) -You can use this template for your own deployments, or customize it to meet your requirements. For the JSON syntax and properties to use in a template, see [Microsoft.Kusto resource types](/azure/templates/microsoft.kusto/allversions). +The cluster and database are created together with the Bicep template in the previous section. -```json -{ - "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "clusters_kustocluster_name": { - "type": "string", - "defaultValue": "[concat('kusto', uniqueString(resourceGroup().id))]", - "metadata": { - "description": "Name of the cluster to create" - } - }, - "databases_kustodb_name": { - "type": "string", - "defaultValue": "kustodb", - "metadata": { - "description": "Name of the database to create" - } - }, - "location": { - "type": "string", - "defaultValue": "[resourceGroup().location]", - "metadata": { - "description": "Location for all resources." - } - } - }, - "variables": {}, - "resources": [ - { - "name": "[parameters('clusters_kustocluster_name')]", - "type": "Microsoft.Kusto/clusters", - "sku": { - "name": "Standard_E8ads_v5", - "tier": "Standard", - "capacity": 2 - }, - "apiVersion": "2022-12-29", - "location": "[parameters('location')]", - "tags": { - "Created By": "GitHub quickstart template" - }, - "properties": { - "trustedExternalTenants": [], - "optimizedAutoscale": { - "version": 1, - "isEnabled": true, - "minimum": 2, - "maximum": 10 - }, - "enableDiskEncryption": false, - "enableStreamingIngest": false, - "virtualNetworkConfiguration": { - "subnetId": "", - "enginePublicIpId": "", - "dataManagementPublicIpId": "" - }, - "keyVaultProperties": { - "keyName": "", - "keyVaultUri": "", - "userIdentity": "" - }, - "enablePurge": false, - "enableDoubleEncryption": false, - "engineType": "V3" - }, - "identity": { - "type": "SystemAssigned, UserAssigned", - "userAssignedIdentities": { - "": {} - } - } - }, - { - "name": "[concat(parameters('clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'))]", - "type": "Microsoft.Kusto/clusters/databases", - "apiVersion": "2022-12-29", - "location": "[parameters('location')]", - "dependsOn": [ - "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_name'))]" - ], - "properties": { - "softDeletePeriodInDays": 365, - "hotCachePeriodInDays": 31 - } - } - ] -} -``` - -### Use the ARM template - -The following steps explain how to deploy the ARM template using PowerShell. +### [PowerShell](#tab/powershell) -1. Open [Azure Cloud Shell](https://shell.azure.com), and follow the instructions to sign in. -1. Select **Copy** to copy the PowerShell script. +1. Create your database by using the following command: ```azurepowershell-interactive - $projectName = Read-Host -Prompt "Enter a project name that is used for generating resource names" - $location = Read-Host -Prompt "Enter the location (i.e. centralus)" - $resourceGroupName = "${projectName}rg" - $clusterName = "${projectName}cluster" - $parameters = @{} - $parameters.Add("clusters_kustocluster_name", $clusterName) - $templateUri = "https://azure.microsoft.com/resources/templates/kusto-cluster-database/" - New-AzResourceGroup -Name $resourceGroupName -Location $location - New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri -TemplateParameterObject $parameters - Write-Host "Press [ENTER] to continue ..." + New-AzKustoDatabase -ResourceGroupName testrg -ClusterName mykustocluster -Name mykustodatabase -SoftDeletePeriod 3650:00:00:00 -HotCachePeriod 3650:00:00:00 ``` -1. Right-click the shell console, and then select **Paste**. - - > [!NOTE] - > It takes a few minutes to create an Azure Data Explorer cluster and database. + |**Setting** | **Suggested value** | **Field description**| + |---|---|---| + | ClusterName | *mykustocluster* | The name of your cluster where the database will be created.| + | Name | *mykustodatabase* | The name of your database.| + | ResourceGroupName | *testrg* | The resource group name where the cluster will be created. | + | SoftDeletePeriod | *3650:00:00:00* | The amount of time that data will be kept available to query. | + | HotCachePeriod | *3650:00:00:00* | The amount of time that data will be kept in cache. | -1. To verify the deployment, use the following Azure PowerShell script. If the Cloud Shell is still open, you don't need to copy/run the first line (Read-Host). +1. Run the following command to see the database that you created: ```azurepowershell-interactive - $projectName = Read-Host -Prompt "Enter the same project name that you used in the last procedure" - - Install-Module -Name Az.Kusto - $resourceGroupName = "${projectName}rg" - $clusterName = "${projectName}cluster" - - Get-AzKustoCluster -ResourceGroupName $resourceGroupName -Name $clusterName - Write-Host "Press [ENTER] to continue ..." + Get-AzKustoDatabase -ClusterName mykustocluster -ResourceGroupName testrg -Name mykustodatabase ``` ---- - -## Create an Azure Data Explorer database - -In this section, you'll create a database within the cluster created in the previous section. - ### [C#](#tab/csharp) 1. Create your database by using the following code: @@ -702,6 +703,9 @@ The following code shows how to create a database. The package imports and envir ### [Azure CLI](#tab/azcli) +> [!IMPORTANT] +> The Kusto extension for Azure CLI is outdated and not maintained. We recommend using PowerShell or ARM/Bicep templates for cluster and database creation. If you choose to use Azure CLI, make sure to install the [Kusto extension](/cli/azure/kusto/cluster?view=azure-cli-latest&preserve-view=true) to ensure you have the latest CLI commands for Azure Data Explorer. + 1. Create your database by using the following command: ```azurecli-interactive @@ -721,32 +725,6 @@ The following code shows how to create a database. The package imports and envir az kusto database show --database-name clidatabase --resource-group testrg --cluster-name azureclitest ``` -### [PowerShell](#tab/powershell) - -1. Create your database by using the following command: - - ```azurepowershell-interactive - New-AzKustoDatabase -ResourceGroupName testrg -ClusterName mykustocluster -Name mykustodatabase -SoftDeletePeriod 3650:00:00:00 -HotCachePeriod 3650:00:00:00 - ``` - - |**Setting** | **Suggested value** | **Field description**| - |---|---|---| - | ClusterName | *mykustocluster* | The name of your cluster where the database will be created.| - | Name | *mykustodatabase* | The name of your database.| - | ResourceGroupName | *testrg* | The resource group name where the cluster will be created. | - | SoftDeletePeriod | *3650:00:00:00* | The amount of time that data will be kept available to query. | - | HotCachePeriod | *3650:00:00:00* | The amount of time that data will be kept in cache. | - -1. Run the following command to see the database that you created: - - ```azurepowershell-interactive - Get-AzKustoDatabase -ClusterName mykustocluster -ResourceGroupName testrg -Name mykustodatabase - ``` - -### [ARM template](#tab/arm) - -The cluster and database are created together with the ARM template in the previous section. - --- ## Next step