Créer et utiliser des tables

Ce document décrit comment créer et utiliser des tables dans BigQuery. Après avoir créé une table, vous pouvez :

  • contrôler l'accès aux données de votre table ;
  • obtenir des informations sur vos tables ;
  • répertorier les tables dans un ensemble de données ;
  • obtenir les métadonnées d'une table.

Pour plus d'informations sur la gestion des tables, y compris la mise à jour des propriétés de tables, la copie et la suppression de tables, consultez la section Gérer des tables.

Limitations des tables

Les tables BigQuery sont soumises aux limitations suivantes :

  • Les noms de table doivent être spécifiques pour chaque ensemble de données.
  • La console et l'UI Web classique de BigQuery permettent la copie d'une table à la fois.
  • Lors de la copie de tables, l'ensemble de données de destination doit résider dans la même zone que la table en cours de copie. Par exemple, vous ne pouvez pas copier une table d'un ensemble de données basé dans l'UE vers un ensemble de données basé aux États-Unis.
  • Lors de la copie de plusieurs tables source vers une table de destination à l'aide de la CLI ou de l'API, toutes les tables source doivent contenir des schémas identiques.
  • Vous ne pouvez supprimer qu'une table à la fois à l'aide de la console, de l'UI Web classique de BigQuery, de l'outil de ligne de commande ou de l'API.
  • Lors de l'exportation des données de table, la seule destination possible est Google Cloud Storage.
  • Lorsque vous atteignez 50 000 tables ou plus dans un ensemble de données, leur énumération est ralentie. Les performances d'énumération sont limitées, que vous utilisiez un appel d'API ou l'UI Web classique de BigQuery. Actuellement, l'UI Web de BigQuery dans la console GCP vous permet d'afficher uniquement 50 000 tables par ensemble de données.

    Pour améliorer les performances de l'UI Web classique de BigQuery, vous pouvez utiliser le paramètre ?minimal pour limiter le nombre de tables affichées à 30 000 par projet. Pour ajouter le paramètre à l'URL de l'UI Web classique de BigQuery, utilisez le format suivant : https://bigquery.cloud.google.com/queries/[PROJECT_NAME]?minimal.

Créer une table

Vous pouvez créer une table dans BigQuery :

  • manuellement, à l'aide de la console GCP, de l'UI Web classique de BigQuery ou de la commande bq mk de l'outil de ligne de commande ;
  • de façon automatisée, en appelant la méthode API tables.insert ;
  • à partir des résultats de la requête ;
  • en définissant une table qui référence une source de données externe ;
  • lorsque vous chargez des données.

Lorsque vous créez une table dans BigQuery, le nom de la table doit être unique pour chaque ensemble de données. Le nom de la table peut :

  • contenir jusqu'à 1 024 caractères ;
  • contenir des lettres (majuscules ou minuscules), des chiffres et des traits de soulignement.

Autorisations requises

Pour créer une table, vous devez disposer d'un accès WRITER au niveau de l'ensemble de données, ou d'un rôle IAM au niveau du projet qui inclut les autorisations bigquery.tables.create. Les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.create :

En outre, étant donné que le rôle bigquery.user dispose des autorisations bigquery.datasets.create, un utilisateur dont le rôle est bigquery.user peut créer des tables dans tous les ensembles de données créés par des utilisateurs. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. L'accès OWNER donne à l'utilisateur un contrôle total sur l'ensemble de données.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la section Contrôle des accès. Pour en savoir plus sur les rôles au niveau de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Créer une table vide avec une définition de schéma

Lorsque vous créez une table vide avec une définition de schéma, vous pouvez :

  • saisir le schéma à l'aide de la console GCP ou de l'UI Web classique de BigQuery ;
  • fournir le schéma en ligne avec l'outil de ligne de commande ;
  • envoyer un fichier de schéma JSON à l'aide de l'outil de ligne de commande ;
  • fournir le schéma dans une ressource de table lorsque vous appelez la méthode API tables.insert.

Pour en savoir plus sur la spécification d'un schéma de table, consultez la page Spécifier un schéma.

Une fois la table créée, vous pouvez y charger des données ou y insérer des données en y écrivant les résultats de la requête.

Pour créer une table vide avec une définition de schéma :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.
    Accéder à l'UI Web de BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données.

  3. À droite de la fenêtre, dans le panneau de détails, cliquez sur Créer une table. Le processus de chargement des données est identique au processus de création d'une table vide.

    Créer une table

  4. Dans la section Source de la page Créer une table, sélectionnez Table vide.

  5. Dans la section Destination de la page Créer une table :

    • Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.

      Sélectionner un ensemble de données

    • Dans le champ Nom de la table, saisissez le nom de la table que vous créez dans BigQuery.

    • Vérifiez que le champ Table type (Type de table) est défini sur Native table (Table native).

  6. Dans la section Schéma, saisissez la définition du schéma.

    • Indiquez manuellement les informations de schéma de l'une des manières suivantes :

      • Activez l'option Modifier sous forme de texte et saisissez le schéma de la table sous forme de tableau JSON.

      • Utilisez l'option Ajouter un champ pour saisir manuellement le schéma.

  7. Dans la section Options avancées, conservez les valeurs par défaut.

  8. Sélectionnez les éléments applicables dans la section Options avancées, puis cliquez sur Créer une table. Pour plus d'informations sur les options disponibles, consultez la section Options JSON.

  9. Cliquez sur Créer une table.

