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 des métadonnées de table à l'aide de métatables.

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 de la table

Les tables BigQuery sont soumises aux limitations suivantes :

  • Les noms de table doivent être spécifiques pour chaque ensemble de données.
  • L'UI Web de BigQuery permet la copie d'une seule 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 l'UI Web de BigQuery, de l'outil de ligne de commande et 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 si vous utilisez un appel d'API, l'UI Web de BigQuery ou la métatable __TABLES_SUMMARY__. Pour améliorer les performances de l'UI, vous pouvez utiliser le paramètre ?minimal pour limiter le chargement à 30 000 tables par projet. Pour ajouter le paramètre à l'URL de l'UI Web 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 l'UI Web 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 bien d'un rôle IAM au niveau du projet qui inclut les autorisations bigquery.tables.create. Les rôles IAM suivants, prédéfinis au niveau du projet, incluent ces 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 autorisations et les rôles 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.

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 l'UI Web ;
  • fournir le schéma en ligne à l'aide de 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 plus d'informations sur la spécification d'un schéma de table, consultez la section 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 :

Interface utilisateur Web

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

  2. Dans la section Données sources de la page Créer une table, cliquez sur 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 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 tableau 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 sections relatives aux tables partitionnées par date d'ingestion ou aux tables partitionnées. Pour en savoir plus sur --destination_kms_key, consultez la section 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). Le délai 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 du tableau 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 un libellé. Vous pouvez entrer plusieurs libellés 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 sur 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.

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 du tableau est définie sur 3 600 secondes (1 heure), la description est définie sur This is my table et le libellé est défini 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 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 dans votre projet par défaut. L'expiration du tableau est définie sur 3 600 secondes (1 heure), la description est définie sur This is my table et le libellé est défini 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 du tableau est définie sur 3 600 secondes (1 heure), la description est définie sur This is my table et le libellé est défini 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 l'expiration, la description et les libellés de la table. 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 sur l'API BigQuery C#.

public void CreateTable(string datasetId, string tableId, BigQueryClient client)
{
    var dataset = client.GetDataset(datasetId);
    // Create schema for new table.
    var schema = new TableSchemaBuilder
    {
        { "title", BigQueryDbType.String },
        { "unique_words", BigQueryDbType.Int64 }
    }.Build();
    // Create the table if it doesn't exist.
    BigQueryTable table = dataset.GetOrCreateTable(tableId, schema);
}

Go

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

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

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

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

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

