Exécuter des requêtes fédérées sur Google BigQuery

Cette page explique comment configurer Lakehouse Federation pour exécuter des requêtes fédérées sur des données BigQuery qui ne sont pas gérées par Azure Databricks. Pour en savoir plus sur lakehouse Federation, consultez Qu’est-ce que la Fédération Lakehouse ?

Pour vous connecter à votre base de données BigQuery à l’aide de Lakehouse Federation, vous devez créer les éléments suivants dans votre metastore Azure Databricks Unity Catalog (les espaces de travail créés après le 9 novembre 2023 disposent déjà d’un metastore Unity Catalog provisionné automatiquement) :

Une connexion à votre base de données BigQuery.
Un catalogue étranger qui met en miroir votre base de données BigQuery dans Unity Catalog pour que vous puissiez utiliser la syntaxe de requête et les outils de gouvernance des données Unity Catalog, afin de gérer l’accès utilisateur Azure Databricks à la base de données.

Avant de commencer

Conditions requises pour l’espace de travail :

Espace de travail activé pour Unity Catalog.

Voici les exigences de calcul à respecter :

Connectivité réseau de votre cluster Databricks Runtime ou de votre entrepôt SQL aux systèmes de base de données cibles. Consultez Recommandations de mise en réseau de la Fédération Lakehouse.
Les clusters Azure Databricks doivent utiliser Databricks Runtime 16.1 ou version ultérieure et le mode d’accès standard ou dédié (anciennement partagé et mono-utilisateur).
Les entrepôts SQL doivent être Pro ou serverless.

Autorisations requises :

Pour créer une connexion, vous devez disposer du privilège CREATE CONNECTION sur le metastore du catalogue Unity associé à l’espace de travail.
Pour créer un catalogue étranger, vous devez disposer de l’autorisation CREATE CATALOG sur le metastore et être le propriétaire de la connexion ou disposer du privilège CREATE FOREIGN CATALOG sur cette connexion.

D'autres exigences en matière d’autorisation sont spécifiées dans les sections basées sur les tâches ci-dessous.

Créer une connexion

Une connexion indique un chemin d’accès et des informations d’identification pour accéder à un système de base de données externe. Pour créer une connexion, vous pouvez utiliser l’Explorateur de catalogues ou la commande SQL CREATE CONNECTION dans un notebook Azure Databricks, ou bien dans l’éditeur de requête SQL Databricks.

Note

Vous pouvez aussi utiliser l’API REST Databricks ou l’interface CLI Databricks pour créer une connexion. Consultez POST /api/2.1/unity-catalog/connections et Commandes Unity Catalog.

Autorisations requises : administrateur du metastore ou utilisateur disposant du privilège CREATE CONNECTION.

Explorateur de catalogues

Dans votre espace de travail Azure Databricks, cliquez sur Catalogue.
En haut du volet Catalogue, cliquez sur , puis sélectionnez Créer une connexion dans le menu.
Dans la page Notions de base de la connexion de l’assistant Configurer la connexion, entrez un Nom de connexion convivial.
Sélectionnez un type de connexionGoogle BigQuery, puis cliquez sur Suivant.

Sur la page Authentification, entrez le JSON de clé de compte de service Google de votre instance BigQuery.

Il s’agit d’un objet JSON brut utilisé pour spécifier le projet BigQuery et fournir l’authentification. Vous pouvez générer cet objet JSON et le télécharger à partir de la page de détails du compte de service dans Google Cloud sous « CLÉS ». Le compte de service doit disposer d’autorisations appropriées accordées dans BigQuery, y compris Utilisateur BigQuery et Lecteur de données BigQuery. Voici un exemple.

{
  "type": "service_account",
  "project_id": "PROJECT_ID",
  "private_key_id": "KEY_ID",
  "private_key": "PRIVATE_KEY",
  "client_email": "SERVICE_ACCOUNT_EMAIL",
  "client_id": "CLIENT_ID",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL",
  "universe_domain": "googleapis.com"
}

(Facultatif) Entrez l’ID de projet pour votre instance BigQuery :

