Créer des tables externes BigLake pour Delta Lake

BigLake vous permet d'accéder aux tables Delta Lake avec un contrôle des accès plus précis. Delta Lake est un format de stockage de données tabulaire Open Source développé par Databricks et compatible avec les tables de données à l'échelle du pétaoctet.

BigQuery est compatible avec les fonctionnalités de tables Delta Lake suivantes :

Délégation d'accès : interrogez des données structurées dans des datastores externes avec la délégation d'accès. La délégation d'accès dissocie l'accès à la table Delta Lake de l'accès au datastore sous-jacent.
Contrôle précis des accès appliquez une sécurité précise au niveau de la table, y compris au niveau des lignes et au niveau des colonnes. Pour les tables Delta Lake basées sur Cloud Storage, vous pouvez également utiliser le masquage des données dynamiques.
Évolution du schéma : les modifications de schéma dans les tables Delta Lake sont détectées automatiquement. Les modifications apportées au schéma sont reflétées dans la table BigQuery.

Les tables Delta Lake sont également compatibles avec toutes les fonctionnalités BigLake lorsque vous les configurez en tant que tables BigLake.

Avant de commencer

Dans la Google Cloud console, sur la page de sélection du projet, sélectionnez ou créez un Google Cloud projet.
Rôles requis pour sélectionner ou créer un projet
- Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
- Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.
Remarque : Si vous ne prévoyez pas de conserver les ressources que vous créez dans cette procédure, créez un projet au lieu d'en sélectionner un existant. Une fois ces étapes terminées, vous pouvez supprimer le projet, ce qui supprimera toutes les ressources associées.

Accéder au sélecteur de projet
Vérifiez que la facturation est activée pour votre Google Cloud projet.
Activez les API BigQuery Connection et BigQuery Reservation.
Rôles requis pour activer les API
Pour activer les API, vous devez disposer du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer les API
Dans la Google Cloud console, activez Cloud Shell.

Activer Cloud Shell
Assurez-vous de disposer d'un ensemble de données BigQuery dataset.
Assurez-vous que votre version du SDK Google Cloud est 366.0.0 ou ultérieure :
```
gcloud version
```
Si nécessaire, mettez à jour le SDK Google Cloud.
Créez une connexion de ressource Cloud basée sur votre source de données externe, puis accordez-lui l'accès à Cloud Storage. Si vous ne disposez pas des autorisations nécessaires pour créer une connexion, demandez à votre administrateur BigQuery de créer une connexion et de la partager avec vous.

Rôles requis

Les autorisations suivantes sont requises pour créer une table Delta Lake :

bigquery.tables.create
bigquery.connections.delegate

Le rôle IAM prédéfini Administrateur BigQuery (roles/bigquery.admin) inclut ces autorisations.

Si vous n'êtes pas un compte principal dans ce rôle, demandez à votre administrateur de vous accorder ces autorisations ou de créer la table Delta Lake pour vous.

En outre, pour permettre aux utilisateurs BigQuery d'interroger la table, le compte de service associé à la connexion doit disposer de l'autorisation et de l'accès suivants :

Rôle de lecteur BigQuery (roles/bigquery.viewer).
Rôle Utilisateur de connexion BigQuery (roles/bigquery.connectionUser)
Accès au bucket Cloud Storage contenant ces données

Pour en savoir plus sur les rôles et les autorisations Identity and Access Management dans BigQuery, consultez la page Rôles et autorisations prédéfinis.

Créer des tables avec Delta Lake

Pour créer des tables Delta Lake, procédez comme suit.

SQL

Utilisez l'instruction CREATE EXTERNAL TABLE pour créer la table Delta Lake :

CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.DELTALAKE_TABLE_NAME`
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  format ="DELTA_LAKE",
  uris=['DELTA_TABLE_GCS_BASE_PATH']);

Remplacez les valeurs suivantes :

PROJECT_ID : ID du projet dans lequel vous souhaitez créer la table Delta Lake
DATASET : ensemble de données BigQuery contenant la table Delta Lake
DELTALAKE_TABLE_NAME : nom de votre table Delta Lake
REGION : région contenant la connexion permettant de créer la table Delta Lake, par exemple us
CONNECTION_ID : ID de connexion, par exemple myconnection.

Lorsque vous affichez les détails de la connexion dans la Google Cloud console, l'ID de connexion est la valeur de la dernière section de l'ID de connexion complet affiché dans ID de connexion, par exemple projects/myproject/locations/connection_location/connections/myconnection.
DELTA_TABLE_GCS_BASE_PATH : préfixe de la table Delta Lake

bq

Dans un environnement de ligne de commande, utilisez la commande bq mk pour créer la table Delta Lake :

bq mk --table --external_table_definition=DEFINITION_FILE PROJECT_ID:DATASET.DELTALAKE_TABLE_NAME

Remplacez les valeurs suivantes :

DEFINITION_FILE : chemin d'accès au fichier de définition de table.
PROJECT_ID : ID du projet dans lequel vous souhaitez créer la table Delta Lake
DATASET : ensemble de données BigQuery contenant la table Delta Lake
DELTALAKE_TABLE_NAME : nom de votre table Delta Lake

REST

Utilisez l'API BigQuery pour créer une table Delta Lake en appelant la méthode API tables.insert :

REQUEST='{
  "autodetect": true,
  "externalDataConfiguration": {
  "sourceFormat": "DELTA_LAKE",
  "connectionId": "PROJECT_ID.REGION.CONNECTION_ID",
  "sourceUris": [
    "DELTA_TABLE_GCS_BASE_PATH"
  ],
 },
"tableReference": {
"tableId": "DELTALAKE_TABLE_NAME"
}
}'

echo $REQUEST | curl -X POST -d @- -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables?autodetect_schema=true

Remplacez les valeurs suivantes :

PROJECT_ID : ID du projet dans lequel vous souhaitez créer la table Delta Lake
REGION : région contenant la connexion permettant de créer la table Delta Lake, par exemple us
CONNECTION_ID : ID de connexion, par exemple myconnection.

Lorsque vous affichez les détails de la connexion dans la Google Cloud console, l'ID de connexion est la valeur de la dernière section de l'ID de connexion complet affiché dans ID de connexion, par exemple projects/myproject/locations/connection_location/connections/myconnection.
DELTA_TABLE_GCS_BASE_PATH : préfixe de la table Delta Lake
DELTALAKE_TABLE_NAME : nom de votre table Delta Lake
DATASET : ensemble de données BigQuery contenant la table Delta Lake

Lorsque vous créez des tables Delta Lake, le préfixe Delta Lake est utilisé comme URI de la table. Par exemple, pour une table qui contient des journaux dans le bucket gs://bucket/warehouse/basictable/_delta_log, l'URI de la table est gs://bucket/warehouse/basictable. Lorsque vous exécutez des requêtes sur la table Delta Lake, BigQuery lit les données associées à ce préfixe pour identifier la version actuelle de la table, puis calcule les métadonnées et les fichiers de la table.

Bien que vous puissiez créer des tables externes Delta Lake sans connexion, cela n'est pas recommandé pour les raisons suivantes :

Les utilisateurs peuvent rencontrer des erreurs ACCESS_DENIED lorsqu'ils tentent d'accéder à des fichiers dans Cloud Storage.
Les fonctionnalités telles que le contrôle précis des accès ne sont disponibles que dans les tables BigLake Delta Lake.

Mettre à jour des tables Delta Lake

Pour mettre à jour (actualiser) le schéma des tables Delta Lake, procédez comme suit.

bq

Dans un environnement de ligne de commande, utilisez la commande bq update pour mettre à jour (actualiser) le schéma de la table Delta Lake :

bq update --autodetect_schema PROJECT_ID:DATASET.DELTALAKE_TABLE_NAME

Remplacez les valeurs suivantes :

PROJECT_ID : ID du projet dans lequel vous souhaitez créer la table Delta Lake
DATASET : ensemble de données BigQuery contenant la table Delta Lake
DELTALAKE_TABLE_NAME : nom de votre table Delta Lake

REST

Utilisez l'API BigQuery pour mettre à jour une table Delta Lake en appelant la méthode API tables.patch :

REQUEST='{
  "externalDataConfiguration": {
    "sourceFormat": "DELTA_LAKE",
    "sourceUris": [
      "DELTA_TABLE_GCS_BASE_PATH"
    ],
    "connectionId": "PROJECT_ID.REGION.CONNECTION_ID",
    "autodetect": true
  }
}'
echo $REQUEST |curl -X PATCH -d @- -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/DELTALAKE_TABLE_NAME?autodetect_schema=true

Remplacez les valeurs suivantes :

DELTA_TABLE_GCS_BASE_PATH : préfixe de la table Delta Lake
PROJECT_ID : ID du projet dans lequel vous souhaitez créer la table Delta Lake
REGION : région contenant la connexion permettant de créer la table Delta Lake, par exemple us
CONNECTION_ID : ID de connexion, par exemple myconnection.

Lorsque vous affichez les détails de la connexion dans la Google Cloud console, l'ID de connexion est la valeur de la dernière section de l'ID de connexion complet affiché dans ID de connexion, par exemple projects/myproject/locations/connection_location/connections/myconnection.
DELTALAKE_TABLE_NAME : nom de votre table Delta Lake
DATASET : ensemble de données BigQuery contenant la table Delta Lake

Interroger des tables Delta Lake

Après avoir créé une table BigLake Delta Lake, vous pouvez l'interroger à l'aide d'une syntaxe GoogleSQL, comme vous le feriez pour une table BigQuery standard. Exemple :

SELECT field1, field2 FROM mydataset.my_cloud_storage_table;

Pour en savoir plus, consultez la section Interroger des données Cloud Storage dans des tables BigLake.

Une connexion externe associée à un compte de service permet de se connecter au data store. Comme le compte de service récupère les données du data store, les utilisateurs n'ont besoin que d'accéder à la table Delta Lake.

Mappage de données

BigQuery convertit les types de données Delta Lake en types de données BigQuery, comme indiqué dans le tableau suivant :

Type Delta Lake	Type BigQuery
`boolean`	`BOOL`
`byte`	`INT64`
`int`	`INT64`
`long`	`INT64`
`float`	`FLOAT64`
`double`	`FLOAT64`
`Decimal(P/S)`	`NUMERIC` ou `BIG_NUMERIC` selon la précision
`date`	`DATE`
`time`	`TIME`
`timestamp (not partition column)`	`TIMESTAMP`
`timestamp (partition column)`	`DATETIME`
`string`	`STRING`
`binary`	`BYTES`
`array<Type>`	`ARRAY<Type>`
`struct`	`STRUCT`
`map<KeyType, ValueType>`	`ARRAY<Struct<key KeyType, value ValueType>>`

Limites

Les tables Delta Lake présentent des limites de table BigLake , ainsi que les limites suivantes :

Compatibilité avec la version 3 du lecteur Delta Lake avec des vecteurs de suppression de chemin relatif et un mappage de colonnes.
Non-compatibilité avec les points de contrôle Delta Lake V2.
Vous devez répertorier la version du lecteur dans le fichier d'entrée de la dernière entrée de journal. Par exemple, les nouvelles tables doivent inclure 00000..0.json.
Les opérations de capture de données modifiées (CDC, Change Data Capture) ne sont pas acceptées. Toutes les opérations CDC existantes sont ignorées.
Le schéma est détecté automatiquement. Il n'est pas possible de modifier le schéma à l'aide de BigQuery.
Les noms de colonne de table doivent respecter les restrictions sur les noms de colonnes de BigQuery.
Les vues matérialisées ne sont pas acceptées.
L'API Read n'est pas compatible avec Delta Lake.
Le type de données timestamp_ntz n'est pas compatible avec les tables BigLake Delta Lake.

Dépannage

Cette section fournit de l'aide concernant les tables BigLake Delta Lake. Pour obtenir de l'aide plus générale sur la résolution des problèmes liés aux requêtes BigQuery, consultez la page Résoudre les problèmes liés aux requêtes.

Délai d'expiration des requêtes et erreurs de ressources

Consultez le répertoire des journaux (gs://bucket/warehouse/basictable/_delta_log) de la table Delta Lake et recherchez les fichiers JSON dont le numéro de version est supérieur à celui du point de contrôle précédent checkpoint. Vous pouvez obtenir le numéro de version en listant le répertoire ou en inspectant le fichier _delta_log/_last_checkpoint. Les fichiers JSON de plus de 10 Mio peuvent ralentir l'expansion de la table, ce qui peut entraîner des problèmes de délai d'expiration et de ressources. Pour résoudre ce problème, utilisez la commande suivante afin de créer un point de contrôle pour que les requêtes ignorent la lecture des fichiers JSON :

  spark.sql("ALTER TABLE delta.`gs://bucket/mydeltatabledir` SET TBLPROPERTIES ('delta.checkpointInterval' = '1')");

