Connecter Azure Data Explorer (Kusto)

Datarelix se connecte à Azure Data Explorer (aussi appelé Kusto, ou ADX) via un service de requêtes en lecture seule. Les requêtes KQL passent par le point de terminaison de requête ; les commandes d’introspection .show passent par le point de terminaison de gestion, jamais sur vos données.

Contrairement aux autres dialectes pris en charge, Kusto utilise KQL (Kusto Query Language), pas SQL. La génération de requêtes tient compte du dialecte — les requêtes générées utilisent la syntaxe à pipes de KQL (|), take au lieu de LIMIT, project au lieu de SELECT, summarize au lieu de GROUP BY.

Prérequis

Un cluster Azure Data Explorer.
Une base de données Kusto (un cluster peut en héberger plusieurs ; choisissez-en une par connexion).
Le principal utilisé pour l’authentification doit avoir au minimum le rôle Database Viewer sur la base de données — voir Manage database security roles.

Trouver vos informations de connexion

Dans le portail Azure :

Ouvrez votre cluster Azure Data Explorer.
Copiez l’URI depuis le panneau Overview. Format : https://<cluster-name>.<region>.kusto.windows.net.
Dans le panneau Databases du cluster, copiez le nom de la base de données.

ADX, Fabric et Log Analytics

Collez le Query URI correspondant à votre moteur — ils diffèrent :

Cluster Azure Data Explorer — https://<cluster>.<region>.kusto.windows.net (panneau Overview).
Microsoft Fabric Eventhouse / base KQL (Real-Time Intelligence) — c’est Kusto en dessous ; copiez le Query URI depuis la carte Database details de la base.
Azure Monitor / Log Analytics / Application Insights — ce sont des proxys de requête, pas des clusters ADX autonomes, et ce connecteur ne les prend pas en charge.

Formulaire de connexion

Cluster URI:    https://your-cluster.eastus.kusto.windows.net
Database:       your-kusto-db
Auth mode:      one of the two below

Modes d’authentification

Entra OBO (par défaut)

Rattache la connexion à l’utilisateur actuellement connecté. La couche d’exécution échange le jeton bearer de l’utilisateur contre un jeton d’audience Kusto via le flux On-Behalf-Of d’Azure AD. Aucun secret à longue durée de vie n’est stocké. Le cluster Kusto voit l’identité de l’utilisateur : les attributions Database Viewer par utilisateur s’appliquent donc au moment de la requête.

Configuration

Accordez le rôle Database Viewer sur la base Kusto à l’utilisateur connecté (ou à son groupe Entra). Exécutez ceci dans l’interface web Azure Data Explorer (https://dataexplorer.azure.com) sur votre base :
```
.add database <db-name> viewers ('aaduser=user@yourtenant.onmicrosoft.com')
```
Ou, pour un groupe :
```
.add database <db-name> viewers ('aadgroup=<group-object-id>;<tenant-id>')
```
L’inscription d’application Entra de Datarelix doit avoir https://kusto.kusto.windows.net/user_impersonation configuré comme autorisation déléguée. Contactez votre administrateur si votre locataire (tenant) exige un consentement administrateur.

Où trouver vos identifiants

Aucun identifiant à saisir — la connexion utilise automatiquement l’identité de l’utilisateur connecté.

Tenant ID est facultatif lorsque le locataire d’origine du cluster Kusto est celui de l’utilisateur. Renseignez-le explicitement lorsqu’ils diffèrent (accès inter-locataires).

À saisir

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)

Application + certificat

Authentification par principal de service à l’aide d’un certificat. Kusto exige des certificats (pas des secrets clients) pour l’accès application seule. L’empreinte du certificat et la clé privée PEM sont stockées chiffrées.

Configuration

Inscrivez une application dans Microsoft Entra ID (par ex. datarelix-kusto-reader).

Générez un certificat :

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

