分割テーブルの管理

このドキュメントでは、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 では、パーティションの有効期限の更新はサポートされていません。ただし、どちらの UI でも、DDL ステートメントを使用すればパーティションの有効期限を更新できます。

テーブルのパーティション有効期限を更新すると、パーティションの作成時点に関係なく、すべてのパーティションに同じ設定が適用されます。

テーブルのパーティション有効期限を更新する際は、パーティションの日付に基づいて UTC の午前 0 時からパーティションの有効期限を計算する必要があります。

分割テーブルにもテーブル有効期限が構成されている場合は、テーブルとテーブル内のすべてのパーティションがテーブル有効期限の設定に従って削除されます。テーブルの有効期限の方がパーティションの有効期限よりも優先されます。

たとえば、分割テーブルの有効期限が 5 日、パーティションの有効期限が 7 日に設定されている場合、テーブルとテーブル内のすべてのパーティションは 5 日後に削除されます。

2016 年 12 月 13 日よりも前に作成された分割テーブルを使用しているプロジェクトの場合、パーティションの有効期限はパーティションの最終更新日で決まります。この規則は、同じプロジェクトに作成された新しいテーブルにも適用されます。プロジェクトを新しい規則に移行するには、BigQuery 公開バグトラッカーでリクエストを送信してください。

分割テーブルのパーティションの有効期限を更新する手順は以下のとおりです。

Console

は、

GCP Console で BigQuery ウェブ UI を開きます。
BigQuery ウェブ UI に移動
[クエリを新規作成] をクリックします。

[クエリエディタ] テキスト領域に DDL ステートメントを入力します。

 #standardSQL
 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   -- Sets partition expiration to 5 days
   partition_expiration_days=5
 )

従来の UI

は、

BigQuery ウェブ UI に移動します。

BigQuery ウェブ UI に移動
[Compose query] をクリックします。

[New Query] テキスト領域に DDL ステートメントを入力します。

 #standardSQL
 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   -- Sets partition expiration to 5 days
   partition_expiration_days=5
 )

コマンドライン

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 プロパティでリージョンを指定します。

ジョブ構成で以下のプロパティを指定します。

sourceTables プロパティに、コピー元のデータセット、テーブル、パーティションを入力します。
destinationTable プロパティに、コピー先のデータセットとテーブルを入力します。
writeDisposition プロパティを使用して、コピー先のテーブルまたはパーティションにデータを追加するか上書きするかを指定します。

複数のパーティションのコピー

複数のパーティションをコピーする手順は以下のとおりです。

Console

現在、GCP Console では、パーティションのコピーはサポート対象外です。

従来の UI

現在、従来の BigQuery ウェブ UI では、パーティションのコピーはサポート対象外です。

コマンドライン

複数のパーティションをコピーするプロセスは単一のパーティションをコピーするプロセスと同じですが、複数のコピー元パーティションをカンマ区切りのリストとして指定します。

bq --location=[LOCATION] cp 'mydataset.mytable$20180130,mydataset.mytable$20180131' myotherproject:mydataset.mytable2

API

ジョブ構成で以下のプロパティを指定します。

sourceTables プロパティに、複数のコピー元パーティション（データセット名とテーブル名を含む）を入力します。
destinationTable プロパティに、コピー先のデータセットとテーブルを入力します。
writeDisposition プロパティを使用して、コピー先のテーブルまたはパーティションにデータを追加するか上書きするかを指定します。

分割テーブルの削除

時間分割テーブルとそのすべてのパーティションを削除するプロセスは、標準テーブルを削除するプロセスと同じです。テーブルの削除の詳細については、テーブルの削除をご覧ください。

分割テーブルのパーティションの削除

分割テーブルのパーティションを削除するには、コマンドラインツールの bq rm コマンドを使用するか、tables.delete API メソッドを呼び出します。現在、従来の 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 アクセス権が付与されたユーザーは、そのデータセット、そこに含まれるすべてのテーブル、およびすべてのテーブルパーティションを完全に制御できます。

分割テーブル内のパーティションの削除

パーティションが 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 パラメータを使用してテーブルとパーティションデコレータを指定します。

分割テーブルのプロパティの更新

必要な権限

分割テーブルの説明の更新

テーブルの有効期限の更新

パーティションの有効期限の更新

Console

従来の UI

コマンドライン

API

スキーマ定義の更新

分割テーブルの名前の変更

分割テーブルのコピー

単一の分割テーブルのコピー

複数の分割テーブルのコピー

パーティションのコピー

必要な権限

単一のパーティションのコピー

Console

従来の UI

コマンドライン

API

複数のパーティションのコピー

Console

従来の UI

コマンドライン

API

分割テーブルの削除

分割テーブルのパーティションの削除

必要な権限

分割テーブル内のパーティションの削除

Console

従来の UI

CLI

API

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