---
title: "Connecter Databricks SQL"
description: "Connectez Datarelix à un SQL Warehouse Databricks en lecture seule, avec un PAT, OAuth M2M ou un JWT fédéré, et Unity Catalog comme prérequis."
canonical: https://docs.datarelix.ai/fr/guides/connections/databricks/
---

# Connecter Databricks SQL

Datarelix se connecte à Databricks via un service de requêtes en lecture seule. Les requêtes s'exécutent sur un **SQL Warehouse** — pas sur un cluster de calcul polyvalent.

## Prérequis

- Un espace de travail Databricks avec **Unity Catalog** activé.
- Un **SQL Warehouse** (Serverless ou Pro). Les warehouses Classic fonctionnent aussi, mais démarrent plus lentement.
- Un principal de service ou un utilisateur disposant des droits `USE CATALOG`, `USE SCHEMA` et `SELECT` sur le catalogue et le schéma ciblés.

## Trouver vos informations de connexion

Voir [Get connection details for a Databricks compute resource](https://docs.databricks.com/aws/en/integrations/compute-details) pour la procédure officielle. Dans l'interface de l'espace de travail Databricks :

1. Allez dans **SQL → SQL Warehouses** dans la barre latérale gauche.
2. Cliquez sur votre warehouse.
3. Ouvrez l'onglet **Connection details**.
4. Copiez :
   - **Server hostname** — trois formes selon le cloud :
     - AWS : `dbc-12345678-abcd.cloud.databricks.com`
     - Azure : `adb-1234567890123456.7.azuredatabricks.net`
     - GCP : `<workspace-id>.<region>.gcp.databricks.com`
   - **HTTP path** — de la forme `/sql/1.0/warehouses/abc123def456`.

Le nom d'hôte correspond au champ **Workspace host** (hôte de l'espace de travail) et le chemin au champ **HTTP path** du formulaire de connexion.

## Formulaire de connexion

```ini
Workspace host:   dbc-12345678-abcd.cloud.databricks.com
HTTP path:        /sql/1.0/warehouses/abc123def456
Catalog:          main
Allowed schema:   default
Auth mode:        one of the three below
```

## Modes d'authentification

### Jeton d'accès personnel (PAT)

La voie la plus simple. Adaptée à un usage de service, sans intervention humaine. Un PAT est un jeton à longue durée de vie rattaché à un utilisateur ou à un principal de service ; il est stocké chiffré sur la connexion.

**Configuration — créer un PAT rattaché à un principal de service**

1. Dans Databricks, allez dans **Settings → Identity and access → Service principals**.
2. Créez ou choisissez un principal de service.
3. Accordez-lui les [privilèges Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog/manage-privileges/) requis via une requête sur le SQL Warehouse :
   ```sql
   GRANT USE CATALOG ON CATALOG main TO `your-sp-app-id`;
   GRANT USE SCHEMA ON SCHEMA main.default TO `your-sp-app-id`;
   GRANT SELECT ON SCHEMA main.default TO `your-sp-app-id`;
   ```