UI classique

  1. Dans le volet de navigation, cliquez sur la flèche vers le bas flèche vers le bas à côté du nom de l'ensemble de données, puis sur Créer une table.

  2. Dans la section Données source de la page Créer une table, cliquez sur Create empty table (Créer une table vide).

  3. Dans la section Destination Table (Table de destination) de la page Create Table (Créer une table) :

    • Dans le champ Table name (Nom de la table), sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table que vous créez.
    • Vérifiez que le champ Table type (Type de table) est défini sur Native table (Table native).
  4. Dans la section Schema (Schéma), saisissez manuellement la définition du schéma.

    • Vous pouvez saisir les informations du schéma manuellement en utilisant les méthodes suivantes :

      • En cliquant sur Modifier sous forme de texte, puis en saisissant le schéma de la table en tant que table JSON

        Ajouter un schéma en tant que tableau JSON

      • En utilisant l'option Ajouter un champ pour saisir le schéma :

        Ajouter un schéma en utilisant l'option d'ajout de champs

  5. Dans la section Options, laissez les valeurs par défaut.

  6. Cliquez sur Créer une table.

Ligne de commande

Utilisez la commande mk avec l'indicateur --table ou -t. Vous pouvez fournir des informations de schéma de table en ligne ou via un fichier de schéma JSON. Les paramètres facultatifs incluent --expiration , --description , --time_partitioning_type , --destination_kms_key et --label. Si vous créez une table dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données au format suivant : [PROJECT_ID]:[DATASET].

--time_partitioning_type et --destination_kms_key ne sont pas démontrés ici. Pour en savoir plus sur --time_partitioning_type, consultez les pages relatives aux tables partitionnées par temps d'ingestion et aux tables partitionnées. Pour en savoir plus sur --destination_kms_key, consultez la page relative aux clés de chiffrement gérées par le client.

Pour créer une table vide dans un ensemble de données existant avec une définition de schéma, entrez :

