Kusto (Azure Data Explorer)

datarelix.ai 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. The planner 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.
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.

Finding your connection details

In the Azure portal:

Open your Azure Data Explorer cluster.
Copy the URI from the Overview blade. Format: https://<cluster-name>.<region>.kusto.windows.net.
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://<cluster>.<region>.kusto.windows.net (Overview blade).
Microsoft Fabric Eventhouse / KQL database (Real-Time Intelligence) — Kusto under the hood; copy the Query 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

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 orchestrator exchanges the user’s bearer token for a Kusto-audience token via Azure AD’s 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

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:
```
.add database <db-name> viewers ('aaduser=user@yourtenant.onmicrosoft.com')
```
Or for a group:
```
.add database <db-name> viewers ('aadgroup=<group-object-id>;<tenant-id>')
```
The datarelix.ai 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

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

Generate a certificate:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 365 \
  -subj "/CN=datarelix-kusto"

In the app registration → Certificates & secrets → Certificates, upload cert.pem (the public cert, not the key). Azure displays the thumbprint after upload — copy it (40-char hex).
Grant the app Database Viewer on the Kusto database. In the Azure Data Explorer web UI:
```
.add database <db-name> viewers ('aadapp=<app-id>;<tenant-id>')
```

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.ai uses to sign the JWT assertion. The private key is never uploaded to Entra.

What to enter

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 <name> 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 — the planner does. For context:

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 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 <db> viewers ('aadapp=<app-id>;<tenant-id>')` 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.