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 pour la procédure officielle. Dans l’interface de l’espace de travail Databricks :

Allez dans SQL → SQL Warehouses dans la barre latérale gauche.
Cliquez sur votre warehouse.
Ouvrez l’onglet Connection details.
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

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

Dans Databricks, allez dans Settings → Identity and access → Service principals.
Créez ou choisissez un principal de service.

Accordez-lui les privilèges Unity Catalog requis via une requête sur le SQL Warehouse :

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

Générez un jeton d’accès personnel 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

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

Dans Databricks, allez dans Settings → Identity and access → Service principals.
Créez un principal de service si vous n’en avez pas.
Accordez-lui les privilèges Unity Catalog (le même SQL GRANT que ci-dessus).
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

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

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.