Créer des tables externes BigLake pour Cloud Storage

Ce document explique comment créer une table BigLake Cloud Storage. Une table BigLake vous permet d'utiliser la délégation d'accès pour interroger des données structurées dans Cloud Storage. La délégation d'accès dissocie l'accès à la table BigLake de l'accès au datastore sous-jacent.

Avant de commencer

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery Connection API.

    Enable the API

    Si vous souhaitez lire des tables BigLake à partir de moteurs Open Source tels qu'Apache Spark, vous devez activer l'API BigQuery Storage Read.

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

  5. Assurez-vous de disposer d'un ensemble de données BigQuery.

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

    1. Facultatif : Pour Terraform, veuillez utiliser terraform-provider-google version 4.25.0 ou ultérieure. Les versions terraform-provider-google sont répertoriées sur GitHub. Vous pouvez télécharger la dernière version de Terraform à partir des téléchargements Terraform de HashiCorp.

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

Pour créer une table BigLake, vous avez besoin des autorisations IAM (Identity and Access Management) BigQuery suivantes :

  • 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 l'accès ou de créer la table BigLake pour vous.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la section Rôles et autorisations prédéfinis.

Considérations au sujet des emplacements

Lorsque vous utilisez Cloud Storage pour stocker des fichiers de données, vous pouvez améliorer les performances en utilisant des buckets à région unique ou birégionaux au lieu des buckets multirégionaux.

Créer des tables BigLake sur des données non partitionnées

Si vous savez comment créer des tables dans BigQuery, le processus de création d'une table BigLake est similaire. Votre table peut utiliser n'importe quel format de fichier compatible avec BigLake. Pour en savoir plus, consultez la section Limites.

Avant de créer une table BigLake, vous devez disposer d'un ensemble de données et d'une connexion à une ressource cloud pouvant accéder à Cloud Storage.

Pour créer une table BigLake, choisissez l'une des options suivantes :

Console

  1. Accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le volet Explorateur, développez votre projet et sélectionnez un ensemble de données.

  3. Développez l'option Actions, puis cliquez sur Créer une table.

  4. Dans la section Source, spécifiez les détails suivants :

    1. Pour le champ Créer une table à partir de, sélectionnez Google Cloud Storage.

    2. Dans le champ Sélectionner un fichier du bucket GCS ou utiliser un modèle d'URI, parcourez la liste pour sélectionner un bucket et un fichier à utiliser, ou saisissez le chemin d'accès au format gs://bucket_name/[folder_name/]file_name.

      Vous ne pouvez pas spécifier plusieurs URI dans la console Google Cloud. En revanche, vous pouvez sélectionner plusieurs fichiers en spécifiant un caractère générique astérisque (*). Par exemple, gs://mybucket/file_name*. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

      Le bucket Cloud Storage doit se trouver dans le même emplacement que l'ensemble de données contenant la table que vous créez.

    3. Pour Format de fichier, sélectionnez le format correspondant à votre fichier.

  5. Dans la section Destination, spécifiez les détails suivants :

    1. Pour Projet, choisissez le projet dans lequel créer la table.

    2. Pour Ensemble de données, choisissez l'ensemble de données dans lequel créer la table.

    3. Pour Table, saisissez le nom de la table que vous créez.

    4. Pour Type de table, sélectionnez Table externe.

    5. Sélectionnez Créer une table BigLake à l'aide d'une connexion à une ressource cloud.

    6. Pour ID de connexion, sélectionnez la connexion que vous avez créée précédemment.

  6. Dans la section Schéma, vous pouvez activer la détection automatique de schéma ou spécifier manuellement un schéma si vous disposez d'un fichier source. Si vous ne disposez pas d'un fichier source, vous devez spécifier manuellement un schéma.

    • Pour activer la détection automatique de schéma, sélectionnez l'option Détection automatique.

    • Pour spécifier manuellement un schéma, ne cochez pas l'option Détection automatique. Activez Modifier sous forme de texte et saisissez le schéma de la table sous forme de tableau JSON.

  7. Pour ignorer les lignes dont les valeurs de colonnes supplémentaires ne correspondent pas au schéma, développez la section Options avancées et sélectionnez Valeurs inconnues.

  8. Cliquez sur Créer une table.

Une fois la table permanente créée, vous pouvez exécuter une requête sur celle-ci comme s'il s'agissait d'une table BigQuery native. Une fois la requête exécutée, vous pouvez exporter les résultats au format CSV ou JSON, ou bien les enregistrer soit sous forme de table, soit dans Google Sheets.

