分割テーブルデータの管理

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

• 分割テーブルへのデータの読み込み
• 分割テーブルデータの閲覧（またはプレビュー）
• 分割テーブルデータのクエリ
• 分割テーブルデータの追加または上書き
• データ操作言語のステートメントを使用した分割テーブルデータの変更
• 分割テーブルデータのコピー
• 分割テーブルへのデータのストリーミング
• 分割テーブルデータのエクスポート

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

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

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

注: 従来の BigQuery ウェブ UI で [Automatically detect] オプションをオンにすると、[Partitioning Type] オプションは無効になります。分割テーブルにデータを読み込むときにスキーマ自動検出を使用するには、GCP Console、CLI、または API を使用します。

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

• Cloud Storage から分割テーブルへのデータの読み込みの詳細については、以下を参照してください。

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

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

テーブルデータの閲覧

分割テーブルのデータは、次の方法で参照できます。

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

必要な権限

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

データセット レベルの権限を使用する代わりに、bigquery.tables.getData 権限が含まれる IAM 役割を利用できます。事前定義されているプロジェクト レベルの IAM 役割のうち、bigquery.user、bigquery.jobUser、bigquery.metadataViewer 以外の役割にはすべて bigquery.tables.getData 権限が含まれています。

さらに、bigquery.user 役割には bigquery.datasets.create 権限があるため、bigquery.user 役割に割り当てられたユーザーは、ユーザーが作成するすべてのデータセット内のすべてのテーブルのデータを読み取ることができます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成したときに、他の所有者が設定されない場合は、そのユーザーにそのデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルを完全に制御できます。

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

分割テーブルデータの閲覧

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

Console

1. GCP Console のナビゲーション パネルで、データセットをクリックしてテーブルとビューを一覧表示します。

2. リスト内の分割テーブルをクリックします。BigQuery ウェブ UI を使用して個々のパーティションをプレビューすることはできません。

3. [詳細] タブをクリックします。

   

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

   

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

従来の UI

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

2. リスト内の分割テーブルをクリックします。BigQuery ウェブ UI を使用して個々のパーティションをプレビューすることはできません。

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

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

   

コマンドライン

--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 - 読み取りを開始する行を指し示す、ゼロから始まるインデックス。

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

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

分割テーブルデータのクエリ

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

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

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

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

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

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

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

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

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

必要な権限

既存のパーティションを上書きするか、既存のパーティションにデータを追加するには、データセット レベルで WRITER アクセス権を持っているか、bigquery.tables.updateData 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。次に示す事前定義されたプロジェクト レベルの IAM 役割には、bigquery.tables.updateData 権限が含まれています。

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

さらに、bigquery.user 役割には bigquery.datasets.create 権限があるため、bigquery.user 役割に割り当てられたユーザーは、データセット内のユーザーが作成するすべてのテーブルのすべてのパーティションで、データを上書きすることも、追加することもできます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成したときに、他の所有者が指定されない場合は、そのユーザーにそのデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセット、そこに含まれるすべてのテーブル、およびすべてのテーブル パーティションを完全に制御できます。

読み込みジョブまたはクエリジョブを実行するには、bigquery.jobs.create 権限も付与されている必要があります。次に示す事前定義されたプロジェクト レベルの IAM 役割には、bigquery.jobs.create 権限が含まれています。

• bigquery.user
• bigquery.jobUser
• bigquery.admin

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

読み込みジョブの使用

bq load コマンドを使用するか、jobs.insert メソッドを呼び出して読み込みジョブを構成することによって、パーティションへのデータの追加やパーティションの上書きを行うことができます。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 バケットから読み込まれます。Cloud Storage バケットと BigQuery データセットは、asia-northeast1 リージョンに作成されています。

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

注: パーティション デコレータの区切り文字（$）は UNIX シェルの特殊変数です。コマンドライン ツールを使用するときにデコレータをエスケープしなければならない場合があります。パーティション デコレータをエスケープする例を次に示します。mydataset.table\$20160519、'mydataset.table$20160519'

読み込みジョブを使用してデータを追加するか、上書きする詳細については、ソースデータ形式のドキュメントをご覧ください。

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

クエリジョブの使用

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

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

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

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

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

たとえば、次のコマンドでは、クエリ結果を使用して、table1 の 2016 年 3 月 1 日（20160301）のパーティションのデータが書き換えられます。宛先テーブルとクエリされるテーブルは、両方とも US マルチリージョン ロケーションにあります。

bq --location=US 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][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 メソッドを呼び出してコピージョブを構成する

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

1 つまたは複数のパーティションをコピーするには、コマンドライン ツールの bq cp コマンドを使用するか、jobs.insert API メソッドを呼び出してコピージョブを構成します。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 を使用してクエリ結果をダウンロードして保存できます。

次のステップ

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

• 取り込み時間分割テーブルの作成と使用
• 分割テーブルの作成と使用
• 分割テーブルの管理
• 分割テーブルのクエリ