azure-kusto-python

azure-kusto-data is Microsoft’s official Python client for Azure Data Explorer (Kusto), the columnar analytics engine behind services like Azure Monitor and Application Insights. It wraps the Kusto REST API in a small, typed surface: build a connection string with KustoConnectionStringBuilder, hand it to a KustoClient, and call execute() to run KQL queries or control commands against a cluster.

The package supports every common Azure AD authentication flow (application key/certificate, username/password, device code, managed identity, Azure CLI, and arbitrary token credentials), ships an async client with an identical API under azure.kusto.data.aio, and can stream very large result sets incrementally instead of buffering them in memory. It is maintained directly by the Azure Data Explorer team as part of a monorepo alongside azure-kusto-ingest.

What You Get

• A synchronous KustoClient for executing KQL queries and control commands against Azure Data Explorer clusters
• An async client (azure.kusto.data.aio) mirroring the same API for asyncio-based applications
• KustoConnectionStringBuilder factory methods covering AAD app, AAD user, managed identity, Azure CLI, and token-credential authentication flows
• Streaming query support that parses large result sets incrementally instead of loading them fully into memory
• A typed exception hierarchy carrying the original HTTP response for troubleshooting failed queries

Common Use Cases

• Running ad-hoc or scheduled KQL queries against a Kusto/Azure Data Explorer cluster from a Python service or notebook
• Pulling query results into a pandas DataFrame for analysis via the optional pandas extra
• Building data pipelines or Jupyter notebooks (including on Azure Databricks) that read telemetry or log data stored in Kusto
• Executing Kusto management/control commands (schema changes, retention policies) from automation scripts

Under The Hood

Architecture _KustoClientBase (client_base.py) is an abstract base class shared by the sync KustoClient (client.py) and its async mirror in aio/client.py, centralizing endpoint construction (v1/rest/mgmt, v2/rest/query, v1/rest/ingest), trusted-endpoint validation via kusto_trusted_endpoints.py, and unified HTTP error mapping in _handle_http_error. Requests are assembled through the ExecuteRequestParams builder, which composes tracing headers (x-ms-client-request-id, x-ms-app, x-ms-user) from a ClientDetails/ClientRequestProperties pair before dispatch. The public execute() method inspects whether a query string starts with ”.” to route between execute_query (KQL) and execute_mgmt (control commands) against the v2 and v1 REST endpoints respectively, and execute_streaming_query returns a StreamingDataSetEnumerator built on a JsonTokenReader so large result sets can be consumed incrementally instead of buffered in memory. Authentication is delegated to a pluggable _AadHelper/token-provider layer in security.py and _token_providers.py, decoupling credential acquisition from request execution.

Tech Stack The package targets Python 3.9+ and is built with the uv build backend inside a uv workspace shared with azure-kusto-ingest and a quick-start sample package. Core runtime dependencies are requests for HTTP, azure-identity and msal for Azure AD token acquisition, azure-core for distributed tracing decorators, python-dateutil for date parsing, and ijson for streaming JSON parsing; optional extras add pandas (dataframe conversion) and aiohttp/asgiref (the async client surface in the aio submodule). CI runs the full matrix across Python 3.9 through 3.13 using GitHub Actions, with ruff for formatting/linting, basedpyright for type checking, and CodeQL for security scanning.

Code Quality The azure-kusto-data test suite contains roughly 150 test functions covering the connection string builder, client execution paths, token providers (sync and async), streaming responses, cloud settings, and endpoint validation, run via pytest with parallel workers (pytest-xdist) and both mocked (responses/aioresponses) and end-to-end suites. Exceptions form a typed hierarchy rooted at KustoError (KustoServiceError, KustoThrottlingError, KustoApiError, KustoClosedError, KustoNetworkError), each carrying the originating HTTP response for debugging. The package ships a py.typed marker and is checked with basedpyright in CI (non-blocking), and ruff enforces consistent formatting and lint rules across the workspace.

API Design The public surface is deliberately small: construct a KustoConnectionStringBuilder via one of several named static factory methods (with_aad_application_key_authentication, with_az_cli_authentication, with_token_credential, etc.) matching a specific auth flow, pass it to KustoClient, and call execute/execute_query/execute_mgmt/execute_streaming_query — the same method names and signatures are mirrored exactly in the azure.kusto.data.aio async client, so switching between sync and async code paths requires no relearning. Context-manager support (enter/exit) handles session cleanup, and ClientRequestProperties offers a fluent options object for per-query tuning (timeouts, server-side caching) without cluttering the core execute() signature.