SQL

Utilisez l'instruction LDD CREATE EXTERNAL TABLE : Vous pouvez spécifier explicitement le schéma ou utiliser la détection automatique de schéma pour déduire le schéma à partir des données externes.

  1. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans l'éditeur de requête, saisissez l'instruction suivante :

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'[,...]],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

    Remplacez les éléments suivants :

    • PROJECT_ID : nom du projet dans lequel vous souhaitez créer la table, par exemple myproject
    • DATASET : nom de l'ensemble de données BigQuery dans lequel vous souhaitez créer la table, par exemple, mydataset.
    • EXTERNAL_TABLE_NAME : nom de la table que vous souhaitez créer (par exemple, mytable).
    • REGION : région contenant la connexion, 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).

    • TABLE_FORMAT : format de la table que vous souhaitez créer (par exemple, PARQUET)

      Pour en savoir plus sur les formats compatibles, consultez la section Limites.

    • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table externe, au format ['gs://bucket_name/[folder_name/]file_name'].

      Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le chemin. Par exemple, ['gs://mybucket/file_name*']. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

      Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

      Les exemples suivants montrent des valeurs uris valides :

      • ['gs://bucket/path1/myfile.csv']
      • ['gs://bucket/path1/*.csv']
      • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

      Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

      Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

    • STALENESS_INTERVAL: indique si les métadonnées mises en cache sont utilisées par les opérations sur la table BigLake et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur de littéral d'intervalle comprise entre 30 minutes et 7 jours. Par exemple, spécifiez INTERVAL 4 HOUR pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé à un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

  3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Option 1 : fichier de définition de table

Exécutez la commande bq mkdef pour créer un fichier de définition de table, puis transmettez le chemin d'accès au fichier à la commande bq mk comme suit :

bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

Remplacez les éléments suivants :

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

  • SOURCE_FORMAT : format de la source de données externe. Par exemple, PARQUET.

  • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table, au format gs://bucket_name/[folder_name/]file_pattern.

    Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le file_pattern. Par exemple, gs://mybucket/file00*.parquet. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

    Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

    Les exemples suivants montrent des valeurs uris valides :

    • gs://bucket/path1/myfile.csv
    • gs://bucket/path1/*.parquet
    • gs://bucket/path1/file1*, gs://bucket1/path1/*

    Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

    Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

  • DEFINITION_FILE : chemin d'accès au fichier de définition de table sur votre ordinateur local.

  • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table BigLake et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mettre en cache les métadonnées pour améliorer les performances.

    Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

    Pour activer la mise en cache des métadonnées, spécifiez une valeur d'intervalle entre 30 minutes et 7 jours, à l'aide du format Y-M D H:M:S décrit dans la documentation de type de données INTERVAL. Par exemple, spécifiez 0-0 0 4:0:0 pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

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

  • EXTERNAL_TABLE_NAME : nom de la table que vous souhaitez créer (par exemple, mytable).

  • SCHEMA : schéma pour la table BigLake

Exemple :

bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

Pour utiliser la détection automatique de schéma, définissez l'option --autodetect=true dans la commande mkdef et omettez le schéma :

bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

Option 2 : Définition de table intégrée

Au lieu de créer un fichier de définition de table, vous pouvez transmettre la définition de table directement à la commande bq mk : Utilisez le décorateur @connection pour spécifier la connexion à utiliser à la fin de l'option --external_table_definition.

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

Remplacez les éléments suivants :

  • SOURCE_FORMAT : format de la source de données externe

    Par exemple, CSV.

  • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table, au format gs://bucket_name/[folder_name/]file_pattern.

    Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le file_pattern. Par exemple, gs://mybucket/file00*.parquet. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

    Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

    Les exemples suivants montrent des valeurs uris valides :

    • gs://bucket/path1/myfile.csv
    • gs://bucket/path1/*.parquet
    • gs://bucket/path1/file1*, gs://bucket1/path1/*

    Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

    Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

  • PROJECT_ID : nom du projet dans lequel vous souhaitez créer la table, par exemple myproject

  • REGION: région contenant la connexion, 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_NAME : nom de l'ensemble de données dans lequel vous souhaitez créer la table BigLake

  • TABLE_NAME : nom de la table BigLake

  • SCHEMA : schéma pour la table BigLake

Exemple :

bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Appelez la méthode API tables.insert, puis créez un objet ExternalDataConfiguration dans la ressource Table que vous transmettez.

