Create an Azure Data Explorer cluster and database

• An Azure subscription. Create a free Azure account.

• An Azure subscription. Create a free Azure account.

• Set up your environment using the instructions in Use Kusto cmdlets in Azure PowerShell.

• An Azure subscription. Create a free Azure account.
• Visual Studio 2022 Community Edition. Turn on Azure development during the Visual Studio setup.
• Install the Microsoft.Azure.Management.Kusto NuGet package.
• A Microsoft Entra application and service principal that can access resources. Save the Directory (tenant) ID, Application ID, and Client Secret.

• An Azure subscription. Create a free Azure account.
• Python 3.4+.
• Install the azure-common and azure-mgmt-kusto packages.
• A Microsoft Entra application and service principal that can access resources. Save the Directory (tenant) ID, Application ID, and Client Secret.

• An Azure subscription. Create a free Azure account.
• Install Git.
• Install an appropriate version of Go. For supported versions, see Azure Kusto Module for Go.
• A Microsoft Entra application and service principal that can access resources. Save the Directory (tenant) ID, Application ID, and Client Secret.

• An Azure subscription. Create a free Azure account.
• You can use Azure Cloud Shell 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. 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.

Configure the CLI parameters

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:

1. Install extension to use the latest Kusto CLI version:

   az extension add -n kusto
   

2. Run the following command to sign in to Azure:

   az login
   

3. Set the subscription where you want your cluster to be created. Replace MyAzureSub with the name of the Azure subscription that you want to use:

   az account set --subscription MyAzureSub
   

4. Set the resource group where you want your cluster to be created. Replace testrg with the name of the resource group that you want to use:

   az group create --name testrg --location westus
   

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 and ARM template database reference.

{
    "$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"
            }
        }
    ]
}

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 and Bicep database reference.

    @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'
      }
    }

1. Create your cluster by using the following command:

    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.

2. Run the following command to check whether your cluster was successfully created:

   Get-AzKustoCluster -Name mykustocluster -ResourceGroupName testrg
   

3. Confirm the successful creation of the cluster by verifying the result contains provisioningState as Succeeded.

1. Create your cluster by using the following code:

   var tenantId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"; //Directory (tenant) ID
   var clientId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"; //Application ID
   var clientSecret = "PlaceholderClientSecret"; //Client Secret
   var subscriptionId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx";
   var credentials = new ClientSecretCredential(tenantId, clientId, clientSecret);
   var resourceManagementClient = new ArmClient(credentials, subscriptionId);
   var resourceGroupName = "testrg";
   var subscription = await resourceManagementClient.GetDefaultSubscriptionAsync();
   var resourceGroup = (await subscription.GetResourceGroupAsync(resourceGroupName)).Value;
   var clusters = resourceGroup.GetKustoClusters();    
   var clusterName = "mykustocluster";
   var skuName = KustoSkuName.StandardE8adsV5;
   var skuTier = KustoSkuTier.Standard;
   var capacity = 5;
   var clusterData = new KustoClusterData(
       location: AzureLocation.CentralUS,
       sku: new KustoSku(skuName, skuTier) { Capacity = capacity }
   );
   await clusters.CreateOrUpdateAsync(WaitUntil.Completed, clusterName, clusterData);
   

   Setting	Suggested value	Field description
   clusterName	mykustocluster	The desired name of your cluster.
   skuName	Standard_E8ads_v5	The SKU that will be used for your cluster.
   tier	Standard	The SKU tier.
   capacity	number	The number of instances of the cluster.
   resourceGroupName	testrg	The resource group name where the cluster will be created.

   Note

   Create a cluster is a long running operation, so it's highly recommended to use CreateOrUpdateAsync, instead of CreateOrUpdate.

2. Run the following command to check whether your cluster was successfully created:

   clusterData = (await clusters.GetAsync(clusterName)).Value.Data;
   

3. Confirm the successful creation of the cluster by verifying the result contains provisioningState as Succeeded.