Il s’agit d’un nom pour le projet BigQuery utilisé pour la facturation pour toutes les requêtes exécutées sous cette connexion. La valeur par défaut est l’ID de projet de votre compte de service. Le compte de service doit disposer des autorisations appropriées pour ce projet dans BigQuery, y compris Utilisateur BigQuery. Un jeu de données supplémentaire utilisé pour stocker des tables temporaires par BigQuery peut être créé dans ce projet.
(Facultatif) Ajoutez un commentaire.
Cliquez sur Create connection (Créer la connexion).
Sur la pageConcepts de base du catalogue, saisissez un nom pour le catalogue étranger. Un catalogue étranger constitue un miroir d'une base de données dans un système de données externe. Cela vous permet d'interroger et de gérer l’accès aux données de cette base de données à l’aide d’Azure Databricks et d'Unity Catalog.
(Facultatif) Cliquez sur Tester la connexion pour vérifier qu’elle fonctionne.
Cliquez sur Créer un catalogue.
Dans la page Access, sélectionnez les espaces de travail dans lesquels les utilisateurs peuvent accéder au catalogue que vous avez créé. Vous pouvez sélectionner Tous les espaces de travail ont accès, ou cliquer sur Affecter aux espaces de travail, sélectionner les espaces de travail, puis cliquer sur Attribuer.
Changez le propriétaire qui pourra gérer l'accès à tous les objets du catalogue. Commencez à taper un responsable dans la zone de texte, puis cliquez sur le responsable dans les résultats affichés.
Accordez des privilèges sur le catalogue. Cliquez sur Octroyer :
1. Spécifiez les Principaux qui auront accès aux objets du catalogue. Commencez à taper un responsable dans la zone de texte, puis cliquez sur le responsable dans les résultats affichés.
2. Sélectionnez les Préréglages de privilège à accorder pour chaque principal. Tous les utilisateurs d'un compte reçoivent BROWSE par défaut.
  - Sélectionnez Lecteur de données dans le menu déroulant pour accorder des privilèges read aux les objets du catalogue.
  - Sélectionnez Éditeur de données dans le menu déroulant pour accorder read et modify privilèges sur les objets du catalogue.
  - Sélectionnez manuellement les privilèges à accorder.
3. Cliquez sur Octroyer.
Cliquez sur suivant.
Sur la page Métadonnées, indiquez des paires clé-valeur pour les balises. Pour plus d’informations, consultez Appliquer des étiquettes aux objets sécurisables du catalogue Unity.
(Facultatif) Ajoutez un commentaire.
Cliquez sur Enregistrer.

SQL

Exécutez la commande suivante dans un notebook ou dans l’éditeur de requête SQL Databricks. Remplacez <GoogleServiceAccountKeyJson> par un objet JSON brut qui spécifie le projet BigQuery et fournit l’authentification. Vous pouvez générer cet objet JSON et le télécharger à partir de la page de détails du compte de service dans Google Cloud sous « CLÉS ». Le compte de service doit disposer d’autorisations appropriées accordées dans BigQuery, notamment Utilisateur BigQuery et Visualiseur de données BigQuery. Pour obtenir un exemple d’objet JSON, consultez l’onglet Catalog Explorer sur cette page.

CREATE CONNECTION <connection-name> TYPE bigquery
OPTIONS (
  GoogleServiceAccountKeyJson '<GoogleServiceAccountKeyJson>'
);

Nous vous recommandons d’utiliser des secrets Azure Databricks au lieu de chaînes de texte en clair pour les données sensibles comme les informations d’identification. Par exemple :

CREATE CONNECTION <connection-name> TYPE bigquery
OPTIONS (
  GoogleServiceAccountKeyJson secret ('<secret-scope>','<secret-key-user>')
)

Pour plus d’informations sur la définition de secrets, consultez Gestion des secrets.

Créer un catalogue étranger

Note

Si vous utilisez l’interface utilisateur pour créer une connexion à la source de données, la création du catalogue étranger est incluse et vous pouvez ignorer cette étape.

