テーブルデータの管理

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

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

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

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

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

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

• Google Cloud Storage からのデータの読み込みの詳細については、次を参照してください。

  • Avro データの読み込み
  • CSV データの読み込み
  • JSON データの読み込み
  • Parquet データの読み込み
  • Cloud Datastore エクスポートからのデータの読み込み
  • Cloud Firestore のエクスポートからのデータの読み込み

• ローカルソースからのデータの読み込みの詳細については、ローカルデータ ソースから BigQuery へのデータの読み込みをご覧ください。

テーブルデータの閲覧

テーブルデータを閲覧するには、BigQuery ウェブ UI を使用する、コマンドライン ツールの bq head コマンドを使用する、API の tabledata.list メソッドを呼び出す、といった方法があります。

必要な権限

データセット レベルでテーブルデータを閲覧するには、閲覧対象のテーブルを含むデータセットへの READER アクセス権が必要です。

データセット レベルの権限を使用する代わりに、bigquery.tables.getData 権限が含まれるプロジェクト レベルの IAM 役割を利用できます。次の定義済みのプロジェクト レベルの IAM 役割には、プロジェクト内のすべてのテーブルに対する bigquery.tables.getData 権限が含まれます。

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

さらに、bigquery.user 役割には bigquery.datasets.create 権限があるため、bigquery.user 役割に割り当てられたユーザーは、ユーザーが作成するすべてのデータセット内のすべてのテーブルのデータを読み取ることができます。bigquery.user 役割に割り当てられたユーザーがデータセットを作成すると、そのユーザーにはデータセットへの OWNER アクセス権が与えられます。データセットへの OWNER アクセス権により、ユーザーはそのデータセットとその中のすべてのテーブルを完全に制御できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

テーブルデータの閲覧

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

ウェブ UI

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

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

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 "[FIELDS]" [PROJECT_ID]:[DATASET].[TABLE]

ここで

• [INTEGER1] は、表示する行数です。
• [INTEGER2] は、データを表示する前にスキップする行数です。
• [FIELDS] は、フィールドのカンマ区切りのリストです。
• [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 内の field1 と field2 のみを表示するには、次のコマンドを入力します。コマンドは --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 - 読み取りを開始する行の、ゼロから始まるインデックス。

注: startIndex に最後の行を超える値を指定してリクエストした場合、メソッドは正常に返されますが、rows プロパティは返されません。テーブルの行数を調べるには、tables.get メソッドを呼び出して numRows プロパティを確認します。

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

C#

GitHub で表示 フィードバック

public int TableDataList(
    string datasetId, string tableId, int pageSize, BigQueryClient client)
{
    int recordCount = 0;
    var result = client.ListRows(datasetId, tableId, null,
        new ListRowsOptions { PageSize = pageSize });
    // If there are more rows than were returned in the first page of results,
    // iterating over the rows will lazily evaluate the results each time,
    // making further requests as necessary.
    foreach (var row in result)
    {
        Console.WriteLine($"{row["title"]}: {row["unique_words"]}");
        recordCount++;
    }
    return recordCount;
}

Go

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

GitHub で表示 フィードバック

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.Println(row)
}

Java

GitHub で表示 フィードバック

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

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

GitHub で表示 フィードバック

// 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";
// const tableId = "my_table";

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

// Lists rows in the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .getRows()
  .then(results => {
    const rows = results[0];
    console.log('Rows:');
    rows.forEach(row => console.log(row));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

PHP 用の Google Cloud クライアント ライブラリの場合、ジェネレータ関数 rows を使用すると、ページ分割が自動的に行われます。この関数は反復処理中に使用して、結果の次のページをフェッチします。

GitHub で表示 フィードバック

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Browse a bigquery table.
 * Example:
 * ```
 * browse_table($projectId, $datasetId, $tableId);
 * ```
 *
 * @param string $projectId  The Google project ID.
 * @param string $datasetId  The BigQuery dataset ID.
 * @param string $tableId    The BigQuery table ID.
 * @param string $maxResults The number of results to return at a time.
 * @param string $startIndex The row index to start on.
 *
 * @return int number of rows returned
 */
function browse_table($projectId, $datasetId, $tableId, $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++;
    }

    return $numRows;
}

Python

GitHub で表示 フィードバック

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

dataset_ref = client.dataset('samples', project='bigquery-public-data')
table_ref = dataset_ref.table('shakespeare')
table = client.get_table(table_ref)  # API call

# Load all rows from a table
rows = client.list_rows(table)
assert len(list(rows)) == table.num_rows

# Load the first 10 rows
rows = client.list_rows(table, max_results=10)
assert len(list(rows)) == 10

# Specify selected fields to limit the results to certain columns
fields = table.schema[:2]  # first two columns
rows = client.list_rows(table, selected_fields=fields, max_results=10)
assert len(rows.schema) == 2
assert len(list(rows)) == 10

# Use the start index to load an arbitrary portion of the table
rows = client.list_rows(table, start_index=10, max_results=10)

# Print row data in tabular format
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

Ruby 用 Google Cloud クライアント ライブラリの場合、Table#data と Data#next を使用すると、ページ分割が自動的に行われます。

GitHub で表示 フィードバック

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset containing table"
# table_id   = "ID of the table to display data for"

require "google/cloud/bigquery"

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

table.data.each do |row|
  row.each      do |column_name, value|
    puts "#{column_name} = #{value}"
  end
end

テーブルデータのクエリ

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

• インタラクティブ クエリ
• バッチクエリ

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

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

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

• BigQuery ウェブ UI の [COMPOSE QUERY] オプション
• BigQuery コマンドライン ツールの bq query コマンド
• プログラムで jobs.query またはクエリタイプの jobs.insert メソッドを呼び出すための BigQuery REST API
• BigQuery クライアント ライブラリ

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

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

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

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

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

• Avro データでテーブルに追加または上書きする
• CSV データをテーブルに追加、または CSV データでテーブルを上書きする
• JSON データでテーブルに追加または上書きする
• Cloud Datastore データでテーブルに追加または上書きする
• ローカル ファイルを使用してテーブルに追加または上書きする

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

• Append to table - クエリ結果を既存のテーブルに追加します。
• Overwrite table - クエリ結果を使用して既存のテーブルを同じ名前で上書きします。

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

テーブルデータの変更

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

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

テーブルデータのコピー

テーブルをコピーするには、BigQuery ウェブ UI を使用する、コマンドライン ツールの bq cp コマンドを使用する、API の jobs.insert メソッドを呼び出して copy ジョブを構成する、といった方法があります。

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

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

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

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

次のステップ

• データの読み込みの詳細については、データの読み込みの概要をご覧ください。
• データのクエリの詳細については、BigQuery データのクエリの概要をご覧ください。
• テーブル スキーマの変更の詳細については、テーブル スキーマの変更をご覧ください。
• テーブルの作成と使用の詳細については、テーブルの作成と使用をご覧ください。
• テーブルの管理の詳細については、テーブルの管理をご覧ください。