1. Create your cluster by using the following command:

   from azure.mgmt.kusto import KustoManagementClient
   from azure.mgmt.kusto.models import Cluster, AzureSku
   from azure.common.credentials import ServicePrincipalCredentials
   
   #Directory (tenant) ID
   tenant_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   #Application ID
   client_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   #Client Secret
   client_secret = "xxxxxxxxxxxxxx"
   subscription_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   credentials = ServicePrincipalCredentials(
       client_id=client_id,
       secret=client_secret,
       tenant=tenant_id
   )
   
   location = 'Central US'
   sku_name = 'Standard_E8ads_v5'
   capacity = 5
   tier = "Standard"
   resource_group_name = 'testrg'
   cluster_name = 'mykustocluster'
   cluster = Cluster(location=location, sku=AzureSku(name=sku_name, capacity=capacity, tier=tier))
   
   kusto_management_client = KustoManagementClient(credentials, subscription_id)
   
   cluster_operations = kusto_management_client.clusters
   
   poller = cluster_operations.begin_create_or_update(resource_group_name, cluster_name, cluster)
   poller.wait()
   

   Setting	Suggested value	Field description
   cluster_name	mykustocluster	The desired name of your cluster.
   sku_name	Standard_E8ads_v5	The SKU that will be used for your cluster.
   tier	Standard	The SKU tier.
   capacity	number	The number of instances of the cluster.
   resource_group_name	testrg	The resource group name where the cluster will be created.

   Note

   Create a cluster is a long running operation. Method begin_create_or_update returns an instance of LROPoller, see LROPoller class to get more information.

2. Run the following command to check whether your cluster was successfully created:

   cluster_operations.get(resource_group_name = resource_group_name, cluster_name= cluster_name, custom_headers=None, raw=False)
   

3. Confirm the successful creation of the cluster by verifying the result contains provisioningState as Succeeded.

The following code shows how to create a cluster.

1. Set the required environment variables including service principal information from the prerequisites. Enter your subscription ID, resource group, and region where you want to create the cluster.

   export AZURE_CLIENT_ID="<enter service principal client ID>"
   export AZURE_CLIENT_SECRET="<enter service principal client secret>"
   export AZURE_TENANT_ID="<enter tenant ID>"
   
   export SUBSCRIPTION="<enter subscription ID>"
   export RESOURCE_GROUP="<enter resource group name>"
   export LOCATION="<enter azure location e.g. Southeast Asia>"
   
   export CLUSTER_NAME_PREFIX="<enter prefix (cluster name will be [prefix]-ADXTestCluster)>"
   export DATABASE_NAME_PREFIX="<enter prefix (database name will be [prefix]-ADXTestDB)>"
   

   Tip

   Use auth.NewAuthorizerFromCLIWithResource if you have Azure CLI installed and configured for authentication. In that situation, you don't need to create a service principal.

2. Run the following code to create the cluster:

   import (
    "context"
    "log"
    "os"
    "strconv"
   
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/kusto/armkusto"
    "github.com/olekukonko/tablewriter"
   )
   
   const (
    subscriptionEnvVar      = "AZURE_SUBSCRIPTION_ID"
    resourceGroupEnvVar     = "AZURE_RESOURCE_GROUP"
    locationEnvVar          = "AZURE_LOCATION"
    clusterNamePrefixEnvVar = "CLUSTER_NAME_PREFIX"
    dbNamePrefixEnvVar      = "DATABASE_NAME_PREFIX"
   
    clusterName  = "ADXTestCluster"
    databaseName = "ADXTestDB"
   )
   
   func init() {
    subscription = os.Getenv(subscriptionEnvVar)
    if subscription == "" {
     log.Fatalf("missing environment variable %s", subscriptionEnvVar)
    }
   
    rgName = os.Getenv(resourceGroupEnvVar)
    if rgName == "" {
     log.Fatalf("missing environment variable %s", resourceGroupEnvVar)
    }
   
    location = os.Getenv(locationEnvVar)
    if location == "" {
     log.Fatalf("missing environment variable %s", locationEnvVar)
    }
   
    clusterNamePrefix = os.Getenv(clusterNamePrefixEnvVar)
    if clusterNamePrefix == "" {
     log.Fatalf("missing environment variable %s", clusterNamePrefixEnvVar)
    }
   
    dbNamePrefix = os.Getenv(dbNamePrefixEnvVar)
    if dbNamePrefix == "" {
     log.Fatalf("missing environment variable %s", dbNamePrefixEnvVar)
    }
   }
   
   func getClustersClient(subscription string) *armkusto.ClustersClient {
    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
     log.Fatal(err)
    }
   
    client, err := armkusto.NewClustersClient(subscription, cred, nil)
    if err != nil {
     log.Fatal(err)
    }
   
    return client
   }
   
   // 1 instance, Basic tier with compute type Dev(No SLA)_Standard_D11_v2
   func createCluster(sub, name, location, rgName string) {
    ctx := context.Background()
   
    numInstances := int32(1)
    client := getClustersClient(sub)
    result, err := client.BeginCreateOrUpdate(
     ctx,
     rgName,
     name,
     armkusto.Cluster{
      Location: &location,
      SKU: &armkusto.AzureSKU{
       Name:     to.Ptr(armkusto.AzureSKUNameDevNoSLAStandardD11V2),
       Capacity: &numInstances,
       Tier:     to.Ptr(armkusto.AzureSKUTierBasic),
      },
     },
     nil,
    )
    if err != nil {
     log.Fatal("failed to start cluster creation ", err)
    }
   
    log.Printf("waiting for cluster creation to complete - %s\n", name)
    r, err := result.PollUntilDone(ctx, nil)
    if err != nil {
     log.Fatal(err)
    }
   
    log.Printf("created cluster %s\n", *r.Name)
   }
   
   createCluster(subscription, clusterNamePrefix+clusterName, location, rgName)
   

