Créer des tables externes Apache Iceberg

Les tables externes Apache Iceberg vous permettent d'accéder aux tables Apache Iceberg avec un contrôle des accès plus précis dans un format en lecture seule. Ces tables ne sont plus recommandées pour la plupart des cas d'utilisation. Consultez plutôt Alternatives recommandées.

Iceberg est un format de table Open Source compatible avec les tables de données à l'échelle du pétaoctet. La spécification ouverte Iceberg vous permet d'exécuter plusieurs moteurs de requête sur une seule copie de données stockées dans un store d'objets. Les tables externes Apache Iceberg (ci-après appelées tables externes Iceberg) sont compatibles avec Iceberg version 2, y compris la fusion à la lecture. La prise en charge d'Iceberg version 3, y compris les vecteurs de suppression binaires, est disponible en preview. Pour envoyer des commentaires ou poser des questions sur cette fonctionnalité en preview, contactez biglake-help@google.com.

En tant qu'administrateur BigQuery, vous pouvez appliquer le contrôle des accès au niveau des lignes et des colonnes, y compris le masquage des données sur les tables. Pour en savoir plus sur la configuration du contrôle des accès au niveau de la table, consultez la page Configurer des stratégies de contrôle d'accès. Les stratégies d'accès aux tables sont également appliquées lorsque vous utilisez l'API BigQuery Storage en tant que source de données pour la table dans Managed Service pour Apache Spark et Spark sans serveur.

Selon l'emplacement de stockage de vos données, nous vous recommandons les alternatives suivantes pour accéder aux tables Iceberg dont les métadonnées ne sont pas gérées parGoogle Cloud :

  • Données Cloud Storage ou Amazon Simple Storage Service (Amazon S3) gérées par des catalogues à distance tels que AWS Glue, Databricks Unity Catalog et Snowflake Horizon Catalog. Utilisez le catalogue d'environnements d'exécution Lakehouse avec accès aux données multicloud. La fonctionnalité d'accès aux données multicloud du catalogue d'environnements d'exécution Lakehouse vous permet d'interroger des données chez d'autres fournisseurs de cloud directement depuis Google Cloud sans migrer de fichiers ni créer de pipelines ETL complexes.
  • Tables Azure Blob Storage ou Apache Iceberg non gérées par un catalogue distant compatible pour le catalogue d'environnements d'exécution Lakehouse avec accès aux données multicloud. Poursuivez avec Tables externes Apache Iceberg utilisant des fichiers de métadonnées JSON Iceberg.

Avant de commencer

Activez les API BigQuery Connection et BigQuery Reservation.

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Rôles requis

Pour obtenir les autorisations nécessaires pour créer une table externe Iceberg, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour créer une table externe Iceberg. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer une table externe Iceberg :

  • bigquery.tables.create
  • bigquery.connections.delegate
  • bigquery.jobs.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer des tables avec un fichier de métadonnées

Vous pouvez créer des tables externes Iceberg avec un fichier de métadonnées JSON. Toutefois, vous devez mettre à jour manuellement l'URI du fichier de métadonnées JSON pour maintenir la table externe Iceberg à jour. Si l'URI n'est pas mis à jour, les requêtes dans BigQuery peuvent échouer ou fournir des résultats différents de ceux d'autres moteurs de requête, qui utilisent directement un catalogue Iceberg.

Les fichiers de métadonnées de la table Iceberg sont créés dans le bucket Cloud Storage que vous spécifiez lorsque vous créez une table Iceberg à l'aide de Spark.

Sélectionnez l'une des options suivantes :

SQL

Utilisez l'instruction CREATE EXTERNAL TABLE. L'exemple suivant crée une table externe Iceberg nommée myexternal-table :

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

Remplacez la valeur uris par le dernier fichier de métadonnées JSON pour un instantané de table spécifique.

Vous pouvez activer l'option Demander un filtre de partitionnement en définissant l'indicateur require_partition_filter.

bq

Dans un environnement de ligne de commande, exécutez la commande bq mk --table avec le décorateur @connection pour spécifier la connexion à utiliser à la fin du paramètre --external_table_definition : Pour activer le filtre de partitionnement obligatoire, utilisez --require_partition_filter. 

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