Spécifiez la propriété schema ou définissez la propriété autodetect sur true pour activer la détection automatique du schéma pour les sources de données acceptées.

Spécifiez la propriété connectionId pour identifier la connexion à utiliser pour la connexion à Cloud Storage.

Terraform

Cet exemple crée une table BigLake sur des données non partitionnées.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}


# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [time_sleep.default]
}

Pour appliquer votre configuration Terraform dans un projet Google Cloud, suivez les procédures des sections suivantes.

Préparer Cloud Shell

  1. Lancez Cloud Shell.

  2. Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

    Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

  1. Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

    Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

    Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.

  3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
  4. Enregistrez les modifications.
  5. Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire. 
    terraform init

    Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade : 

    terraform init -upgrade

Appliquer les modifications

  1. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes : 
    terraform plan

    Corrigez les modifications de la configuration si nécessaire.

  2. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

    Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

  3. Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud, accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

BigLake accepte la détection automatique de schéma. Toutefois, si vous n'avez pas fourni de schéma et que le compte de service n'a pas reçu d'accès lors des étapes précédentes, ces étapes échouent avec un message d'accès refusé si vous essayez de détecter automatiquement le schéma.

Créer des tables BigLake sur des données partitionnées Hive

Vous pouvez créer une table BigLake pour les données partitionnées Hive dans Cloud Storage. Une fois la table partitionnée en externe créée, vous ne pouvez pas modifier la clé de partition. Vous devez recréer la table pour modifier la clé de partition.

Pour créer une table BigLake basée sur des données partitionnées Hive dans Cloud Storage, sélectionnez l'une des options suivantes :

Console

  1. Accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le volet Explorateur, développez votre projet et sélectionnez un ensemble de données.

  3. Cliquez sur Afficher les actions, puis sur Créer une table. Le volet Créer une table s'ouvre.

  4. Dans la section Source, spécifiez les détails suivants :

    1. Pour le champ Créer une table à partir de, sélectionnez Google Cloud Storage.

    2. Indiquez le chemin d'accès au dossier, en utilisant des caractères génériques. Par exemple, my_bucket/my_files*. Le dossier doit se trouver au même emplacement que l'ensemble de données contenant la table que vous souhaitez créer, modifier ou écraser.

    3. Dans la liste Format de fichier, sélectionnez le type de fichier.

    4. Cochez la case Partitionnement des données source, puis spécifiez les informations suivantes :

      1. Pour le champ Sélectionner le préfixe d'URI source, saisissez le préfixe d'URI. Par exemple, gs://my_bucket/my_files.
      2. Facultatif : Pour exiger un filtre de partitionnement sur toutes les requêtes de cette table, cochez la case Demander un filtre de partitionnement. Ce type de filtre peut réduire les coûts et améliorer les performances. Pour en savoir plus, consultez la section Exiger des filtres de prédicat sur les clés de partitionnement dans les requêtes.

      3. Dans la section Mode d'inférence de la partition, sélectionnez l'une des options suivantes :

        • Déduire automatiquement les types : définir le mode de détection du schéma de partition sur AUTO.
        • Toutes les colonnes sont des chaînes : définir le mode de détection du schéma de partition sur STRINGS.
        • Fournir ma propre définition : définir le mode de détection du schéma de partition sur CUSTOM et saisir manuellement les informations de schéma pour les clés de partition. Pour plus d'informations, consultez la section Fournir un schéma de clé de partitionnement personnalisé.

  5. Dans la section Destination, spécifiez les détails suivants :

    1. Pour Projet, sélectionnez le projet dans lequel vous souhaitez créer la table.
    2. Pour Ensemble de données, sélectionnez l'ensemble de données dans lequel vous souhaitez créer la table.
    3. Pour le champ Table, saisissez le nom de la table que vous souhaitez créer.
    4. Pour Type de table, sélectionnez Table externe.
    5. Cochez la case Créer une table BigLake à l'aide d'une connexion à une ressource cloud.
    6. Pour ID de connexion, sélectionnez la connexion que vous avez créée précédemment.

  6. Dans la section Schéma, activez la détection automatique de schéma en sélectionnant l'option Détection automatique.

  7. Pour ignorer les lignes dont les valeurs de colonnes supplémentaires ne correspondent pas au schéma, développez la section Options avancées et sélectionnez Valeurs inconnues.

  8. Cliquez sur Créer une table.

SQL

