Gérer des données de table

Ce document explique comment gérer les données de table dans BigQuery. Vous pouvez effectuer les opérations suivantes sur ces données :

Charger des données dans une table
Les ajouter à une table ou les utiliser pour écraser une table
Les parcourir (ou les prévisualiser)
Interroger les données de la table
Les modifier à l'aide du langage de manipulation de données (LMD)
Les copier
Les exporter

Pour en savoir plus sur la gestion des schémas de table, consultez la page Modifier des schémas de table.

Avant de commencer

Attribuez des rôles qui accordent les autorisations nécessaires aux utilisateurs qui doivent effectuer chaque tâche de ce document. Les autorisations requises (le cas échéant) sont indiquées dans la section "Autorisations requises" de la tâche.

Charger des données dans une table

Vous pouvez charger des données lors de la création d'une table, ou créer une table vide et charger les données ultérieurement. Lors du chargement des données, vous pouvez utiliser la fonctionnalité de détection automatique de schéma pour les formats de données acceptés, ou vous pouvez spécifier le schéma.

Pour plus d'informations sur le chargement des données, consultez la documentation correspondant au format et à l'emplacement de vos données source :

Pour en savoir plus sur le chargement des données depuis Cloud Storage, consultez les pages :
Pour plus d'informations sur le chargement de données à partir d'une source locale, consultez la section Charger des données à partir de fichiers locaux.

Ajouter ou écraser des données dans une table

Vous pouvez écraser les données d'une table en effectuant une opération de chargement ou de requête. Vous avez la possibilité d'inclure des données dans une table existante en exécutant un chargement avec ajout ou en ajoutant des résultats de requête à la table.

Pour savoir comment ajouter ou écraser des données dans une table lors d'une opération de chargement, consultez la documentation correspondant au format de vos données sources :

Pour ajouter ou écraser des données dans une table à l'aide de résultats de requête, spécifiez une table de destination et définissez la disposition d'écriture sur l'un des paramètres suivants :

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

Vous pouvez utiliser la requête suivante pour ajouter des enregistrements d'une table à une autre :

  INSERT INTO .. (
    ,
    ) (SELECT * FROM ..)

Pour savoir comment utiliser des résultats de requête pour ajouter ou écraser des données, consultez la section Écrire des résultats de requête.

Parcourir les données d'une table

Vous pouvez parcourir les données d'une table des manières suivantes :

En utilisant la console Google Cloud
En exécutant la commande bq head de l'outil de ligne de commande bq
En appelant la méthode API tabledata.list
En utilisant les bibliothèques clientes

Autorisations requises

Pour parcourir les données d'une table ou d'une partition, vous devez disposer de l'autorisation IAM bigquery.tables.getData.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour parcourir les données d'une table ou d'une partition :

roles/bigquery.dataViewer
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

Si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez parcourir les données des tables et des partitions des ensembles de données que vous créez.

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

Parcourir les données d'une table

Pour parcourir les données d'une table, procédez comme indiqué ci-dessous.

Console

Dans la console Google Cloud, ouvrez la page "BigQuery".

Accéder à BigQuery
Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Cliquez sur une table dans la liste.
Cliquez sur Détails et notez la valeur indiquée pour le Nombre de lignes. Vous aurez peut-être besoin de cette valeur pour contrôler le point de départ de vos résultats à l'aide de l'interface de ligne de commande bq ou de l'API.
Cliquez sur Aperçu. Un exemple d'ensemble de données s'affiche.

Ligne de commande

Exécutez la commande bq head avec l'option --max_rows pour répertorier toutes les colonnes présentes dans un certain nombre de lignes de la table. Si l'option --max_rows n'est pas spécifiée, la valeur par défaut est 100.

Pour parcourir un sous-ensemble de colonnes de la table (y compris des colonnes imbriquées et répétées), utilisez l'option --selected_fields et renseignez les colonnes sous forme de liste d'éléments séparés par une virgule.

Pour spécifier le nombre de lignes à ignorer avant d'afficher les données de la table, utilisez l'option --start_row=integer (ou le raccourci -s). La valeur par défaut est 0. Vous pouvez récupérer le nombre de lignes d'une table en utilisant la commande bq show afin de récupérer les informations sur la table.

