テーブルデータの管理

このドキュメントでは、BigQuery でテーブルデータを管理する方法について説明します。BigQuery テーブルデータは、次の方法で操作できます。

  • テーブルにデータを読み込む
  • テーブルデータを参照(またはプレビュー)する
  • テーブルデータをクエリする
  • テーブルデータを追加または上書きする
  • データ操作言語を使用してテーブルデータを変更する
  • テーブルデータをコピーする
  • テーブルデータをエクスポートする

テーブル スキーマの管理については、テーブル スキーマの変更をご覧ください。

テーブルへのデータの読み込み

テーブルを作成するときにデータを読み込むことも、空のテーブルを作成して、後でデータを読み込むこともできます。データを読み込む際は、サポートされているデータ形式であればスキーマの自動検出を使用できますが、スキーマを指定することもできます。

データの読み込みの詳細については、ソースデータの形式とロケーションに関するドキュメントをご覧ください。

テーブルデータのブラウジング

次の方法でテーブルデータを閲覧できます。

  • Cloud Console または従来の BigQuery ウェブ UI を使用する
  • コマンドライン ツールの bq head コマンドを使用する
  • tabledata.list API メソッドを呼び出す
  • クライアント ライブラリを使用する

必要な権限

テーブルとパーティションのデータをブラウジングするには、少なくとも bigquery.tables.getData 権限が付与されている必要があります。bigquery.tables.getData 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

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

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner アクセス権がユーザーに付与されます。bigquery.dataOwner アクセス権により、ユーザーはデータセットに含まれるテーブルとパーティションのデータをブラウジングできます。

BigQuery での Cloud IAM の役割と権限については、事前定義された役割と権限をご覧ください。

テーブルデータのブラウジング

テーブルデータを閲覧するには:

Console

  1. Cloud Console で BigQuery ウェブ UI を開きます。
    Cloud Console に移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。これにより、データセット内のテーブルとビューが表示されます。

  3. リスト内のテーブルを 1 つクリックします。

  4. [詳細] をクリックし、[行数] の値を書き留めます。CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。

  5. [プレビュー] をクリックします。データのサンプルセットが表示されます。

    テーブルのプレビュー

従来の UI

  1. BigQuery ウェブ UI のナビゲーション ペインで、データセットの左側にある青色の矢印をクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。

  2. リスト内のテーブルを 1 つクリックします。

  3. [Details] をクリックし、[Number of Rows] の値を書き留めます。CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。

  4. [Preview] をクリックします。データのサンプルセットが表示されます。

    テーブルのプレビュー

コマンドライン

--max_rows フラグを指定して bq head コマンドを発行すると、特定の数のテーブル行のすべての列が一覧表示されます。--max_rows が指定されていない場合、デフォルトは 100 です。

テーブル内の列のサブセット(ネストした列と繰り返し列を含む)をブラウジングするには、--selected_fields フラグを使用して、列の値をカンマ区切りのリストとして入力します。

テーブルデータを表示する前にスキップする行数を指定するには、--start_row=integer フラグ(または -s ショートカット)を使用します。デフォルト値は 0 です。テーブルの行数を取得するには、bq show コマンドを使用してテーブル情報を取得します。

ブラウジングしているテーブルがデフォルトのプロジェクト以外のプロジェクトにある場合は、project_id:dataset.table の形式でプロジェクト ID をコマンドに追加します。

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

ここで

  • integer1 は、表示する行数です。
  • integer2 は、データを表示する前にスキップする行数です。
  • columns は、列のカンマ区切りのリストです。
  • project_id はプロジェクト ID です。
  • dataset は、テーブルを含むデータセットの名前です。
  • table は、閲覧するテーブルの名前です。

例:

mydataset.mytable の最初の 10 行の列をすべて表示するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトにあります。

bq head --max_rows=10 mydataset.mytable
    

mydataset.mytable の最初の 100 行の列をすべて表示するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトではなく myotherproject にあります。

bq head myotherproject:mydataset.mytable
    

mydataset.mytable 内の field1field2 のみを表示するには、次のコマンドを入力します。このコマンドでは --start_row フラグを使用して 100 行目にスキップしています。mydataset.mytable はデフォルト プロジェクトにあります。

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

bq head コマンドはクエリジョブを作成しないため、クエリ履歴には bq head コマンドは示されません。また、このコマンドに対して料金は発生しません。

API

tabledata.list を呼び出して、テーブルのデータをブラウジングします。tableId パラメータでテーブルの名前を指定します。