Un catalogue étranger constitue un miroir d'une base de données dans un système de données externe. Cela vous permet d'interroger et de gérer l’accès aux données de cette base de données à l’aide d’Azure Databricks et d'Unity Catalog. Pour créer un catalogue étranger, utilisez une connexion à la source de données qui a déjà été définie.

Pour créer un catalogue étranger, vous pouvez utiliser Catalog Explorer ou CREATE FOREIGN CATALOG dans un notebook Azure Databricks ou dans l’éditeur de requête Databricks SQL. Vous pouvez aussi utiliser l’API REST Databricks ou l’interface CLI Databricks pour créer un catalogue. Consultez POST /api/2.1/unity-catalog/catalogs ou Commandes Unity Catalog.

Autorisations requises :CREATE CATALOG autorisation sur le meta store et propriété de la connexion, ou bien privilège CREATE FOREIGN CATALOG sur la connexion.

Explorateur de catalogues

Dans votre espace de travail Azure Databricks, cliquez sur Catalogue pour ouvrir l’Explorateur de catalogues.
En haut du volet Catalogue, cliquez sur l’icône Ajouter, puis, dans le menu, sélectionnez Ajouter un catalogue.

Vous pouvez également accéder à Accès rapide. Cliquez ensuite sur le bouton Catalogues, puis sur Créer un catalogue.
(Facultatif) Entrez la propriété de catalogue suivante :

Id de projet de données : nom du projet BigQuery contenant les données qui seront mappées à ce catalogue. Par défaut, l’ID du projet de facturation est défini au niveau de la connexion.
Suivez les instructions pour créer des catalogues étrangers dans Créer des catalogues.
(Facultatif) Spécifiez les options de catalogue suivantes :
- Materialization Dataset: nom de jeu de données BigQuery facultatif à utiliser pour matérialiser les résultats de la requête. Si ce n’est pas spécifié, un jeu de données de matérialisation est provisionné automatiquement si nécessaire. Pour plus d’informations, consultez Matérialisation .
- BIGNUMERIC Default Scale: valeur d’échelle facultative pour le mappage de BigQuery BIGNUMERIC à Spark DecimalType. Pour plus d’informations, consultez mappages de types de données .

SQL

Exécutez la commande SQL suivante dans un notebook ou dans l’éditeur Databricks SQL. Les éléments entre crochets sont optionnels. Remplacez les valeurs d’espace réservé.

<catalog-name> : nom du catalogue dans Azure Databricks.
<connection-name> : L'objet Connection qui indique la source de données, le chemin et les informations d’identification d’accès.
<data-project-id>: ID de projet facultatif du projet BigQuery contenant des données à mapper à ce catalogue. S’il n’est pas spécifié, l’ID de projet défini sur la connexion est utilisé, suivi de l’ID de projet du compte de service.
<dataset-name>: nom de jeu de données BigQuery facultatif à utiliser pour matérialiser les résultats de la requête. Si ce n’est pas spécifié, un jeu de données de matérialisation est provisionné automatiquement si nécessaire. Pour plus d’informations, consultez Matérialisation .
<scale>: valeur d’échelle facultative [0, 38] pour mapper BigQuery BIGNUMERIC à Spark DecimalType(38, scale). La valeur par défaut est 38. Pour plus d’informations, consultez mappages de types de données .

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
[OPTIONS (dataProjectId '<data-project-id>', materializationDataset '<dataset-name>', bigNumericDefaultScale '<scale>')];

Matérialisation

Contrairement à d’autres connecteurs de fédération, le connecteur BigQuery utilise les API Stockage BigQuery au lieu de JDBC pour améliorer les performances. Azure Databricks peut lire directement dans BigQuery depuis le stockage ou en utilisant un jeu de données matérialisé. Les lectures directes offrent de meilleures performances pour les parcours volumineux et prennent en charge le décalement de filtre et de projection. La matérialisation envoie des opérations supplémentaires (limite, agrégats, jointures, tri) vers le calcul BigQuery avant de diffuser les résultats vers Azure Databricks.

Les vues et les tables externes sont toujours matérialisées. Toutes les autres lectures utilisent un stockage direct sans matérialisation par défaut.

