Azure Kusto Data Client

6.0.3 · active · verified Sun Apr 05

The Azure Kusto Data Client is a Python library that provides capabilities to query Azure Data Explorer (Kusto) clusters. It is Python 3.x compatible and supports various data types through a familiar Python DB API interface, enabling its use within environments like Jupyter Notebooks. The library is actively maintained and receives regular updates, with the current version being 6.0.3.

Warnings

breaking Version 6.0.0 raised the minimum supported Python version to 3.9, aligning with other Azure SDKs. Earlier versions (e.g., 5.x) supported Python 3.7+.
Fix: Upgrade your Python environment to 3.9 or newer before upgrading to `azure-kusto-data` 6.0.0 or later.
breaking Version 5.0.0 introduced breaking changes to the `KustoConnectionStringBuilder` keywords, removing `msi_auth`, `msi_authentication`, `msi_params`, and `msi_type`. While building connection strings via the builder methods still works, direct parsing of these keywords will fail.
Fix: Review and update any custom connection string parsing logic to remove references to the deprecated keywords. Always use the provided builder methods (e.g., `with_aad_managed_service_identity_authentication`) to construct connection strings.
gotcha When using `dataframe_from_result_table` with pandas, ensure compatibility. Version 6.0.2 fixed an issue with pandas 3.0 when datetime columns contained all null values, and the minimum supported pandas version is now 2.3.1.
Fix: Upgrade to `azure-kusto-data` 6.0.2 or later if using pandas 3.0. Ensure your pandas version is 2.3.1 or newer for optimal compatibility with recent `azure-kusto-data` versions. Install with `pip install azure-kusto-data[pandas]`.
gotcha The `KustoClient` instance should be reused across multiple operations for optimal performance, as it manages a pool of connections. Frequently recreating clients can lead to performance issues and increased load on your Kusto cluster.
Fix: Initialize `KustoClient` once and reuse the instance throughout your application's lifecycle, preferably within a context manager (e.g., `with KustoClient(kcsb) as client:`).
gotcha Managed Streaming ingestion in earlier versions might not correctly handle throttling events. This was addressed in version 6.0.1.
Fix: Upgrade to `azure-kusto-data` version 6.0.1 or later to ensure proper handling of throttling events during managed streaming ingestion.

Install

pip install azure-kusto-data Basic Installation
pip install azure-kusto-data[aio] For Asynchronous Client
pip install azure-kusto-data[pandas] For Pandas DataFrame Support

Imports

KustoClient
```
from azure.kusto.data import KustoClient
```
The primary synchronous client for interacting with Kusto.
KustoConnectionStringBuilder
```
from azure.kusto.data import KustoConnectionStringBuilder
```
Used to construct connection strings with various authentication methods.
KustoClient (async)
```
from azure.kusto.data.aio import KustoClient
```
The asynchronous client requires the `aio` extra during installation.
dataframe_from_result_table
```
from azure.kusto.data.helpers import dataframe_from_result_table
```
A helper function to convert Kusto query results into a pandas DataFrame. Requires the `pandas` extra during installation.

Quickstart

This quickstart demonstrates how to connect to an Azure Data Explorer (Kusto) cluster using Azure Active Directory (AAD) application key authentication, execute a Kusto Query Language (KQL) query, and print the results. Ensure you replace the placeholder values for `KUSTO_CLUSTER_URI`, `KUSTO_CLIENT_ID`, `KUSTO_CLIENT_SECRET`, and `KUSTO_TENANT_ID` with your actual credentials, ideally via environment variables for security. The example queries the 'Samples' database for 5 'StormEvents' records.

import os
from azure.kusto.data import KustoClient, KustoConnectionStringBuilder
from azure.kusto.data.exceptions import KustoServiceError

# Replace with your Kusto cluster URI
CLUSTER_URI = os.environ.get('KUSTO_CLUSTER_URI', 'https://<your_cluster_name>.kusto.windows.net')
# Replace with your AAD application ID (client ID)
CLIENT_ID = os.environ.get('KUSTO_CLIENT_ID', 'your_aad_application_id')
# Replace with your AAD application key (client secret)
CLIENT_SECRET = os.environ.get('KUSTO_CLIENT_SECRET', 'your_aad_application_key')
# Replace with your AAD tenant ID
TENANT_ID = os.environ.get('KUSTO_TENANT_ID', 'your_aad_tenant_id')

DB_NAME = 'Samples'
QUERY = 'StormEvents | take 5'

def main():
    if 'your_aad_application_id' in CLIENT_ID or 'your_aad_application_key' in CLIENT_SECRET:
        print("Please set KUSTO_CLUSTER_URI, KUSTO_CLIENT_ID, KUSTO_CLIENT_SECRET, and KUSTO_TENANT_ID environment variables or replace placeholders.")
        return

    # Build connection string for AAD application key authentication
    kcsb = KustoConnectionStringBuilder.with_aad_application_key_authentication(
        CLUSTER_URI, CLIENT_ID, CLIENT_SECRET, TENANT_ID
    )

    # It is good practice to re-use the KustoClient instance, as it maintains a pool of connections.
    try:
        with KustoClient(kcsb) as client:
            print(f"Executing query on database '{DB_NAME}'...")
            response = client.execute(DB_NAME, QUERY)

            for row in response.primary_results[0]:
                print(f"Timestamp: {row['StartTime']}, EventType: {row['EventType']}, State: {row['State']}")

    except KustoServiceError as e:
        print(f"Kusto service error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == '__main__':
    main()

view raw JSON →