Aller au contenu principal
Dernière mise à jour le

Exécutez des query 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 les données BigQuery qui ne sont pas gérées par Databricks. Pour en savoir plus sur Lakehouse Federation, consultez Connecter aux bases de données et catalogues externes

Pour vous connecter à votre base de données BigQuery à l'aide de Lakehouse Federation, vous devez créer ce qui suit dans votre métastore Databricks Unity Catalog (les Workspaces créés après le 8 novembre 2023 disposent déjà d'un métastore Unity Catalog provisionné automatiquement) :

  • Une connexion à votre base de données BigQuery.
  • Un *catalogue étranger* qui reflète votre base de données BigQuery dans Unity Catalog afin que vous puissiez utiliser la syntaxe de query et les outils de gouvernance des données d'Unity Catalog pour gérer l'accès des utilisateurs Databricks à la base de données.

Avant de commencer​

Pour exécuter des queries fédérées sur BigQuery, créez une connexion à BigQuery et un catalogue étranger qui reflète votre base de données BigQuery. Ensuite, vous pouvez interroger et gérer les données BigQuery à l'aide de Databricks et d'Unity Catalog. Les exigences d'autorisation supplémentaires sont spécifiées dans chaque section basée sur les tâches qui suit.

Exigences du Workspace :

  • Workspace activé pour Unity Catalog.

Compute requis :

  • Connectivité réseau de votre cluster Databricks Runtime ou de votre SQL Warehouse aux systèmes de base de données cibles. Consultez les recommandations de mise en réseau pour Lakehouse Federation.
  • Les clusters Databricks doivent utiliser Databricks Runtime 16.1 ou versions ultérieures et le mode d'accès standard ou dédié (anciennement partagé et utilisateur unique).
  • Les SQL Warehouse doivent être Pro ou Serverless.

Exigences en matière d'autorisations :

  • Pour créer une connexion, vous devez disposer du privilège CREATE CONNECTION sur le métastore Unity Catalog rattaché au workspace.
  • Pour créer un catalogue externe, 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 la connexion.

Créer une connexion​

Une connexion spécifie un chemin d'accès et des identifiants pour accéder à un système de base de données externe. Pour créer une connexion, vous pouvez utiliser Catalog Explorer ou la commande SQL CREATE CONNECTION dans un Notebook Databricks ou l'éditeur de query Databricks SQL.

remarque

Vous pouvez également utiliser l'API REST Databricks ou la CLI Databricks pour créer une connexion. Voir POST /api/2.1/unity-catalog/connections et les commandes Unity Catalog.

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

  1. Dans votre workspace Databricks, cliquez sur Icône de données. Catalogue .

  2. En haut du volet **Catalogue**, cliquez sur Icône Ajouter ou plus l'icône **Ajouter** et sélectionnez **Créer une connexion** dans le menu.

  3. Sur la page **Principes de base de la connexion** de l’assistant **Configurer la connexion**, saisissez un **Nom de connexion** convivial.

  4. Sélectionnez un type de connexion Google BigQuery , puis cliquez sur Suivant .

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

    Il s'agit d'un objet JSON brut qui est utilisé pour spécifier le projet BigQuery et fournir l'authentification. Vous pouvez générer cet objet JSON et le download depuis la page de détails du compte de service dans Google Cloud sous 'KEYS'. Le compte de service doit disposer des autorisations appropriées accordées dans BigQuery, y compris **BigQuery User** et **BigQuery Data Viewer**. Voici un exemple.

    JSON
    {
      "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://oauth2.googleapis.com/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"
    }
remarque