Les utilisateurs peuvent ensuite utiliser la même commande pour réinitialiser l'intervalle de point de contrôle sur la valeur par défaut de 10 ou sur une valeur qui évite d'avoir plus de 50 Mo de fichiers JSON entre les points de contrôle.

Nom de colonne non valide

Assurez-vous que le mappage de colonnes est activé pour la table Delta Lake. Le mappage de colonnes est compatible avec la version 2 ou ultérieure du lecteur. Pour la version 1 du lecteur, définissez "delta.columnMapping.mode" sur "name" à l'aide de la commande suivante :

spark.sql("ALTER TABLE delta.`gs://bucket/mydeltatabledir` SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name', 'delta.minReaderVersion' = '3', 'delta.minWriterVersion' = '7')");

Si le nom de colonne non valide respecte les restrictions sur les noms de colonnes flexibles, contactez l'assistance client Cloud ou biglake-help@google.com.

Erreurs de type accès refusé

Pour diagnostiquer les problèmes liés aux tables BigLake Delta Lake, vérifiez les points suivants :

Assurez-vous d'utiliser des tables BigLake Delta Lake (avec une connexion).
Les utilisateurs disposent des autorisations requises.

Performances

Pour améliorer les performances des requêtes, procédez comme suit :

Utilisez les utilitaires Delta Lake pour compacter les fichiers de données sous-jacents et supprimer les fichiers redondants, tels que les données et les métadonnées.
Assurez-vous que delta.checkpoint.writeStatsAsStruct est défini sur true.
Assurez-vous que les variables fréquemment utilisées dans les clauses de prédicat se trouvent dans les colonnes de partition.

Les ensembles de données volumineux (plus de 100 To) peuvent bénéficier de configurations et de fonctionnalités supplémentaires. Si les étapes précédentes ne résolvent pas vos problèmes, envisagez de contacter l'assistance client ou biglake-help@google.com, en particulier pour les ensembles de données de plus de 100 To.