{"library":"azure-kusto-data","title":"Azure Kusto Data Client","description":"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.","status":"active","version":"6.0.3","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-kusto-python","tags":["azure","kusto","data","client","analytics","database","query"],"install":[{"cmd":"pip install azure-kusto-data","lang":"bash","label":"Basic Installation"},{"cmd":"pip install azure-kusto-data[aio]","lang":"bash","label":"For Asynchronous Client"},{"cmd":"pip install azure-kusto-data[pandas]","lang":"bash","label":"For Pandas DataFrame Support"}],"dependencies":[{"reason":"Required for `dataframe_from_result_table` helper and other DataFrame-related functionalities.","package":"pandas","optional":true},{"reason":"Required for the asynchronous KustoClient (`azure.kusto.data.aio.KustoClient`).","package":"aiohttp","optional":true}],"imports":[{"note":"The primary synchronous client for interacting with Kusto.","symbol":"KustoClient","correct":"from azure.kusto.data import KustoClient"},{"note":"Used to construct connection strings with various authentication methods.","symbol":"KustoConnectionStringBuilder","correct":"from azure.kusto.data import KustoConnectionStringBuilder"},{"note":"The asynchronous client requires the `aio` extra during installation.","symbol":"KustoClient (async)","correct":"from azure.kusto.data.aio import KustoClient"},{"note":"A helper function to convert Kusto query results into a pandas DataFrame. Requires the `pandas` extra during installation.","symbol":"dataframe_from_result_table","correct":"from azure.kusto.data.helpers import dataframe_from_result_table"}],"quickstart":{"code":"import os\nfrom azure.kusto.data import KustoClient, KustoConnectionStringBuilder\nfrom azure.kusto.data.exceptions import KustoServiceError\n\n# Replace with your Kusto cluster URI\nCLUSTER_URI = os.environ.get('KUSTO_CLUSTER_URI', 'https://<your_cluster_name>.kusto.windows.net')\n# Replace with your AAD application ID (client ID)\nCLIENT_ID = os.environ.get('KUSTO_CLIENT_ID', 'your_aad_application_id')\n# Replace with your AAD application key (client secret)\nCLIENT_SECRET = os.environ.get('KUSTO_CLIENT_SECRET', 'your_aad_application_key')\n# Replace with your AAD tenant ID\nTENANT_ID = os.environ.get('KUSTO_TENANT_ID', 'your_aad_tenant_id')\n\nDB_NAME = 'Samples'\nQUERY = 'StormEvents | take 5'\n\ndef main():\n    if 'your_aad_application_id' in CLIENT_ID or 'your_aad_application_key' in CLIENT_SECRET:\n        print(\"Please set KUSTO_CLUSTER_URI, KUSTO_CLIENT_ID, KUSTO_CLIENT_SECRET, and KUSTO_TENANT_ID environment variables or replace placeholders.\")\n        return\n\n    # Build connection string for AAD application key authentication\n    kcsb = KustoConnectionStringBuilder.with_aad_application_key_authentication(\n        CLUSTER_URI, CLIENT_ID, CLIENT_SECRET, TENANT_ID\n    )\n\n    # It is good practice to re-use the KustoClient instance, as it maintains a pool of connections.\n    try:\n        with KustoClient(kcsb) as client:\n            print(f\"Executing query on database '{DB_NAME}'...\")\n            response = client.execute(DB_NAME, QUERY)\n\n            for row in response.primary_results[0]:\n                print(f\"Timestamp: {row['StartTime']}, EventType: {row['EventType']}, State: {row['State']}\")\n\n    except KustoServiceError as e:\n        print(f\"Kusto service error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    main()\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer before upgrading to `azure-kusto-data` 6.0.0 or later.","message":"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+.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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]`.","message":"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.","severity":"gotcha","affected_versions":">=6.0.2 (for pandas 3.0 fix), <6.0.2 (for pandas <2.3.1 issues)"},{"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:`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `azure-kusto-data` version 6.0.1 or later to ensure proper handling of throttling events during managed streaming ingestion.","message":"Managed Streaming ingestion in earlier versions might not correctly handle throttling events. This was addressed in version 6.0.1.","severity":"gotcha","affected_versions":"<6.0.1"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}