Si la table que vous parcourez se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet à la commande, en respectant le format suivant : project_id:dataset.table.

bq head \
--max_rows integer1 \
--start_row integer2 \
--selected_fields "columns" \
project_id:dataset.table

Où :

integer1 correspond au nombre de lignes à afficher.
integer2 correspond au nombre de lignes à ignorer avant d'afficher les données.
columns est une liste de noms de colonnes séparés par des virgules.
project_id est l'ID de votre projet.
dataset est le nom de l'ensemble de données contenant la table.
table est le nom de la table à parcourir.

Exemples :

Saisissez la commande suivante pour répertorier toutes les colonnes des 10 premières lignes de mydataset.mytable. mydataset se trouve dans votre projet par défaut.

bq head --max_rows=10 mydataset.mytable

Saisissez la commande suivante pour répertorier toutes les colonnes des 100 premières lignes de mydataset.mytable. mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq head myotherproject:mydataset.mytable

Saisissez la commande suivante pour n'afficher que les champs field1 et field2 de mydataset.mytable. Elle utilise l'option --start_row pour passer directement à la ligne 100. mydataset.mytable se trouve dans votre projet par défaut.

bq head --start_row 100 --selected_fields "field1,field2" mydataset.mytable

Étant donné que la commande bq head ne crée pas de tâche de requête, elle n'apparaît pas dans l'historique des requêtes. Les commandes bq head ne vous sont donc pas facturées.

API

Vous pouvez parcourir les données d'une table en appelant tabledata.list. Indiquez le nom de la table dans le paramètre tableId.

Configurez les paramètres facultatifs ci-dessous pour contrôler la sortie.

maxResults : nombre maximal de résultats à renvoyer.
selectedFields : liste de colonnes à renvoyer, séparées par une virgule. Si ce paramètre n'est pas spécifié, toutes les colonnes sont renvoyées.
startIndex : index basé sur zéro de la première ligne à lire.

Les valeurs renvoyées sont encapsulées dans un objet JSON que vous devez analyser, comme décrit dans la documentation de référence de tabledata.list.

C#

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

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


using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Linq;

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

Go

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

Par défaut, les bibliothèques clientes Cloud pour Go effectuent automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// browseTable demonstrates reading data from a BigQuery table directly without the use of a query.
// For large tables, we also recommend the BigQuery Storage API.
func browseTable(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	table := client.Dataset(datasetID).Table(tableID)
	it := table.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableDataListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;

// Sample to directly browse a table with optional paging
public class BrowseTable {

  public static void runBrowseTable() {
    // TODO(developer): Replace these variables before running the sample.
    String table = "MY_TABLE_NAME";
    String dataset = "MY_DATASET_NAME";
    browseTable(dataset, table);
  }

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

      // Identify the table itself
      TableId tableId = TableId.of(dataset, table);

      // Page over 100 records. If you don't need pagination, remove the pageSize parameter.
      TableResult result = bigquery.listTableData(tableId, TableDataListOption.pageSize(100));

      // Print the records
      result
          .iterateAll()
          .forEach(
              row -> {
                row.forEach(fieldValue -> System.out.print(fieldValue.toString() + ", "));
                System.out.println();
              });

      System.out.println("Query ran successfully");
    } catch (BigQueryException e) {
      System.out.println("Query failed to run \n" + e.toString());
    }
  }
}

Node.js

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

Par défaut, les bibliothèques clientes Cloud pour Node.js effectuent automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :


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