次のオプション パラメータを構成して出力を制御します。

  • maxResults - 返される結果の最大数。
  • selectedFields - 返される列のカンマ区切りのリスト(指定しなかった場合、すべての列が返されます)
  • startIndex - 読み取りを開始する行を指し示す、ゼロから始まるインデックス。

値は 1 つの JSON オブジェクトにラップされて返されます。このオブジェクトは、tabledata.list リファレンス ドキュメントに記載されている手順に従って解析する必要があります。

C#

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。


    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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の設定手順を実施してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。

Go 用の Google Cloud クライアント ライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。

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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

TableId tableIdObject = TableId.of(datasetName, tableName);
    // This example reads the result 100 rows per RPC call. If there's no need to limit the number,
    // simply omit the option.
    TableResult tableData =
        bigquery.listTableData(tableIdObject, TableDataListOption.pageSize(100));
    for (FieldValueList row : tableData.iterateAll()) {
      // do something with the row
    }

Node.js

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。

Node.js 用の Google Cloud クライアント ライブラリでは、デフォルトで自動的に結果がページ分割されるため、ページ分けを自分で実装する必要はありません。次に例を示します。


    // 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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の PHP の設定手順を実施してください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。

PHP 用の Google Cloud クライアント ライブラリでジェネレータ関数 rows を使用すると、ページ分けが自動的に発生します。この関数はイテレーション中に結果の次のページをフェッチします。

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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の設定手順を実施してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。


    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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Ruby の設定手順を実施してください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。

Ruby 用 Google Cloud クライアント ライブラリTable#dataData#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

テーブルデータのクエリ

BigQuery にデータを読み込んだ後に、テーブル内のデータをクエリで取得できます。BigQuery は次の 2 種類のクエリをサポートします。

デフォルトで、BigQuery はインタラクティブ クエリを実行します。つまり、クエリはすぐに実行されます。

BigQuery ではバッチクエリも提供されています。BigQuery はユーザーに代わって各バッチクエリをキューに格納し、アイドル状態のリソースが使用可能になると直ちに(通常は数分以内に)クエリを開始します。

以下を使用して、インタラクティブ クエリとバッチクエリを実行できます。

BigQuery テーブルのクエリの詳細については、BigQuery データのクエリの概要をご覧ください。

BigQuery テーブルに格納されたデータをクエリするだけでなく、外部に保存されたデータをクエリすることもできます。詳細については、外部データソースへのクエリの実行をご覧ください。

テーブルデータの追加と上書き

読み込みまたはクエリ オペレーションを使用してテーブルデータを上書きできます。既存のテーブルにデータを追加するには、読み込み追加オペレーションを実行するか、クエリ結果をテーブルに追加します。

データの読み込み時にテーブルに追加するか、上書きする方法の詳細については、ソースデータ形式のドキュメントを参照してください。

クエリ結果を使用して、テーブルに追加または上書きするには、宛先のテーブルを指定し、次のいずれかに書き込み処理を設定します。

  • テーブルに追加する - クエリ結果を既存のテーブルに追加します。
  • テーブルを上書きする - クエリ結果を既存のテーブルに同じ名前で上書きします。

クエリ結果を使用してデータを追加または上書きする方法の詳細については、クエリ結果の書き込みをご覧ください。

テーブルデータの変更

標準 SQL 言語を使用すると、DML ステートメントを使用してテーブル内のデータを変更できます。DML ステートメントを使用すると、行の一括更新、挿入、削除を実行できます。DML の使用例については、データ操作言語を使用したテーブルデータの更新をご覧ください。

レガシー SQL は DML ステートメントをサポートしていません。レガシー SQL を使用してデータを更新または削除するには、テーブルを削除してから、新しいデータでテーブルを再作成する必要があります。または、データを変更し、クエリ結果を新しい宛先テーブルに書き込むクエリを記述することもできます。

テーブルデータのコピー

テーブルは次の方法でコピーできます。

  • Cloud Console または従来の BigQuery ウェブ UI を使用する
  • コマンドライン ツールの bq cp コマンドを使用する
  • jobs.insert API メソッドを呼び出して copy ジョブを構成する
  • クライアント ライブラリを使用する

テーブルのコピーの詳細については、テーブルのコピーをご覧ください。

テーブルデータのエクスポート

テーブルデータは、CSV、JSON、Avro 形式でエクスポートできます。現時点では、データを Cloud Storage バケットにエクスポートする必要があります。ローカルマシンへのエクスポートはサポートされていません。ただし、Cloud Console や従来の BigQuery ウェブ UI を使用してクエリ結果をダウンロードして保存できます。

詳細については、テーブルデータのエクスポートをご覧ください。

次のステップ