Connecter Elasticsearch (ES|QL)

Datarelix se connecte à Elasticsearch 8.11+ via un service de requêtes en lecture seule. Les requêtes passent par ES|QL — le langage à pipes d’Elastic, disponible dans le niveau Basic gratuit sur ES 8.11+.

Prérequis

Elasticsearch 8.11+ — ES|QL est passé en disponibilité générale en 8.11. Les versions antérieures rejettent le point de terminaison /_query.
Fonctionnalités de sécurité activées (par défaut sur Elastic Cloud ; pour les clusters auto-hébergés, vérifiez xpack.security.enabled: true et une configuration TLS).
Une clé d’API disposant des privilèges read et view_index_metadata sur les index ciblés.

Ce connecteur est destiné à Elasticsearch, pas à OpenSearch. AWS OpenSearch Service et le projet OpenSearch sont des forks qui n’implémentent pas ES|QL (ils utilisent PPL à la place) et ne sont pas pris en charge ici.

Types de déploiement — le même connecteur fonctionne pour les trois, mais l’endroit où récupérer le point de terminaison et la clé d’API change :

Elastic Cloud Hosted — console Cloud → votre déploiement → copiez le point de terminaison Elasticsearch ; créez les clés d’API dans Kibana.
Elastic Cloud Serverless — modèle d’authentification différent : créez une project API key depuis l’interface de gestion du projet serverless, et utilisez le point de terminaison Elasticsearch du projet. Les mêmes privilèges read + view_index_metadata s’appliquent.
Auto-hébergé — le point de terminaison HTTPS de votre cluster (par exemple https://es.example.com:9200) ; clés d’API via Kibana ou l’API.

Licence : ES|QL sur un cluster unique relève du niveau Basic gratuit sur ES 8.11+. Seule la recherche ES|QL inter-clusters exige un abonnement Enterprise — Datarelix utilise ES|QL sur un seul cluster.

Modes d’authentification

API key (clé d’API, recommandé)

Une clé d’API à portée restreinte authentifie chaque requête. La clé est stockée chiffrée et peut être révoquée sans redémarrer le moindre service.

Mise en place — créer une clé d’API à portée restreinte

Option A : interface Kibana

Dans Kibana, créez une clé d’API (Stack Management → Security → API Keys → Create API key).
Donnez-lui un nom (par exemple datarelix-prod).
Sous Restrict privileges, ajoutez des privilèges d’index : sélectionnez vos index cibles, puis ajoutez les privilèges read et view_index_metadata.
Cliquez sur Create. Copiez l’API key (id:secret encodé en base64) — elle n’est affichée qu’une seule fois.

Option B : API Elasticsearch

POST /_security/api_key
{
  "name": "datarelix-prod",
  "role_descriptors": {
    "logs_reader": {
      "indices": [
        { "names": ["logs-*", "metrics-*"], "privileges": ["read", "view_index_metadata"] }
      ]
    }
  }
}

La réponse contient id et api_key — le formulaire attend ces valeurs dans deux champs distincts, API key ID et API key secret.

Où trouver vos identifiants

Elastic Cloud : console Elastic Cloud → votre déploiement → Copy endpoint pour l’URL du cluster ; clés d’API via Kibana, comme ci-dessus.
Auto-hébergé : l’URL du cluster est le point de terminaison HTTP de votre Elasticsearch (par exemple https://es.example.com:9200) ; clés d’API via Kibana ou l’API.

Ce qu’il faut saisir

Cluster URL:     https://your-deployment.es.us-east-1.aws.elastic-cloud.com:9243
API key ID:      your-key-id
API key secret:  ••••••••
Verify TLS:      on
Allowed indices: logs-*,metrics-*

Basic auth (authentification basique, dev uniquement)

Nom d’utilisateur et mot de passe via le basic_auth du SDK Elasticsearch. Un avertissement s’affiche dans l’interface.

Déconseillé en production. L’authentification basique attribue chaque requête au même utilisateur (aucune piste d’audit par connexion), et changer les identifiants oblige à modifier la connexion.

Mise en place

Utilisez un utilisateur Elasticsearch existant disposant de read et view_index_metadata sur les index ciblés, ou créez un rôle et un utilisateur dédiés :

# Create a role
POST /_security/role/datarelix_reader
{
  "indices": [{ "names": ["logs-*"], "privileges": ["read", "view_index_metadata"] }]
}

# Create a user with that role
POST /_security/user/datarelix_reader
{
  "password": "choose-a-strong-password",
  "roles": ["datarelix_reader"]
}

Ce qu’il faut saisir

Cluster URL:     https://your-deployment.es.example.com:9200
Username:        datarelix_reader
Password:        ••••••••
Verify TLS:      on
Allowed indices: logs-*

Formulaire de connexion

Cluster URL:        https://es.example.com:9243
API key ID:         your-key-id           (API key mode)
API key secret:     ••••••••              (API key mode)
Verify TLS:         on
CA cert PEM:        (optional, for clusters with a self-signed or internal CA cert)
Allowed indices:    logs-*,metrics-*

TLS / certificat CA

Si votre cluster utilise un certificat auto-signé ou une autorité de certification interne, collez le PEM dans CA cert PEM (certificat de l’autorité, au format PEM). Où le récupérer :

Elastic Cloud : page du déploiement → Security → téléchargez le certificat de l’autorité.
Auto-hébergé (installation par défaut) : $ES_HOME/config/certs/http_ca.crt sur n’importe quel nœud du cluster.
Installation Docker par défaut : docker cp <es-container>:/usr/share/elasticsearch/config/certs/http_ca.crt ./http_ca.crt

Collez le bloc PEM entier, y compris -----BEGIN CERTIFICATE----- / -----END CERTIFICATE-----.

Désactiver Verify TLS (vérification TLS) est possible, mais réservé au développement — la connexion devient alors vulnérable aux attaques MITM actives.

Sémantique de la portée

La connexion enregistre deux champs de portée :

Allowed indices (index autorisés) — une liste de motifs, séparés par des virgules dans l’interface. Évaluée en premier.
Index pattern (motif d’index) — un motif unique de repli, utilisé uniquement quand Allowed indices est vide.

Au moins l’un des deux doit être renseigné. Une même connexion peut couvrir plusieurs groupes d’index en les listant dans Allowed indices (par exemple logs-*,metrics-*).

Découverte

Entièrement prise en charge. L’introspection appelle l’API cat indices d’Elasticsearch et récupère les mappings de champs de chaque index dans la portée, en aplatissant les objets imbriqués en colonnes à notation pointée (user.name, request.headers.user_agent). Elasticsearch n’a pas de clés primaires ni étrangères — la passe d’enrichissement par LLM déduit les liens entre index à partir des conventions de nommage, si vous l’activez.

Petit guide ES|QL

Les requêtes générées utilisent ES|QL. Vous n’écrivez pas ES|QL vous-même — Datarelix le génère. Pour situer :

FROM logs-*
| WHERE response.status == 500
| STATS count() BY url.path
| SORT count desc
| LIMIT 10

FROM <index-or-pattern> désigne la source.
| envoie la sortie d’une étape dans l’opérateur suivant.
KEEP sélectionne les colonnes ; WHERE filtre ; STATS agrège ; SORT trie ; LIMIT plafonne le nombre de lignes.
Les champs imbriqués sont aplatis en notation pointée (par exemple user.name).

Voir la référence ES|QL pour le langage complet.

Limites

Pas de mutations — le validateur rejette tout mot-clé de mutation, en défense en profondeur.
LOOKUP JOIN en ES|QL exige ES 8.13+ — les versions antérieures n’ont pas de JOIN ; limitez l’analyse multi-index à un seul motif FROM, ou enrichissez les données en amont.
Nombre de champs élevé (plus de 1 000 champs par index) — les limites de taille du prompt peuvent être atteintes au moment où le plan est construit. La découverte fonctionne toujours, mais vous devrez peut-être restreindre la portée des index autorisés.
Limite de lignes — plafond côté serveur de 5 000 lignes par défaut ; le validateur ajoute un LIMIT quand il manque.
Résultats partiels en cas d’échec de shard — si un shard est indisponible, ES renvoie ce qu’il peut, accompagné d’un indicateur partial=true. L’interface d’exécution affiche un badge d’avertissement ; relancez quand le cluster est rétabli.

Dépannage

Symptôme	Cause probable	Correction
`401 Unauthorized`	Clé d’API changée, expirée, ou privilèges manquants	Recréez la clé avec `read` + `view_index_metadata`.
`TLS verify failed`	Cluster auto-signé ou autorité de certification personnalisée	Collez le PEM du certificat CA dans le formulaire de connexion, ou désactivez la vérification TLS en développement.
`parsing_exception`	Erreur de syntaxe ES	QL
`Index 'foo' is not in allowlist`	La requête générée vise un index hors de Allowed indices	Ajoutez le motif d’index à la liste d’autorisation de la connexion.
Schéma vide après la découverte	ES	QL non activé ou privilège `view_index_metadata` manquant
`unknown URI [/_query]`	Le cluster est antérieur à 8.11	Mettez à niveau — le point de terminaison historique `_sql/query` n’est pas utilisé par cette intégration.
Avertissement `partial=true`	Un ou plusieurs shards indisponibles	Relancez quand la santé du cluster repasse en yellow/green.