テーブルデータの管理

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

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

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

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

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

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

Cloud Storage からのデータの読み込みの詳細については、以下をご覧ください。
ローカルソースからのデータの読み込みの詳細については、ローカルデータソースから 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

Cloud Console で BigQuery ウェブ UI を開きます。
Cloud Console に移動する
ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。これにより、データセット内のテーブルとビューが表示されます。
リスト内のテーブルを 1 つクリックします。
[詳細] をクリックし、[行数] の値を書き留めます。CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。
[Preview] をクリックします。データのサンプルセットが表示されます。

従来の UI

BigQuery ウェブ UI のナビゲーションパネルで、データセットの左側にある青色の矢印をクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。
リスト内のテーブルを 1 つクリックします。
[Details] をクリックし、[Number of Rows] の値を書き留めます。CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。
[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 内の 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 - 読み取りを開始する行を指し示す、ゼロから始まるインデックス。

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

C#

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

GitHub で表示フィードバック


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 クライアントライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

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

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

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

GitHub で表示フィードバック


// 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 を使用すると、ページ分けが自動的に発生します。この関数はイテレーション中に結果の次のページをフェッチします。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック


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#data と Data#next を使用すると、ページ分けが自動的に発生します。

GitHub で表示フィードバック

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 はユーザーに代わって各バッチクエリをキューに格納し、アイドル状態のリソースが使用可能になると直ちに（通常は数分以内に）クエリを開始します。

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

Cloud Console のクエリエディタ
BigQuery ウェブ UI の [クエリを新規作成] オプション
BigQuery コマンドラインツールの bq query コマンド
プログラムによって jobs.query メソッドまたはクエリ形式の jobs.insert メソッドを呼び出す BigQuery REST API
BigQuery クライアントライブラリ

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

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

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

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

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

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

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

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

テーブルデータの変更

標準 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 を使用してクエリ結果をダウンロードして保存できます。

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

次のステップ

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