---
title: "Connecter Elasticsearch (ES|QL)"
description: "Connectez Datarelix à Elasticsearch 8.11+ via ES|QL : clé d’API ou authentification basique, portée des index, certificats TLS et limites du langage."
canonical: https://docs.datarelix.ai/fr/guides/connections/elasticsearch/
---

# 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](https://www.elastic.co/docs/reference/query-languages/esql) — 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`](https://www.elastic.co/docs/reference/elasticsearch/security-privileges) 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**

1. Dans Kibana, [créez une clé d'API](https://www.elastic.co/docs/deploy-manage/api-keys/elasticsearch-api-keys) (**Stack Management → Security → API Keys → Create API key**).
2. Donnez-lui un nom (par exemple `datarelix-prod`).
3. Sous **Restrict privileges**, ajoutez des privilèges d'index : sélectionnez vos index cibles, puis ajoutez les privilèges `read` et `view_index_metadata`.
4. 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**

```bash
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**

```ini
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 :

```bash
# 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**

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

---

## Formulaire de connexion

```ini
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 :

```text
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](https://www.elastic.co/docs/reference/query-languages/esql) 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 | [Contactez-nous](https://datarelix.ai/fr/contact/) avec la question posée et la requête générée. |
| `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 | Vérifiez ES 8.11+ et les privilèges de la clé d'API. |
| `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. |