--- title: "Connect Azure Data Explorer (Kusto)" description: "Connect Datarelix to Azure Data Explorer (Kusto) for read-only KQL." canonical: https://docs.datarelix.ai/guides/connections/kusto/ --- # Connect Azure Data Explorer (Kusto) Datarelix connects to Azure Data Explorer (also called Kusto, or ADX) through a read-only query service. KQL queries route through the query endpoint; `.show` introspection commands route through the management endpoint, never against your data. Unlike the other supported dialects, Kusto uses **KQL** (Kusto Query Language), not SQL. Query generation is dialect-aware — generated queries use KQL pipe syntax (`|`), `take` instead of `LIMIT`, `project` instead of `SELECT`, `summarize` instead of `GROUP BY`. ## Prerequisites - An [Azure Data Explorer cluster](https://learn.microsoft.com/en-us/azure/data-explorer/create-cluster-and-database). - A Kusto **database** (clusters can host many; pick one per connection). - The principal used for auth must have at least `Database Viewer` role on the database — see [Manage database security roles](https://learn.microsoft.com/en-us/kusto/management/manage-database-security-roles). ## Finding your connection details In the Azure portal: 1. Open your **Azure Data Explorer cluster**. 2. Copy the **URI** from the Overview blade. Format: `https://..kusto.windows.net`. 3. In the cluster's **Databases** blade, copy the database name. ### ADX, Fabric, and Log Analytics Paste the **Query URI** for your engine — they differ: - **Azure Data Explorer cluster** — `https://..kusto.windows.net` (Overview blade). - **Microsoft Fabric Eventhouse / KQL database** (Real-Time Intelligence) — Kusto under the hood; copy the [**Query URI**](https://learn.microsoft.com/en-us/fabric/real-time-intelligence/access-database-copy-uri) from the database's **Database details** card. - **Azure Monitor / Log Analytics / Application Insights** — these are query proxies, **not** standalone ADX clusters, and are not supported by this connector. ## Connection form ```ini Cluster URI: https://your-cluster.eastus.kusto.windows.net Database: your-kusto-db Auth mode: one of the two below ``` ## Auth modes ### Entra OBO (default) Binds the connection to the **currently signed-in user**. The execution layer exchanges the user's bearer token for a Kusto-audience token via Azure AD's [On-Behalf-Of flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow). No long-lived secret stored. The Kusto cluster sees the user's identity, so per-user `Database Viewer` grants apply at query time. **Setup** 1. Grant the signed-in user (or their Entra group) `Database Viewer` on the Kusto database. Run this in the **Azure Data Explorer web UI** (https://dataexplorer.azure.com) against your database: ```kql .add database viewers ('aaduser=user@yourtenant.onmicrosoft.com') ``` Or for a group: ```kql .add database viewers ('aadgroup=;') ``` 2. The Datarelix Entra app registration must have `https://kusto.kusto.windows.net/user_impersonation` configured as a delegated permission. Contact your administrator if your tenant requires admin consent. **Where to find your credentials** No credentials to enter — the connection uses the signed-in user's identity automatically. **Tenant ID** is optional when the Kusto cluster's home tenant matches the user's tenant. Set it explicitly when they differ (cross-tenant access). **What to enter** ```ini Cluster URI: https://your-cluster.eastus.kusto.windows.net Database: your-kusto-db Auth mode: Entra OBO Tenant ID: (optional — required only for cross-tenant access) ``` --- ### App + Certificate Service-principal authentication using a certificate. Kusto requires certificates (not client secrets) for app-only access. The certificate thumbprint and private key PEM are stored encrypted. **Setup** 1. [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in Microsoft Entra ID (e.g. `datarelix-kusto-reader`). 2. Generate a certificate: ```bash openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 365 \ -subj "/CN=datarelix-kusto" ``` 3. In the app registration → **Certificates & secrets → Certificates**, [upload `cert.pem`](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials) (the public cert, **not** the key). Azure displays the thumbprint after upload — copy it (40-char hex). 4. Grant the app `Database Viewer` on the Kusto database. In the Azure Data Explorer web UI: ```kql .add database viewers ('aadapp=;') ``` **Where to find your credentials** | Field | Where to get it | |-------|----------------| | Tenant ID | Azure AD → your app registration → **Overview** → Directory (tenant) ID | | Client ID | Azure AD → your app registration → **Overview** → Application (client) ID | | Certificate thumbprint | Azure AD → app registration → **Certificates & secrets → Certificates** → 40-char hex after upload | | Certificate PEM | The `key.pem` file you generated — paste the full `-----BEGIN PRIVATE KEY-----` … `-----END PRIVATE KEY-----` block | > **Thumbprint vs PEM** — the thumbprint identifies *which* certificate Entra should expect; the PEM is the private key Datarelix uses to sign the JWT assertion. The private key is never uploaded to Entra. **What to enter** ```ini Cluster URI: https://your-cluster.eastus.kusto.windows.net Database: your-kusto-db Auth mode: App + Certificate Tenant ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Certificate thumbprint: AABBCCDDEEFF... Certificate PEM: -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- ``` --- ## Scope semantics Kusto has a flat namespace within a database — no schemas. The **Database** field is the scope. To analyze multiple databases, create multiple connections. ## Discovery Fully supported via Kusto control commands (`.show tables`, `.show table schema as json`). These run on the management endpoint, never against your data. - Kusto has no PK/FK concept — relationships are always empty from introspection; the LLM enrichment pass infers links from column-name conventions. - All columns are reported as nullable (Kusto has no `NOT NULL` constraint at the storage layer). - Polymorphic columns (`dynamic` type) are reported as JSON. ## KQL primer Generated queries use KQL. You don't write KQL yourself — Datarelix generates it. For context: ```kql StormEvents | where State == "FLORIDA" | summarize Count=count() by EventType | order by Count desc | take 10 ``` - `|` pipes the previous step's output into the next operator. - `take` limits rows. - `project` selects columns. - `where` filters rows. - `summarize` aggregates. - `order by` / `sort by` orders rows. See the [KQL quick reference](https://learn.microsoft.com/en-us/kusto/query/) for the full language. ## Limitations - **No mutations** — the validator rejects `.create`, `.alter`, `.drop`, `.ingest`, `.set`, `.append`, `.purge`, `.delete`, and injection-form control commands. - **No cross-database joins** — one database per connection. - **Row limit** — server-side cap of 5 000 rows. ## Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | `401 Unauthorized` / token audience mismatch | Wrong scope on user token | Verify the Entra app has `https://kusto.kusto.windows.net/user_impersonation` as a delegated permission. | | `Forbidden: Principal ... is not authorized` | Missing Kusto role | Run `.add database viewers ('aadapp=;')` in the Azure Data Explorer web UI. | | `Certificate not found` | Thumbprint typo | Re-copy the thumbprint from Azure AD — must be 40 hex chars, no spaces. | | `Cluster not found` | URI typo or wrong region | Verify the URI in the cluster Overview blade. | | Discovery returns 0 tables | Principal lacks `Database Viewer` | Grant the role and re-run discovery. | | `Semantic error: 'table not found'` (KQL) | Querying a table in another database | One database per connection; create another connection for the other database. |