Remplacez les éléments suivants :

  • TABLE_FORMAT : nom de la table que vous souhaitez créer

    Dans ce cas, ICEBERG.

  • URI : dernier fichier de métadonnées JSON pour un instantané de table spécifique

    Par exemple, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

    L'URI peut également pointer vers un emplacement cloud externe, tel qu'Amazon S3 ou Azure Blob Storage.

    • Exemple pour AWS : s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Exemple pour Azure : azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID : projet contenant la connexion permettant de créer la table externe Iceberg, par exemple myproject

  • CONNECTION_REGION : région contenant la connexion permettant de créer la table externe Iceberg, par exemple us

  • CONNECTION_ID : ID de connexion de la table, par exemple myconnection

    Lorsque vous affichez les détails de la connexion dans la console Google Cloud , il s'agit de 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).

  • DATASET : nom de l'ensemble de données BigQuery dans lequel vous souhaitez créer une table

    Par exemple, mydataset.

  • EXTERNAL_TABLE : nom de la table que vous souhaitez créer

    Par exemple, mytable.

Mettre à jour les métadonnées d'une table

Si vous utilisez un fichier de métadonnées JSON pour créer une table externe Iceberg, mettez à jour la définition de la table avec les dernières métadonnées de la table. Pour mettre à jour le schéma ou le fichier de métadonnées, sélectionnez l'une des options suivantes :

bq

  1. Créer un fichier de définition de table :

    bq mkdef --source_format=ICEBERG \
"URI" > TABLE_DEFINITION_FILE

  2. Exécutez la commande bq update avec l'option --autodetect_schema :

    bq update --autodetect_schema --external_table_definition=TABLE_DEFINITION_FILE
PROJECT_ID:DATASET.TABLE

    Remplacez les éléments suivants :

    • URI : votre URI Cloud Storage par le dernier fichier de métadonnées JSON

      Par exemple, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

    • TABLE_DEFINITION_FILE : nom du fichier contenant le schéma de la table

    • PROJECT_ID : ID du projet contenant la table que vous souhaitez mettre à jour

    • DATASET : ensemble de données contenant la table que vous souhaitez mettre à jour

    • TABLE : table dont vous souhaitez prendre un instantané

API

Utilisez la méthode tables.patch avec la propriété autodetect_schema définie sur true :

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant la table que vous souhaitez mettre à jour
  • DATASET : ensemble de données contenant la table que vous souhaitez mettre à jour
  • TABLE : table dont vous souhaitez prendre un instantané

Dans le corps de la requête, spécifiez les valeurs mises à jour pour les champs suivants :

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

Remplacez URI par le dernier fichier de métadonnées Iceberg. Exemple : gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

Configurer des stratégies de contrôle d'accès

Vous pouvez contrôler l'accès aux tables externes Iceberg grâce à la sécurité au niveau des colonnes, à la sécurité au niveau des lignes et au masquage des données.

Interroger des tables externes Iceberg

Pour en savoir plus, consultez la section Interroger des données Iceberg.

Interroger les données historiques

Vous pouvez accéder aux instantanés des tables externes Iceberg conservés dans vos métadonnées Iceberg à l'aide de la clause FOR SYSTEM_TIME AS OF.

Les périodes de conservation des données avec la fonctionnalité temporelle et la prévention des défaillances ne sont pas compatibles avec les tables externes.

Mappage de données

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

Type de données Iceberg Type de données BigQuery
boolean BOOL
int INT64
long INT64
float FLOAT64
double FLOAT64
Decimal(P/S) NUMERIC or BIG_NUMERIC depending on precision
date DATE
time TIME
timestamp DATETIME
timestamptz TIMESTAMP
string STRING
uuid BYTES
fixed(L) BYTES
binary BYTES
list<Type> ARRAY<Type>
struct STRUCT
map<KeyType, ValueType> ARRAY<Struct<key KeyType, value ValueType>>

Limites

Outre les limites des tables externes, les tables externes Iceberg présentent les limites suivantes :

  • Les requêtes qui utilisent VPC Service Controls ne sont pas acceptées et génèrent une erreur telle que NO_MATCHING_ACCESS_LEVEL.

  • Les tables utilisant la fusion à la lecture présentent les limites suivantes :

    • Une requête peut traiter jusqu'à 100 000 entrées de vecteurs de suppression au total dans le tableau. Pour les tables Iceberg version 3 qui utilisent des vecteurs de suppression binaires, chaque fichier de données associé à un vecteur de suppression est comptabilisé comme une entrée de suppression dans cette limite.
    • Chaque fichier de données peut être associé à un maximum de 10 000 fichiers de suppression.
    • Vous ne pouvez pas appliquer plus de 100 000 suppressions d'égalité à un fichier de données.
    • Vous pouvez contourner ces limites en compactant fréquemment les fichiers de suppression et les vecteurs de suppression, en créant une vue au-dessus de la table Iceberg qui évite les partitions fréquemment mutées ou en filtrant les requêtes sur les colonnes partitionnées pour réduire le nombre de fichiers de données et de vecteurs de suppression analysés.

  • BigQuery accepte l'élagage des fichiers manifestes à l'aide de toutes les fonctions de transformation de partition Iceberg. Pour en savoir plus sur l'élimination des partitions, consultez la section Interroger des tables partitionnées. Les requêtes faisant référence à des tables externes Iceberg doivent contenir des littéraux dans les prédicats par rapport aux colonnes partitionnées.

  • Seuls les fichiers de données Apache Parquet sont acceptés.

  • Les fonctionnalités suivantes d'Iceberg version 3 ne sont pas compatibles :

    • Nouveaux types de données : code temporel en nanosecondes(tz), inconnu, variante, géométrie, géographie
    • Valeurs par défaut initiales
    • Clés de chiffrement de table

