テーブルデータの管理

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

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

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

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

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

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

Cloud Storage からのデータの読み込みの詳細については、以下を参照してください。
ローカルソースからのデータの読み込みの詳細については、ローカルデータソースから BigQuery へのデータの読み込みをご覧ください。

テーブルデータの閲覧

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

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

必要な権限

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

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

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

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

テーブルデータの閲覧

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

Console

GCP Console で BigQuery ウェブ UI を開きます。
GCP 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 で表示フィードバック

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

このサンプルを試す前に、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
# 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

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

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

GCP Console 内のクエリエディター
BigQuery ウェブ UI の [COMPOSE QUERY] オプション
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 を使用してデータを更新または削除するには、テーブルを削除してから、新しいデータでテーブルを再作成する必要があります。または、データを変更し、クエリ結果を新しい宛先テーブルに書き込むクエリを記述することもできます。

テーブルデータのコピー

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

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

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

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

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

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

次のステップ

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

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

テーブルデータの閲覧

必要な権限

テーブルデータの閲覧

Console

従来の UI

コマンドライン

API

C#

Go

Java

Node.js

PHP

Python

Ruby

テーブルデータのクエリ

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

テーブルデータの変更

テーブルデータのコピー

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

次のステップ

フィードバックを送信...