パーティション分割テーブルデータの管理

このドキュメントでは、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 のナビゲーションパネルで、データセットをクリックしてテーブルとビューを一覧表示します。
リスト内のパーティション分割テーブルをクリックします。
[詳細] タブをクリックします。
[行数] の値を書き留めます。CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。
[プレビュー] タブをクリックします。データのサンプルセットが表示されます。GCP Console を使用して個々のパーティションをプレビューすることはできません。

従来の UI

BigQuery ウェブ UI のナビゲーションペインで、データセットの左側にある青色の矢印をクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。
リスト内のパーティション分割テーブルをクリックします。
[Details] をクリックし、[Number of Rows] の値を書き留めます。CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。
[Preview] をクリックします。データのサンプルセットが表示されます。BigQuery ウェブ UI を使用して個々のパーティションをプレビューすることはできません。

CLI

--max_rows フラグを指定して bq head コマンドを発行すると、特定の数のテーブル行のすべてのフィールドが一覧表示されます。--max_rows が指定されていない場合、デフォルトは 100 です。パーティションデコレータを使用して閲覧するパーティションを指定します（例: $20180224）。

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

テーブル内のフィールドのサブセット（ネストフィールドと繰り返しフィールドを含む）を閲覧するには、--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$partition

ここで

integer1 は、表示する行数です。
integer2 は、データを表示する前にスキップする行数です。
fields は、フィールドのカンマ区切りのリストです。
project_id は、プロジェクト ID です。
dataset は、テーブルを含むデータセットの名前です。
table は、閲覧するテーブルの名前です。
$partition は、パーティションデコレータです。

例:

"2018-02-24" パーティションの mydataset.mytable 内の最初の 10 行にあるすべてのフィールドを一覧表示するには、次のコマンドを入力します。mydataset はデフォルトのプロジェクト内にあります。

bq head --max_rows=10 mydataset.mytable$20180224

"2016-09-01" パーティションの mydataset.mytable 内の最初の 100 行にあるすべてのフィールドを一覧表示するには、次のコマンドを入力します。mydataset はデフォルトのプロジェクトではなく、myotherproject 内にあります。

bq head --format=prettyjson 'mydataset.mycolumntable2$20160901'

"2016-09-01" パーティションの mydataset.mytable 内の field1 と field2 のみを表示するには、次のコマンドを入力します。このコマンドでは、- -start_row フラグを使用して 100 行目にスキップします。mydataset.mytable はデフォルトのプロジェクト内にあります。

bq head \
--format=prettyjson \
--start_row 100 \
--selected_fields "state_number" \
'mydataset.mycolumntable2$20160901'

API

tabledata.list を呼び出して、テーブルのデータを閲覧します。tableId パラメータでテーブルの名前とパーティションデコレータを指定します。

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

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

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

パーティション分割テーブルデータのクエリ

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

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

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

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

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

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

詳細については、パーティション分割テーブルのクエリをご覧ください。

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

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

必要な権限

既存のパーティションを上書きする場合や、既存のパーティションにデータを追加する場合は、少なくとも次の権限が付与されている必要があります。

bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create

追加するデータまたは上書きに使用するデータにアクセスするには、bigquery.tables.getData などの権限が必要になる場合もあります。

事前定義された以下の Cloud IAM 役割には、bigquery.tables.updateData と bigquery.tables.create の権限が含まれています。

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

事前定義された以下の Cloud IAM 役割には bigquery.jobs.create 権限が含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

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

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

読み込みジョブの使用

パーティションに対するデータの追加または上書きを行うには、bq load コマンドを使用するか、jobs.insert メソッドを呼び出して load ジョブを構成します。GCP Console と従来の BigQuery ウェブ UI では、読み込みジョブによるパーティションに対するデータの追加や上書きはサポートされていません。

読み込みジョブを使用して特定のパーティションでデータを追加または上書きする場合は、次の点に注意してください。

Cloud Storage からデータを読み込む場合は、バケットが BigQuery データセットと同じロケーションにある必要があります。
読み込むデータが、テーブルのパーティショニングスキームに準拠している必要があります。パーティションに書き込まれるすべての行は、パーティションの日付内に収まる値を持つ必要があります。
1 つの分割テーブル内のパーティションはテーブルのスキーマを共有するので、パーティションのデータを置き換えてもテーブルのスキーマは置き換えられません。その代わりに、新しいデータのスキーマがテーブルのスキーマに適合している必要があります。読み込みジョブでテーブルのスキーマを更新する方法については、テーブルスキーマの管理をご覧ください。
取り込み時間分割テーブルにデータを追加するときにパーティションデコレータを指定しないと、現在のパーティションが使用されます。

読み込みジョブを使用して、分割テーブルデータを追加または上書きするには、宛先テーブルとパーティションデコレータを指定し、書き込み処理フラグを次のいずれかに設定します。

CLI オプション	API オプション	説明
`--noreplace`	WRITE_APPEND	既存のパーティションにデータを追加します。書き込み処理オプションが指定されていない場合は、デフォルトのアクションとしてパーティションにデータが追加されます。
`--replace`	WRITE_TRUNCATE	パーティションを上書き（書き換え）します。

パーティションデコレータは特定の日付を表しており、次の形式をとります。

$YYYYMMDD

たとえば、次のコマンドでは、mydataset.table1 というパーティション分割テーブルの 2016 年 1 月 1 日（20160101）のパーティション全体でデータが置き換えられます。JSON データは Cloud Storage バケットから読み込まれます。

