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 :

  • Les charger dans une table
  • Les parcourir (ou les prévisualiser)
  • Les interroger
  • Les ajouter à une table ou les utiliser pour écraser une table
  • Les modifier à l'aide du langage de manipulation de données
  • 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.

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 :

Parcourir les données d'une table

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

  • En utilisant Cloud Console
  • 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 au minimum des autorisations bigquery.tables.getData. Les rôles IAM prédéfinis suivants incluent les autorisations bigquery.tables.getData :

  • bigquery.dataViewer
  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

En outre, si un utilisateur possède les autorisations bigquery.datasets.create, il obtient également un accès bigquery.dataOwner à l'ensemble de données qu'il crée. L'accès bigquery.dataOwner permet à l'utilisateur de parcourir les données des tables et des partitions dans l'ensemble de données.

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

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données. Les tables et les vues de l'ensemble de données s'affichent.

  3. Cliquez sur une table dans la liste.

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

  5. Cliquez sur Preview (Aperçu). Un exemple d'ensemble de données s'affiche.

    Aperçu d'une table

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 l'exemple ci-dessous, suivez la procédure de configuration pour C# 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 de l'API BigQuery en langage C#.


using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
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 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 de l'API BigQuery en langage 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 l'exemple ci-dessous, suivez la procédure de configuration pour Java 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 de l'API BigQuery 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 l'exemple ci-dessous, suivez la procédure de configuration pour Node.js 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 de l'API BigQuery en langage 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 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 en langage 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 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 de l'API BigQuery en langage 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 l'exemple ci-dessous, suivez la procédure de configuration pour Ruby 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 de l'API BigQuery en langage 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

Une fois chargées dans BigQuery, les données peuvent être interrogées dans des tables. BigQuery accepte les deux types de requêtes suivants :

Par défaut, BigQuery exécute des requêtes interactives, ce qui signifie que ces dernières sont exécutées dès que possible.

Le service BigQuery permet également d'exécuter des requêtes par lot. Il met en file d'attente chaque requête par lot en votre nom et en lance une dès que des ressources inactives sont disponibles, généralement en quelques minutes.

Vous pouvez exécuter des requêtes interactives et par lot en utilisant les éléments suivants :

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.

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

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.

Modifier les données d'une table

En utilisant le dialecte SQL standard, vous pouvez modifier les données d'une table à l'aide d'instructions LMD. Ces instructions vous permettent d'effectuer de façon groupée des mises à jour, des insertions et des suppressions de lignes. Pour voir des exemples d'utilisation des instructions LMD, consultez la page Mettre à jour des données de table à l'aide du langage de manipulation de données.

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 Cloud Console
  • 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

Les données d'une table peuvent être exportées au format CSV, JSON ou Avro. Actuellement, vous devez exporter les données dans un bucket Cloud Storage. 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 Cloud Console.

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

Étapes suivantes