3. List the clusters to ensure successful creation:

   func listClusters(sub, rgName string) {
    log.Printf("listing clusters in resource group %s\n", rgName)
    ctx := context.Background()
   
    result := getClustersClient(sub).NewListByResourceGroupPager(rgName, nil)
   
    data := [][]string{}
   
    for result.More() {
     temp, err := result.NextPage(ctx)
     if err != nil {
      log.Fatal(err)
     }
     for _, c := range temp.Value {
      data = append(data, []string{*c.Name, string(*c.Properties.State), *c.Location, strconv.Itoa(int(*c.SKU.Capacity)), *c.Properties.URI})
     }
    }
   
    table := tablewriter.NewWriter(os.Stdout)
    table.SetHeader([]string{"Name", "State", "Location", "Instances", "URI"})
   
    for _, v := range data {
     table.Append(v)
    }
    table.Render()
   }
   
   listClusters(subscription, rgName)
   

1. Create your cluster by using the following command:

   az kusto cluster create --cluster-name azureclitest --sku name="Standard_E8ads_v5" tier="Standard" --resource-group testrg --location westus
   

   Setting	Suggested value	Field description
   name	azureclitest	The desired name of your cluster.
   sku	Standard_E8ads_v5	The SKU that will be used for your cluster. Parameters: name - The SKU name. tier - The SKU tier.
   resource-group	testrg	The resource group name where the cluster will be created.
   location	westus	The location where the cluster will be created.

   There are other optional parameters that you can use, such as the capacity of the cluster.

2. Run the following command to check whether your cluster was successfully created:

   az kusto cluster show --cluster-name azureclitest --resource-group testrg
   

3. Confirm the successful creation of the cluster by verifying the result contains provisioningState as Succeeded.

The cluster and database are created together with the ARM template in the previous section.

The cluster and database are created together with the Bicep template in the previous section.

1. Create your database by using the following command:

   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.

2. Run the following command to see the database that you created:

   Get-AzKustoDatabase -ClusterName mykustocluster -ResourceGroupName testrg -Name mykustodatabase
   

1. Create your database by using the following code:

   var cluster = (await clusters.GetAsync(clusterName)).Value;
   var databases = cluster.GetKustoDatabases();
   var databaseName = "mykustodatabase";
   var softDeletePeriod = TimeSpan.FromDays(3650);
   var hotCachePeriod = TimeSpan.FromDays(3650);
   var databaseData = new KustoReadWriteDatabase
   {
       Location = clusterData.Location, SoftDeletePeriod = softDeletePeriod, HotCachePeriod = hotCachePeriod
   };
   await databases.CreateOrUpdateAsync(WaitUntil.Completed, databaseName, databaseData);
   

   Note

   If you are using C# version 2.0.0 or below, use Database instead of ReadWriteDatabase.

   Setting	Suggested value	Field description
   clusterName	mykustocluster	The name of your cluster where the database will be created.
   databaseName	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.

2. Run the following command to see the database that you created:

   databaseData = (await databases.GetAsync(databaseName)).Value.Data as KustoReadWriteDatabase;
   