4. [Générez un jeton d'accès personnel](https://docs.databricks.com/aws/en/dev-tools/auth/pat) pour ce principal de service : **Settings → Identity and access → Service principals → [your SP] → Generate token**.

> N'utilisez pas votre PAT personnel pour des connexions de service partagées — le jour où vous partez, la connexion casse. Rattachez-le toujours à un principal de service.

**Où trouver vos identifiants**

- PAT : **Settings → Identity and access → Service principals → [your SP] → Tokens** (ou **User settings → Developer → Access tokens** pour les jetons personnels)

**À saisir**

```ini
Workspace host:  dbc-12345678-abcd.cloud.databricks.com
HTTP path:       /sql/1.0/warehouses/abc123def456
Catalog:         main
Allowed schema:  default
Auth mode:       Personal Access Token
Token:           dapi••••••••••••••••
```

---

### OAuth M2M (principal de service)

Octroi client credentials [OAuth machine-to-machine (M2M)](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m). Préférable en production — les jetons sont de courte durée et renouvelés automatiquement. Nécessite un ID client et un secret client, stockés chiffrés sur la connexion.

**Configuration**

1. Dans Databricks, allez dans **Settings → Identity and access → Service principals**.
2. Créez un principal de service si vous n'en avez pas.
3. Accordez-lui les privilèges Unity Catalog (le même SQL `GRANT` que ci-dessus).
4. Allez dans **[your SP] → Secrets → Generate secret**. Copiez le **Client ID** (l'ID d'application du principal de service) et la **Secret value** immédiatement — elle n'est affichée qu'une seule fois.

**Où trouver vos identifiants**

| Champ | Où le trouver |
|-------|----------------|
| Client ID | **Settings → Identity and access → Service principals → [your SP]** → Application ID |
| Client secret | **[your SP] → Secrets** → la valeur affichée au moment où vous avez généré le secret |

**À saisir**

```ini
Workspace host:  dbc-12345678-abcd.cloud.databricks.com
HTTP path:       /sql/1.0/warehouses/abc123def456
Catalog:         main
Allowed schema:  default
Auth mode:       OAuth M2M
Client ID:       your-sp-application-id
Client secret:   ••••••••
```

---

### JWT fédéré (SSO)

Rattache la connexion à **l'utilisateur actuellement connecté**. La couche d'exécution émet, à partir de la session de l'utilisateur, un JWT limité à l'espace de travail et l'échange contre un jeton Databricks via la [fédération de jetons OAuth](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) de l'espace de travail. Aucun secret à longue durée de vie n'est stocké.

Nécessite :
- Un espace de travail Databricks avec la fédération OIDC configurée auprès de votre fournisseur d'identité.
- Que l'utilisateur connecté dispose de `CAN USE` sur le SQL Warehouse.

C'est le mode d'authentification par défaut pour les locataires SSO dont l'espace de travail est déjà fédéré.

**À saisir**

```ini
Workspace host:  dbc-12345678-abcd.cloud.databricks.com
HTTP path:       /sql/1.0/warehouses/abc123def456
Catalog:         main
Allowed schema:  default
Auth mode:       Federated JWT
```

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

---

## Espace de noms Unity Catalog

Databricks utilise l'espace de noms à trois niveaux d'Unity Catalog : `catalog.schema.table`.

- **Catalog** (catalogue) — niveau supérieur de l'espace de noms. La plupart des espaces de travail utilisent `main` ; les organisations plus grandes le découpent en `dev`, `staging`, `prod`, ou par domaine.
- **Schema** (schéma) — deuxième niveau, souvent appelé « database » dans l'interface Spark pour des raisons historiques. Correspond au champ **Allowed schema** (schéma autorisé) de la connexion.
- **Table** — la table ou la vue elle-même.

Pour analyser plusieurs schémas, créez une connexion par schéma.

## Sémantique de la portée

- **Catalog** (`main` par défaut) — niveau supérieur de l'espace de noms.
- **Allowed schema** (`default` par défaut) — le schéma auquel la connexion est restreinte. Datarelix bloque toute requête qui référence un schéma hors de la liste autorisée.

## Découverte

Entièrement prise en charge sur **Unity Catalog**. L'introspection lit `<catalog>.information_schema` — tables, colonnes, contraintes de table et usage des colonnes de clés. Les contraintes PK/FK sont détectées lorsqu'elles sont déclarées ; beaucoup de schémas Unity Catalog n'en déclarent pas, auquel cas la passe d'enrichissement par le modèle déduit les relations à partir des conventions de nommage des colonnes.

> **Unity Catalog est obligatoire.** L'ancien catalogue `hive_metastore` n'a pas d'`information_schema` : la découverte n'y renvoie donc rien. Pointez la connexion vers un catalogue Unity Catalog (par ex. `main`), pas vers `hive_metastore`. Migrez les tables héritées vers Unity Catalog si vous devez les analyser.

## Limites

- **Unity Catalog uniquement** — l'ancien catalogue `hive_metastore` n'est pas pris en charge pour la découverte (pas d'`information_schema`).
- **SQL Warehouse uniquement** — les clusters de calcul polyvalents (notebooks, jobs) ne sont pas pris en charge.
- **Lecture seule** — le validateur rejette les instructions d'écriture et DDL.
- **Démarrages à froid** — les warehouses Serverless reprennent en ~5 s ; les Pro en ~30 s ; les Classic en 2–5 min. La première requête après une période d'inactivité paie ce coût.
- **Limite de lignes** — plafond côté serveur de 5 000 lignes par défaut.

## Dépannage

| Symptôme | Cause probable | Solution |
|---------|--------------|-----|
| `Warehouse is not running` | Warehouse arrêté et reprise automatique désactivée | Activez la reprise automatique sur le warehouse, ou démarrez-le manuellement. |
| `403 PERMISSION_DENIED` sur `USE CATALOG` | Le principal de service n'a pas les droits Unity Catalog | Réexécutez le SQL `GRANT USE CATALOG / SCHEMA / SELECT` ci-dessus. |
| `403 INVALID_HTTP_PATH` | HTTP path incorrect | Vérifiez dans **SQL Warehouses → Connection details** ; le chemin commence par `/sql/1.0/warehouses/`. |
| `OAuth client not authorized for scope sql` | Le principal de service M2M n'a pas la portée `sql` | Réémettez le secret avec `Scopes: all-apis` (ou `sql` explicitement) à la création. |
| `Token expired` (PAT) | Durée de vie du PAT écoulée | Les PAT ont une durée limitée ; renouvelez-le via l'API d'administration Databricks ou les paramètres de jetons du principal de service. |
| La découverte renvoie 0 table | Le catalogue n'a aucune table dans le schéma autorisé | Vérifiez avec `SHOW TABLES IN <catalog>.<schema>` depuis un éditeur SQL Databricks. |