Dans l’inscription d’application → Certificates & secrets → Certificates, téléversez cert.pem (le certificat public, pas la clé). Azure affiche l’empreinte après le téléversement — copiez-la (40 caractères hexadécimaux).
Accordez à l’application le rôle Database Viewer sur la base Kusto. Dans l’interface web Azure Data Explorer :
```
.add database <db-name> viewers ('aadapp=<app-id>;<tenant-id>')
```

Où trouver vos identifiants

Champ	Où le trouver
Tenant ID	Azure AD → votre inscription d’application → Overview → Directory (tenant) ID
Client ID	Azure AD → votre inscription d’application → Overview → Application (client) ID
Certificate thumbprint (empreinte)	Azure AD → inscription d’application → Certificates & secrets → Certificates → 40 caractères hexadécimaux après le téléversement
Certificate PEM	Le fichier `key.pem` que vous avez généré — collez le bloc complet `-----BEGIN PRIVATE KEY-----` … `-----END PRIVATE KEY-----`

Empreinte et PEM — l’empreinte indique quel certificat Entra doit attendre ; le PEM est la clé privée que Datarelix utilise pour signer l’assertion JWT. La clé privée n’est pas téléversée dans Entra.

À saisir

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-----

Sémantique de la portée

Kusto a un espace de noms plat à l’intérieur d’une base de données — pas de schémas. Le champ Database (base de données) définit la portée. Pour analyser plusieurs bases, créez plusieurs connexions.

Découverte

Entièrement prise en charge via les commandes de contrôle Kusto (.show tables, .show table <name> schema as json). Elles s’exécutent sur le point de terminaison de gestion, jamais sur vos données.

Kusto n’a pas de notion de PK/FK — les relations issues de l’introspection sont donc toujours vides ; la passe d’enrichissement par le modèle déduit les liens à partir des conventions de nommage des colonnes.
Toutes les colonnes sont signalées comme nullables (Kusto n’a pas de contrainte NOT NULL au niveau du stockage).
Les colonnes polymorphes (type dynamic) sont signalées comme du JSON.

Petit guide KQL

Les requêtes générées sont en KQL. Vous n’écrivez pas de KQL vous-même — Datarelix le génère. Pour le contexte :

StormEvents
| where State == "FLORIDA"
| summarize Count=count() by EventType
| order by Count desc
| take 10

| transmet la sortie de l’étape précédente à l’opérateur suivant.
take limite le nombre de lignes.
project sélectionne des colonnes.
where filtre les lignes.
summarize agrège.
order by / sort by trie les lignes.

Voir la référence rapide KQL pour l’ensemble du langage.

Limites

Aucune mutation — le validateur rejette .create, .alter, .drop, .ingest, .set, .append, .purge, .delete et les commandes de contrôle sous forme d’injection.
Pas de jointures entre bases — une base de données par connexion.
Limite de lignes — plafond côté serveur de 5 000 lignes.

Dépannage

Symptôme	Cause probable	Solution
`401 Unauthorized` / audience du jeton incohérente	Portée incorrecte sur le jeton utilisateur	Vérifiez que l’application Entra a `https://kusto.kusto.windows.net/user_impersonation` comme autorisation déléguée.
`Forbidden: Principal ... is not authorized`	Rôle Kusto manquant	Exécutez `.add database <db> viewers ('aadapp=<app-id>;<tenant-id>')` dans l’interface web Azure Data Explorer.
`Certificate not found`	Faute de frappe dans l’empreinte	Recopiez l’empreinte depuis Azure AD — 40 caractères hexadécimaux, sans espaces.
`Cluster not found`	Faute de frappe dans l’URI ou mauvaise région	Vérifiez l’URI dans le panneau Overview du cluster.
La découverte renvoie 0 table	Le principal n’a pas `Database Viewer`	Attribuez le rôle et relancez la découverte.
`Semantic error: 'table not found'` (KQL)	Requête sur une table d’une autre base	Une base de données par connexion ; créez une autre connexion pour l’autre base.