Coûts de la fusion à la lecture

La facturation à la demande pour les données de fusion à la lecture correspond à la somme des analyses des données suivantes :

  • Tous les octets logiques lus dans le fichier de données (y compris les lignes marquées comme supprimées par les suppressions par position et par égalité).
  • Octets logiques lus lors du chargement des fichiers de suppression par égalité, de suppression par position et du vecteur de suppression pour trouver les lignes supprimées dans un fichier de données.

Demander un filtre de partitionnement

Vous pouvez exiger l'utilisation de filtres de prédicat en activant l'option Demander un filtre de partitionnement pour votre table Iceberg. Si vous activez cette option, toute tentative d'interrogation de la table sans spécifier de clause WHERE alignée sur chaque fichier manifeste génère l'erreur suivante :

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

Chaque fichier manifeste nécessite au moins un prédicat adapté à l'élimination de partitions.

Vous pouvez activer require_partition_filter de différentes manières lors de la création d'une table Iceberg :

SQL

Utilisez l'instruction CREATE EXTERNAL TABLE.L'exemple suivant crée une table externe Iceberg nommée TABLE avec l'option "Demander un filtre de partitionnement" activée :

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

Remplacez les éléments suivants :

  • TABLE : nom de la table que vous souhaitez créer.
  • PROJECT_ID : ID du projet contenant la table que vous souhaitez créer
  • REGION : emplacement dans lequel vous souhaitez créer la table Iceberg

  • CONNECTION_ID : ID de connexion Par exemple, myconnection.

  • URI : votre URI Cloud Storage avec le dernier fichier de métadonnées JSON

    Par exemple, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

    L'URI peut également pointer vers un emplacement cloud externe, tel qu'Amazon S3 ou Azure Blob Storage.

    • Exemple pour AWS : s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Exemple pour Azure : azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

bq

Exécutez la commande bq mk --table avec le décorateur @connection pour spécifier la connexion à utiliser à la fin du paramètre --external_table_definition. Utilisez --require_partition_filter pour activer le filtre de partitionnement obligatoire. L'exemple suivant crée une table externe Iceberg nommée TABLE avec l'option "Demander un filtre de partitionnement" activée : 

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

Remplacez les éléments suivants :

  • URI : dernier fichier de métadonnées JSON pour un instantané de table spécifique

    Par exemple, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

    L'URI peut également pointer vers un emplacement cloud externe, tel qu'Amazon S3 ou Azure Blob Storage.

    • Exemple pour AWS : s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Exemple pour Azure : azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID : projet contenant la connexion permettant de créer la table externe Iceberg, par exemple myproject

  • CONNECTION_REGION : région contenant la connexion permettant de créer la table externe Iceberg. Par exemple, us.

  • CONNECTION_ID : ID de connexion Par exemple, myconnection.

    Lorsque vous affichez les détails de la connexion dans la console Google Cloud , il s'agit de 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).

  • DATASET : nom de

    l'ensemble de données BigQuery contenant la table que vous souhaitez mettre à jour. Par exemple, mydataset.

  • EXTERNAL_TABLE : nom de la table que vous souhaitez créer

    Par exemple, mytable.

Vous pouvez également mettre à jour votre table Iceberg pour activer l'option "Demander un filtre de partitionnement".

Si vous n'activez pas l'option Demander un filtre de partitionnement lorsque vous créez la table partitionnée, vous pouvez mettre la table à jour pour ajouter l'option.

bq

Utilisez la commande bq update et saisissez l'option --require_partition_filter.

Par exemple :

Pour mettre à jour mypartitionedtable dans l'ensemble de données mydataset de votre projet par défaut, saisissez :

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

Étapes suivantes