Envisagez d'activer la matérialisation si vous avez besoin de descentes avancées, si vous lisez de petits ensembles de résultats à partir de grands ensembles de données ou si vous lisez des données entre régions. La matérialisation entraîne des frais de calcul BigQuery supplémentaires. Pour activer la matérialisation, définissez la configuration Spark suivante :

SET spark.databricks.bigquery.enableMaterialization = true;

Par défaut, un jeu de données de matérialisation est provisionné automatiquement si nécessaire. Vous pouvez spécifier un jeu de données personnalisé à l’aide de l’option de materializationDataset catalogue lors de la création ou de la modification du catalogue externe. Cela est utile si le compte de service n’a pas les autorisations nécessaires pour créer des jeux de données ou si vous souhaitez contrôler l’emplacement de stockage des tables de matérialisation temporaires. Par exemple :

CREATE FOREIGN CATALOG my_catalog USING CONNECTION my_bq_connection
OPTIONS (materializationDataset 'my_materialization_dataset');

Pour mettre à jour un catalogue existant, exécutez :

ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Pushdowns pris en charge

Les pushdowns suivants sont pris en charge sans matérialisation :

Filtres
Prévisions

Les pushdowns supplémentaires suivants sont pris en charge lorsque la matérialisation est activée :

Limite
Fonctions (prise en charge partielle, expressions de filtre uniquement : fonctions de chaîne, fonctions mathématiques, date, heure et fonctions d’horodatage, et autres fonctions diverses telles que Alias, Cast, SortOrder)
Agrégats
Tri, lorsque l’utilisation est limitée
Jointures (Databricks Runtime 16.1 ou version ultérieure)

Les pushdowns suivants ne sont pas prises en charge :

Fonctions de fenêtre

Mappages de types de données

Le tableau ci-dessous illustre le mappage de type de données BigQuery vers Spark.

Type de BigQuery	Type Spark
BIGNUMERIC, NUMERIC	DecimalType*
INT64	LongType
FLOAT64	DoubleType
ARRAY, GEOGRAPHY, INTERVAL, JSON, STRING, STRUCT	VarcharType
BYTES	BinaryType
BOOL	Type Booléen
DATE (jj/mm/aaaa)	DateType
DATETIME, TIME, TIMESTAMP	TimestampType/TimestampNTZType

* BigQuery BIGNUMERIC a une précision allant jusqu’à 76 chiffres, qui dépasse la précision maximale DecimalType de Spark de 38. Par défaut, BIGNUMERIC mappe à DecimalType(38, 38). Pour configurer l’échelle, utilisez l’option bigNumericDefaultScale catalog. Les valeurs autorisées sont [0, 38]. Par exemple, bigNumericDefaultScale = '10' mappe BIGNUMERIC à DecimalType(38, 10). BigQuery NUMERIC correspond à sa précision et à son échelle déclarées.

Lorsque vous lisez à partir de BigQuery, le type BigQuery Timestamp est mappé au type Spark TimestampType si preferTimestampNTZ = false (valeur par défaut). BigQuery Timestamp est mappé à TimestampNTZType si preferTimestampNTZ = true.

Résolution des problèmes

`Error creating destination table using the following query [<query>]`

Cause courante : le compte de service utilisé par la connexion n’a pas le rôle Utilisateur BigQuery .

Résolution :

Accordez le rôle Utilisateur BigQuery au compte de service utilisé par la connexion. Ce rôle est nécessaire pour créer le jeu de données de matérialisation qui stocke temporairement les résultats de la requête.
Réexécutez la requête.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-04-04

Partager via

Exécuter des requêtes fédérées sur Google BigQuery

Avant de commencer

Créer une connexion

Explorateur de catalogues

SQL

Créer un catalogue étranger

Explorateur de catalogues

SQL

Matérialisation

Pushdowns pris en charge

Mappages de types de données

Résolution des problèmes

Error creating destination table using the following query [<query>]

Commentaires

Ressources supplémentaires

`Error creating destination table using the following query [<query>]`