// Create a new table in the dataset
bigquery
  .dataset(datasetId)
  .createTable(tableId, options)
  .then(results => {
    const table = results[0];
    console.log(`Table ${table.id} created.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

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 sur 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 de tester cet exemple, suivez la procédure de configuration de Python 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
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

schema = [
    bigquery.SchemaField('full_name', 'STRING', mode='REQUIRED'),
    bigquery.SchemaField('age', 'INTEGER', mode='REQUIRED'),
]
table_ref = dataset_ref.table('my_table')
table = bigquery.Table(table_ref, schema=schema)
table = client.create_table(table)  # API request

assert table.table_id == 'my_table'

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 sur l'API BigQuery Ruby.

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create table in"
# table_id   = "ID of the table to create"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id

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}"

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.

UI Web

  1. Accédez à l'interface utilisateur Web de BigQuery.
    Accéder à l'interface utilisateur Web 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. Il doit comporter 1 024 caractères maximum et peut contenir uniquement des lettres (A-Z, a-z), des chiffres (0-9) et des traits 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 Emplacement de traitement, cliquez sur Non spécifié 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 également 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].

Fournissez l'indicateur --location et définissez la valeur correspondant à votre emplacement.

Pour contrôler la disposition en écriture d'une table de destination existante, spécifiez 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. L'indicateur --location est facultatif. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez l'indicateur sur la valeur 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 query et spécifiez une valeur pour la propriété configuration.query.destinationTable. Pour contrôler la disposition en écriture d'une table de destination existante, configurez la propriété configuration.query.writeDisposition.

Spécifiez votre 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 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 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'identificateur 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 de tester cet exemple, suivez la procédure de configuration de Python 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 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 l'article Présentation du processus de chargement des 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 attribues 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 Gérer des données de table.

Utiliser les tables

Obtenir des informations sur les tables

Vous pouvez obtenir des informations sur les tables à l'aide de l'UI Web de BigQuery, la commande CLI bq show ou en appelant la méthode API tables.get.

Autorisations requises

Pour obtenir des informations sur les tables, vous devez disposer du rôle READER 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.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 des rôles 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 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.

Obtenir des informations sur la table

Pour obtenir des informations sur les tables :

UI Web

  1. Dans le volet de navigation, cliquez sur la flèche vers le bas flèche vers le bas à gauche de votre 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 Table Details (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] correspond à l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données.
  • [TABLE] est le nom de la table.

Exemples :

Entrez 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

Entrez 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

Entrez 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 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 sur 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 sur 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 de tester cet exemple, suivez la procédure de configuration de Python 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
# client = bigquery.Client()
# dataset_id = 'my_dataset'
# table_id = 'my_table'

dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)  # API Request

# View table properties
print(table.schema)
print(table.description)
print(table.num_rows)

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

Vous pouvez répertorier des tables dans des ensembles de données à l'aide de l'UI Web de BigQuery, la commande CLI bq ls ou en appelant 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 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 du rôle 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 :

UI Web

  1. Dans l'interface Web, dans le volet de navigation, utilisez la flèche vers le bas flèche vers le bas à gauche de votre 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].

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

Où :

  • [PROJECT_ID] correspond à 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 :

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

bq ls --format=pretty mydataset

Entrez la commande suivante pour répertorier les tables dans 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 sur l'API BigQuery C#.

public List<BigQueryTable> ListTables(BigQueryClient client, string datasetId)
{
    var tables = client.ListTables(datasetId).ToList();
    return tables;
}

Go

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

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

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

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Lists all tables in the dataset
bigquery
  .dataset(datasetId)
  .getTables()
  .then(results => {
    const tables = results[0];
    console.log('Tables:');
    tables.forEach(table => console.log(table.id));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

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 sur 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 de tester cet exemple, suivez la procédure de configuration de Python 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
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

tables = list(client.list_tables(dataset_ref))  # API request(s)
assert len(tables) == 0

table_ref = dataset.table('my_table')
table = bigquery.Table(table_ref)
client.create_table(table)                  # API request
tables = list(client.list_tables(dataset))  # API request(s)

assert len(tables) == 1
assert tables[0].table_id == 'my_table'

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 sur l'API BigQuery Ruby.

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create table in"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id

dataset.tables.each do |table|
  puts table.table_id
end

Obtenir des métadonnées de tables à l'aide de métatables

BigQuery offre des tables spéciales qui représentent les métadonnées, telles que la liste des tables et des vues d'un ensemble de données. Les "métatables" sont en lecture seule. Pour accéder aux métadonnées sur les tables et les vues d'un ensemble de données, servez-vous de la métatable __TABLES_SUMMARY__ dans l'instruction de requête SELECT. Vous pouvez exécuter la requête à l'aide de l'interface utilisateur Web de BigQuery ou de la commande bq query de l'outil de ligne de commande, ou bien en appelant la méthode API jobs.insert et en configurant une tâche de requête.

Une requête qui utilise la métatable __TABLES_SUMMARY__ ressemble à ce qui suit :

    SELECT [FIELD] FROM [DATASET].__TABLES_SUMMARY__

Où :

  • DATASET est le nom de votre ensemble de données.
  • FIELD est l'une des valeurs suivantes :
Valeur Description
project_id Nom du projet.
dataset_id Nom de l'ensemble de données.
table_id Nom de la table ou de la vue.
creation_time Heure à laquelle la table ou la vue a été créée, en millisecondes, depuis le 1er janvier 1970 UTC.
type Un entier représentant le type de table : une table régulière (1) ou une vue (2).

Autorisations requises

Pour exécuter une tâche de requête utilisant la métatable __TABLES_SUMMARY__, vous devez disposer des autorisations bigquery.jobs.create. Les rôles IAM suivants, prédéfinis au niveau du projet, incluent les autorisations bigquery.jobs.create :

Vous devez également disposer du rôle READER 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.getData. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.getData, à l'exception des rôles bigquery.user, bigquery.jobUser et bigquery.metadataViewer.

Limitations des métatables

Les métatables BigQuery sont soumises aux limitations suivantes :

  • En règle générale, __TABLES_SUMMARY__ est relativement rapide pour les ensembles de données contenant quelques milliers de tables. Pour les ensembles de données plus importants, __TABLES_SUMMARY__ devient de plus en plus lent et peut dépasser les ressources disponibles.
  • Les métatables ne peuvent pas être utilisées avec la méthode tables.insert.
  • Les métatables ne peuvent pas être utilisées en tant que tables de destination.
  • Les métatables ne sont pas compatibles avec les décorateurs de tables en ancien SQL.
  • Les métatables n'apparaissent pas lorsque vous répertoriez les tables dans un ensemble de données.

Exemples de métatables

La requête suivante récupère toutes les métadonnées pour l'ensemble de données bigquery-public-data.samples.

Interface utilisateur Web

#standardSQL
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

Ligne de commande

bq --location=US query --use_legacy_sql=false '
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

Le résultat doit se présenter sous la forme suivante :

+----------------------+------------+-----------------+---------------+------+
| project_id           | dataset_id |    table_id     | creation_time | type |
+----------------------+------------+-----------------+---------------+------+
| bigquery-public-data | samples    | github_nested   | 1348782587310 |    1 |
| bigquery-public-data | samples    | github_timeline | 1335915950690 |    1 |
| bigquery-public-data | samples    | gsod            | 1335916040125 |    1 |
| bigquery-public-data | samples    | natality        | 1335916045005 |    1 |
| bigquery-public-data | samples    | shakespeare     | 1335916045099 |    1 |
| bigquery-public-data | samples    | trigrams        | 1335916127449 |    1 |
| bigquery-public-data | samples    | wikipedia       | 1335916132870 |    1 |
+----------------------+------------+-----------------+---------------+------+

La requête suivante extrait toutes les tables et les vues de l'ensemble de données bigquery-public-data.samples.

Interface utilisateur Web

#standardSQL
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

Ligne de commande

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

Le résultat doit se présenter sous la forme suivante :

+-----------------+
|    table_id     |
+-----------------+
| github_nested   |
| github_timeline |
| gsod            |
| natality        |
| shakespeare     |
| trigrams        |
| wikipedia       |
+-----------------+

La requête suivante répertorie le type de chacune des tables de l'ensemble de données bigquery-public-data.samples.

Interface utilisateur Web

#standardSQL
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

Ligne de commande

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

Le résultat doit se présenter sous la forme suivante :

+-----------------+------+
|    table_id     | type |
+-----------------+------+
| github_nested   |   1  |
| github_timeline |   1  |
| gsod            |   1  |
| natality        |   1  |
| shakespeare     |   1  |
| trigrams        |   1  |
| wikipedia       |   1  |
+-----------------+------+

Étapes suivantes

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

Envoyer des commentaires concernant…

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