bq mk --table --expiration [INTEGER] --description [DESCRIPTION] --label [KEY:VALUE, KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

Où :

  • [INTEGER] est la durée de vie par défaut (en secondes) de la table. La valeur minimale est de 3 600 secondes (une heure). L'heure d'expiration correspond à l'heure actuelle plus la valeur entière. Si vous définissez le délai d'expiration lorsque vous créez une table, le paramètre d'expiration de la table par défaut de l'ensemble de données est ignoré.
  • [DESCRIPTION] est une description de la table entre guillemets.
  • [KEY:VALUE] est la paire clé/valeur qui représente une étiquette. Vous pouvez entrer plusieurs étiquettes en utilisant une liste séparée par des virgules.
  • [PROJECT_ID] correspond à l'ID de votre projet.
  • [DATASET] correspond à un ensemble de données dans votre projet.
  • [TABLE] est le nom de la table que vous créez.
  • [SCHEMA] est une définition de schéma en ligne au format [FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] ou le chemin d'accès au fichier de schéma JSON sur votre machine locale.

Lorsque vous spécifiez le schéma dans la ligne de commande, vous ne pouvez pas inclure un type RECORD (STRUCT) ou une description de colonne, ni spécifier le mode de la colonne. Tous les modes sont définis sur NULLABLE par défaut. Pour inclure des descriptions, des modes et des types RECORD, il est recommandé de fournir un fichier de schéma JSON à la place.

Exemples :

Saisissez la commande suivante pour créer une table à l'aide d'une définition de schéma en ligne. Cette commande crée une table nommée mytable dans mydataset dans votre projet par défaut. L'expiration de la table est définie sur 3 600 secondes (1 heure), la description est définie sur This is my table et l'étiquette est définie sur organization:development. La commande utilise le raccourci -t au lieu de --table. Le schéma est spécifié en ligne comme suit : qtr:STRING,sales:FLOAT,year:STRING.

bq mk -t --expiration 3600 --description "This is my table" --label organization:development mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

Saisissez la commande ci-dessous pour créer une table à l'aide d'un fichier de schéma JSON. Cette commande crée une table nommée mytable dans mydataset dans votre projet par défaut. L'expiration de la table est définie sur 3 600 secondes (1 heure), la description est définie sur This is my table et l'étiquette est définie sur organization:development. Le chemin d'accès au fichier de schéma est : /tmp/myschema.json.

bq mk --table --expiration 3600 --description "This is my table" --label organization:development mydataset.mytable /tmp/myschema.json

Saisissez la commande suivante pour créer une table à l'aide d'un fichier de schéma JSON. Cette commande crée une table nommée mytable dans mydataset et myotherproject. L'expiration de la table est définie sur 3 600 secondes (1 heure), la description est définie sur This is my table et l'étiquette est définie sur organization:development. Le chemin d'accès au fichier de schéma est : /tmp/myschema.json.

bq mk --table --expiration 3600 --description "This is my table" --label organization:development myotherproject:mydataset.mytable /tmp/myschema.json

Une fois la table créée, vous pouvez mettre à jour son délai d'expiration, sa description et ses étiquettes. Vous pouvez également modifier la définition du schéma.

API

Appelez la méthode tables.insert avec une ressource de table définie.

C#

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour C# dans le 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 C#.

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

sampleSchema := bigquery.Schema{
	{Name: "full_name", Type: bigquery.StringFieldType},
	{Name: "age", Type: bigquery.IntegerFieldType},
}

metaData := &bigquery.TableMetadata{
	Schema:         sampleSchema,
	ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metaData); err != nil {
	return err
}

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le 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 Java.

TableId tableId = TableId.of(datasetName, tableName);
// Table field definition
Field field = Field.of(fieldName, LegacySQLTypeName.STRING);
// Table schema definition
Schema schema = Schema.of(field);
TableDefinition tableDefinition = StandardTableDefinition.of(schema);
TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();
Table table = bigquery.create(tableInfo);

Node.js

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js dans le 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 Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

async function createTable() {
  // Creates a new table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_new_dataset";
  // const tableId = "my_new_table";
  // const schema = "Name:string, Age:integer, Weight:float, IsMagic:boolean";

  // Create a client
  const bigqueryClient = new BigQuery();

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
  };

  // Create a new table in the dataset
  const [table] = await bigqueryClient
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created.`);
}
createTable();

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP dans le 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 PHP.

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId = 'The BigQuery table ID';
// $fields = [
//    [
//        'name' => 'field1',
//        'type' => 'string',
//        'mode' => 'required'
//    ],
//    [
//        'name' => 'field2',
//        'type' => 'integer'
//    ],
//];

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$schema = ['fields' => $fields];
$table = $dataset->createTable($tableId, ['schema' => $schema]);
printf('Created table %s' . PHP_EOL, $tableId);

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

from google.cloud import bigquery

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create
# table_id = "your-project.your_dataset.your_table_name"

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Ruby

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Ruby dans le 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 Ruby.

require "google/cloud/bigquery"

def create_table dataset_id = "my_dataset"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "my_table"

  table = dataset.create_table table_id do |updater|
    updater.string  "full_name", mode: :required
    updater.integer "age",       mode: :required
  end

  puts "Created table: #{table_id}"
end

Créer une table à partir d'un résultat de requête

Pour créer une table à partir d'un résultat de requête, écrivez les résultats dans une table de destination.

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.
    Accéder à l'UI Web de BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données.

  3. Si l'éditeur de requête est masqué, cliquez sur Afficher l'éditeur en haut à droite de la fenêtre.

  4. Saisissez une requête SQL valide dans la zone de texte de l'éditeur de requête.

  5. Sous l'éditeur, cliquez sur More (Plus) et sélectionnez Query settings (Paramètres de requête).

    Paramètres de requête

  6. Cochez la case Set a destination table for query results (Définir une table de destination pour les résultats de la requête).

    Définir la destination

  7. Dans la section Destination, sélectionnez le nom du projet et le nom de l'ensemble de données où la table doit être créée, puis choisissez le nom de la table.

  8. Dans la section Préférence d'écriture pour la table de destination, choisissez l'une des options suivantes :

    • Écrire si la table est vide : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Ajouter à la table : ajoute les résultats de requête à une table existante.
    • Écraser la table : écrase une table existante portant le même nom à l'aide des résultats de requête.
  9. (Facultatif) Dans le champ Zone de traitement, cliquez sur Sélection automatique et choisissez l'emplacement de vos données.

  10. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats dans la table spécifiée.

Si vous oubliez de spécifier une table de destination avant d'exécuter la requête, vous pouvez copier la table temporaire dans une table permanente. Pour ce faire, cliquez sur le bouton Enregistrer l'affichage situé sous l'éditeur.

UI classique

Option 1 : Utiliser une instruction LDD

Les instructions LDD (langage de définition de données) vous permettent de créer et modifier des tables à l'aide de la syntaxe de requête SQL standard.

Pour plus d'informations, consultez la page relative à l'instruction CREATE TABLE et l'exemple CREATE TABLE : Créer une table à partir d'une table existante.

Option 2 : Utiliser l'UI Web classique

  1. Accédez à l'UI Web classique de BigQuery.
    Accéder à l'UI Web classique de BigQuery

  2. Cliquez sur le bouton Saisir une requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte Nouvelle requête.

  4. Cliquez sur Afficher les options.

  5. Dans la section Table de destination, cliquez sur Sélectionner une table.

  6. Dans la boîte de dialogue Sélectionner une table de destination :

    1. Pour Projet, choisissez le projet où la table de destination sera créée.

    2. Pour Ensemble de données, choisissez l'ensemble de données où sera stockée la table.

    3. Dans le champ ID de la table, saisissez un nom de table. Le nom doit être unique dans l'ensemble de données de destination. Le nom de la table peut contenir jusqu'à 1 024 caractères et uniquement les caractères de a à z, A à Z, 0 à 9 ou _ (le trait de soulignement).

    4. Cliquez sur OK.

  7. Dans la section Table de destination, pour Préférence d'écriture, sélectionnez l'une des options suivantes :

    • Écrire si la table est vide : n'écrit les résultats de requête dans la table que si celle-ci est vide.
    • Ajouter à la table : ajoute les résultats de requête à une table existante.
    • Écraser la table : écrase une table existante portant le même nom à l'aide des résultats de requête.
  8. (Facultatif) Dans le champ Zone de traitement, cliquez sur Non spécifiée et sélectionnez l'emplacement de vos données.

  9. Cliquez sur Exécuter la requête. Cette action crée une tâche de requête qui écrit les résultats dans la table spécifiée.

Si vous oubliez de spécifier une table de destination avant d'exécuter la requête, vous pouvez copier la table temporaire dans une table permanente. Pour ce faire, cliquez sur le bouton Enregistrer en tant que table dans la fenêtre des résultats.

CLI

Saisissez la commande bq query et spécifiez l'indicateur --destination_table pour créer une table permanente en fonction des résultats de requête. Spécifiez l'indicateur use_legacy_sql=false pour utiliser la syntaxe SQL standard. Pour écrire les résultats de requête dans une table qui ne se trouve pas dans votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en respectant le format suivant : [PROJECT_ID]:[DATASET].

Définissez l'indicateur --location sur la valeur correspondant à votre emplacement.

Pour contrôler la disposition en écriture d'une table de destination existante, fournissez l'un des indicateurs facultatifs suivants :

  • --append_table : si la table de destination existe, les résultats de requête y sont ajoutés.
  • --replace : si la table de destination existe, elle est remplacée par les résultats de requête.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --use_legacy_sql=false '[QUERY]'
    

Où :

  • [LOCATION] est le nom de l'emplacement utilisé pour traiter la requête. Cet indicateur --location est facultatif. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données contenant la table dans laquelle vous écrivez les résultats de requête.
  • [TABLE] est le nom de la table dans laquelle vous écrivez les résultats de requête.
  • [QUERY] est une requête en syntaxe SQL standard.

Si aucun indicateur de disposition en écriture n'est spécifié, le comportement par défaut consiste à écrire les résultats dans la table uniquement si celle-ci est vide. Si la table existe et qu'elle n'est pas vide, l'erreur suivante est renvoyée : BigQuery error in query operation: Error processing job '[PROJECT_ID]:bqjob_123abc456789_00000e1234f_1': Already Exists: Table [PROJECT_ID]:[DATASET].[TABLE].

Exemples :

Saisissez la commande suivante pour écrire les résultats de requête dans une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. Aucun indicateur de disposition en écriture n'étant spécifié dans la commande, la table doit être nouvelle ou vide. Sinon, une erreur Already exists est renvoyée. La requête extrait les données de l'ensemble de données public USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Saisissez la commande suivante pour utiliser les résultats de requête afin d'écraser une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans votre projet par défaut. La commande utilise l'indicateur --replace pour écraser la table de destination.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Saisissez la commande suivante pour ajouter des résultats de requête à une table de destination nommée mytable dans mydataset. L'ensemble de données se trouve dans myotherproject, et non dans votre projet par défaut. La commande utilise l'indicateur --append pour ajouter les résultats de requête à la table de destination.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

API

Pour enregistrer des résultats de requête dans une table permanente, appelez la méthode jobs.insert, configurez une tâche de type query et incluez une valeur pour la propriété destinationTable. Pour contrôler la disposition en écriture d'une table de destination existante, configurez la propriété writeDisposition.

Spécifiez l'emplacement dans la propriété location de la section jobReference de la ressource de tâche.

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

q := client.Query("SELECT 17 as my_col")
q.Location = "US" // Location must match the dataset(s) referenced in query.
q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le 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 Java.

Pour enregistrer des résultats de requête dans une table permanente, définissez la table de destination sur l'identifiant TableId souhaité dans une configuration QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

Pour enregistrer des résultats de requête dans une table permanente, créez une configuration QueryJobConfig et définissez la destination sur la valeur TableReference souhaitée. Transmettez la configuration de la tâche à la méthode de requête.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

Créer une table faisant référence à une source de données externe

Une source de données externe (également appelée source de données fédérée) peut être interrogée directement, même si les données ne sont pas stockées dans BigQuery. Au lieu de charger ou de diffuser les données, vous créez une table qui renvoie à la source de données externe.

BigQuery prend en charge l'interrogation directe de données depuis :

Vous pouvez interroger des données dans une source de données externe compatible en créant une table temporaire ou permanente qui référence les données stockées dans la source de données externe. Pour plus d'informations sur l'utilisation des sources de données externes, consultez :

Créer une table lorsque vous chargez des données

Lorsque vous chargez des données dans BigQuery, vous pouvez charger des données dans une nouvelle table ou partition, les ajouter à une table ou une partition existante, ou bien les utiliser pour écraser une table ou une partition. Vous n'avez pas besoin de créer une table vide avant de charger des données. Vous pouvez créer la table et charger vos données en même temps.

Lorsque vous chargez des données dans BigQuery, vous pouvez fournir le schéma de table ou de partition. Pour les formats de données compatibles, vous pouvez également utiliser la détection automatique de schéma.

Pour en savoir plus sur le chargement des données, consultez la page intitulée Présentation du chargement de données dans BigQuery.

Contrôler l'accès aux tables

Vous ne pouvez pas attribuer directement de contrôles d'accès aux tables. Vous pouvez contrôler l'accès aux tables en configurant les contrôles d'accès au niveau de l'ensemble de données ou au niveau du projet.

Les contrôles d'accès au niveau d'un ensemble de données spécifient les opérations que les utilisateurs, les groupes et les comptes de service sont autorisés à effectuer sur les tables de cet ensemble de données. Si vous n'attribuez que des autorisations au niveau de l'ensemble de données, vous devez également attribuer un rôle primitif ou prédéfini au niveau du projet permettant d'accéder au projet, par exemple, bigquery.user.

Au lieu d'accorder l'accès à des ensembles de données individuels, vous pouvez affecter des rôles IAM prédéfinis au niveau du projet qui autorisent l'accès aux données de toutes les tables de tous les ensembles de données d'un projet.

Vous pouvez également créer des rôles personnalisés IAM. Si vous créez un rôle personnalisé, les autorisations que vous attribuez dépendent des opérations sur les tables que vous souhaitez que l'utilisateur, le groupe ou le compte de service puisse effectuer.

Pour en savoir plus sur les rôles et les autorisations, consultez les pages suivantes :

Pour plus d'informations sur l'utilisation des données de table, consultez la section Gérer des données de table.

Utiliser les tables

Obtenir des informations sur les tables

Vous pouvez obtenir des informations ou des métadonnées sur les tables de différentes manières :

  • Utilisation de la console GCP ou de l'UI Web classique de BigQuery
  • Utilisation de la commande CLI bq show
  • Appel de la méthode API tables.get
  • Interrogation des vues INFORMATION_SCHEMA (version bêta)

Autorisations requises

Pour obtenir des informations sur des tables, vous devez disposer du rôle READER au niveau de l'ensemble de données ou détenir au niveau du projet un rôle IAM qui comprend les autorisations bigquery.tables.get. Si vous disposez des autorisations bigquery.tables.get au niveau du projet, vous pouvez obtenir des informations sur toutes les tables du projet. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.get, à l'exception de bigquery.jobUser et bigquery.user.

En outre, comme le rôle bigquery.user dispose des autorisations bigquery.datasets.create, un utilisateur ayant le rôle bigquery.user peut obtenir des informations sur les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. Un accès OWNER à un ensemble de données confère à l'utilisateur un contrôle total sur cet ensemble et sur toutes les tables qu'il contient.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Obtenir des informations sur la table

Pour obtenir des informations sur les tables :

Console

  1. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données. Cliquez sur le nom de l'ensemble de données pour le développer. Les tables et vues de ce dernier s'affichent.

  2. Cliquez sur le nom de la table.

  3. Sous l'éditeur, cliquez sur Détails. Cette page affiche la description de la table et ses informations.

  4. Cliquez sur l'onglet Schéma pour afficher la définition du schéma de la table.

UI classique

  1. Dans le volet de navigation, cliquez sur la flèche vers le bas flèche vers le bas située à gauche de l'ensemble de données pour le développer, ou double-cliquez sur le nom de l'ensemble de données. Les tables et vues de ce dernier s'affichent.

  2. Cliquez sur le nom de la table.

  3. Cliquez sur Détails. La page Détails de la table affiche la description et les informations relatives à la table.

    Afficher les détails de la table

  4. Cliquez sur l'onglet Schéma pour afficher la définition du schéma de la table.

CLI

Exécutez la commande bq show pour afficher toutes les informations de la table. Utilisez l'indicateur --schema pour n'afficher que les informations du schéma de table. Vous pouvez contrôler le résultat à l'aide de l'indicateur --format.

Si vous souhaitez obtenir des informations sur une table dans un projet différent du projet par défaut, ajoutez l'ID du projet à l'ensemble de données au format suivant : [PROJECT_ID]:[DATASET].

bq show --schema --format=prettyjson [PROJECT_ID]:[DATASET].[TABLE]

Où :

  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données.
  • [TABLE] est le nom de la table.

Exemples :

Saisissez la commande suivante pour afficher toutes les informations sur mytable dans mydataset. mydataset se trouve dans votre projet par défaut.

bq show --format=prettyjson mydataset.mytable

Saisissez la commande suivante pour afficher toutes les informations sur mytable dans mydataset. mydataset se trouve dans myotherproject, pas dans votre projet par défaut.

bq show --format=prettyjson myotherproject:mydataset.mytable

Saisissez la commande suivante pour n'afficher que les informations du schéma sur mytable dans mydataset. mydataset se trouve dans myotherproject, pas dans votre projet par défaut.

bq show --schema --format=prettyjson myotherproject:mydataset.mytable

API

Appelez la méthode tables.get et indiquez tous les paramètres pertinents.

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
if err != nil {
	return err
}
// Print basic information about the table.
fmt.Printf("Schema has %d top-level fields\n", len(meta.Schema))
fmt.Printf("Description: %s\n", meta.Description)
fmt.Printf("Row in managed storage: %d\n", meta.NumRows)

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le 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 Java.

TableId tableId = TableId.of(projectId, datasetName, tableName);
Table table = bigquery.getTable(tableId);

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP dans le 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 PHP.

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
//$projectId = 'The Google project ID';
//$datasetId = 'The BigQuery dataset ID';
//$tableId   = 'The BigQuery table ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)

print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)

# View table properties
print("Table schema: {}".format(table.schema))
print("Table description: {}".format(table.description))
print("Table has {} rows".format(table.num_rows))

Obtenir des informations sur les tables à l'aide de INFORMATION_SCHEMA (version bêta)

INFORMATION_SCHEMA est une série de vues offrant un accès aux métadonnées sur les ensembles de données, les tables et les vues.

Vous pouvez interroger les vues INFORMATION_SCHEMA.TABLES et INFORMATION_SCHEMA.TABLE_OPTIONS pour récupérer des métadonnées sur les tables et les vues d'un projet. Vous pouvez également interroger les vues INFORMATION_SCHEMA.COLUMNS et INFORMATION_SCHEMA.COLUMN_FIELD_PATHS pour récupérer des métadonnées sur les colonnes (champs) d'une table.

Les vues TABLES et TABLE_OPTIONS contiennent également des informations générales sur les vues. Pour obtenir des informations détaillées, interrogez plutôt la vue INFORMATION_SCHEMA.VIEWS.

Vue TABLES

Lorsque vous interrogez la vue INFORMATION_SCHEMA.TABLES, les résultats de la requête contiennent une ligne pour chaque table ou vue d'un ensemble de données.

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.TABLES doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables ou les vues.

La vue INFORMATION_SCHEMA.TABLES présente le schéma suivant :

Nom de la colonne Type de données Valeur
TABLE_CATALOG STRING Nom du projet qui contient l'ensemble de données
TABLE_SCHEMA STRING Nom de l'ensemble de données contenant la table ou la vue (également appelé datasetId)
TABLE_NAME STRING Nom de la table ou de la vue (également appelé tableId)
TABLE_TYPE STRING Type de table :
IS_INSERTABLE_INTO STRING YES ou NO suivant que la table accepte ou non les instructions LMD
IS_TYPED STRING La valeur est toujours NO
CREATION_TIME TIMESTAMP Date/Heure de création de la table

Pour en savoir plus sur les propriétés des ensembles de données, consultez la page relative à la ressource d'ensemble de données dans la documentation de l'API REST. Pour en savoir plus sur les propriétés des tables et des vues, consultez la page relative à la ressource de table dans la documentation de l'API REST.

Exemples

Exemple 1 :

L'exemple suivant récupère toutes les colonnes de la vue INFORMATION_SCHEMA.TABLES, à l'exception de is_typed qui est réservée en vue d'une utilisation ultérieure. Les métadonnées renvoyées concernent toutes les tables de l'ensemble de données mydataset de votre projet par défaut (myproject).

mydataset contient les tables suivantes :

  • mytable1 : table BigQuery standard
  • myview1 : vue BigQuery

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.TABLES doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

Pour exécuter la requête sur un projet autre que celui par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] , par exemple, `myproject`.mydataset.INFORMATION_SCHEMA.TABLES.

Pour exécuter la requête :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez la requête SQL standard suivante dans la zone Éditeur de requête. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans la console GCP.

    SELECT
     * EXCEPT(is_typed)
    FROM
     mydataset.INFORMATION_SCHEMA.TABLES
    
  3. Cliquez sur Exécuter.

Ligne de commande

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'indicateur --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez la commande suivante :

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES'

Les résultats doivent se présenter sous la forme suivante :

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 |
  | myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  

Exemple 2 :

L'exemple suivant récupère toutes les tables de type BASE TABLE de la vue INFORMATION_SCHEMA.TABLES. La colonne is_typed est exclue. Les métadonnées renvoyées concernent les tables de l'ensemble de données mydataset de votre projet par défaut (myproject).

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.TABLES doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

Pour exécuter la requête sur un projet autre que celui par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] , par exemple, `myproject`.mydataset.INFORMATION_SCHEMA.TABLES.

Pour exécuter la requête :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez la requête SQL standard suivante dans la zone Éditeur de requête. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans la console GCP.

    SELECT
     * EXCEPT(is_typed)
    FROM
     mydataset.INFORMATION_SCHEMA.TABLES
    WHERE
     table_type="BASE TABLE"
    
  3. Cliquez sur Exécuter.

Ligne de commande

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'indicateur --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez la commande suivante :

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES
WHERE table_type="BASE TABLE"'

Les résultats doivent se présenter sous la forme suivante :

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | NO                 | 2018-10-31 22:40:05 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  

Vue TABLE_OPTIONS

Lorsque vous interrogez la vue INFORMATION_SCHEMA.TABLE_OPTIONS, les résultats de la requête contiennent une ligne pour chaque table ou vue d'un ensemble de données.

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.TABLE_OPTIONS doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables ou les vues.

La vue INFORMATION_SCHEMA.TABLE_OPTIONS présente le schéma suivant :

Nom de la colonne Type de données Valeur
TABLE_CATALOG STRING Nom du projet qui contient l'ensemble de données
TABLE_SCHEMA STRING Nom de l'ensemble de données contenant la table ou la vue (également appelé datasetId)
TABLE_NAME STRING Nom de la table ou de la vue (également appelé tableId)
OPTION_NAME STRING Une des valeurs de nom figurant dans la table d'options
OPTION_TYPE STRING Une des valeurs de type de données figurant dans la table d'options
OPTION_VALUE STRING Une des options de valeur figurant dans la table d'options
Table d'options
OPTION_NAME OPTION_TYPE OPTION_VALUE
partition_expiration_days FLOAT64 Durée de vie par défaut, en jours, de toutes les partitions d'une table partitionnée
expiration_timestamp FLOAT64 Durée de vie par défaut, en jours, de la table
kms_key_name STRING Nom de la clé Cloud KMS employée pour chiffrer la table
friendly_name STRING Nom descriptif de la table
description STRING Description de la table
labels ARRAY<STRUCT<STRING, STRING>> Tableau de valeurs STRUCT représentant les étiquettes de la table

Pour en savoir plus sur les propriétés des ensembles de données, consultez la page relative à la ressource d'ensemble de données dans la documentation de l'API REST. Pour en savoir plus sur les propriétés des tables et des vues, consultez la page relative à la ressource de table dans la documentation de l'API REST.

Exemples

Exemple 1 :

L'exemple suivant récupère les délais d'expiration par défaut pour toutes les tables de l'ensemble de données mydataset de votre projet par défaut (myproject) en interrogeant la vue INFORMATION_SCHEMATA.TABLE_OPTIONS.

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.TABLE_OPTIONS doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

Pour exécuter la requête sur un projet autre que celui par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] , par exemple, `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS.

Pour exécuter la requête :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez la requête SQL standard suivante dans la zone Éditeur de requête. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans la console GCP.

    SELECT
     *
    FROM
     mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE
     option_name="expiration_timestamp"
    
  3. Cliquez sur Exécuter.

Ligne de commande

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'indicateur --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez la commande suivante :

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="expiration_timestamp"'

Les résultats doivent se présenter sous la forme suivante :

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  

Exemple 2 :

L'exemple suivant récupère les métadonnées sur toutes les tables de l'ensemble de données mydataset contenant des données de test. La requête utilise les valeurs de l'option description pour rechercher les tables dont la description contient "test". mydataset se trouve dans votre projet par défaut (myproject).

Pour exécuter la requête sur un projet autre que celui par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] , par exemple, `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS.

Pour exécuter la requête :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez la requête SQL standard suivante dans la zone Éditeur de requête. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans la console GCP.

    SELECT
     *
    FROM
     mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE
     option_name="description" AND option_value LIKE "%test%"
    
  3. Cliquez sur Exécuter.

Ligne de commande

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'indicateur --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez la commande suivante :

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="description" AND option_value LIKE "%test%"'

Les résultats doivent se présenter sous la forme suivante :

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+
  

Vue COLUMNS

Lorsque vous interrogez la vue INFORMATION_SCHEMA.COLUMNS, les résultats de la requête contiennent une ligne pour chaque colonne (champ) d'une table.

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.COLUMNS doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

La vue INFORMATION_SCHEMA.COLUMNS présente le schéma suivant :

Nom de la colonne Type de données Valeur
TABLE_CATALOG STRING Nom du projet qui contient l'ensemble de données
TABLE_SCHEMA STRING Nom de l'ensemble de données contenant la table (également appelé datasetId)
TABLE_NAME STRING Nom de la table ou de la vue (également appelé tableId)
COLUMN_NAME STRING Nom de la colonne
ORDINAL_POSITION INT64 Décalage avec un indice de 1 de la colonne dans la table. S'il s'agit d'une pseudo-colonne telle que _PARTITIONTIME ou _PARTITIONDATE, la valeur est NULL.
IS_NULLABLE STRING YES ou NO selon que le mode de la colonne autorise ou non les valeurs NULL
DATA_TYPE STRING Type de données SQL standard de la colonne
IS_GENERATED STRING La valeur est toujours NEVER
GENERATION_EXPRESSION STRING La valeur est toujours NULL
IS_STORED STRING La valeur est toujours NULL
IS_HIDDEN STRING YES ou NO selon que la colonne est une pseudo-colonne telle que _PARTITIONTIME ou _PARTITIONDATE
IS_UPDATABLE STRING La valeur est toujours NULL
IS_SYSTEM_DEFINED STRING YES ou NO selon que la colonne est une pseudo-colonne telle que _PARTITIONTIME ou _PARTITIONDATE
IS_PARTITIONING_COLUMN STRING YES ou NO selon que la colonne est une colonne de partitionnement ou non
CLUSTERING_ORDINAL_POSITION STRING Décalage avec un indice de 1 de la colonne dans les colonnes de clustering de la table. La valeur est NULL si la table n'est pas une table en cluster.

Pour en savoir plus sur les propriétés des ensembles de données, consultez la page relative à la ressource d'ensemble de données dans la documentation de l'API REST. Pour en savoir plus sur les propriétés des tables et des vues, consultez la page relative à la ressource de table dans la documentation de l'API REST.

Exemples

L'exemple suivant récupère les métadonnées de la vue INFORMATION_SCHEMA.COLUMNS pour la table population_by_zip_2010 de l'ensemble de données census_bureau_usa. Ce dernier fait partie du programme d'ensembles de données publics de BigQuery.

Comme cette table se trouve dans le projet bigquery-public-data, ajoutez l'ID de ce dernier à l'ensemble de données, en respectant le format suivant : `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] , par exemple, `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES.

Les colonnes suivantes sont exclues des résultats de la requête, car elles sont actuellement réservées en vue d'une utilisation ultérieure :

  • IS_GENERATED
  • GENERATION_EXPRESSION
  • IS_STORED
  • IS_UPDATABLE

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.COLUMNS doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

Pour exécuter la requête :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez la requête SQL standard suivante dans la zone Éditeur de requête. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans la console GCP.

    SELECT
     * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
    FROM
     `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
    WHERE
     table_name="population_by_zip_2010"
    
  3. Cliquez sur Exécuter.

