分割テーブルの管理

このドキュメントでは、BigQuery で分割テーブルを管理する方法について説明します。取り込み時間分割テーブルと分割テーブルはどちらも同じ方法で管理されます。分割テーブルの管理タスクには以下のようなものがあります。

• 時間分割テーブルの以下の情報を更新する
  • テーブルの有効期限
  • パーティションの有効期限
  • 説明
  • スキーマ定義
  • ラベル
• 時間分割テーブルの名前を変更する（テーブルをコピーする）
• 時間分割テーブルをコピーする
• パーティションをコピーする
• 時間分割テーブルを削除する
• 時間分割テーブルのパーティションを削除する

テーブル情報の取得、テーブルの一覧表示、テーブルデータへのアクセス制御など、分割テーブルの作成と使用の詳細については、取り込み時間分割テーブルの作成と使用または分割テーブルの作成と使用をご覧ください。

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

分割テーブルの以下の情報を更新できます。

• 説明
• テーブルの有効期限
• パーティションの有効期限
• スキーマ定義
• ラベル

必要な権限

テーブルのプロパティを更新するユーザーには、データセット レベルで WRITER アクセス権が付与されているか、bigquery.tables.update 権限が必要なプロジェクト レベルの IAM 役割が割り当てられている必要があります。事前定義されたプロジェクト レベルの IAM 役割のうち、bigquery.tables.update 権限を含むものは以下のとおりです。

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

これに加えて、bigquery.user 役割には bigquery.datasets.create 権限が含まれていることから、bigquery.user 役割が割り当てられたユーザーは、そのユーザーがデータセット内に作成したどのテーブルも更新できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルとビューを完全に制御できます。

BigQuery の IAM 役割と権限の詳細については、アクセス制御をご覧ください。

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

分割テーブルの説明を更新するプロセスは、標準テーブルの説明を更新するプロセスと同じです。テーブルの説明を追加または変更する方法については、テーブルの説明の更新をご覧ください。

現時点では、個々のパーティションの説明を作成することはできません。

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

分割テーブルの有効期限を更新するプロセスは、標準テーブルの有効期限を更新するプロセスと同じです。テーブルの有効期限を追加または変更する方法については、テーブルの有効期限の更新をご覧ください。

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

分割テーブルの作成時にテーブルのパーティションの有効期限を指定するには、コマンドライン ツールの bq mk コマンドを使用するか、API の tables.insert メソッドを呼び出します。現時点では、BigQuery ウェブ UI によってパーティションの有効期限を指定することはできません。

テーブルの作成時にパーティションの有効期限を指定すると、すべてのパーティションに有効期限が適用されます。個々のパーティションに異なる有効期限を適用することはできません。

テーブルが作成された後はいつでも、CLI の bq update コマンドまたは API の tables.patch メソッドを使用してテーブルのパーティションの有効期限を更新できます。現時点では、BigQuery ウェブ UI によってパーティションの有効期限を更新することはできません。

テーブルのパーティションの有効期限を更新すると、パーティションがいつ作成されたかにかかわらず、すべてのパーティションに同じ設定が適用されます。

テーブルのパーティションの有効期限を更新するときは、パーティションの日付に基づいてパーティションの有効期限を計算する必要があります。たとえば、パーティションの日付が 2018 年 1 月 3 日で、パーティションの有効期限を 5 日に設定した場合は、最終更新日時に関係なく、そのパーティションは 2018 年 1 月 8 日に期限切れになります。

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

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

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

分割テーブルのパーティションの有効期限を更新するには:

ウェブ 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 つの分割テーブルのコピー

1 つの分割テーブルをコピーするプロセスは、1 つの標準テーブルをコピーするプロセスと同じです。詳細については、テーブルのコピーをご覧ください。

分割テーブルをコピーする際は、以下の点に注意してください。

• コピー元テーブルとコピー先テーブルは、同じロケーションにあるデータセット内に存在する必要があります。

