このドキュメントでは、BigQuery でパーティション分割テーブルを管理する方法について説明します。取り込み時間パーティション分割テーブルとパーティション分割テーブルはどちらも同じ方法で管理されます。パーティション分割テーブルでは、以下の管理タスクを実行できます。
- 時間パーティション分割テーブルに関する以下の情報を更新する
- 時間分割テーブルの名前を変更する(テーブルをコピーする)
- 時間パーティション分割テーブルをコピーする
- パーティションをコピーする
- 時間パーティション分割テーブルを削除する
- 時間分割テーブルのパーティションを削除する
テーブル情報の取得、テーブルの一覧表示、テーブルデータへのアクセス権の制御など、パーティション分割テーブルの作成方法と使用方法の詳細については、取り込み時間パーティション分割テーブルの作成と使用、およびパーティション分割テーブルの作成と使用をご覧ください。
パーティション分割テーブルのプロパティの更新
分割テーブルの以下の情報を更新できます。
- 説明
- テーブルの有効期限
- パーティションの有効期限
- スキーマ定義
- ラベル
必要な権限
テーブル プロパティを更新するユーザーには、少なくとも bigquery.tables.update
権限と bigquery.tables.get
権限が付与されている必要があります。次の事前定義済みの IAM ロールには bigquery.tables.update
権限と bigquery.tables.get
権限が含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、そのデータセットに含まれるテーブルのプロパティの更新が許可されます。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
分割テーブルの説明の更新
分割テーブルの説明を更新するプロセスは、標準テーブルの説明を更新するプロセスと同じです。テーブルの説明を追加または変更する方法については、テーブルの説明の更新をご覧ください。
現時点では、個々のパーティションごとに説明を作成することはできません。
テーブルの有効期限の更新
分割テーブルの有効期限を更新するプロセスは、標準テーブルの有効期限を更新するプロセスと同じです。テーブルの有効期限を追加または変更する方法については、テーブルの有効期限の更新をご覧ください。
パーティションの有効期限の更新
取り込み時間、または日付 / タイムスタンプ列でパーティション分割されたテーブルを作成する際に、パーティションの有効期限を指定できます。指定した場合、この値はデータセット レベルのデフォルトのパーティション有効期限よりも優先されます。整数範囲パーティション分割テーブルは、パーティションの有効期限をサポートしていません。詳細については、取り込み時間パーティション分割テーブルの作成と使用と、日付 / タイムスタンプ パーティション分割テーブルの作成と使用をご覧ください。
テーブルの作成後はいつでも、bq
コマンドライン ツールの bq update
コマンドまたは API の tables.patch
メソッドを使用して、テーブルのパーティションの有効期限を更新できます。現在のところ、Cloud Console では、パーティション有効期限の更新はサポートされていません。ただし、DDL ステートメントを使用すると、Cloud Console のパーティション有効期限を更新できます。
テーブルのパーティション有効期限を更新すると、パーティションがいつ作成されたかにかかわらず、すべてのパーティションに同じ設定が適用されます。
テーブルのパーティション有効期限を更新する際は、パーティションの日付に基づいて UTC の午前 0 時からパーティションの有効期限を計算する必要があります。
パーティション分割テーブルにもテーブル有効期限が設定されている場合は、テーブルとテーブル内のすべてのパーティションがテーブル有効期限の設定に従って削除されます。テーブルの有効期限の方がパーティションの有効期限よりも優先されます。
たとえば、分割テーブルの有効期限が 5 日、パーティションの有効期限が 7 日に設定されている場合、テーブルとテーブル内のすべてのパーティションは 5 日後に削除されます。
2016 年 12 月 13 日よりも前に作成された分割テーブルを使用しているプロジェクトの場合、パーティションの有効期限はパーティションの最終更新日で決まります。この規則は、同じプロジェクトに作成された新しいテーブルにも適用されます。プロジェクトを新しい規則に移行するには、BigQuery 公開バグトラッカーでリクエストを送信してください。
パーティション分割テーブルのパーティションの有効期限を更新する手順は以下のとおりです。
SQL
データ定義言語(DDL)ステートメントを使用すると、標準 SQL クエリ構文を使用してテーブルとビューの作成と変更ができます。
データ定義言語ステートメントの使用をご覧ください。
DDL ステートメントを使用してパーティション分割テーブルのパーティションの有効期限を更新するには:
Cloud Console で [BigQuery] ページを開きます。
[クエリを新規作成] をクリックします。
[クエリエディタ] テキスト領域に DDL ステートメントを入力します。
ALTER TABLE mydataset.mytable SET OPTIONS ( -- Sets partition expiration to 5 days partition_expiration_days=5 )
[実行] をクリックします。
bq
--time_partitioning_expiration
フラグを指定して bq update
コマンドを発行します。更新するパーティション分割テーブルがデフォルト プロジェクト以外のプロジェクトにある場合は、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
メソッドの方が適切です。
パーティション フィルタ要件の更新
パーティション分割テーブルを作成するときに、[パーティション フィルタを要求] オプションを有効にすると、述語フィルタの使用を要求できます。このオプションを適用した場合、WHERE
句を指定しないでパーティション分割テーブルにクエリを実行すると、次のエラーが発生します。
Cannot query over table 'project_id.dataset.table' without a
filter that can be used for partition elimination
。
パーティション分割テーブルを作成するときに [パーティション フィルタを要求] オプションを追加する方法については、パーティション分割テーブルの作成をご覧ください。
パーティション分割テーブルを作成するときに [パーティション フィルタを要求] オプションを有効にしない場合でも、テーブルを更新してオプションを追加できます。
[パーティション フィルタを要求] オプションの更新
パーティションを除外する WHERE
句を含むクエリを要求するようにパーティション分割テーブルを更新するには:
Console
パーティション分割テーブルの作成後に、Cloud Console でパーティション フィルタを要求することはできません。
bq
bq
コマンドライン ツールを使用してパーティション フィルタを要求するようにパーティション分割テーブルを更新するには、bq update
コマンドを入力して、--require_partition_filter
フラグを指定します。
デフォルト プロジェクト以外のプロジェクトにあるパーティション分割テーブルを更新するには、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。
例:
デフォルト プロジェクトで mydataset
の mypartitionedtable
を更新するには、次のように入力します。
bq update --require_partition_filter mydataset.mytable
myotherproject
で mydataset
の mypartitionedtable
を更新するには、次のように入力します。
bq update --require_partition_filter myotherproject:mydataset.mytable
API
tables.patch
メソッドを呼び出して、requirePartitionFilter
プロパティを true
に設定すると、パーティション フィルタが要求されます。tables.update
メソッドはテーブル リソース全体を置き換えるため、tables.patch
メソッドの方が適切です。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
スキーマ定義の更新
パーティション分割テーブルのスキーマ定義を更新するプロセスは、標準テーブルのスキーマ定義を更新するプロセスと同じです。詳細については、テーブル スキーマの変更をご覧ください。
分割テーブルの名前の変更
現時点では、既存の分割テーブルの名前を変更することはできません。テーブル名を変更する場合は、テーブルをコピーする手順に従います。コピー オペレーションでコピー先のテーブルを指定する場合は、新しいテーブル名を使用します。
パーティション分割テーブルのコピー
単一の分割テーブルのコピー
単一の分割テーブルをコピーするプロセスは、単一の標準テーブルをコピーするプロセスと同じです。詳細については、テーブルのコピーをご覧ください。
分割テーブルをコピーする際は、以下の点に注意してください。
コピー元テーブルとコピー先テーブルは、同じロケーションにあるデータセット内に存在する必要があります。
- パーティション分割テーブルを新しいパーティション分割テーブルにコピーする場合
- 時間パーティション分割テーブルを新しいテーブルにコピーした場合、すべてのパーティショニング情報がテーブルとともにコピーされます。新しいテーブルに設定されるパーティションは古いテーブルと同じです。
- パーティション分割されていないテーブルをパーティション分割テーブルにコピーする場合
- パーティション分割されていないテーブルをパーティション分割テーブルにコピーした場合、コピー元のデータは現在の日付に対応するパーティションにコピーされます。
- パーティション分割テーブルを別のパーティション分割テーブルにコピーする場合
- パーティション分割テーブルを別のパーティション分割テーブルにコピーするには、コピー元テーブルとコピー先テーブルのパーティションの設定が一致している必要があります。コピー先テーブルにデータを追加するか、コピー先テーブルを上書きするかを指定できます。
- パーティション分割テーブルを分割されていないテーブルにコピーする場合
- パーティション分割テーブルをパーティション分割されていないテーブルにコピーした場合、コピー先テーブルは分割されません。設定に応じて、パーティション分割されていないテーブルにデータが追加されるか、パーティション分割されていないテーブルが上書きされます。
複数の分割テーブルのコピー
複数の分割テーブルをコピーするプロセスは、複数の標準テーブルをコピーするプロセスと同じです。詳細については、複数のテーブルのコピーをご覧ください。
複数の分割テーブルをコピーする際は、以下の点に注意してください。
- 同じジョブで複数のテーブルを分割テーブルにコピーする場合、コピー元に分割テーブルと分割されていないテーブルが混在していてはなりません。
- コピー元のテーブルがすべてパーティション分割テーブルの場合、すべてのコピー元テーブルのパーティションの設定がコピー先テーブルのパーティションの設定と一致している必要があります。コピー先テーブルにデータが追加されるか、コピー先テーブルが上書きされるかは、設定によって決まります。
- コピー元テーブルとコピー先テーブルは、同じロケーションにあるデータセット内に存在する必要があります。
パーティションのコピー
次の方法で 1 つ以上のパーティションをコピーできます。
bq
コマンドライン ツールのbq cp
コマンドを使用する- jobs.insert API メソッドを呼び出して
copy
ジョブを構成する - クライアント ライブラリの使用
現在、Cloud Console では、パーティションのコピーはサポート対象外です。
必要な権限
テーブルとパーティションをコピーするユーザーには、少なくとも以下の権限が付与されている必要があります。
コピー元データセットに対して:
bigquery.tables.get
bigquery.tables.getData
コピー先データセットに対して:
bigquery.tables.create
でコピー先データセット内のテーブルまたはパーティションのコピーを作成する
bigquery.tables.create
権限、bigquery.tables.get
権限、bigquery.tables.getData
権限は、以下の IAM 事前定義ロールに含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
また、コピー ジョブを実行するには、bigquery.jobs.create
権限が付与されている必要があります。
次の事前定義された IAM ロールには bigquery.jobs.create
権限が含まれています。
bigquery.user
bigquery.jobUser
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、ユーザーはデータセット内のテーブルとパーティションをコピーできますが、コピー先データセットについては、同じユーザーが作成した場合を除き、アクセス権を明示的に指定する必要があります。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
単一のパーティションのコピー
Console
Cloud Console では、パーティションのコピーはサポート対象外です。
bq
パーティションをコピーするには、bq
コマンドライン ツールの bq cp
(コピー)コマンドに $20160201
などのパーティション デコレータ($date
)を指定して使用します。
オプションのフラグを使用して、コピー先パーティションの書き込み処理を制御できます。
-a
または--append_table
を指定すると、コピー元パーティションのデータがコピー先データセット内の既存のテーブルまたはパーティションに追加されます。-f
または--force
を指定すると、コピー先データセット内の既存のテーブルまたはパーティションが上書きされますが、確認を求めるプロンプトは表示されません。-n
または--no_clobber
を指定すると、コピー先データセット内にテーブルまたはパーティションが存在する場合、「Table '<var>project_id:dataset.table</var> or <var>table$date</var>' 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
はデフォルト プロジェクトにあります。
bq cp -a 'mydataset.mytable$20180130' mydataset.mytable2
パーティションをパーティション分割されていないテーブルにコピーする
次のコマンドを入力して mydataset.mytable
にある 2018 年 1 月 30 日のパーティションをパーティション分割されていないテーブル(mydataset2.mytable2
)にコピーします。-a
ショートカットが指定されているため、パーティションのデータはパーティション分割されていないコピー先テーブルに追加されます。データセットは両方ともデフォルト プロジェクトにあります。
bq cp -a 'mydataset.mytable$20180130' mydataset2.mytable2
次のコマンドを入力して mydataset.mytable
にある 2018 年 1 月 30 日のパーティションをパーティション分割されていないテーブル(mydataset2.mytable2
)にコピーします。-f
ショートカットが指定されているため、パーティション分割されていないコピー先テーブルがプロンプトなしで上書きされます。
bq --location=US cp -f 'mydataset.mytable$20180130' mydataset2.mytable2
パーティションを別のパーティション分割テーブルにコピーする
次のコマンドを入力して mydataset.mytable
にある 2018 年 1 月 30 日のパーティションを別のパーティション分割テーブル(mydataset2.mytable2
)にコピーします。-a
ショートカットが指定されているため、パーティションのデータはコピー先テーブルに追加されます。コピー先テーブルにはパーティション デコレータが指定されていないため、コピー元のパーティション キーが維持され、データはコピー先テーブルの 2018 年 1 月 30 日のパーティションにコピーされます。コピー先テーブルでパーティション デコレータを指定して特定のパーティションにデータをコピーすることもできます。mydataset
はデフォルト プロジェクトにあります。mydataset2
はデフォルト プロジェクトではなく myotherproject
にあります。
bq --location=US cp \
-a \
'mydataset.mytable$20180130' \
myotherproject:mydataset2.mytable2
次のコマンドを入力して mydataset.mytable
にある 2018 年 1 月 30 日のパーティションを別のパーティション分割テーブルの 2018 年 2 月 20 日のパーティション(mydataset2.mytable2
)にコピーします。-f
ショートカットが指定されているため、コピー先テーブルの 2018 年 2 月 20 日のパーティションがプロンプトなしに上書きされます。パーティション デコレータを使用しない場合、コピー先テーブルのすべてのデータが上書きされます。mydataset
はデフォルト プロジェクトにあります。mydataset2
はデフォルト プロジェクトではなく myotherproject
にあります。
bq cp \
-f \
'mydataset.mytable$20180130' \
'myotherproject:mydataset2.mytable2$20180220'
次のコマンドを入力して mydataset.mytable
にある 2018 年 1 月 30 日のパーティションを別のパーティション分割テーブル(mydataset2.mytable2
)にコピーします。mydataset
はデフォルト プロジェクトにあります。mydataset2
はデフォルト プロジェクトではなく myotherproject
にあります。コピー先テーブルにデータがある場合は、デフォルトの動作として、上書きするかどうかを確認するプロンプトが表示されます。
bq cp \
'mydataset.mytable$20180130' \
myotherproject:mydataset2.mytable2
API
jobs.insert
メソッドを呼び出して、copy
ジョブを構成します。(省略可)ジョブリソースの jobReference
セクションにある location
プロパティでリージョンを指定します。
ジョブ構成で以下のプロパティを指定します。
sourceTables
プロパティに、コピー元のデータセット、テーブル、パーティションを入力します。destinationTable
プロパティに、コピー先のデータセットとテーブルを入力します。writeDisposition
プロパティを使用して、コピー先のテーブルまたはパーティションにデータを追加するか上書きするかを指定します。
複数のパーティションのコピー
複数のパーティションをコピーするには:
Console
現在、Cloud Console では、パーティションのコピーはサポート対象外です。
bq
複数のパーティションをコピーするプロセスは単一のパーティションをコピーするプロセスと同じですが、複数のコピー元パーティションをカンマ区切りのリストとして指定します。
bq cp \ 'mydataset.mytable$20180130,mydataset.mytable$20180131' \ myotherproject:mydataset.mytable2
API
jobs.insert
メソッドを呼び出して、copy
ジョブを構成します。ジョブリソースの jobReference
セクションにある location
プロパティでリージョンを指定します。
ジョブ構成で以下のプロパティを指定します。
sourceTables
プロパティに、複数のコピー元パーティション(データセット名とテーブル名を含む)を入力します。destinationTable
プロパティに、コピー先のデータセットとテーブルを入力します。writeDisposition
プロパティを使用して、コピー先のテーブルまたはパーティションにデータを追加するか上書きするかを指定します。
分割テーブルの削除
時間分割テーブルとそのすべてのパーティションを削除するプロセスは、標準テーブルを削除するプロセスと同じです。テーブルの削除の詳細については、テーブルの削除をご覧ください。
分割テーブルのパーティションの削除
パーティション分割テーブルのパーティションを削除するには、bq
コマンドライン ツールの bq rm
コマンドを使用するか、tables.delete
API メソッドを呼び出します。
パーティション デコレータを使用すると、特定のパーティションを削除できます。たとえば、mydataset.mytable
というパーティション分割テーブルの 2016 年 3 月 1 日のパーティション($20160301
)は、次のコマンドを使用して削除できます。
bq rm 'mydataset.mytable$20160301'
パーティション分割テーブル内のパーティションのリストを取得するには、取り込み時間パーティション分割テーブル内のパーティションの一覧表示またはパーティション分割テーブル内のパーティションの一覧表示をご覧ください。
現時点では、一度に削除できるパーティションは 1 つだけです。
必要な権限
パーティションを削除するには、少なくとも bigquery.tables.delete
権限と bigquery.tables.get
権限が付与されている必要があります。次の事前定義済みの IAM ロールには bigquery.tables.delete
権限と bigquery.tables.get
権限が含まれています。
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、ユーザーはデータセットに含まれるテーブルとパーティションを削除できます。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
分割テーブル内のパーティションの削除
次に挙げる 2 つの特別なパーティションではない限り、パーティションのデコレータを指定することでパーティションを削除できます。現在、__NULL__
パーティションと __UNPARTITIONED__
パーティションは削除できません。
パーティション分割テーブルのパーティションを削除するには:
Console
Cloud Console では、パーティションの削除はサポート対象外です。
bq
bq rm
コマンドで --table
フラグ(または -t
ショートカット)を指定し、パーティション デコレータ($date
)を参照してパーティション分割テーブルの特定のパーティションを削除します。bq
コマンドライン ツールを使用してパーティションを削除する場合、操作の確認を求められます。--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
パラメータを使用してテーブルおよびパーティション デコレータを指定します。