Ligne de commande

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'indicateur --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez la commande suivante :

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
FROM `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
WHERE table_name="population_by_zip_2010"'

Les résultats doivent se présenter sous la forme suivante. Pour des raisons de lisibilité, les colonnes table_catalog et table_schema sont exclues des résultats :

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
  

Vue COLUMN_FIELD_PATHS

Lorsque vous interrogez la vue INFORMATION_SCHEMA.COLUMN_FIELD_PATHS, les résultats de la requête contiennent une ligne pour chaque colonne imbriquée dans une colonne RECORD (ou STRUCT).

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.COLUMN_FIELD_PATHS doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

La vue INFORMATION_SCHEMA.COLUMN_FIELD_PATHS présente le schéma suivant :

Nom de la colonne Type de données Value
TABLE_CATALOG > STRING Nom du projet qui contient l'ensemble de données
TABLE_SCHEMA STRING Nom de l'ensemble de données contenant la table (également appelé datasetId)
TABLE_NAME STRING Nom de la table ou de la vue (également appelé tableId)
COLUMN_NAME STRING Nom de la colonne
FIELD_PATH STRING Chemin d'accès à une colonne imbriquée dans une colonne RECORD (ou STRUCT)
DATA_TYPE STRING Type de données SQL standard de la colonne
DESCRIPTION STRING Description de la colonne

Pour en savoir plus sur les propriétés des ensembles de données, consultez la page relative à la ressource d'ensemble de données dans la documentation de l'API REST. Pour en savoir plus sur les propriétés des tables et des vues, consultez la page relative à la ressource de table dans la documentation de l'API REST.

Exemples

L'exemple suivant récupère les métadonnées de la vue INFORMATION_SCHEMA.COLUMN_FIELD_PATHS pour la table commits de l'ensemble de données github_repos. Ce dernier fait partie du programme d'ensembles de données publics de BigQuery.

Comme cette table se trouve dans le projet bigquery-public-data, ajoutez l'ID de ce dernier à l'ensemble de données, en respectant le format suivant : `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW], par exemple, `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS.

La table commits contient les colonnes imbriquées ainsi que les colonnes imbriquées et répétées suivantes :

  • author : colonne RECORD imbriquée
  • committer : colonne RECORD imbriquée
  • trailer : colonne RECORD imbriquée et répétée
  • difference : colonne RECORD imbriquée et répétée

La requête récupérera des métadonnées sur les colonnes author et difference.

Les requêtes exécutées sur la vue INFORMATION_SCHEMA.COLUMN_FIELD_PATHS doivent avoir un qualificatif d'ensemble de données. L'utilisateur qui soumet la requête doit avoir accès à l'ensemble de données contenant les tables.

Pour exécuter la requête :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Saisissez la requête SQL standard suivante dans la zone Éditeur de requête. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans la console GCP.

    SELECT
     *
    FROM
     `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
    WHERE
     table_name="commits"
     AND column_name="author"
     OR column_name="difference"
    
  3. Cliquez sur Exécuter.