• 分割テーブルを新しい分割テーブルにコピーする場合

  時間分割テーブルを新しいテーブルにコピーした場合、すべてのパーティショニング情報がテーブルとともにコピーされます。新しいテーブルと古いテーブルは同一のパーティションを持ちます。

• 分割されていないテーブルを分割テーブルにコピーする場合

  分割されていないテーブルを分割テーブルにコピーした場合、コピー元のデータは現在の日付に対応するパーティションにコピーされます。

• 分割テーブルを別の分割テーブルにコピーする場合

  分割テーブルを別の分割テーブルにコピーするには、コピー元テーブルとコピー先テーブルのパーティションの設定が一致している必要があります。コピー先テーブルにデータを追加するか、コピー先テーブルを上書きするかを指定できます。

• 分割テーブルを分割されていないテーブルにコピーする場合

  分割テーブルを分割されていないテーブルにコピーした場合、コピー先テーブルは分割されません。設定に応じて、分割されていないテーブルにデータが追加されるか、分割されていないテーブルが上書きされます。

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

複数の分割テーブルをコピーするプロセスは、複数の標準テーブルをコピーするプロセスと同じです。詳細については、複数のテーブルのコピーをご覧ください。

複数の分割テーブルをコピーする際は、以下の点に注意してください。

• 同じジョブで複数のテーブルを分割テーブルにコピーする場合、コピー元に分割テーブルと分割されていないテーブルが混在していてはなりません。
• コピー元のテーブルがすべて分割テーブルの場合、すべてのコピー元テーブルのパーティションの設定がコピー先テーブルのパーティションの設定と一致している必要があります。コピー先テーブルにデータが追加されるか、コピー先テーブルが上書きされるかは、設定によって決まります。
• コピー元テーブルとコピー先テーブルは、同じロケーションにあるデータセット内に存在する必要があります。

パーティションのコピー

1 つ以上のパーティションをコピーするには、コマンドライン ツールの bq cp コマンドを使用するか、API の jobs.insert メソッドを呼び出してコピージョブを構成します。現時点では、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.dataEditor
• bigquery.dataOwner
• bigquery.admin

コピージョブを実行するには、bigquery.jobs.create 権限も付与されている必要があります。事前定義されたプロジェクト レベルの IAM 役割のうち、bigquery.jobs.create 権限を含むものは以下のとおりです。

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

また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分が作成した任意のテーブルまたはパーティション内のデータを読み取りまたはコピーできます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルとパーティションを完全に制御できます。

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

1 つのパーティションのコピー

ウェブ 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] は、コピー先パーティションのパーティション デコレータです。

例:

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

パーティションを新しいテーブルにコピーする

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 プロパティを使用して、コピー先テーブルまたはパーティションにデータを追加するか、上書きするかを指定します。

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

複数のパーティションをコピーするには:

ウェブ UI

現時点では、BigQuery ウェブ UI によってパーティションをコピーすることはできません。

コマンドライン

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

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 権限が含まれています。

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

事前定義されたプロジェクト レベルの役割が割り当てられているユーザーは、そのプロジェクト内の任意の分割テーブルのパーティションを削除できます。データセット レベルで OWNER 権限が割り当てられているユーザーが削除できるのは、そのデータセット内のテーブルのパーティションだけです。

また、bigquery.user 役割には bigquery.datasets.create 権限が含まれているため、bigquery.user 役割に割り当てられたユーザーは、自分が作成した任意のデータセット内のテーブルまたはパーティションを削除できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーには、作成したデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセット、そこに含まれるすべてのテーブル、およびすべてのテーブル パーティションを完全に制御できます。

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

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

パーティションが 2 つの特別なパーティションではない限り、パーティションのデコレータを指定してパーティションを削除できます。現在、__NULL__ パーティションと __UNPARTITIONED__ パーティションは削除できません。

分割テーブルのパーティションを削除するには:

ウェブ 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] は、削除するパーティションのパーティション デコレータです。

例:

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

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