Google définit les valeurs d'URL dans le fichier JSON du compte de service, et celles-ci peuvent varier selon le compte. Utilisez-les exactement tels qu'ils apparaissent dans votre fichier JSON download. Si vous configurez des règles de proxy réseau pour que Databricks atteigne les APIs Google, autorisez à la fois https://accounts.google.com et https://oauth2.googleapis.com.

  1. (Facultatif) Saisissez l' ID de projet de votre instance BigQuery :

    Il s'agit d'un nom pour le projet BigQuery utilisé pour la facturation de toutes les queries exécutées sous cette connexion. Default to the project ID of your service account. Le compte de service doit disposer des autorisations appropriées pour ce projet dans BigQuery, y compris BigQuery User . Un dataset supplémentaire utilisé pour stocker des tables temporaires par BigQuery pourrait être créé dans ce projet.

  2. Ajouter un commentaire (facultatif).

  3. Cliquez sur Créer une connexion .

  4. Sur la page **Bases du catalogue**, veuillez saisir un nom pour le catalogue étranger. Un catalogue étranger reflète une base de données dans un système de données externe afin que vous puissiez query et gérer l'accès aux données de cette base de données à l'aide de Databricks et de Unity Catalog.

  5. (Facultatif) Cliquez sur **Tester la connexion** pour confirmer que cela fonctionne.

  6. Cliquez sur **Créer un catalogue**.

  7. Sur la page Accès , sélectionnez les workspaces dans lesquels les utilisateurs peuvent accéder au catalogue que vous avez créé. Vous pouvez sélectionner Tous les workspaces ont accès , ou cliquer sur Attribuer aux workspaces , sélectionner les workspaces, puis cliquer sur Attribuer .

  8. Modifiez le propriétaire qui pourra gérer l'accès à tous les objets du catalogue. start à taper un principal dans la zone de texte, puis cliquez sur le principal dans les résultats renvoyés.

  9. Accordez les **Privilèges** sur le catalogue. Cliquez sur Accorder :

    1. Spécifiez les **principals** qui auront accès aux objets dans le catalogue. start à taper un principal dans la zone de texte, puis cliquez sur le principal dans les résultats renvoyés.

    2. Sélectionnez les **Préréglages de privilèges** à accorder à chaque principal. Tous les utilisateurs du compte se voient accorder BROWSE par default.

      • Sélectionnez Data Reader dans le menu déroulant pour accorder read privilèges sur les objets du catalogue.
      • Sélectionnez **Data Editor** dans le menu déroulant pour accorder read les modify privilèges et sur les objets du catalogue.
      • Sélectionnez manuellement les privilèges à accorder.

    3. Cliquez sur Accorder .

  10. Cliquez sur Suivant .

  11. Sur la page Métadonnées , spécifiez les paires clé-valeur de balises. Pour plus d'informations, consultez Appliquer des balises aux objets sécurisables d'Unity Catalog.

  12. Ajouter un commentaire (facultatif).

  13. Cliquez sur Enregistrer .

Créer un catalogue étranger​

remarque

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

Un catalogue étranger reflète une base de données dans un système de données externe afin que vous puissiez query et gérer l'accès aux données dans cette base de données à l'aide de 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 externe, vous pouvez utiliser l'Explorateur de catalogue ou CREATE FOREIGN CATALOG dans un Notebook Databricks ou l'éditeur de query Databricks SQL. Vous pouvez également utiliser l'API REST Databricks ou la CLI Databricks pour créer un catalogue. Voir POST /api/2.1/unity-catalog/catalogs ou les commandes Unity Catalog.

Autorisations requises : autorisation CREATE CATALOG sur le metastore et soit la propriété de la connexion, soit le privilège CREATE FOREIGN CATALOG sur la connexion.

  1. Dans votre Workspace Databricks, cliquez sur Icône de données. **Catalogue** pour ouvrir l’Explorateur de catalogues.

  2. En haut du volet Catalogue , cliquez sur l'icône Icône Ajouter ou plus Ajouter et sélectionnez Ajouter un catalogue dans le menu.

    Autrement, depuis la page Quick access , cliquez sur le bouton Catalogs , puis cliquez sur le bouton Create catalog .

  3. (Facultatif) Veuillez saisir 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. default, l'ID du projet de facturation est défini au niveau de la connexion.

  4. Suivez les instructions pour créer des catalogues étrangers dans Créer des catalogues.

  5. (Facultatif) Spécifiez les options de catalogue suivantes :

    • Materialization Dataset: Nom facultatif de l'ensemble de données BigQuery à utiliser pour matérialiser les résultats des requêtes. S'il n'est pas spécifié, un ensemble de données de matérialisation est automatiquement provisionné selon les besoins. Consultez Matérialisation pour plus d'informations.
    • BIGNUMERIC Default Scale: Une valeur d'échelle facultative pour mapper BigQuery BIGNUMERIC à Spark DecimalType. Consultez Mappages des types de données pour plus d'informations.