Ligne de commande

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'indicateur --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez la commande suivante :

bq query --nouse_legacy_sql \
'SELECT * FROM `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE table_name="commits" AND column_name="author" OR column_name="difference"'

Les résultats doivent se présenter sous la forme suivante. Pour des raisons de lisibilité, les colonnes table_catalog et table_schema sont exclues des résultats.

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  

Répertorier des tables dans un ensemble de données

Vous pouvez répertorier les tables d'ensembles de données selon les méthodes suivantes :

  • Utilisation de la console GCP ou de l'UI Web classique de BigQuery
  • Utilisation de la commande CLI bq ls
  • Appel de la méthode API tables.list

Autorisations requises

Pour répertorier les tables d'un ensemble de données, vous devez disposer du rôle READER (lecteur) au niveau de l'ensemble de données, ou bien d'un rôle IAM au niveau du projet qui inclut les autorisations bigquery.tables.list. Si vous disposez d'autorisations bigquery.tables.list au niveau du projet, vous pouvez répertorier les tables dans tous les ensembles de données du projet. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.list, à l'exception de bigquery.jobUser.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la section Contrôle des accès. Pour en savoir plus sur les rôles au niveau de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Répertorier des tables

Pour répertorier les tables dans un ensemble de données :

Console

  1. Dans le volet de navigation de l'interface utilisateur Web, cliquez sur la flèche vers le bas flèche vers le bas située à gauche de l'ensemble de données pour le développer, ou double-cliquez sur le nom de l'ensemble de données. Les tables et vues de ce dernier s'affichent.

  2. Faites défiler la liste pour voir les tables de l'ensemble de données. Les tables et les vues sont identifiées par des icônes différentes.

