Créer des tables BigLake Amazon S3

Ce document explique comment créer une table BigLake Amazon 3S (Amazon Simple Storage Service). Une table BigLake vous permet d'utiliser la délégation d'accès pour interroger des données dans Amazon S3. La délégation d'accès dissocie l'accès à la table BigLake de l'accès au data store sous-jacent.

Pour en savoir plus sur la manière dont les données circulent entre BigQuery et Amazon S3, consultez la section Flux de données lors de l'interrogation de données.

Avant de commencer

Assurez-vous de disposer d'une connexion pour accéder aux données Amazon S3.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer une table externe, demandez à votre administrateur de vous accorder le rôle IAM Administrateur BigQuery (roles/bigquery.admin) sur votre ensemble de données. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ce rôle prédéfini contient les autorisations requises pour créer une table externe. 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 :

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

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

Créer un ensemble de données

Avant de créer une table externe, vous devez créer un ensemble de données dans la région disponible. Sélectionnez l'une des options suivantes :

Console

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le panneau Explorateur, sélectionnez le projet dans lequel vous souhaitez créer l'ensemble de données.
3. Développez l'option Afficher les actions, puis cliquez sur Créer un ensemble de données.
4. Sur la page Créer un ensemble de données, spécifiez les détails suivants :
1. Pour Dataset ID (ID de l'ensemble de données), renseignez le nom unique de l'ensemble de données.
2. Pour Emplacement des données, choisissez une région compatible.
3. Facultatif : Pour supprimer automatiquement les tables, cochez la case Activer l'expiration de la table et définissez l'âge maximal par défaut de la table en jours. Les données dans Amazon S3 ne sont pas supprimées lorsque la table expire.
4. Si vous souhaitez utiliser le classement par défaut, développez la section Options avancées, puis sélectionnez l'option Activer le classement par défaut.
5. Cliquez sur Créer un ensemble de données.

SQL

Utilisez l'instruction LDD CREATE SCHEMA : L'exemple suivant crée un ensemble de données dans la région aws-us-east-1:

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 SCHEMA mydataset
   OPTIONS (
     location = 'aws-us-east-1');
   

3. Cliquez sur Exécuter.

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

bq

Dans un environnement de ligne de commande, créez un ensemble de données à l'aide de la commande bq mk :

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

Le paramètre --project_id remplace le projet par défaut.

Remplacez les éléments suivants :

• LOCATION : emplacement de votre ensemble de données

  Pour en savoir plus sur les régions disponibles, consultez la page Emplacements. Une fois que vous avez créé un ensemble de données, vous ne pouvez plus modifier son emplacement. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.

• PROJECT_ID : ID de votre projet.

• DATASET_NAME : nom de l'ensemble de données que vous souhaitez créer

  Pour créer un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données de la manière suivante : PROJECT_ID:DATASET_NAME.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

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

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, puis sélectionnez un ensemble de données.

3. Dans la section Informations sur l'ensemble de données, cliquez sur Créer une table.

4. Dans la section Source de la page Create table (Créer une table), procédez comme suit :

   1. Dans le champ Créer une table à partir de, sélectionnez Amazon S3.
   2. Dans le champ Sélectionnez un chemin S3, saisissez un URI pointant vers les données Amazon S3 au format s3://BUCKET_NAME/PATH. Remplacez BUCKET_NAME par le nom du bucket Amazon S3. La région du bucket doit être identique à celle de l'ensemble de données. Remplacez PATH par le chemin d'accès dans lequel vous souhaitez écrire le fichier exporté. Il peut contenir un caractère générique *.
   3. Dans le champ Format de fichier, sélectionnez le format de données Amazon S3. Les formats acceptés sont AVRO, CSV, DELTA_LAKE, ICEBERG, JSONL, ORC et PARQUET.

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

   1. Dans le champ Ensemble de données, sélectionnez l'ensemble de données approprié.
   2. Dans le champ Table, saisissez le nom de la table.
   3. Vérifiez que le paramètre Type de table est défini sur Table externe.
   4. Dans le champ ID de connexion, sélectionnez l'ID de connexion approprié dans la liste déroulante. Pour en savoir plus sur les connexions, consultez la page Se connecter à Amazon S3.

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. Cliquez sur Créer une table.

SQL

Pour créer une table BigLake, utilisez l'instruction CREATE EXTERNAL TABLE avec la clause WITH CONNECTION :

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 DATASET_NAME.TABLE_NAME
     WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME`
     OPTIONS (
       format = "DATA_FORMAT",
       uris = ["S3_URI"],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE');
   

   Remplacez les éléments suivants :

   • DATASET_NAME : nom de l'ensemble de données que vous avez créé.
   • TABLE_NAME : nom à attribuer à la table.
   • AWS_LOCATION : emplacement AWS dans Google Cloud (par exemple, "aws-us-east-1").
   • CONNECTION_NAME : nom de la connexion créée
   • DATA_FORMAT : tout format BigQuery fédéré accepté (tel que AVRO, CSV, DELTA_LAKE, ICEBERG, PARQUET (preview)
   • S3_URI : URI pointant vers les données Amazon S3 (par exemple, s3://bucket/path)
   • 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 d'Amazon S3.

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

Exemple :

CREATE EXTERNAL TABLE awsdataset.awstable
  WITH CONNECTION `aws-us-east-1.s3-read-connection`
  OPTIONS (
    format="CSV",
    uris=["s3://s3-bucket/path/file.csv"],
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

bq

Créer un fichier de définition de table

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

Remplacez les éléments suivants :

• DATA_FORMAT : tout format BigQuery fédéré accepté (tel que AVRO, CSV, DELTA_LAKE, ICEBERG ou PARQUET).
• S3_URI : URI pointant vers les données Amazon S3 (par exemple, s3://bucket/path)
• AWS_LOCATION : emplacement AWS dans Google Cloud (par exemple, aws-us-east-1)

• CONNECTION_NAME : nom de la connexion créée

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

Remarque : Pour remplacer le projet par défaut, utilisez le paramètre --project_id=PROJECT_ID. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud.

Ensuite, créez la table BigLake :

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.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 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 l'option 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 d'Amazon S3.

• DATASET_NAME : nom de l'ensemble de données créé

• TABLE_NAME : nom à attribuer à la table

Par exemple, la commande suivante crée une table BigLake, awsdataset.awstable, qui peut interroger vos données Amazon S3 stockées sur le chemin d'accès s3://s3-bucket/path/file.csv et dispose d'une connexion en lecture à l'emplacement aws-us-east-1 :

bq mkdef  \
--autodetect \
--source_format=CSV \
--connection_id=aws-us-east-1.s3-read-connection \
--metadata_cache_mode=AUTOMATIC \
s3://s3-bucket/path/file.csv > table_def

bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=table_def awsdataset.awstable

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 à Amazon S3.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

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

Vous pouvez créer une table BigLake pour les données partitionnées Hive dans Amazon S3. 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, 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. Dans le champ Créer une table à partir de, sélectionnez Amazon S3.

   2. Indiquez le chemin d'accès au dossier, en utilisant des caractères génériques. Par exemple, s3://mybucket/*.

      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, s3://mybucket/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 contribuer à 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, vérifiez que l'option Table externe est sélectionnée.
   5. 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.

SQL

Utilisez l'instruction LDD CREATE EXTERNAL TABLE :

1. Dans Google Cloud Console, 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'],
     format ="TABLE_FORMAT"
     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)
   • 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 : nom de la connexion, par exemple myconnection
   • HIVE_PARTITION_URI_PREFIX : préfixe d'URI de partitionnement Hive (par exemple, s3://mybucket/)
   • FILE_PATH : chemin d'accès à la source de données de la table externe que vous souhaitez créer (par exemple, s3://mybucket/*.parquet)
   • TABLE_FORMAT : format de la table que vous souhaitez créer (par exemple, 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 d'Amazon S3.

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

Exemples

L'exemple suivant crée une table BigLake sur des données partitionnées dans Amazon S3. Le schéma est détecté automatiquement.

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

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=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 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 : nom de la connexion, par exemple 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.
• 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.

• URIS : chemin d'accès au dossier Amazon S3, 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=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 --max_staleness=STALENESS_INTERVAL \
--external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

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 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 l'option 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 d'Amazon S3.

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

• 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 Hive AUTO pour les données Amazon S3 :

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

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

L'exemple suivant utilise le mode de partitionnement Hive STRING pour les données Amazon S3 :

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/myTable/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --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 : s3://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.

Tables Delta Lake

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour demander de l'aide ou envoyer des commentaires concernant cette fonctionnalité, envoyez un e-mail à l'adresse [e-mail].

Delta Lake est un format de table Open Source compatible avec les tables de données à l'échelle du pétaoctet. Les tables Delta Lake peuvent être interrogées à la fois en tant que tables temporaires et permanentes, et sont acceptées en tant que table BigLake.

Synchronisation des schémas

Delta Lake conserve un schéma canonique dans ses métadonnées. Vous ne pouvez pas mettre à jour un schéma à l'aide d'un fichier de métadonnées JSON. Pour mettre à jour le schéma, procédez comme suit :

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

   bq update --autodetect_schema
   PROJECT_ID:DATASET.TABLE
   

   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é

Conversion des types de données

BigQuery convertit les types de données Delta Lake en types de données BigQuery, comme décrit ci-dessous :

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 limites suivantes s'appliquent aux tables Delta Lake :

• Les limites des tables externes s'appliquent aux tables Delta Lake.

• Les tables Delta Lake ne sont compatibles qu'avec BigQuery Omni et sont soumises aux limites suivantes.

• Vous ne pouvez pas mettre à jour une table avec un nouveau fichier de métadonnées JSON. Vous devez utiliser une opération de mise à jour de table de schéma à détection automatique. Pour en savoir plus, consultez la section Synchronisation des schémas.

• Les fonctionnalités de sécurité de BigLake protègent les tables Delta Lake uniquement lorsque leur accès est effectué par l'intermédiaire des services BigQuery.

Créer une table Delta Lake

L'exemple suivant crée une table externe à l'aide de l'instruction CREATE EXTERNAL TABLE au format Delta Lake :

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

Remplacez les éléments suivants :

• table_name : nom de la table.

• connection_name : nom de la connexion. La connexion doit identifier une source Amazon S3 ou Blob Storage.

• parent_directory : URI du répertoire parent.

Transfert de cloud à cloud avec Delta Lake

L'exemple suivant utilise l'instruction LOAD DATA pour charger des données dans la table appropriée :

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

Pour plus d'exemples de transferts de données inter-cloud, consultez la section Charger des données avec des opérations multicloud.

Interroger des tables BigLake

Pour en savoir plus, consultez la page Interroger des données Amazon S3.

Afficher les métadonnées des ressources

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez afficher les métadonnées des ressources avec des vues INFORMATION_SCHEMA. Lorsque vous interrogez les vues JOBS_BY_*, JOBS_TIMELINE_BY_* et RESERVATION*, vous devez spécifier l'emplacement de traitement de la requête colocalisé avec la région de la table. Pour en savoir plus sur les emplacements BigQuery Omni, consultez la section Emplacements. Pour toutes les autres tables système, spécifier l'emplacement de la tâche de requête est facultatif.

Consultez la section Limites pour en savoir plus sur les tables système compatibles avec BigQuery Omni.

Pour interroger les tables système JOBS_* et RESERVATION*, sélectionnez l'une des méthodes suivantes pour spécifier l'emplacement de traitement :

Console

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Si l'onglet Éditeur n'est pas visible, cliquez sur Saisir une nouvelle requête.

3. Cliquez sur Plus> Paramètres de requête. La boîte de dialogue Query Settings (Paramètres de la requête) s'ouvre.

4. Dans la boîte de dialogue Paramètres de requête, pour Paramètres supplémentaires > Emplacement des données, sélectionnez BigQuery région située dans la région BigQuery Omni. Par exemple, si votre région BigQuery Omni est aws-us-east-1, spécifiez us-east4.

5. Sélectionnez les champs restants, puis cliquez sur Enregistrer.

bq

Utilisez l'option --location pour définir l'emplacement de traitement de la tâche sur la région BigQuery qui est hébergée en colocation avec la région BigQuery Omni. Par exemple, si votre région BigQuery Omni est aws-us-east-1, spécifiez us-east4.

Exemple

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"

bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"

API

Si vous exécutez des tâches de manière automatisée, définissez l'argument d'emplacement sur la région BigQuery qui est colocalisée avec la région BigQuery Omni. Par exemple, si votre région BigQuery Omni est aws-us-east-1, spécifiez us-east4.

L'exemple suivant répertorie les jobs d'actualisation des métadonnées :

SELECT
 *
FROM
 `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT`
WHERE
 job_id LIKE '%metadata_cache_refresh%'
 AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR)
ORDER BY start_time desc
LIMIT 10;

VPC Service Controls

Vous pouvez utiliser les périmètres VPC Service Controls en tant que couche de défense supplémentaire, afin de limiter l'accès à un service cloud externe depuis BigQuery Omni. Par exemple, les périmètres VPC Service Controls peuvent limiter les exportations depuis vos tables BigQuery Omni vers un bucket Amazon S3 ou un conteneur Blob Storage spécifique.

Pour en savoir plus sur VPC Service Controls, consultez la page Présentation de VPC Service Controls.

Autorisation requise

Assurez-vous de disposer des autorisations requises pour configurer des périmètres de service. Pour afficher la liste des rôles IAM requis pour configurer VPC Service Controls, consultez la page Contrôle des accès avec IAM dans la documentation de VPC Service Controls.

Configurer VPC Service Controls à l'aide de la console Google Cloud

1. Dans le menu de navigation de la console Google Cloud, cliquez sur Sécurité, puis sur VPC Service Controls.

   Accéder à VPC Service Controls

2. Pour configurer VPC Service Controls pour BigQuery Omni, suivez les étapes du guide Créer un périmètre de service, puis lorsque vous êtes dans le volet Règles de sortie, procédez comme suit :

   1. Dans le volet Règles de sortie, cliquez sur Ajouter une règle.

   2. Dans la section Attributs "FROM" du client API, sélectionnez une option dans la liste Identité.

   3. Sélectionnez Attributs "TO" des ressources externes.

   4. Pour ajouter une ressource externe, cliquez sur Ajouter des ressources externes.

   5. Dans la boîte de dialogue Ajouter une ressource externe, saisissez un nom de ressource valide dans le champ Nom de la ressource externe. Exemple :

      • Pour Amazon Simple Storage Service (Amazon S3) : s3://BUCKET_NAME

        Remplacez BUCKET_NAME par le nom de votre bucket Amazon S3.

      • Pour Azure Blob Storage : azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        Remplacez CONTAINER NAME par le nom de votre conteneur Blob Storage.

      Pour obtenir la liste des attributs de règle de sortie, consultez la documentation de référence sur les règles de sortie.

   6. Sélectionnez les méthodes que vous souhaitez autoriser sur vos ressources externes :

      1. Si vous souhaitez autoriser toutes les méthodes, sélectionnez Toutes les méthodes dans la liste Méthodes.
      2. Si vous souhaitez autoriser des méthodes spécifiques, sélectionnez Méthode sélectionnée, cliquez sur Sélectionner des méthodes, puis sélectionnez les méthodes à autoriser sur vos ressources externes.

   7. Cliquez sur Créer un périmètre.

Configurer VPC Service Controls à l'aide de gcloud CLI

Pour configurer VPC Service Controls à l'aide de gcloud CLI, procédez comme suit :

1. Définissez la règle d'accès par défaut.
2. Créez le fichier d'entrée de la règle de sortie.
3. Ajoutez la règle de sortie.

Définir la règle d'accès par défaut

Une règle d'accès est un conteneur à l'échelle de l'organisation pour les niveaux d'accès et les périmètres de service. Pour en savoir plus sur la définition d'une règle d'accès par défaut ou l'obtention d'un nom de règle d'accès, consultez la page Gérer une règle d'accès.

Créer le fichier d'entrée de règle de sortie

Un bloc de règles de sortie définit l'accès autorisé depuis un périmètre aux ressources situées en dehors de ce périmètre. Pour les ressources externes, la propriété externalResources définit les chemins d'accès aux ressources externes auxquelles l'accès est autorisé à partir de votre périmètre VPC Service Controls.

Les règles de sortie peuvent être configurées à l'aide d'un fichier JSON ou d'un fichier YAML. L'exemple suivant utilise le format .yaml :

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

• egressTo : répertorie les opérations de service autorisées sur les ressources Google Cloud situées dans des projets spécifiés qui sont extérieurs au périmètre.

• operations : répertorie les services et actions/méthodes auxquels un client qui satisfait les conditions du bloc from est autorisé à accéder.

• serviceName : définissez bigquery.googleapis.com pour BigQuery Omni.

• methodSelectors : répertorie les méthodes auxquelles un client qui satisfait les conditions from peut accéder. Pour connaître les méthodes et autorisations pouvant faire l'objet de restrictions pour les services, consultez la section Méthodes de service compatibles avec les restrictions.

• method : méthode de service valide, ou \"*\" pour autoriser toutes les méthodes serviceName.

• permission : autorisation de service valide, telle que \"*\", externalResource.read ou externalResource.write. L'accès aux ressources situées en dehors du périmètre est autorisé pour les opérations nécessitant cette autorisation.

• externalResources : répertorie les ressources externes auxquelles les clients situés au sein d'un périmètre peuvent accéder. Remplacez EXTERNAL_RESOURCE_PATH par un bucket Amazon S3 valide, tel que s3://bucket_name, ou par un chemin d'accès à un conteneur Blob Storage, tel que azure://myaccount.blob.core.windows.net/container_name.

• egressFrom : répertorie les opérations de service autorisées sur les ressources Google Cloud dans des projets spécifiés dans le périmètre.

• identityType ou identities : définit les types d'identité pouvant accéder aux ressources spécifiées en dehors du périmètre. Remplacez IDENTITY_TYPE par l'une des valeurs valides suivantes :

  • ANY_IDENTITY : permet d'autoriser toutes les identités.
  • ANY_USER_ACCOUNT : permet d'autoriser tous les utilisateurs.
  • ANY_SERVICE_ACCOUNT : permet d'autoriser tous les comptes de service.

• identities : répertorie les comptes de service pouvant accéder aux ressources spécifiées qui sont situées en dehors du périmètre.

• serviceAccount (facultatif) : remplacez SERVICE_ACCOUNT par le compte de service qui peut accéder aux ressources spécifiées en dehors du périmètre.

Examples

L'exemple suivant est une règle qui autorise les opérations de sortie depuis l'intérieur du périmètre vers l'emplacement Amazon S3 s3://mybucket dans AWS.

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

L'exemple suivant autorise les opérations de sortie vers un conteneur Blob Storage :

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

Pour en savoir plus sur les règles de sortie, consultez la documentation de référence sur les règles de sortie.

Ajouter la règle de sortie

Pour ajouter la règle de sortie lorsque vous créez un périmètre de service, exécutez la commande gcloud access-context-manager perimeters create. Par exemple, la commande suivante crée un périmètre nommé omniPerimeter, qui inclut le projet portant le numéro de projet 12345, limite l'API BigQuery et ajoute une règle de sortie définie dans le fichier egress.yaml :

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

Pour ajouter la règle de sortie à un périmètre de service existant, exécutez la commande gcloud access-context-manager perimeters update. Par exemple, la commande suivante ajoute une règle de sortie définie dans le fichier egress.yaml à un périmètre de service existant nommé omniPerimeter :

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

Vérifier votre périmètre

Pour vérifier le périmètre, exécutez la commande gcloud access-context-manager perimeters describe :

gcloud access-context-manager perimeters describe PERIMETER_NAME

Remplacez PERIMETER_NAME par le nom du périmètre.

Par exemple, la commande suivante décrit le périmètre omniPerimeter :

gcloud access-context-manager perimeters describe omniPerimeter

Pour en savoir plus, consultez la page Gérer les périmètres de service.

Limites

Pour obtenir la liste complète des limites applicables aux tables BigLake basées sur Amazon S3 et Blob Storage, consultez la section Limites.

Étapes suivantes

• Découvrez BigQuery Omni.
• Utilisez l'atelier BigQuery Omni avec AWS.
• Découvrez les tables BigLake.
• Apprenez à exporter les résultats de requêtes vers Amazon S3.
• Découvrez comment créer des vues matérialisées sur des tables compatibles avec le cache des métadonnées Amazon Simple Storage Service (Amazon S3).
• Découvrez comment rendre les données Amazon S3 dans une vue matérialisée disponibles localement pour les jointures en créant une instance répliquée de la vue matérialisée.