Matérialisation​

Contrairement aux autres connecteurs de fédération, le connecteur BigQuery utilise l'API BigQuery Storage au lieu de JDBC pour des performances améliorées. Databricks peut lire à partir de BigQuery directement depuis le stockage ou en utilisant un dataset matérialisé. Les lectures directes offrent de meilleures performances pour les analyses volumineuses et prennent en charge les descentes de filtre et de projection. La matérialisation transfère des opérations supplémentaires (limite, agrégats, jointures, tri) vers le compute BigQuery avant de diffuser les résultats en streaming vers Databricks.

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

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

SQL
SET spark.databricks.bigquery.enableMaterialization = true;
remarque

Vous ne pouvez définir spark.databricks.bigquery.enableMaterialization que sur un cluster éligible. Voir Avant de commencer pour les exigences de compute. L'activation de la matérialisation n'est pas prise en charge sur les SQL Warehouse (Pro ou Serverless).

Par default, un jeu de données de matérialisation est auto-provisionné si nécessaire. Vous pouvez spécifier un ensemble de données personnalisé à l'aide de l'option de catalogue materializationDataset lors de la création ou de la modification du catalogue étranger. C'est utile si le compte de service n'a pas les autorisations de créer des ensembles de données ou si vous souhaitez contrôler où les tables de matérialisation temporaires sont stockées. Par exemple :

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

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

SQL
ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Lire les tables externes BigQuery​

Vous pouvez interroger les tables externes BigQuery, y compris les tables BigLake et celles sauvegardées dans le stockage cloud, directement depuis votre workflow. Ces tables sont automatiquement matérialisées avant l'exécution de la query, ce qui permet un accès complet à leur contenu sans configuration supplémentaire.

Tables externes prises en charge​

Les tables externes BigLake et de stockage cloud sont prises en charge.

  • Les tables BigLake font référence aux données stockées dans le stockage cloud et incluent un contrôle d'accès granulaire géré via BigQuery.
  • Les tables externes du stockage cloud référencent les fichiers directement à l’aide d’URI.

Lorsque vous interrogez ces tables, le système matérialise les données afin que votre requête s'exécute sur le stockage BigQuery intégré pour une prise en charge complète des fonctionnalités SQL et des performances optimales.

Pour plus d'informations, consultez la documentation BigQuery sur les tables BigLake et les tables externes de stockage cloud.

Pushdowns pris en charge​

La prise en charge du pushdown dépend de l’activation de la matérialisation. Certaines opérations sont automatiquement transmises à BigQuery compute, tandis que d'autres nécessitent une matérialisation.

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

  • Filtres, transmis en tant que restrictions de lignes BigQuery Storage API (prédicats simples uniquement — comparaisons colonne-à-littéral, IN, IS NULL, LIKE et combinaisons AND ou OR de celles-ci). Les filtres qui font référence aux opérateurs ou fonctions listés ci-dessous nécessitent une matérialisation.
  • Projections