UI classique

  1. Dans le volet de navigation de l'interface utilisateur Web, cliquez sur la flèche vers le bas flèche vers le bas située à gauche de l'ensemble de données pour le développer, ou double-cliquez sur le nom de l'ensemble de données. Les tables et vues de ce dernier s'affichent.

  2. Faites défiler la liste pour voir les tables de l'ensemble de données. Les tables et les vues sont identifiées par des icônes différentes.

    Afficher des tables

Ligne de commande

Exécutez la commande bq ls. L'indicateur --format peut être utilisé pour contrôler la sortie. Si vous répertoriez des tables dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données au format suivant : [PROJECT_ID]:[DATASET].

Les indicateurs supplémentaires comprennent les éléments suivants :

  • --max_results ou -n : entier indiquant le nombre maximal de résultats. La valeur par défaut est 50.

    bq ls --format=pretty --max_results [INTEGER] [PROJECT_ID]:[DATASET]
    

Où :

  • [INTEGER] est un entier représentant le nombre de tables à répertorier.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données.

Lorsque vous exécutez la commande, le champ Type affiche TABLE ou VIEW. Par exemple :

+-------------------------+-------+----------------------+-------------------+
|         tableId         | Type  |        Labels        | Time Partitioning |
+-------------------------+-------+----------------------+-------------------+
| mytable                 | TABLE | department:shipping  |                   |
| myview                  | VIEW  |                      |                   |
+-------------------------+-------+----------------------+-------------------+