Utilisez l'instruction LDD CREATE EXTERNAL TABLE :

  1. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans l'éditeur de requête, saisissez l'instruction suivante :

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
WITH PARTITION COLUMNS
(
  PARTITION_COLUMN PARTITION_COLUMN_TYPE,
)
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
  uris=['FILE_PATH'],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE',
  format ="TABLE_FORMAT"
);

    Remplacez les éléments suivants :

    • PROJECT_ID : nom du projet dans lequel vous souhaitez créer la table, par exemple myproject
    • DATASET : nom de l'ensemble de données BigQuery dans lequel vous souhaitez créer la table, par exemple, mydataset
    • EXTERNAL_TABLE_NAME : nom de la table que vous souhaitez créer (par exemple, mytable)
    • PARTITION_COLUMN : nom de la colonne de partitionnement
    • PARTITION_COLUMN_TYPE : type de la colonne de partitionnement
    • REGION : région contenant la connexion, 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).

    • HIVE_PARTITION_URI_PREFIX : préfixe d'URI de partitionnement Hive, par exemple gs://mybucket/
    • FILE_PATH : chemin d'accès à la source de données de la table externe que vous souhaitez créer (par exemple, gs://mybucket/*.parquet)
    • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table BigLake et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur de littéral d'intervalle comprise entre 30 minutes et 7 jours. Par exemple, spécifiez INTERVAL 4 HOUR pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé à un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

    • TABLE_FORMAT : format de la table que vous souhaitez créer (par exemple, PARQUET)

  3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

Exemples

L'exemple suivant crée une table BigLake sur des données partitionnées dans lesquelles :

  • Le schéma est détecté automatiquement.
  • L'intervalle d'obsolescence du cache de métadonnées pour la table est fixé à un jour.
  • Le cache de métadonnées est actualisé automatiquement.
CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

L'exemple suivant crée une table BigLake sur des données partitionnées dans lesquelles :

  • Le schéma est spécifié.
  • L'intervalle d'obsolescence du cache de métadonnées pour la table est de 8 heures.
  • Le cache de métadonnées doit être actualisé manuellement.
CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

bq

Tout d'abord, utilisez la commande bq mkdef pour créer un fichier de définition de table :

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_URIS > DEFINITION_FILE

Remplacez les éléments suivants :

  • SOURCE_FORMAT : format de la source de données externe. Par exemple, CSV.
  • REGION : région contenant la connexion, 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).

  • PARTITIONING_MODE : mode de partitionnement Hive. Utilisez l'une des valeurs suivantes :

    • AUTO : détecte automatiquement les noms et les types de clés.
    • STRINGS : convertit automatiquement les noms de clés en chaînes.
    • CUSTOM : encode le schéma de clé dans le préfixe d'URI source.

  • GCS_URI_SHARED_PREFIX : préfixe de l'URI source.

  • BOOLEAN : spécifie si un filtre de prédicat est requis au moment de la requête. Cette option est facultative. La valeur par défaut est false.

  • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement. Vous ne devez inclure cette option que si vous prévoyez également d'utiliser l'option --max_staleness dans la commande bq mk suivante pour activer la mise en cache des métadonnées. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

    Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé à un intervalle défini par le système, généralement entre 30 et 60 minutes.

    Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

    Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

  • GCS_URIS : chemin d'accès au dossier Cloud Storage, au format générique.

  • DEFINITION_FILE : chemin d'accès au fichier de définition de table sur votre ordinateur local.

Si la valeur de PARTITIONING_MODE est CUSTOM, incluez le schéma de clé de partitionnement dans le préfixe d'URI source, en utilisant le format suivant :

--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Après avoir créé le fichier de définition de table, créez la table BigLake à l'aide de la commande bq mk :

bq mk --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

Remplacez les éléments suivants :

  • DEFINITION_FILE : chemin d'accès au fichier de définition de table.

  • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table BigLake et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Si vous incluez cette option, vous devez également avoir spécifié une valeur pour l'option --metadata_cache_mode dans la commande bq mkdef précédente. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

    Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

    Pour activer la mise en cache des métadonnées, spécifiez une valeur d'intervalle comprise entre 30 minutes et 7 jours, à l'aide du format Y-M D H:M:S décrit dans la documentation sur les type de données INTERVAL. Par exemple, spécifiez 0-0 0 4:0:0 pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

  • DATASET_NAME : nom de l'ensemble de données contenant la table.

  • TABLE_NAME : nom de la table que vous créez.

  • SCHEMA : spécifie un chemin d'accès à un fichier de schéma JSON, ou spécifie le schéma au format field:data_type,field:data_type,.... Pour utiliser la détection automatique de schéma, omettez cet argument.