bq load \
--replace \
--source_format=NEWLINE_DELIMITED_JSON \
'mydataset.table1$20160101' \
gs://mybucket/myfile.json

クエリジョブの使用

パーティションに対するデータの追加や上書きを行うには、bq query コマンドを使用するか、jobs.insert メソッドを呼び出して query ジョブを構成します。GCP Console と従来の BigQuery ウェブ UI では、パーティションに対するデータの追加や上書きはサポートされていません。

クエリジョブを使用してパーティションにデータを追加する場合やパーティションを上書きする場合は、次の点に注意してください。

クエリするテーブルは、データを追加または上書きするテーブルと同じロケーションにある必要があります。
取り込み時間分割テーブルのパーティションにデータを追加したりパーティションを上書きしたりする場合は、レガシー SQL 構文または標準 SQL 構文を使用できます。
分割テーブルのパーティションにデータを追加したりパーティションを上書きしたりする場合は、クエリで標準 SQL 構文を使用する必要があります。現時点では、分割テーブルをクエリする場合や、クエリ結果を分割テーブルに書き込む場合には、レガシー SQL がサポートされていません。
クエリ結果をパーティションに書き込む場合、パーティションに書き込まれるデータは、テーブルのパーティショニングスキームに準拠している必要があります。パーティションに書き込まれるすべての行は、パーティションの日付内に収まる値を持つ必要があります。
取り込み時間分割テーブルにデータを追加するときにパーティションデコレータを指定しないと、現在のパーティションが使用されます。

クエリ結果を使用してパーティションにデータを追加したりパーティションを上書きしたりするには、宛先テーブルとパーティションデコレータを指定し、書き込み処理を次のいずれかに設定します。

CLI オプション	API オプション	説明
`--append_table`	WRITE_APPEND	既存のパーティションにクエリ結果を追加します。
`--replace`	WRITE_TRUNCATE	クエリ結果を使用してパーティションを上書き（書き換え）します。

たとえば次のコマンドでは、クエリ結果を使用して、table1 の 2016 年 3 月 1 日（20160301）のパーティションのデータが修正されます。

bq query \
--use_legacy_sql=false \
--replace \
--destination_table 'mydataset.table1$20160301' \
'SELECT
  column1,
  column2
FROM
  mydataset.mytable'

宛先テーブルが存在し、かつ分割されていない場合は、次のエラーが返されます。BigQuery error in query operation: Error processing job 'project_id job_id' Incompatible table partitioning specification. Expects partitioning specification interval (type:day), but input partitioning specification is none`.

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

DML ステートメントを使用した分割テーブルデータの変更

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

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

分割テーブルデータのコピー

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

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

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

1 つ以上のパーティションをコピーするには、コマンドラインツールの bq cp コマンドを使用するか、jobs.insert API メソッドを呼び出して copy ジョブを構成します。現在のところ、GCP Console または従来の BigQuery ウェブ UI では、パーティションのコピーはサポートされていません。

パーティションのコピーの詳細については、パーティションのコピーをご覧ください。

分割テーブルへのデータのストリーミング

特定のパーティションにデータをストリーミングするには、ストリーミング先のテーブルの tableId を指定するときにパーティションデコレータを使用します。たとえば、次のコマンドでは、mydataset.mytable というパーティション分割テーブルの 2017 年 1 月 1 日（$20170101）のパーティションに単一の行がストリーミングされます。

echo '{"a":1, "b":2}' | bq insert 'mydataset.mytable$20170101'

このコマンドは、パーティションデコレータの使用を示すために使用されています。bq insert コマンドは、テスト専用です。データを BigQuery にストリーミングするには、API の tabledata.insertAll メソッドを使用します。データをパーティションにストリーミングする方法の詳細については、分割テーブルへのストリーミングをご覧ください。

パーティションデコレータを使用してストリーミングする場合、現在の日付（現在の UTC 時間に基づく）の 30 日前から 5 日後までのパーティションにストリーミングできます。この範囲に含まれない日付のパーティションに書き込むには、読み込みジョブまたはクエリジョブを使用します。

データをストリーミングするときに、時間パーティション分割テーブルを宛先テーブルとして指定すると、各パーティションでストリーミングバッファが保持されます。writeDisposition プロパティを WRITE_TRUNCATE に設定すると、パーティションを上書きする読み込み、クエリ、またはコピーのジョブを実行したときにストリーミングバッファが保持されます。ストリーミングバッファを削除するには、そのパーティションに対して tables.get を呼び出し、ストリーミングバッファが空であることを確認します。

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

分割テーブルからすべてのデータをエクスポートする処理は、分割されていないテーブルからデータをエクスポートする処理と同じプロセスです。詳細については、テーブルデータのエクスポートをご覧ください。個々のパーティションからデータをエクスポートするには、テーブル名にパーティションデコレータ $date を追加します（例: mytable$20160201）。

テーブル名にパーティション名を追加して、__NULL__ および __UNPARTITIONED__ のパーティションからデータをエクスポートすることもできます。たとえば、mytable$__NULL__ や mytable$__UNPARTITIONED__ のように指定します。

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

次のステップ

分割テーブルの操作の詳細については、次をご覧ください。

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

テーブルデータの閲覧

必要な権限

パーティション分割テーブルデータの閲覧

Console

従来の UI

CLI

API

パーティション分割テーブルデータのクエリ

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

必要な権限

読み込みジョブの使用

クエリジョブの使用

DML ステートメントを使用した分割テーブルデータの変更

分割テーブルデータのコピー

分割テーブルへのデータのストリーミング

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

次のステップ

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