Registry / azure / azure-kusto-ingest

azure-kusto-ingest

JSON →
library6.0.3pypypi✓ verified 52d ago

The `azure-kusto-ingest` library provides a client for ingesting data into Azure Data Explorer (Kusto) clusters. It supports queued ingestion (batching for high throughput) and streaming ingestion (low latency). The current version is 6.0.3, with frequent bug fix releases and occasional major versions aligning with Python and Azure SDK ecosystem changes. Version 6.0.3 introduced allowing transformation functions for CSV and SCSV formats.

azuredatabase
pip install azure-kusto-ingest
Install & Compatibility
Where this runs
tested against v6.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.960 runs
installs and imports cleanly · install 0.0s · import 1.612s · 51.1MB
glibc
py 3.103.960 runs
installs and imports cleanly · install 7.5s · import 1.492s · 52MB
51MB installed
● package 51MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

KustoConnectionStringBuilder
from azure.kusto.data import KustoConnectionStringBuilder
Used to construct connection strings, part of the core Kusto data library.
KustoIngestClient
from azure.kusto.ingest import KustoIngestClient
Main client for queued (batch) data ingestion.
KustoStreamingIngestClient
from azure.kusto.ingest import KustoStreamingIngestClient
Client for low-latency streaming data ingestion.
IngestionProperties
from azure.kusto.ingest import IngestionProperties
Configures ingestion behavior like target database/table, data format, and mapping.
DataFormat
from azure.kusto.data import DataFormat
Enum for specifying the format of the ingested data (e.g., CSV, TSV, JSON).
BlobDescriptor
from azure.kusto.ingest import BlobDescriptor
Used for ingesting data directly from Azure Blob Storage.

This quickstart demonstrates how to perform queued ingestion of in-memory CSV data into an Azure Data Explorer table. It uses Azure CLI authentication for simplicity but can be adapted for other authentication methods. The example sets up the Kusto client, defines ingestion properties, and sends a small CSV string as a stream. Remember to set `KUSTO_CLUSTER_URL`, `KUSTO_DATABASE`, and `KUSTO_TABLE` environment variables.