Exemples

L'exemple suivant utilise le mode de partitionnement AUTO Hive et définit également le cache de métadonnées sur un intervalle d'obsolescence de 12 heures et pour l'actualiser automatiquement :

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

L'exemple suivant utilise le mode de partitionnement Hive STRING :

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

L'exemple suivant utilise le mode de partitionnement Hive CUSTOM :

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Pour définir le partitionnement Hive à l'aide de l'API BigQuery, incluez l'objet hivePartitioningOptions dans l'objet ExternalDataConfiguration lorsque vous créez le fichier de définition de table. Pour créer une table BigLake, vous devez également spécifier une valeur pour le champ connectionId.

Si vous définissez le champ hivePartitioningOptions.mode sur CUSTOM, vous devez encoder le schéma de clé de partitionnement dans le champ hivePartitioningOptions.sourceUriPrefix comme suit : gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Pour forcer l'application d'un filtre de prédicat au moment de la requête, définissez le champ hivePartitioningOptions.requirePartitionFilter sur true.

Terraform

Cet exemple crée une table BigLake sur des données partitionnées.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.


# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }


  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

Pour appliquer votre configuration Terraform dans un projet Google Cloud, suivez les procédures des sections suivantes.

Préparer Cloud Shell

  1. Lancez Cloud Shell.

  2. Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

    Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

  1. Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

    Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

    Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.

  3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
  4. Enregistrez les modifications.
  5. Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire. 
    terraform init

    Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade : 

    terraform init -upgrade

Appliquer les modifications

  1. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes : 
    terraform plan

    Corrigez les modifications de la configuration si nécessaire.

  2. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

    Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

  3. Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud, accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

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

Vous pouvez contrôler l'accès aux tables BigLake à l'aide de plusieurs méthodes :

Par exemple, supposons que vous souhaitez limiter l'accès aux lignes de la table mytable dans l'ensemble de données mydataset :

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
| JP      | tablet  |   300 |
| UK      | laptop  |   200 |
+---------+---------+-------+

Vous pouvez créer un filtre au niveau de la ligne pour Kim (kim@example.com), qui limite son accès aux lignes où country est égal à US.

CREATE ROW ACCESS POLICY only_us_filter
ON mydataset.mytable
GRANT TO ('user:kim@example.com')
FILTER USING (country = 'US');

Kim peut ensuite exécuter la requête suivante :

SELECT * FROM projectid.mydataset.mytable;

Le résultat n'affiche que les lignes où country est égal à US :

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
+---------+---------+-------+

Interroger des tables BigLake

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

Mettre à jour des tables BigLake

Vous pouvez mettre à jour les tables BigLake si nécessaire, par exemple pour modifier la mise en cache des métadonnées. Pour obtenir des détails sur la table, tels que le format source et l'URI source, consultez la section Obtenir des informations sur la table.

Vous pouvez également utiliser cette même procédure pour mettre à niveau les tables externes basées sur Cloud Storage vers des tables BigLake en associant la table externe à une connexion. Pour en savoir plus, consultez la section Mettre à niveau des tables externes vers des tables BigLake.

Pour créer une table BigLake, choisissez l'une des options suivantes :

SQL