1. Create your database by using the following command:

   from azure.mgmt.kusto import KustoManagementClient
   from azure.common.credentials import ServicePrincipalCredentials
   from azure.mgmt.kusto.models import ReadWriteDatabase
   from datetime import timedelta
   
   #Directory (tenant) ID
   tenant_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   #Application ID
   client_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   #Client Secret
   client_secret = "xxxxxxxxxxxxxx"
   subscription_id = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx"
   credentials = ServicePrincipalCredentials(
       client_id=client_id,
       secret=client_secret,
       tenant=tenant_id
   )
   
   location = 'Central US'
   resource_group_name = 'testrg'
   cluster_name = 'mykustocluster'
   soft_delete_period = timedelta(days=3650)
   hot_cache_period = timedelta(days=3650)
   database_name = "mykustodatabase"
   
   kusto_management_client = KustoManagementClient(credentials, subscription_id)
   
   database_operations = kusto_management_client.databases
   database = ReadWriteDatabase(location=location,
         soft_delete_period=soft_delete_period,
         hot_cache_period=hot_cache_period)
   
   poller = database_operations.begin_create_or_update(resource_group_name = resource_group_name, cluster_name = cluster_name, database_name = database_name, parameters = database)
   poller.wait()
   

   Note

   If you are using Python version 0.4.0 or below, use Database instead of ReadWriteDatabase.

   Setting	Suggested value	Field description
   cluster_name	mykustocluster	The name of your cluster where the database will be created.
   database_name	mykustodatabase	The name of your database.
   resource_group_name	testrg	The resource group name where the cluster will be created.
   soft_delete_period	3650 days, 0:00:00	The amount of time that data will be kept available to query.
   hot_cache_period	3650 days, 0:00:00	The amount of time that data will be kept in cache.

2. Run the following command to see the database that you created:

   database_operations.get(resource_group_name = resource_group_name, cluster_name = cluster_name, database_name = database_name)
   

The following code shows how to create a database. The package imports and environment variable initiation is the same as in the previous section.

1. Run the following code to create the database:

   func createDatabase(sub, rgName, clusterName, location, dbName string) {
    ctx := context.Background()
   
    client := getDBClient(sub)
    future, err := client.BeginCreateOrUpdate(ctx, rgName, clusterName, dbName, &armkusto.ReadWriteDatabase{Kind: to.Ptr(armkusto.KindReadWrite), Location: &location}, nil)
   
    if err != nil {
     log.Fatal("failed to start database creation ", err)
    }
   
    log.Printf("waiting for database creation to complete - %s\n", dbName)
    resp, err := future.PollUntilDone(ctx, nil)
    if err != nil {
     log.Fatal(err)
    }
   
    kdb := resp.GetDatabase()
    log.Printf("created DB %s with ID %s and type %s\n", *kdb.Name, *kdb.ID, *kdb.Type)
   }
   
   createDatabase(subscription, rgName, clusterNamePrefix+clusterName, location, dbNamePrefix+databaseName)
   

2. List the databases to ensure successful creation:

   func listDatabases(sub, rgName, clusterName string) {
    log.Printf("listing databases in cluster %s\n", clusterName)
   
    ctx := context.Background()
    result := getDBClient(sub).NewListByClusterPager(rgName, clusterName, nil)
   
    data := [][]string{}
   
    for result.More() {
     temp, err := result.NextPage(ctx)
     if err != nil {
      log.Fatal(err)
     }
     for _, db := range temp.Value {
      if *db.GetDatabase().Kind == armkusto.KindReadWrite {
       data = append(data, []string{*db.GetDatabase().Name, string(*db.GetDatabase().Kind), *db.GetDatabase().Location, *db.GetDatabase().Type})
      }
     }
    }
   
    table := tablewriter.NewWriter(os.Stdout)
    table.SetHeader([]string{"Name", "State", "Location", "Type"})
   
    for _, v := range data {
     table.Append(v)
    }
    table.Render()
   }
   
   listDatabases(subscription, rgName, clusterNamePrefix+clusterName)
   

1. Create your database by using the following command:

   az kusto database create --cluster-name azureclitest --database-name clidatabase --resource-group testrg --read-write-database soft-delete-period=P365D hot-cache-period=P31D location=westus
   

   Setting	Suggested value	Field description
   cluster-name	azureclitest	The name of your cluster where the database will be created.
   database-name	clidatabase	The name of your database.
   resource-group	testrg	The resource group name where the cluster will be created.
   read-write-database	P365D P31D westus	The database type. Parameters: soft-delete-period - Signifies the amount of time the data will be kept available to query. See retention policy for more information. hot-cache-period - Signifies the amount of time the data will be kept in cache. See cache policy for more information. location -The location where the database will be created.

2. Run the following command to see the database that you created:

   az kusto database show --database-name clidatabase --resource-group testrg --cluster-name azureclitest