async function browseRows() {
  // Displays rows from "my_table" in "my_dataset".

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

  // List rows in the table
  const [rows] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .getRows();

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

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

La pagination s'effectue automatiquement dans les bibliothèques clientes Cloud pour PHP à l'aide de la fonction de générateur rows, qui récupère la page de résultats suivante lors de l'itération.

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';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

Python

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


from google.cloud import bigquery

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

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

# Download all rows from a table.
rows_iter = client.list_rows(table_id)  # Make an API request.

# Iterate over rows to make the API requests to fetch row data.
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Download at most 10 rows.
rows_iter = client.list_rows(table_id, max_results=10)
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Specify selected fields to limit the results to certain columns.
table = client.get_table(table_id)  # Make an API request.
fields = table.schema[:2]  # First two columns.
rows_iter = client.list_rows(table_id, selected_fields=fields, max_results=10)
rows = list(rows_iter)
print("Selected {} columns from table {}.".format(len(rows_iter.schema), table_id))
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Print row data in tabular format.
rows = client.list_rows(table, max_results=10)
format_string = "{!s:<16} " * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # Prints column headers.
for row in rows:
    print(format_string.format(*row))  # Prints row data.

Ruby

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

La pagination s'effectue automatiquement dans les bibliothèques clientes Cloud pour Ruby à l'aide de Table#data et de Data#next.

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

Interroger les données d'une table

Après avoir chargé des données dans BigQuery, vous pouvez interroger les données à l'aide de l'un des types de tâches de requête suivants :

Tâches de requête interactives. Par défaut, BigQuery exécute des tâches de requête interactives (à la demande) dès que possible.
Tâches de requête par lot. Avec ces tâches, BigQuery met en file d'attente chaque requête par lot en votre nom, puis lance la requête lorsque des ressources inactives sont disponibles, généralement en quelques minutes.

Vous pouvez exécuter des tâches de requête interactives ou par lot à l'aide des méthodes suivantes :

Rédigez et exécutez une requête dans la console Google Cloud.
Exécutez la commande bq query dans l'outil de ligne de commande bq.
Appelez de manière automatisée la méthode jobs.query ou jobs.insert dans l'API REST BigQuery.
Utilisez les bibliothèques clientes BigQuery.

Pour en savoir plus sur l'interrogation des tables BigQuery, consultez la page Présentation du processus d'interrogation des données BigQuery.

Vous pouvez interroger non seulement les données présentes dans les tables BigQuery, mais également celles stockées hors de ces tables. Pour en savoir plus, consultez la page Présentation des sources de données externes.

Modifier les données d'une table

Vous pouvez modifier les données d'une table à l'aide d'instructions LMD (Langage de manipulation de données) en langage SQL. Les instructions LMD vous permettent de mettre à jour, de fusionner, d'insérer et de supprimer des lignes dans des tables. Pour obtenir des informations de référence sur la syntaxe et des exemples de chaque type d'instruction LMD, consultez la page Instructions de langage de manipulation de données en GoogleSQL.

L'ancien dialecte SQL n'accepte pas les instructions LMD. Pour mettre à jour ou supprimer des données à l'aide de l'ancien SQL, vous devez supprimer la table, puis la recréer avec de nouvelles données. Vous pouvez également créer une requête qui modifie les données et écrire les résultats de la requête dans une nouvelle table de destination.

Copier les données d'une table

Vous pouvez copier une table des manières suivantes :

En utilisant la console Google Cloud
En exécutant la commande bq cp de l'outil de ligne de commande bq
En appelant la méthode API jobs.insert et en configurant une tâche de copie
En utilisant les bibliothèques clientes

Pour en savoir plus sur la copie de tables, consultez la section Copier une table.

Exporter des données de table

Vous pouvez exporter des données de table vers un bucket Cloud Storage au format CSV, JSON, Avro ou Parquet (format Bêta). Il n'est pas possible de procéder à une exportation vers une machine locale. Cependant, vous pouvez télécharger et enregistrer des résultats de requête à l'aide de la console Google Cloud.

Pour en savoir plus, consultez la page Exporter des données de table.

Sécurité des tables

Pour savoir comment contrôler l'accès aux tables dans BigQuery, consultez la page Présentation des contrôles d'accès aux tables.

Étapes suivantes

Pour plus d'informations sur le chargement des données, consultez la page Introduction au chargement des données.
Pour plus d'informations sur l'interrogation des données, consultez la page Introduction à l'interrogation des données BigQuery.
Pour plus d'informations sur la modification des schémas de table, consultez la page Modifier des schémas de table.
Pour plus d'informations sur la création et l'utilisation des tables, consultez la page Créer et utiliser des tables.
Pour plus d'informations sur la gestion des tables, consultez la page Gérer des tables.