{"id":1155,"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":"python","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,"search_vec":"'3':27 '6.0.3':64 'activ':53 'analyt':69 'api':40 'azur':1,6,19,65 'capabl':16 'client':4,9,68 'cluster':23 'compat':29 'current':61 'data':3,8,20,33,67 'databas':70 'db':39 'enabl':42 'environ':46 'explor':21 'familiar':37 'interfac':41 'jupyt':48 'kusto':2,7,22,66 'librari':13,51 'like':47 'maintain':54 'notebook':49 'provid':15 'python':12,26,38 'queri':18,71 'receiv':56 'regular':57 'support':31 'type':34 'updat':58 'use':44 'various':32 'version':62 'within':45 'x':28","created_at":"2026-04-05T14:30:29.090492+00:00","updated_at":"2026-04-17T15:01:42.592352+00:00","problems":[{"fix":"Ensure the package is installed in your active Python environment. If using a virtual environment, activate it before installing. Restart your kernel if in a notebook. \n`pip install azure-kusto-data`","cause":"The `azure-kusto-data` package or its dependencies were not installed correctly or are not accessible in the current Python environment. This can happen if `pip install azure-kusto-data` was not run, or if there are virtual environment issues.","error":"ModuleNotFoundError: No module named 'azure.kusto.data'"},{"fix":"Verify that the Azure AD application registration's certificate subject name is correct and authorized. Ensure the service principal has the 'Viewer' (or appropriate) role assigned at the cluster or database level in Azure Data Explorer. For cross-tenant access, additional configurations might be needed.","cause":"Authentication failed because the Azure Active Directory (AAD) application's certificate, or the service principal used, does not have the necessary permissions or is improperly configured (e.g., incorrect subject name, missing role assignment) for the Kusto cluster. Another common authentication error is `action Principal 'aaduser=[AAD account id];[ AAD tenant id ]' is not authorized to perform operation.` due to insufficient database permissions.","error":"KustoAuthenticationError: AADSTS700030: Invalid certificate - subject name in certificate is not authorized."},{"fix":"Double-check the cluster URI for typos (it should be `https://<ClusterName>.<Region>.kusto.windows.net`). Confirm the Azure Data Explorer cluster's status in the Azure portal and start it if it's stopped. Review network security group (NSG) rules if the cluster is in a virtual network.","cause":"The Kusto cluster URI is incorrect, the cluster is stopped, or there are network connectivity issues preventing the client from reaching the cluster endpoint. This can also manifest as a `KustoNetworkError`.","error":"Failed to connect to cluster. Please verify the URI and check if the cluster is available."},{"fix":"Verify the exact name and existence of the table (or entity) in your Kusto database. Check for typos in the query. If ingesting data, ensure that the table exists and any required ingestion mappings are correctly defined and applied.","cause":"The Kusto Query Language (KQL) query attempts to access a table or other entity (like a function or materialized view) that does not exist in the specified database or is misspelled. This can also be caused by missing or incorrect ingestion mappings if the data is being ingested.","error":"Entity 'table name that doesn't exist' of kind 'Table' wasn't found."},{"fix":"Verify that the Azure AD application ID and tenant ID are correct, and ensure the application is properly registered and configured in Azure Active Directory with appropriate permissions.","cause":"The provided Azure AD application ID or tenant ID is incorrect, or the application registration is missing or misconfigured in the specified Azure AD tenant.","error":"azure.kusto.data.exceptions.KustoClientError: AADSTS700016: Application with identifier '{app_id}' was not found in the directory '{tenant_id}'."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"6.0.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://learn.microsoft.com/azure/data-explorer/kusto/api/python/kusto-python-client","github":"https://github.com/Azure/azure-kusto-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/azure-kusto-data/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["azure","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}