Les optimisations pushdown supplémentaires suivantes sont prises en charge avec la matérialisation activée. Avec la matérialisation, les filtres sont compilés en SQL au lieu des restrictions de lignes de l'API de stockage BigQuery, de sorte qu'ils peuvent contenir en plus les opérateurs et fonctions suivants :

  • Limite
  • Offset, lorsqu'il est utilisé avec une limite
  • Agrégats
  • Tri, lorsqu'il est utilisé avec une limite
  • Jointures (Databricks Runtime 16.1 ou version ultérieure)
  • Opérateurs de comparaison, booléens, bit à bit et arithmétiques (les opérateurs arithmétiques ne sont transférés que lorsque le mode ANSI est activé)
  • Fonctions mathématiques (ABS, FLOOR) — prise en charge partielle, expressions de filtre uniquement
  • Fonctions de chaîne (CONCAT, UPPER, LOWER, LENGTH, TRIM, LTRIM, RTRIM) — prise en charge partielle, expressions de filtre uniquement
  • Contains, Startswith, Endswith
  • Fonctions de date, d'heure et de Timestamp (DATE_TRUNC et EXTRACT pour l'année, le trimestre, le mois, le jour, l'heure et la minute) — support partiel, expressions de filtre uniquement
  • Fonctions diverses (COALESCE, Cast, CASE WHEN, IF et accès aux éléments de tableau) — prise en charge partielle, expressions de filtre uniquement

Les pushdowns suivants ne sont pas pris en charge :

  • Fonctions de fenêtre

Mappages des types de données​

Le tableau suivant présente le mappage des types de données de BigQuery à Spark.

Type BigQuery

Type Spark

BIGNUMERIC, NUMERIC

DecimalType*

INT64

LongType

FLOAT64

DoubleType

ARRAY, GEOGRAPHY, INTERVAL, JSON, STRING, STRUCT

VarcharType

BYTES

BinaryType

BOOL

BooleanType

DATE

DateType

DATETIME

TimestampNTZType, à l'exception de StringType dans Databricks Runtime 16.4 à 17.x**

TIME, TIMESTAMP

TimestampType/TimestampNTZType

Tout type avec le mode REPEATED

ArrayType du type Spark correspondant***

Type BigQuery

Type Spark

BIGNUMERIC, NUMERIC

DecimalType*

INT64

LongType

FLOAT64

DoubleType

ARRAY, GEOGRAPHY, INTERVAL, JSON, STRING, STRUCT

VarcharType

BYTES

BinaryType

BOOL

BooleanType

DATE

DateType

DATETIME

TimestampNTZType, à l'exception de StringType dans Databricks Runtime 16.4 à 17.x**

TIME, TIMESTAMP

TimestampType/TimestampNTZType

Tout type avec le mode REPEATED

ArrayType du type Spark correspondant***

* BigQuery BIGNUMERIC a une précision allant jusqu’à 76 chiffres, ce qui dépasse la précision maximale de Spark DecimalType de 38. Par default, BIGNUMERIC correspond à DecimalType(38, 38). Pour configurer l’échelle, utilisez l’option de catalogue bigNumericDefaultScale. 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.

** Le connecteur a commencé à utiliser l'API BigQuery Storage dans Databricks Runtime 16.4. De Databricks Runtime 16.4 à 17.x, l'API Storage a mappé BigQuery DATETIME à Spark StringType au lieu de TimestampNTZType. Databricks Runtime 18.0 restaure le mappage TimestampNTZType.

*** Dans BigQuery, une colonne avec le mode REPEATED correspond à un Spark ArrayType contenant le type Spark correspondant. Par exemple, une colonne BigQuery REPEATED STRING correspond à ArrayType(VarcharType), et une colonne BigQuery REPEATED INT64 correspond à ArrayType(LongType).

Lorsque vous lisez depuis BigQuery, BigQuery Timestamp est mappé à Spark TimestampType si preferTimestampNTZ = false (default). BigQuery Timestamp est mappé à TimestampNTZType si preferTimestampNTZ = true.

Dépannage​

La section suivante décrit une erreur courante et sa résolution lors de l'utilisation du connecteur BigQuery.

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

Cause fréquente : le compte de service utilisé par la connexion ne possède pas le rôle Utilisateur BigQuery .

Résolution :

  1. Accordez le rôle d'**utilisateur BigQuery** au compte de service utilisé par la connexion. Ce rôle est requis pour créer le dataset de matérialisation qui stocke temporairement les résultats de query.
  2. Réexécutez la query.
Sur cette page