Exemples :

Saisissez la commande suivante pour répertorier les tables de l'ensemble de données mydataset dans votre projet par défaut.

bq ls --format=pretty mydataset

Saisissez la commande suivante pour renvoyer plus de résultats que la sortie par défaut, correspondant à 50 tables de mydataset. L'ensemble de données mydataset se situe dans votre projet par défaut.

bq ls --format=pretty --max_results 60 mydataset

Saisissez la commande suivante pour répertorier les tables de l'ensemble de données mydataset dans myotherproject.

bq ls --format=pretty myotherproject:mydataset

API

Pour répertorier les tables avec l'API, appelez la méthode tables.list.

C#

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour C# dans le 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 C#.

using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryListTables
{
    public void ListTables(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Retrieve list of tables in the dataset
        List<BigQueryTable> tables = client.ListTables(datasetId).ToList();
        // Display the results
        if (tables.Count > 0)
        {
            Console.WriteLine($"Tables in dataset {datasetId}:");
            foreach (var table in tables)
            {
                Console.WriteLine($"\t{table.Reference.TableId}");
            }
        }
        else
        {
            Console.WriteLine($"{datasetId} does not contain any tables.");
        }
    }
}

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

ts := client.Dataset(datasetID).Tables(ctx)
for {
	t, err := ts.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Table: %q\n", t.TableID)
}

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le 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 Java.

DatasetId datasetId = DatasetId.of(projectId, datasetName);
Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
for (Table table : tables.iterateAll()) {
  // do something with the table
}

Node.js

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js dans le 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 Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const datasetId = "my_dataset";

// Create a client
const bigqueryClient = new BigQuery();

async function listTables() {
  // Lists tables in "my_dataset".

  // List all tables in the dataset
  const [tables] = await bigqueryClient.dataset(datasetId).getTables();

  console.log('Tables:');
  tables.forEach(table => console.log(table.id));
}
listTables();

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP dans le 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 PHP.

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$tables = $dataset->tables();
foreach ($tables as $table) {
    print($table->id() . PHP_EOL);
}

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Ruby

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Ruby dans le 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 Ruby.

require "google/cloud/bigquery"

def list_tables dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id

  puts "Tables in dataset #{dataset_id}:"
  dataset.tables.each do |table|
    puts "\t#{table.table_id}"
  end
end

Étapes suivantes

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.