このドキュメントでは、BigQuery で分割テーブルを管理する方法について説明します。取り込み時間分割テーブルと分割テーブルはどちらも同じ方法で管理されます。分割テーブルでは、以下の管理タスクを実行できます。
- 時間分割テーブルに関する以下の情報を更新する
- テーブルの有効期限
- パーティションの有効期限
- 説明
- スキーマ定義
- ラベル
- 時間分割テーブルの名前を変更する（テーブルをコピーする）
- 時間分割テーブルをコピーする
- パーティションをコピーする
- 時間分割テーブルを削除する
- 時間分割テーブルのパーティションを削除する
テーブル情報の取得、テーブルの一覧表示、テーブルデータへのアクセス制御など、分割テーブルの作成と使用の詳細については、取り込み時間分割テーブルの作成と使用または分割テーブルの作成と使用をご覧ください。
分割テーブルのプロパティの更新
分割テーブルの以下の情報を更新できます。
必要な権限
テーブルのプロパティを更新するには、データセット レベルで WRITER アクセス権が付与されているか、必要な bigquery.tables.update 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。事前定義されたプロジェクトレベルの IAM 役割のうち、bigquery.tables.update 権限が含まれているものは次のとおりです。
また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分がデータセット内に作成した任意のテーブルを更新できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルとビューを完全に制御できます。
BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。
分割テーブルの説明の更新
分割テーブルの説明を更新するプロセスは、標準テーブルの説明を更新するプロセスと同じです。テーブルの説明を追加または変更する方法については、テーブルの説明の更新をご覧ください。
現時点では、個々のパーティションの説明を作成することはできません。
テーブルの有効期限の更新
分割テーブルの有効期限を更新するプロセスは、標準テーブルの有効期限を更新するプロセスと同じです。テーブルの有効期限を追加または変更する方法については、テーブルの有効期限の更新をご覧ください。
パーティションの有効期限の更新
分割テーブルの作成時にテーブルのパーティションの有効期限を指定するには、コマンドライン ツールの bq mk コマンドを使用するか、tables.insert API メソッドを呼び出します。現在、GCP Console および従来の BigQuery ウェブ UI ではパーティションの有効期限の指定がサポートされていません。
テーブルの作成時にパーティションの有効期限を指定すると、指定したパーティションの有効期限で、データセット レベルでのデフォルトのパーティション有効期限がオーバーライドされます。テーブルレベルで設定したパーティションの有効期限は、すべてのパーティションに適用されます。個々のパーティションに異なる有効期限を適用することはできません。
テーブルが作成された後はいつでも、CLI の bq update コマンドまたは API の tables.patch メソッドを使用してテーブルのパーティションの有効期限を更新できます。現在、GCP Console および従来の BigQuery ウェブ UI ではパーティションの有効期限を更新がサポートされていません。
テーブルのパーティションの有効期限を更新すると、パーティションの作成時点に関係なく、すべてのパーティションに同じ設定が適用されます。
テーブルのパーティションの有効期限を更新するときは、パーティションの日付に基づいてパーティションの有効期限を計算する必要があります。たとえば、パーティションの日付が 2018 年 1 月 3 日で、パーティションの有効期限を 5 日に設定した場合は、最終更新日時に関係なく、そのパーティションは 2018 年 1 月 8 日に期限切れになります。
分割テーブルにもテーブルの有効期限が設定されている場合は、テーブルとテーブル内のすべてのパーティションがテーブルの有効期限設定に従って削除されます。テーブルの有効期限の方がパーティションの有効期限よりも優先されます。
たとえば、分割テーブルの有効期限が 5 日、パーティションの有効期限が 7 日に設定されている場合、テーブルとテーブル内のすべてのパーティションは 5 日後に削除されます。
2016 年 12 月 13 日よりも前に作成された分割テーブルを使用しているプロジェクトの場合、パーティションの有効期限はパーティションの最終更新日で決まります。この規則は、同じプロジェクトに作成された新しいテーブルにも適用されます。プロジェクトを新しい規則に移行するには、BigQuery 公開バグトラッカーでリクエストを送信してください。
分割テーブルのパーティションの有効期限を更新する手順は以下のとおりです。
Console
GCP Console では、パーティションの有効期限の追加や更新はできません。
従来の UI
従来の BigQuery ウェブ UI では、パーティションの有効期限の追加や更新はできません。
コマンドライン
bq update コマンドを --time_partitioning_expiration フラグ付きで発行します。更新する分割テーブルがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセット名に追加します。
bq update --time_partitioning_expiration [INTEGER] [PROJECT_ID]:[DATASET].[TABLE]
各項目の説明は次のとおりです。
[INTEGER]は、テーブルのパーティションのデフォルトの存続期間（秒）です。最小値はありません。パーティションの日付にこの整数値を足した値が有効期限になります。0または負の数を指定すると、パーティションの有効期限が削除され、パーティションは無期限に有効になります。有効期限のないパーティションは手動で削除する必要があります。[PROJECT_ID]はプロジェクト ID です。[DATASET]は、更新しているテーブルを含むデータセットの名前です。[TABLE]は更新するテーブルの名前です。
例:
mydataset.mytable にあるパーティションの有効期限を 5 日（432,000 秒）に更新するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトにあります。
bq update --time_partitioning_expiration 432000 mydataset.mytable
mydataset.mytable にあるパーティションの有効期限を 5 日（432,000 秒）に更新するには、次のコマンドを入力します。mydataset はデフォルトのプロジェクトではなく myotherproject にあります。
bq update --time_partitioning_expiration 432000 myotherproject:mydataset.mytable
API
tables.patch メソッドを呼び出し、timePartitioning.expirationMs プロパティを使用してパーティションの有効期限をミリ秒単位で更新します。tables.update メソッドはテーブル リソース全体を置き換えるため、tables.patch メソッドの方が適切です。
スキーマ定義の更新
分割テーブルのスキーマ定義を更新するプロセスは、標準テーブルのスキーマ定義を更新するプロセスと同じです。詳細については、テーブル スキーマの変更をご覧ください。
分割テーブルの名前の変更
現時点では、既存の分割テーブルの名前を変更することはできません。テーブル名を変更する場合は、テーブルをコピーする手順に従い、コピー オペレーションでコピー先のテーブルを指定する際に新しいテーブル名を使用します。
分割テーブルのコピー
単一の分割テーブルのコピー
単一の分割テーブルをコピーするプロセスは、単一の標準テーブルをコピーするプロセスと同じです。詳細については、テーブルのコピーをご覧ください。
分割テーブルをコピーする際は、以下の点に注意してください。
コピー元テーブルとコピー先テーブルは、同じロケーションにあるデータセット内に存在する必要があります。
- 分割テーブルを新しい分割テーブルにコピーする場合
- 時間分割テーブルを新しいテーブルにコピーした場合、すべてのパーティショニング情報がテーブルとともにコピーされます。新しいテーブルが持つパーティションは古いテーブルと同じです。
- 分割されていないテーブルを分割テーブルにコピーする場合
- 分割されていないテーブルを分割テーブルにコピーした場合、コピー元のデータは現在の日付に対応するパーティションにコピーされます。
- 分割テーブルを別の分割テーブルにコピーする場合
- 分割テーブルを別の分割テーブルにコピーするには、コピー元テーブルとコピー先テーブルのパーティションの設定が一致している必要があります。コピー先テーブルにデータを追加するか、コピー先テーブルを上書きするかを指定できます。
- 分割テーブルを分割されていないテーブルにコピーする場合
- 分割テーブルを分割されていないテーブルにコピーした場合、コピー先テーブルは分割されません。設定に応じて、分割されていないテーブルにデータが追加されるか、分割されていないテーブルが上書きされます。
複数の分割テーブルのコピー
複数の分割テーブルをコピーするプロセスは、複数の標準テーブルをコピーするプロセスと同じです。詳細については、複数のテーブルのコピーをご覧ください。
複数の分割テーブルをコピーする際は、以下の点に注意してください。
- 同じジョブで複数のテーブルを分割テーブルにコピーする場合、コピー元に分割テーブルと分割されていないテーブルが混在していてはなりません。
- コピー元のテーブルがすべて分割テーブルの場合、すべてのコピー元テーブルのパーティションの設定がコピー先テーブルのパーティションの設定と一致している必要があります。コピー先テーブルにデータが追加されるか、コピー先テーブルが上書きされるかは、設定によって決まります。
- コピー元テーブルとコピー先テーブルは、同じロケーションにあるデータセット内に存在する必要があります。
パーティションのコピー
次の方法で 1 つ以上のパーティションをコピーできます。
- コマンドライン ツールの
bq cpコマンドを使用する - jobs.insert API メソッドを呼び出してコピージョブを構成する
現在、GCP Console および従来の BigQuery ウェブ UI ではパーティションのコピーがサポートされていません。
必要な権限
データセット レベルでの権限のうちパーティションのコピーに必要なものは、コピー対象のパーティションが含まれるコピー元データセットに対する READER アクセス権と、コピー先データセットに対する WRITER アクセス権です。
データセット レベルの権限を使用するのではなく、bigquery.tables.create と bigquery.tables.getData の権限が含まれるプロジェクト レベルの IAM 役割を活用することもできます。bigquery.tables.create 権限は、コピー先のデータセットでのパーティションのコピーの作成に必要です（コピー先テーブルが新規の場合）。bigquery.tables.getData 権限は、コピー元のパーティションのデータの読み取りに必要です。
事前定義されたプロジェクト レベルの IAM 役割のうち、プロジェクト内のすべてのデータセットに対する bigquery.tables.create と bigquery.tables.getData 権限をともに含むものは以下のとおりです。
コピージョブを実行するには、bigquery.jobs.create 権限も付与されている必要があります。事前定義されたプロジェクト レベルの IAM 役割のうち、bigquery.jobs.create 権限を含むものは以下のとおりです。
また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分が作成した任意のテーブルまたはパーティション内のデータを読み取りまたはコピーできます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルとパーティションを完全に制御できます。
BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。
単一のパーティションのコピー
Console
GCP Console では、パーティションのコピーはサポート対象外です。
従来の UI
従来の BigQuery ウェブ UI では、パーティションのコピーはサポート対象外です。
コマンドライン
パーティションをコピーするには、コマンドライン ツールの bq cp（コピー）コマンドとパーティション デコレータ（$[DATE]、使用例: $20160201）を組み合わせます。
オプションのフラグを使用して、コピー先パーティションの書き込み処理を制御できます。
-aまたは--append_tableを指定すると、コピー元パーティションのデータがコピー先データセット内の既存のテーブルまたはパーティションに追加されます。-fまたは--forceを指定すると、コピー先データセット内の既存のテーブルまたはパーティションが上書きされますが、確認を求めるプロンプトは表示されません。-nまたは--no_clobberを指定すると、コピー先データセット内にテーブルまたはパーティションが存在している場合、エラー メッセージTable '[PROJECT_ID]:[DATASET].[TABLE] or [TABLE]$[DATE]' already exists, skippingが返されます。-nが指定されていない場合は、デフォルトの動作として、コピー先のテーブルやパーティションを置き換えるかどうかの選択を求めるプロンプトが表示されます。--destination_kms_keyは顧客管理 Cloud KMS 鍵であり、コピー先テーブルまたはパーティションの暗号化に使用されます。
cp コマンドでは --time_partitioning_field フラグと --time_partitioning_type フラグはサポートされていません。コピージョブを使用して取り込み時間分割テーブルを分割テーブルに変換することはできません。
--destination_kms_key はここでは説明しません。詳細については、Cloud KMS 鍵によるデータの保護をご覧ください。
コピー元またはコピー先のデータセットがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセット名に追加します。
--location フラグを指定して、その値を該当するロケーションに設定します。
bq --location=[LOCATION] cp -a -f -n [PROJECT_ID]:[DATASET].[SOURCE_TABLE]$[SOURCE_PARTITION] [PROJECT_ID]:[DATASET].[DESTINATION_TABLE]$[DESTINATION_PARTITION]
各項目の説明は次のとおりです。
[LOCATION]はロケーションの名前です。--locationフラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。[PROJECT_ID]はプロジェクト ID です。[DATASET]は、コピー元またはコピー先データセットの名前です。[SOURCE_TABLE]は、コピーするテーブルです。[SOURCE_PARTITION]は、コピー元パーティションのパーティション デコレータです。[DESTINATION_TABLE]は、宛先データセット内のテーブルの名前です。[DESTINATION_PARTITION]は、コピー先パーティションのパーティション デコレータです。
例:
パーティションを新しいテーブルにコピーする
mydataset.mytable にある 2018 年 1 月 30 日のパーティションを新しいテーブル mydataset.mytable2 にコピーするには、次のコマンドを入力します。mydataset はデフォルト プロジェクトにあります。mydataset は US マルチリージョン ロケーションに存在します。
bq --location=US cp -a 'mydataset.mytable$20180130' mydataset.mytable2
パーティションを分割されていないテーブルにコピーする
mydataset.mytable にある 2018 年 1 月 30 日のパーティションを分割されていないテーブル mydataset2.mytable2 にコピーするには、次のコマンドを入力します。-a ショートカットが指定されているため、パーティションのデータは分割されていないコピー先テーブルに追加されます。データセットは両方ともデフォルト プロジェクトにあります。どちらのデータセットも asia-northeast1 リージョンに存在します。
bq --location=asia-northeast1 cp -a 'mydataset.mytable$20180130' mydataset2.mytable2
mydataset.mytable にある 2018 年 1 月 30 日のパーティションを分割されていないテーブル mydataset2.mytable2 にコピーするには、次のコマンドを入力します。-f ショートカットが指定されているため、分割されていないコピー先テーブルがプロンプトなしで上書きされます。どちらのデータセットもデフォルト プロジェクトにあり、US マルチリージョン ロケーションに存在します。
bq --location=US cp -f 'mydataset.mytable$20180130' mydataset2.mytable2
パーティションを別の分割テーブルにコピーする
mydataset.mytable にある 2018 年 1 月 30 日のパーティションを別の分割テーブル mydataset2.mytable2 にコピーするには、次のコマンドを入力します。-a ショートカットが指定されているため、パーティションのデータはコピー先テーブルに追加されます。コピー先テーブルにはパーティション デコレータが指定されていないため、コピー元のパーティション キーが維持され、データはコピー先テーブルの 2018 年 1 月 30 日のパーティションにコピーされます。コピー先テーブルにパーティション デコレータを指定して、データを特定のパーティションにコピーすることもできます。mydataset はデフォルト プロジェクトにあります。
mydataset2 はデフォルト プロジェクトではなく myotherproject にあります。どちらのデータセットも US マルチリージョン ロケーションに存在します。
bq --location=US cp -a 'mydataset.mytable$20180130' myotherproject:mydataset2.mytable2
mydataset.mytable にある 2018 年 1 月 30 日のパーティションを、別の分割テーブル mydataset2.mytable2 の 2018 年 2 月 20 日のパーティションにコピーするには、次のコマンドを入力します。-f ショートカットが指定されているため、コピー先テーブルの 2018 年 2 月 20 日のパーティションがプロンプトなしに上書きされます。パーティション デコレータを使用しない場合は、コピー先テーブル内のすべてのデータが上書きされます。mydataset はデフォルト プロジェクトにあります。mydataset2 はデフォルト プロジェクトではなく myotherproject にあります。どちらのデータセットも US マルチリージョン ロケーションに存在します。
bq --location=US cp -f 'mydataset.mytable$20180130' 'myotherproject:mydataset2.mytable2$20180220'
mydataset.mytable にある 2018 年 1 月 30 日のパーティションを別の分割テーブル mydataset2.mytable2 にコピーするには、次のコマンドを入力します。
mydataset はデフォルト プロジェクトにあります。mydataset2 はデフォルト プロジェクトではなく myotherproject にあります。コピー先テーブルにデータがある場合は、デフォルトの動作として、上書きするかどうかを確認するプロンプトが表示されます。どちらのデータセットも asia-northeast1 リージョンに存在します。
bq --location=asia-northeast1 cp 'mydataset.mytable$20180130' myotherproject:mydataset2.mytable2
API
jobs.insert メソッドを呼び出し、コピージョブを構成します。ジョブリソースの jobReference セクションにある location プロパティでリージョンを指定します。
ジョブ構成で以下のプロパティを指定します。
sourceTableプロパティに、コピー元のデータセット、テーブル、パーティションを入力します。destinationTableプロパティに、コピー先のデータセットとテーブルを入力します。writeDispositionプロパティを使用して、コピー先のテーブルまたはパーティションにデータを追加するか、上書きするかを指定します。
複数のパーティションのコピー
複数のパーティションをコピーする手順は以下のとおりです。
Console
現在、GCP Console では、パーティションのコピーはサポート対象外です。
従来の UI
現在、従来の BigQuery ウェブ UI では、パーティションのコピーはサポート対象外です。
コマンドライン
複数のパーティションをコピーするプロセスは単一のパーティションをコピーするプロセスと同じですが、複数のコピー元パーティションをカンマ区切りのリストとして指定します。
bq --location=[LOCATION] cp 'mydataset.mytable$20180130,mydataset.mytable$20180131' myotherproject:mydataset.mytable2
API
jobs.insert メソッドを呼び出し、コピージョブを構成します。ジョブリソースの jobReference セクションにある location プロパティでリージョンを指定します。
ジョブ構成で以下のプロパティを指定します。
sourceTablesプロパティに、複数のコピー元パーティション（データセット名とテーブル名を含む）を入力します。destinationTableプロパティに、コピー先のデータセットとテーブルを入力します。writeDispositionプロパティを使用して、コピー先のテーブルまたはパーティションにデータを追加するか、上書きするかを指定します。
分割テーブルの削除
時間分割テーブルとそのすべてのパーティションを削除するプロセスは、標準テーブルを削除するプロセスと同じです。テーブルの削除の詳細については、テーブルの削除をご覧ください。
分割テーブルのパーティションの削除
分割テーブルのパーティションを削除するには、コマンドライン ツールの bq rm コマンドを使用するか、API の tables.delete メソッドを呼び出します。現在、従来の BigQuery ウェブ UI によるパーティションの削除はサポートされていません。
パーティション デコレータを使用すると、特定のパーティションを削除できます。たとえば、mydataset.mytable という分割テーブルにある 2016 年 3 月 1 日のパーティション（$20160301）を削除するには、次のコマンドを使用します。
bq rm 'mydataset.mytable$20160301'
分割テーブル内のパーティションのリストを取得するには、取り込み時間分割テーブル内のパーティションの一覧表示または分割テーブル内のパーティションの一覧表示をご覧ください。
現時点では、一度に削除できるパーティションは 1 つだけです。
必要な権限
パーティションを削除するには、データセット レベルで OWNER アクセス権が付与されているか、bigquery.tables.delete 権限を含むプロジェクトレベルの IAM 役割が割り当てられている必要があります。次の事前定義されたプロジェクト レベルの IAM 役割には、bigquery.tables.delete 権限が含まれています。
事前定義されたプロジェクト レベルの役割が割り当てられているユーザーは、そのプロジェクト内の任意の分割テーブルのパーティションを削除できます。データセット レベルで OWNER 権限が割り当てられているユーザーが削除できるのは、そのデータセット内のテーブルのパーティションだけです。
また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分が作成した任意のデータセット内のテーブルまたはパーティションを削除できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセット、そこに含まれるすべてのテーブル、およびすべてのテーブル パーティションを完全に制御できます。
BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセット レベルの役割の詳細については、データセットに対する基本の役割をご覧ください。
分割テーブル内のパーティションの削除
パーティションが 2 つある特別なパーティションではない限り、パーティションのデコレータを指定することでパーティションを削除できます。現在、__NULL__ パーティションと __UNPARTITIONED__ パーティションは削除できません。
分割テーブルのパーティションを削除する手順は以下のとおりです。
Console
GCP Console では、パーティションの削除はサポート対象外です。
従来の UI
従来の BigQuery ウェブ UI では、パーティションの削除はサポート対象外です。
CLI
bq rm コマンドで --table フラグ（または -t ショートカット）を指定し、パーティション デコレータ（$[DATE]）を参照して分割テーブルの特定のパーティションを削除します。CLI を使用してパーティションを削除するときは、操作の確認を求められます。--force フラグ（または -f ショートカット）を使用すると、確認をスキップできます。
分割テーブルを含むデータセットがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセット名に追加します。
bq rm -f -t [PROJECT_ID]:[DATASET].[TABLE]$[DATE]
各項目の説明は次のとおりです。
[PROJECT_ID]はプロジェクト ID です。[DATASET]は、テーブルを含むデータセットの名前です。[TABLE]は、テーブルの名前です。$[DATE]は、削除するパーティションのパーティション デコレータです。
例:
mydataset.mytable という分割テーブルの 2016 年 3 月 1 日のパーティション（$20160301）を削除するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトにあります。
bq rm 'mydataset.mytable$20160301'
mydataset.mytable という分割テーブルの 2017 年 1 月 1 日のパーティション（$20170101）を削除するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトではなく myotherproject にあります。
bq rm 'myotherproject:mydataset.mytable$20170101'
mydataset.mytable という分割テーブルの 2018 年 1 月 18 日のパーティション（$20180118）を削除するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトではなく myotherproject にあります。-f ショートカットを使用して確認をスキップします。
bq rm -f 'myotherproject:mydataset.mytable$20180118'
API
tables.delete メソッドを呼び出し、tableId パラメータを使用してテーブルとパーティション デコレータを指定します。
ご不明な点がありましたら、Google の