import os import io from azure.kusto.data import KustoConnectionStringBuilder, DataFormat from azure.kusto.ingest import KustoIngestClient, IngestionProperties # Configuration from environment variables (replace with your actual values) KUSTO_CLUSTER_URL = os.environ.get('KUSTO_CLUSTER_URL', 'https://yourcluster.region.kusto.windows.net') KUSTO_DATABASE = os.environ.get('KUSTO_DATABASE', 'yourdatabase') KUSTO_TABLE = os.environ.get('KUSTO_TABLE', 'yourtable') # Ensure environment variables are set or replace with actual connection string details # For AAD app authentication: # KCSB = KustoConnectionStringBuilder.with_aad_application_key( # KUSTO_CLUSTER_URL, os.environ.get('KUSTO_CLIENT_ID', ''), os.environ.get('KUSTO_CLIENT_SECRET', ''), os.environ.get('KUSTO_TENANT_ID', '') # ) # For Azure CLI authentication: KCSB = KustoConnectionStringBuilder.with_az_cli_authentication(KUSTO_CLUSTER_URL) # Create an Ingest Client ingest_client = KustoIngestClient(KCSB) # Define Ingestion Properties ingestion_properties = IngestionProperties( database=KUSTO_DATABASE, table=KUSTO_TABLE, data_format=DataFormat.CSV, # For real-time monitoring of ingestion status, set flush_immediately=True # but be aware of performance implications for large batches. flush_immediately=False ) # Sample data as a CSV string data_rows = [ "id,name,value", "1,TestItemA,100", "2,TestItemB,200" ] data_csv = "\n".join(data_rows) # Ingest data from an in-memory stream print(f"Attempting to ingest data into {KUSTO_DATABASE}.{KUSTO_TABLE}...") with io.StringIO(data_csv) as stream: result = ingest_client.ingest_from_stream(stream, ingestion_properties) # For queued ingestion, the result indicates submission, not completion. # Actual status must be monitored in Azure Data Explorer using .show commands. print("Ingestion job submitted. Check Azure Data Explorer for status details.") # print(f"Ingestion result object: {result}") # Uncomment to see the result object
Debug
Known issues
breakingStarting with version 6.0.0, the minimum supported Python version for `azure-kusto-ingest` (and other Azure SDKs) is Python 3.9. Prior versions supported older Python versions (e.g., v5.x supported Python 3.8, v4.x supported Python 3.7).
fix
Upgrade your Python environment to 3.9 or higher. If you must use an older Python version, pin `azure-kusto-ingest` to `<6.0.0` (e.g., `azure-kusto-ingest<6.0.0`).
affects: >=6.0.0
breakingVersion 5.0.0 introduced breaking changes to `KustoConnectionStringBuilder` keywords, aligning them with other Azure SDKs. Keywords like `msi_auth`, `msi_authentication`, `msi_params`, and `msi_type` were removed from direct parsing.
fix
Review your `KustoConnectionStringBuilder` usage. Use the builder methods (e.g., `with_aad_managed_identity`) instead of relying on parsing specific keyword arguments in the connection string directly. If using older keyword-based strings, downgrade to `<5.0.0`.
affects: >=5.0.0
gotchaIngesting data from Pandas DataFrames (using `ingest_from_dataframe`) has seen multiple bug fixes across versions related to datetime columns, null values, and specific Pandas versions (e.g., Pandas 3.0). Ensure compatibility.
fix
Always use the latest version of `azure-kusto-ingest` with the latest compatible Pandas version. If encountering issues, specifically check the changelog for fixes related to `dataframe_from_result_table` and `ingest_from_dataframe` in your library version relative to your Pandas version. Pinning `pandas` to a known working version might be necessary if unable to update `azure-kusto-ingest`.
affects: <6.0.2
gotchaManaged Streaming Ingestion can encounter throttling events. While version 6.0.1 included a fix to handle these events more gracefully, users on older versions might experience issues with managed streaming stability under high load.
fix
Upgrade to version `6.0.1` or higher for improved throttling event handling in Managed Streaming. If using streaming ingestion, ensure your cluster is adequately scaled for the expected ingestion rate.
affects: <6.0.1
breakingThe class `KustoIngestClient` was renamed to `KustoClient` starting from version 6.0.0. Attempting to import `KustoIngestClient` from `azure.kusto.ingest` in versions `>=6.0.0` will result in an `ImportError`.
fix
Update your code to import `KustoClient` instead of `KustoIngestClient`. For example, `from azure.kusto.ingest import KustoClient`. If you need to support older versions, consider conditional imports or pin the library to `<6.0.0`.
affects: >=6.0.0
breakingStarting with version 6.0.0, the `KustoIngestClient` class was removed from the `azure.kusto.ingest` top-level module. Users should transition to `QueuedKustoIngestClient` for queued ingestion or `StreamKustoIngestClient` for streaming ingestion, depending on their use case.
fix
Update your code to import and use either `QueuedKustoIngestClient` or `StreamKustoIngestClient` from `azure.kusto.ingest` instead of `KustoIngestClient`. For example, change `from azure.kusto.ingest import KustoIngestClient` to `from azure.kusto.ingest import QueuedKustoIngestClient` or `StreamKustoIngestClient` and adjust the client instantiation accordingly.
affects: >=6.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure'
This error occurs when the `azure-kusto-ingest` package (or its dependencies within the `azure` namespace) is not properly installed or accessible in the Python environment where the code is being run. This is particularly common in isolated environments like Databricks notebooks or virtual environments where the installation might be in a different interpreter or not linked correctly.
fix
Ensure the `azure-kusto-ingest` package is installed in the correct Python environment. If using a virtual environment, activate it before installing. For platforms like Databricks, ensure the library is installed for the cluster's Python environment. 
`pip install azure-kusto-ingest`
ImportError: cannot import name 'DataFormat' from 'azure.kusto.ingest'
This error typically indicates that the `DataFormat` enum (or a similar constant/class) has been moved, renamed, or removed from the direct `azure.kusto.ingest` module in a newer version of the library, or that a user is trying to import it incorrectly.
fix
Check the official `azure-kusto-ingest` documentation for the correct import path of `DataFormat` in your installed version. It is often located in a submodule like `azure.kusto.data.data_format`. 
`from azure.kusto.data.data_format import DataFormat`
KustoAuthenticationError
This error occurs when the client fails to authenticate with the Azure Data Explorer cluster. Common reasons include incorrect credentials (e.g., Azure AD application ID, secret, or certificate), insufficient permissions for the authenticating identity (e.g., 'ingestor' role not assigned), or an incorrect cluster endpoint.
fix
Verify that your Azure AD application or managed identity has the necessary 'Ingestor' permissions on the target database in Azure Data Explorer. Double-check the client ID, client secret (or certificate), tenant ID, and the Kusto cluster URI in your connection string.
Entity 'table name that doesn't exist' of kind 'Table' wasn't found.
This error indicates that the target table specified in the ingestion command does not exist in the Azure Data Explorer database, or its name is misspelled.
fix
Ensure the table name provided to the ingestion client is correct and that the table has been created in your Azure Data Explorer database. You can create a table using Kusto Query Language (KQL) commands in the Azure Data Explorer web UI or programmatically.
Query schema doesn't match table schema / Inconsistent number of fields in the input records.
These errors indicate a mismatch between the schema of the data being ingested and the schema of the target table in Azure Data Explorer, or an inconsistency within the input data itself (e.g., a CSV file with varying numbers of columns per row). This can also occur if ingestion mappings are incorrect or outdated.
fix
Review your data source and ensure its schema (column names, types, order) aligns with the target Kusto table's schema. If using ingestion mappings, verify they are correctly defined and reference the appropriate columns. For CSV files, ensure all rows have a consistent number of fields. You may need to modify your ingestion mapping or the table schema to align with the incoming data.
Upgrade
Version history
6.0.4latest on PyPI
Audit
Dependencies
pandasoptionalRequired for `ingest_from_dataframe` functionality, installed via `[pandas]` extra.
Agent activity
85 hits · last 30 days
node
10
mj12bot
3
ahrefsbot
3
seranking-bot
3
amazonbot
1
Resources