Skip to content

Connect Azure Data Explorer (Kusto)

Datarelix connects to Azure Data Explorer (also called Kusto, or ADX) through a read-only query service. KQL queries use the query endpoint; discovery’s .show commands use the management endpoint and never read 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

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://<cluster-name>.<region>.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://<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 execution layer 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

  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:

    .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>')
  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

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. This Datarelix authentication mode uses a certificate. Kusto itself supports other application authentication methods, including application keys. The certificate thumbprint and private key PEM are stored encrypted.

Setup

  1. Register an application in Microsoft Entra ID (e.g. datarelix-kusto-reader).
  2. Generate a certificate:
    Terminal window
    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 (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:
    .add database <db-name> viewers ('aadapp=<app-id>;<tenant-id>')

Where to find your credentials

FieldWhere to get it
Tenant IDAzure AD → your app registration → Overview → Directory (tenant) ID
Client IDAzure AD → your app registration → Overview → Application (client) ID
Certificate thumbprintAzure AD → app registration → Certificates & secrets → Certificates → 40-char hex after upload
Certificate PEMThe 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

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 primary or foreign keys, so discovery finds no relationships; optional AI schema analysis suggests 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:

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 — Datarelix rejects .create, .alter, .drop, .ingest, .set, .append, .purge, .delete, and control commands hidden inside a query, before they run.
  • No cross-database joins — one database per connection.
  • Row limit — results are capped at 5,000 rows.

Troubleshooting

SymptomLikely causeFix
401 Unauthorized / token audience mismatchWrong scope on user tokenVerify the Entra app has https://kusto.kusto.windows.net/user_impersonation as a delegated permission.
Forbidden: Principal ... is not authorizedMissing Kusto roleRun .add database <db> viewers ('aadapp=<app-id>;<tenant-id>') in the Azure Data Explorer web UI.
Certificate not foundThumbprint typoRe-copy the thumbprint from Azure AD — must be 40 hex chars, no spaces.
Cluster not foundURI typo or wrong regionVerify the URI in the cluster Overview blade.
Discovery returns 0 tablesPrincipal lacks Database ViewerGrant the role and re-run discovery.
Semantic error: 'table not found' (KQL)Querying a table in another databaseOne database per connection; create another connection for the other database.