Utilisez l'instruction LDD CREATE OR REPLACE EXTERNAL TABLE pour mettre à jour une table :

  1. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans l'éditeur de requête, saisissez l'instruction suivante :

    CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION `REGION.CONNECTION_ID`
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

    Remplacez les éléments suivants :

    • PROJECT_ID : nom du projet contenant la table
    • DATASET : nom de l'ensemble de données contenant la table
    • EXTERNAL_TABLE_NAME : nom de la table
    • REGION : région qui contient la connexion
    • CONNECTION_ID : nom de la connexion à utiliser
    • TABLE_FORMAT : format utilisé par la table

      Vous ne pouvez pas modifier ce paramètre lors de la mise à jour de la table.

    • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table externe, au format ['gs://bucket_name/[folder_name/]file_name'].

      Vous pouvez sélectionner plusieurs fichiers dans le bucket en spécifiant un caractère générique astérisque (*) dans le chemin. Par exemple, ['gs://mybucket/file_name*']. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

      Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

      Les exemples suivants montrent des valeurs uris valides :

      • ['gs://bucket/path1/myfile.csv']
      • ['gs://bucket/path1/*.csv']
      • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

      Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

      Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

    • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser.

      Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur de littéral d'intervalle comprise entre 30 minutes et 7 jours. Par exemple, spécifiez INTERVAL 4 HOUR pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement.

      Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé à un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

  3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Exécutez les commandes bq mkdef et bq update pour mettre à jour une table :

  1. Générez une définition de table externe décrivant les aspects de la table à modifier :

    bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE

    Remplacez les éléments suivants :

    • PROJECT_ID : nom du projet contenant la connexion
    • REGION : région qui contient la connexion
    • CONNECTION_ID : nom de la connexion à utiliser.
    • TABLE_FORMAT : format utilisé par la table. Vous ne pouvez pas modifier ce paramètre lors de la mise à jour de la table.

    • CACHE_MODE : indique si le cache de métadonnées est actualisé automatiquement ou manuellement. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mettre en cache les métadonnées pour améliorer les performances.

      Définissez cet élément sur AUTOMATIC pour que le cache de métadonnées soit actualisé selon un intervalle défini par le système, généralement entre 30 et 60 minutes.

      Définissez la valeur sur MANUAL si vous souhaitez actualiser le cache de métadonnées selon une programmation que vous déterminez. Dans ce cas, vous pouvez appeler la procédure système BQ.REFRESH_EXTERNAL_METADATA_CACHE pour actualiser le cache.

      Vous devez définir CACHE_MODE si STALENESS_INTERVAL est défini sur une valeur supérieure à 0.

    • BUCKET_PATH : chemin d'accès au bucket Cloud Storage contenant les données de la table externe, au format gs://bucket_name/[folder_name/]file_name.

      Vous pouvez limiter les fichiers sélectionnés à partir du bucket en spécifiant un caractère générique astérisque (*) dans le chemin. Par exemple, gs://mybucket/file_name*. Pour en savoir plus, consultez la section Gestion des caractères génériques dans les URI Cloud Storage.

      Vous pouvez spécifier plusieurs buckets pour l'option uris en fournissant plusieurs chemins d'accès.

      Les exemples suivants montrent des valeurs uris valides :

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.csv
      • gs://bucket/path1/*,gs://bucket/path2/file00*

      Lorsque vous spécifiez des valeurs uris qui ciblent plusieurs fichiers, tous ces fichiers doivent partager un schéma compatible.

      Pour en savoir plus sur l'utilisation des URI Cloud Storage dans BigQuery, consultez la page Chemin d'accès aux ressources Cloud Storage.

    • DEFINITION_FILE : nom du fichier de définition de table que vous créez.

  2. Mettez à jour la table en utilisant la nouvelle définition de table externe :

    bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

    Remplacez les éléments suivants :

    • STALENESS_INTERVAL : indique si les métadonnées mises en cache sont utilisées par les opérations sur la table et indique le niveau nécessaire de fraîcheur des métadonnées mises en cache pour que l'opération puisse les utiliser. Pour en savoir plus sur les considérations liées à la mise en cache des métadonnées, consultez la section Mise en cache des métadonnées pour améliorer les performances.

      Pour désactiver la mise en cache des métadonnées, spécifiez 0. Il s'agit de la valeur par défaut.

      Pour activer la mise en cache des métadonnées, spécifiez une valeur d'intervalle entre 30 minutes et 7 jours, à l'aide du format Y-M D H:M:S décrit dans la documentation de type de données INTERVAL. Par exemple, spécifiez 0-0 0 4:0:0 pour un intervalle d'obsolescence de quatre heures. Avec cette valeur, les opérations sur la table utilisent les métadonnées mises en cache si elles ont été actualisées au cours des quatre dernières heures. Si les métadonnées mises en cache sont plus anciennes, l'opération extrait les métadonnées de Cloud Storage.

    • DEFINITION_FILE : nom du fichier de définition de table que vous avez créé ou mis à jour.

    • PROJECT_ID : nom du projet contenant la table.

    • DATASET : nom de l'ensemble de données contenant la table.

    • EXTERNAL_TABLE_NAME : nom de la table

Exemple

L'exemple suivant met à jour mytable pour utiliser les métadonnées mises en cache tant qu'elles ont été actualisées au cours des dernières 4,5 heures, et pour actualiser automatiquement les métadonnées mises en cache:

bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

Où enable_metadata.json a le contenu suivant : { "metadataCacheMode": "AUTOMATIC" }

Journaux d'audit

Pour plus d'informations sur la journalisation dans BigQuery, consultez la page Présentation de la surveillance BigQuery. Pour en savoir plus sur la journalisation dans Google Cloud, consultez la page Cloud Logging.

Étapes suivantes