取り込み時間パーティション分割テーブルの作成と使用

このドキュメントでは、BigQuery で取り込み時間パーティション分割テーブルを作成および使用する方法について説明します。日付 / タイムスタンプパーティション分割テーブルについては、日付 / タイムスタンプパーティション分割テーブルの作成と使用をご覧ください。整数範囲のパーティション分割テーブルについては、パーティション分割テーブルの作成と使用をご覧ください。

取り込み時間パーティション分割テーブルを作成すると、次のことができるようになります。

テーブルデータへのアクセスを制御する
パーティション分割テーブルに関する情報を取得する
データセット内のパーティション分割テーブルのリストを取得する
メタテーブルを使用してパーティション分割テーブルのメタデータを取得する

パーティション分割テーブルのプロパティの更新、パーティション分割テーブルのコピー、パーティション分割テーブルの削除など、パーティション分割テーブルを管理する方法の詳細については、パーティション分割テーブルの管理をご覧ください。

取り込み時間パーティション分割テーブルの作成

BigQuery では次のようにして取り込み時間パーティション分割テーブルを作成できます。

partition_expression を指定した DDL CREATE TABLE ステートメントを使用する
Cloud Console または従来の BigQuery ウェブ UI を手動で使用する
コマンドラインツールの bq mk コマンドを使用する
プログラムで tables.insert API メソッドを呼び出す
クライアントライブラリを使用する
クエリ結果から作成する
データを読み込むときに作成する
日付別テーブルをパーティション分割テーブルに変換して作成

テーブルの命名

BigQuery でテーブルを作成するとき、テーブル名はデータセットごとに一意である必要があります。テーブル名の要件は次のとおりです。

1,024 文字以内
英字（大文字または小文字）、数字、アンダースコアだけが含まれている

必要な権限

テーブルを作成するには、少なくとも次の権限が付与されている必要があります。

bigquery.tables.create（テーブルを作成する権限）
bigquery.tables.updateData（読み込みジョブ、クエリジョブ、コピージョブを使用してテーブルにデータを書き込む権限）
bigquery.jobs.create（クエリジョブ、読み込みジョブ、コピージョブを実行してテーブルにデータを書き込む権限）

テーブルに書き込むデータにアクセスするには、bigquery.tables.getData などの追加の権限が必要になる場合があります。

bigquery.tables.create 権限および bigquery.tables.updateData 権限はいずれも、事前定義された以下の Cloud IAM のロールに含まれています。

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

bigquery.jobs.create 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner アクセス権がユーザーに付与されます。bigquery.dataOwner アクセス権があれば、データセット内でテーブルを作成および更新できます。

BigQuery での Cloud IAM の役割と権限については、事前定義された役割と権限をご覧ください。

スキーマ定義を持つ空の取り込み時間パーティション分割テーブルの作成

スキーマ定義を持つ空の取り込み時間パーティション分割テーブルを作成すると、次のことができるようになります。

Cloud Console または従来の BigQuery ウェブ UI を使用してスキーマを入力する
コマンドラインツールを使用してインラインでスキーマを指定する
コマンドラインツールを使用して JSON スキーマファイルを送信する
API の tables.insert メソッドを呼び出すときに、テーブルリソースでスキーマを指定する

テーブルスキーマの指定方法の詳細については、スキーマの指定をご覧ください。

時間パーティション分割テーブルを作成すると、次のことができるようになります。

データを読み込む
クエリの結果を書き込む
データをコピーする

スキーマ定義を持つ空の時間パーティション分割テーブルを作成するには、次の手順に従います。

Console

ナビゲーションパネルの [リソース] セクションで、データセットを選択します。ウィンドウの右側にある [テーブルを作成] をクリックします。
[テーブルの作成] ページの [ソース] セクションで、[Create empty table] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。
- スキーマ情報を手動で入力します。
  - [テキストとして編集] を有効にし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --format=prettyjson dataset.table を入力します。
  - [フィールドを追加] を使用して、スキーマを手動で入力します。
[パーティションとクラスタの設定] セクションで、次の操作を行います。
- [パーティショニング] で [パーティショニングなし] をクリックし、[取り込み時間により分割] を選択します。
（省略可）クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[パーティショニングフィルタ] で [パーティションフィルタを要求] ボックスをクリックします。パーティションフィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。
（省略可）[詳細オプション] をクリックします。Cloud Key Management Service 鍵を使用する場合は、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
[テーブルを作成] をクリックします。

テーブルの作成後に、パーティション分割テーブルのテーブル有効期限、説明、ラベルを更新できます。BigQuery ウェブ UI を使用してテーブルを作成した後にパーティションの有効期限を追加することはできません。

従来の UI

ナビゲーション内のデータセット名の横にある下矢印アイコンをクリックし、[Create new table] をクリックします。
[Create Table] ページの [Source Data] セクションで、[Create empty table] をクリックします。
[Create Table] ページの [Destination Table] セクションで、次の操作を行います。
- [Table name] で適切なデータセットを選択し、作成するテーブルの名前をテーブル名のフィールドに入力します。
- [Table type] が [Native table] に設定されていることを確認します。
[Schema] セクションで、スキーマ定義を手動で入力します。
- スキーマ情報は次の方法により手動で入力できます。
  - [Edit as Text] をクリックし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --schema --format=prettyjson project_id:dataset.table を入力します。
  - [Add Field] を使用してスキーマを入力します。
[Options] セクションで、次の操作を行います。
- [Partitioning] で、[None] をクリックして [Day] を選択します。
- [Encryption Type] は Default オプションのままにします。このプロパティは、顧客管理の暗号鍵に使用されます。BigQuery のデフォルトでは、格納するお客様のコンテンツを保存時に暗号化します。
[Create Table] をクリックします。

bq

--table フラグ（または -t ショートカット）および -- time_partitioning_type フラグ（DAY または HOUR をパーティショニングタイプに合わせて設定）を指定し、mk コマンドを実行します。テーブルのスキーマ定義をインラインで、または JSON スキーマファイルを使用して指定できます。オプションパラメータには --expiration、-- description、--time_partitioning_expiration、--destination_kms_key、--label があります。デフォルト以外のプロジェクトでテーブルを作成する場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

--destination_kms_key はここでは説明しません。このフラグの使用の詳細については、Cloud KMS 鍵によるデータの保護をご覧ください。

次のコマンドを入力して、スキーマ定義を持つ空の取り込み時間パーティション分割テーブルを作成します。

bq mk --table \
--expiration integer1 \
--time_partitioning_type=unit_time \
--time_partitioning_expiration integer2 \
--description "description" \
-label key:value,key:value \
project_id:dataset.table \
schema

ここで

integer1 はテーブルのデフォルトの存続期間（秒）です。最小値は 3,600 秒（1 時間）です。現在の UTC 時間にこの整数値を足した値が有効期限になります。パーティション分割テーブルの作成時に有効期限を設定した場合、データセットのデフォルトのテーブル有効期限設定は無視されます。この値を設定すると、指定した時間が経過したときにテーブルとすべてのパーティションは削除されます。
unit_time は、パーティショニングタイプに応じて DAY または HOUR です。time_partitioning_type が指定されていない場合は、デフォルトで DAY になります。
integer2 は、テーブルのパーティションのデフォルトの存続期間（秒）です。最小値はありません。パーティションの日付にこの整数値を足した値が有効期限になります。パーティションの有効期限はテーブルの有効期限とは無関係であり、それをオーバーライドしません。テーブルの有効期限より長いパーティション有効期限を設定すると、テーブルの有効期限が優先されます。
description はテーブルの説明です。引用符で囲みます。
key:value は、ラベルを表す Key-Value ペアです。カンマ区切りのリストを使用して複数のラベルを入力できます。
project_id はプロジェクト ID です。
dataset は、プロジェクト内のデータセットです。
table は、作成する時間パーティション分割テーブルの名前です。
schema は、column:data_type,column:data_type という形式のインラインスキーマ定義、またはローカルマシン上の JSON スキーマファイルへのパスです。

コマンドラインでスキーマを指定する場合、RECORD（STRUCT）型と列の説明を含めることはできません。また、列のモードも指定できません。すべてのモードはデフォルトの NULLABLE になります。説明、モード、RECORD 型を含めるには、JSON スキーマファイルを指定します。

例:

デフォルトプロジェクトにある mydataset 内に mytable という名前の取り込み時間パーティション分割テーブルを作成するには、次のコマンドを入力します。パーティショニングタイプは DAY、パーティショニングの有効期限は 259,200 秒（3 日）、テーブルの有効期限は 2,592,000 秒（1 か月、つまり 30 日）、説明は This is my time partitioned table、ラベルは organization:development に設定されます。このコマンドでは --table ではなく -t ショートカットを使用しています。スキーマはインラインで qtr:STRING,sales:FLOAT,year:STRING と指定されています。

bq mk -t \
--expiration 2592000 \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
--description "This is my time partitioned table" \
--label organization:development \
mydataset.mytable \
qtr:STRING,sales:FLOAT,year:STRING

デフォルトプロジェクトではない myotherproject 内に mytable という名前のパーティション分割テーブルを作成するには、次のコマンドを入力します。パーティショニングタイプは DAY、パーティショニングの有効期限は 259,200 秒（3 日）、説明は This is my time partitioned table、ラベルは organization:development に設定されます。このコマンドでは --table ではなく -t ショートカットを使用しています。このコマンドではテーブルの有効期限を指定していません。データセットにデフォルトのテーブル有効期限がある場合、それが適用されます。データセットにデフォルトのテーブル有効期限がない場合、テーブルは期限切れになりませんが、パーティションは 3 日で期限切れになります。スキーマファイルのパスは /tmp/myschema.json です。

bq mk -t \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
--description "This is my time partitioned table" \
--label organization:development \
myotherproject:mydataset.mytable \
/tmp/myschema.json

テーブルの作成後に、取り込み時間パーティション分割テーブルのテーブル有効期限、パーティションの有効期限、説明、ラベルを更新できます。

API

timePartitioning プロパティと schema プロパティを指定する定義済みのテーブルリソースを使用して tables.insert メソッドを呼び出します。

クエリ結果から取り込み時間パーティション分割テーブルを作成する

クエリ結果からパーティション分割テーブルを作成するには、結果を新しい宛先テーブルに書き込みます。パーティション分割テーブルまたはパーティション分割されていないテーブルをクエリすることによって、新しいパーティション分割テーブルを作成できます。クエリ結果を使用して、既存のテーブルをパーティション分割テーブルに変更することはできません。

時間パーティション分割テーブルに対するクエリの詳細については、パーティション分割テーブルのクエリをご覧ください。

Console

Console の BigQuery ウェブ UI を使用してデータをクエリする場合、宛先テーブルのパーティショニングオプションを指定できません。

従来の UI

従来の BigQuery ウェブ UI を使用してデータのクエリを実行する場合、宛先テーブルのパーティショニングオプションを指定できません。

bq

bq query コマンドを入力し、クエリ結果に基づいて永続テーブルを作成することを --destination_table フラグによって指定した後、作成するテーブルが取り込み時間パーティション分割テーブルであることを --time_partitioning_type フラグによって指定します。DAY と HOUR は、パーティションの粒度に応じて --time_partitioning_type に指定できる値です。

標準 SQL 構文を使用するには、use_legacy_sql=false フラグを指定します。デフォルトプロジェクト以外のプロジェクトにあるテーブルにクエリ結果を書き込むには、project_id:dataset の形式でプロジェクト ID をデータセット名に追加します。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

次のコマンドを入力して、クエリ結果から宛先の取り込み時間パーティション分割テーブルを新規作成します。

bq --location=location query \
--destination_table project_id:dataset.table \
--time_partitioning_type=unit_time \
--use_legacy_sql=false \
'query'

ここで

location はロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
project_id はプロジェクト ID です。
dataset は、新しい時間パーティション分割テーブルが組み込まれるデータセットの名前です。
table は、クエリ結果を使用して作成する時間パーティション分割テーブルの名前です。
- unit_time は、パーティショニングタイプに応じて DAY または HOUR です。time_partitioning_type が指定されていない場合は、デフォルトで DAY になります。
query は、標準 SQL 構文のクエリです。

例:

次のコマンドを入力して、mydataset にある mytable という宛先の日付別取り込み時間パーティション分割テーブルにクエリ結果を書き込みます。このデータセットはデフォルトプロジェクトにあります。このクエリは、パーティション分割されていないテーブル（USA Name データの一般公開データセット）からデータを取得します。

bq query \
--destination_table mydataset.mytable \
--time_partitioning_type=DAY \
--use_legacy_sql=false \
'SELECT
   name,
   number
 FROM
   `bigquery-public-data`.usa_names.usa_1910_current
 WHERE
   gender = "M"
 ORDER BY
   number DESC'

次のコマンドを入力すると、mydataset 内の mytable という取り込み時間パーティション分割テーブルにクエリ結果が書き込まれます。このデータセットはデフォルトプロジェクトではなく myotherproject にあります。このクエリは、パーティション分割されていないテーブル（一般公開データセット USA Name Data）からデータを取得します。

bq query \
--destination_table myotherproject:mydataset.mytable \
--time_partitioning_type=DAY \
--use_legacy_sql=false \
'SELECT
   name,
   number
 FROM
   `bigquery-public-data`.usa_names.usa_1910_current
 WHERE
   gender = "M"
 ORDER BY
   number DESC'

API

クエリの結果を永続的な取り込み時間パーティション分割テーブルに保存するには、jobs.insert メソッドを呼び出し、query ジョブを構成して destinationTable プロパティと timePartitioning プロパティの値を含めます。

データを読み込むときの取り込み時間パーティション分割テーブルの作成

新しいテーブルにデータを読み込むときにパーティショニングオプションを指定することによって、取り込み時間パーティション分割テーブルを作成できます。データを読み込む前に空のパーティション分割テーブルを作成しておく必要はありません。パーティション分割テーブルを作成すると同時にデータを読み込むことができます。

BigQuery にデータを読み込むときに、テーブルスキーマを指定できます。また、サポートされているデータ形式であれば、スキーマの自動検出を使用できます。

パーティションデコレータを使用してデータを特定のパーティションに読み込むことができます。タイムゾーンを調整するには、パーティションデコレータを使用し、目的のタイムゾーンに基づいてデータをパーティションに読み込みます。たとえば、太平洋標準時（PST）を使用している場合、対応するパーティションデコレータを使用して、2016 年 5 月 1 日 PST に生成されたすべてのデータをその日付のパーティションに読み込みます。

table_name$20160501

データの読み込みの詳細については、BigQuery へのデータの読み込みの概要をご覧ください。

日付別テーブルの取り込み時間パーティション分割テーブルへの変換

日付分割テーブルを以前に作成している場合は、bq コマンドラインツールで partition コマンドを使用することで、関連テーブルのセット全体を 1 つの取り込み時間パーティション分割テーブルに変換できます。日付別テーブルでは、table_YYYYMMDD の形式の命名規則を使用している必要があります。例: mytable_20160101、...、mytable_20160331。

オプションパラメータには --time_partitioning_expiration、--location、--time_partitioning_type があります。指定されていない場合、--time_partitioning_type はデフォルトで DAY になります。ソーステーブルまたは宛先テーブルがデフォルト以外のプロジェクトにある場合は、project_id:dataset の形式でプロジェクト ID をデータセット名に追加します。

次のコマンドを入力して、一連の日付別テーブルを、日付でパーティション分裂された、単一の取り込み時間パーティション分割テーブルに変換します。

bq --location=location partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration integer \
project_id:dataset.source_table_ \
project_id:dataset.destination_table

ここで

location はロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
integer は、テーブルのパーティションのデフォルトの存続期間（秒）です。最小値はありません。パーティションの日付（UTC）に、この整数値を足した値が有効期限になります。パーティションの有効期限はテーブルの有効期限とは無関係であり、それをオーバーライドしません。テーブルの有効期限より長いパーティション有効期限を設定すると、テーブルの有効期限が優先されます。
project_id はプロジェクト ID です。
dataset は、プロジェクト内のデータセットです。
sourcetable は、日付別テーブルの接頭辞です。
destination_table は、作成するパーティション分割テーブルの名前です。

例:

デフォルトプロジェクトにある mydataset 内に mytable_partitioned という名前の取り込み時間パーティション分割テーブルを作成するには、次のコマンドを入力します。テーブルは日付でパーティション分割され、パーティショニングの有効期限は 259,200 秒（3 日間）に設定されます。日付別ソーステーブルには sourcetable_ という接頭辞が付いています。ソーステーブルもデフォルトプロジェクトにあります。

bq partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
mydataset.sourcetable_ \
mydataset.mytable_partitioned

このコマンドを実行すると、日付別テーブルからパーティションを生成するコピージョブが作成されます。たとえば、日付別テーブルが sourcetable_20180126 と sourcetable_20180127 である場合、コピージョブによって mydataset.mytable_partitioned$20180126 と mydataset.mytable_partitioned$20180127 というパーティションが作成されます。

mydataset 内に mytable_partitioned という名前の取り込み時間パーティション分割テーブルを作成するには、次のコマンドを入力します。mydataset はデフォルトプロジェクトではなく myotherproject にあります。テーブルは日付でパーティション分割され、パーティショニングの有効期限は 86,400 秒（1 日）に設定されます。日付別ソーステーブルには sourcetable_ という接頭辞が付いています。ソーステーブルはデフォルトプロジェクトにあります。

bq partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration 86400 \
mydataset.sourcetable_ \
myotherproject:mydataset.mytable_partitioned

デフォルトプロジェクトにある mydataset 内に mytable_partitioned という名前の取り込み時間パーティション分割テーブルを作成するには、次のコマンドを入力します。mydataset は asia-northeast1 リージョンに作成されたデータセットです。テーブルは日付でパーティション分割され、パーティショニングの有効期限は 259,200 秒（3 日間）に設定されます。日付別ソーステーブルには sourcetable_ という接頭辞が付いています。ソーステーブルもデフォルトプロジェクトにあります。

bq --location=asia-northeast1 partition \
--time_partitioning_type=DAY \
--time_partitioning_expiration 259200 \
mydataset.sourcetable_ \
mydataset.mytable_partitioned

時間パーティション分割テーブルへのアクセスの制御

テーブルまたはパーティションにアクセス制御を直接割り当てることはできません。テーブルアクセスを制御するには、データセットレベル以上のレベルでアクセス制御を構成します。

個々のデータセットへのアクセス権を付与するのではなく、事前定義された Cloud IAM の役割を割り当てることにより、プロジェクトレベル以上のレベルで権限を付与できます。

カスタムの役割を作成することもできます。カスタムの役割を作成する場合、付与する権限は、ユーザー、グループ、サービスアカウントにどのテーブルオペレーションを許可するかによって異なります。

役割と権限の詳細については、以下をご覧ください。

取り込み時間パーティション分割テーブルの使用

取り込み時間パーティション分割テーブルに関する情報の取得

テーブルに関する情報は、次の方法で入手できます。

Cloud Console または従来の BigQuery ウェブ UI を使用する
bq show CLI コマンドを使用する
tables.get API メソッドを呼び出す
クライアントライブラリを使用する

必要な権限

テーブルに関する情報を取得するには、少なくとも bigquery.tables.get 権限が付与されている必要があります。bigquery.tables.get 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner アクセス権がユーザーに付与されます。bigquery.dataOwner アクセス権により、データセットのテーブルに関する情報の取得が許可されます。

BigQuery での Cloud IAM の役割と権限については、事前定義された役割と権限をご覧ください。

取り込み時間パーティション分割テーブルの情報の取得

取り込み時間パーティション分割テーブルに関する情報を表示するには次の手順に従います。

Console

Cloud Console で BigQuery ウェブ UI を開きます。
Cloud Console に移動
ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。これにより、データセットに含まれているテーブルとビューが表示されます。
テーブル名をクリックします。
[詳細] をクリックします。このタブには、テーブルの説明と表の情報が表示されます。
[スキーマ] タブをクリックすると、テーブルのスキーマ定義が表示されます。_PARTITIONTIME という追加された疑似列に、テーブルに読み込まれたデータの日付別のタイムスタンプが格納されています。

従来の UI

ナビゲーションペインで、データセットの左側にある下矢印アイコンをクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。
テーブル名をクリックします。
[Details] をクリックします。[Table Details] ページに、テーブルの説明とテーブル情報が表示されます。
[Schema] タブをクリックすると、テーブルのスキーマ定義が表示されます。_PARTITIONTIME という追加された疑似列に、テーブルに読み込まれたデータの日付別のタイムスタンプが格納されています。

bq

すべてのテーブル情報を表示するには、bq show コマンドを発行します。テーブルのスキーマ情報のみを表示するには、--schema フラグを使用します。--format フラグを使用して出力を制御できます。

デフォルト以外のプロジェクトにあるテーブルの情報を取得する場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

bq show --schema --format=prettyjson <var>project_id:dataset.table</var>

ここで

project_id はプロジェクト ID です。
dataset はデータセットの名前です。
table はテーブルの名前です。

例:

次のコマンドを入力して、mydataset にある mytable に関するすべての情報を表示します。mydataset はデフォルトプロジェクトにあります。

bq show --format=prettyjson mydataset.mytable

次のコマンドを入力して、mydataset にある mytable に関するすべての情報を表示します。mydataset はデフォルトプロジェクトではなく myotherproject にあります。

bq show --format=prettyjson myotherproject:mydataset.mytable

mydataset 内の mytable に関するスキーマ情報のみを表示するには、次のコマンドを入力します。mydataset はデフォルトプロジェクトではなく myotherproject にあります。

時間パーティション分割テーブルのスキーマ情報を表示する場合、_PARTITIONTIME 疑似列は表示されません。

bq show --schema --format=prettyjson myotherproject:mydataset.mytable

API

bigquery.tables.get メソッドを呼び出し、関連パラメータを指定します。

データセット内の取り込み時間パーティション分割テーブルの一覧表示

データセット内のテーブルを一覧表示するには、Cloud Console、従来の BigQuery ウェブ UI、または bq ls CLI コマンドを使用するか、あるいは tables.list API メソッドを呼び出します。

必要な権限

データセットに含まれるテーブルを一覧表示するには、少なくとも bigquery.tables.list 権限が付与されている必要があります。bigquery.tables.list 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.user
bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin

BigQuery での IAM の役割と権限については、事前定義された役割と権限をご覧ください。

パーティション分割テーブルの一覧表示

データセット内のテーブル（パーティション分割テーブルを含む）を一覧表示するには、次の手順に従います。

Console

Cloud Console で BigQuery ウェブ UI を開きます。
Cloud Console に移動
ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットをクリックします。
リストをスクロールして、データセット内のテーブルを表示します。テーブル、パーティション分割テーブル、モデル、ビューは、別々のアイコンで区別できます。

従来の UI

ウェブ UI のナビゲーションペインで、データセットの左側にある下矢印アイコンをクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。
リストをスクロールして、データセット内のテーブルを表示します。テーブルとビューはアイコンで区別できます。

bq

bq ls コマンドを発行します。--format フラグを使用して出力を制御できます。デフォルトプロジェクト以外のプロジェクトにあるテーブルを一覧表示する場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

bq ls --format=pretty project_id:dataset

ここで

project_id はプロジェクト ID です。
dataset はデータセットの名前です。

このコマンドを実行すると、Type フィールドに TABLE または VIEW が表示されます。取り込み時間パーティション分割テーブルの場合は、Time Partitioning フィールドに DAY とパーティションの有効期限（指定されている場合）がミリ秒単位で表示されます。

例:

+-------------------------+-------+----------------------+--------------------------------+
|         tableId         | Type  |        Labels        | Time Partitioning              |
+-------------------------+-------+----------------------+--------------------------------+
| mytable                 | TABLE | department:shipping  |  DAY (expirationMs: 259200000) |
| myview                  | VIEW  |                      |                                |
+-------------------------+-------+----------------------+--------------------------------+

例:

次のコマンドを入力すると、デフォルトプロジェクトの mydataset データセット内のテーブルが一覧表示されます。

bq ls --format=pretty mydataset

次のコマンドを入力すると、myotherproject にある mydataset データセット内のテーブルが一覧表示されます。

bq ls --format=pretty myotherproject:mydataset

API

API を使用してテーブルを一覧表示するには、tables.list メソッドを呼び出します。

取り込み時間パーティション分割テーブル内のパーティションの一覧表示

_PARTITIONTIME 疑似列（標準 SQL の場合）または __PARTITIONS_SUMMARY__ メタテーブル（レガシー SQL の場合）をクエリすることによって、取り込み時間パーティション分割テーブル内のパーティションを一覧表示できます。

このクエリは、Cloud Console、従来の BigQuery ウェブ UI で、bq query コマンドを使用するか、jobs.insert メソッドを呼び出して query ジョブを構成して実行します。

必要な権限

__PARTITIONS_SUMMARY__ メタテーブルまたは _PARTITIONTIME 疑似列を使用するクエリジョブを実行するには、bigquery.jobs.create 権限が付与されている必要があります。bigquery.jobs.create 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

bigquery.tables.getData 権限も必要です。bigquery.tables.getData 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
bigquery.dataViewer

BigQuery での Cloud IAM の役割と権限については、事前定義された役割と権限をご覧ください。

取り込み時間パーティション分割テーブル内のパーティションの一覧表示

標準 SQL（推奨）またはレガシー SQL を使用して、取り込み時間パーティション分割テーブル内のパーティションを一覧表示できます。パーティションを一覧表示するには、次の操作を行います。

標準 SQL:

Console

Cloud Console で BigQuery ウェブ UI を開きます。
BigQuery ウェブ UI に移動
[クエリを新規作成] ボタンをクリックします。
[クエリエディタ] ボックスに次のテキストを入力して、_PARTITIONTIME 疑似列をクエリします。
```
SELECT
  _PARTITIONTIME as pt
FROM
  `dataset.table`
GROUP BY 1
```
ここで
- dataset は、テーブルが含まれているデータセットです。
- table はテーブルの名前です。
（省略可）[その他] をクリックして [クエリの設定] を選択します。
[実行] をクリックします。

従来の UI

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

BigQuery ウェブ UI に移動
[Compose query] ボタンをクリックします。
[New Query] ボックスに次のテキストを入力して、テーブルの _PARTITIONTIME 疑似列をクエリします。
```
#standardSQL
SELECT
  _PARTITIONTIME as pt
FROM
  `dataset.table`
GROUP BY 1
```
ここで
- dataset は、テーブルが含まれているデータセットです。
- table はテーブルの名前です。
[Show Options] をクリックします。
（省略可）[Processing Location] で [Unspecified] をクリックし、データのロケーションを選択します。
[RUN QUERY] をクリックします。

bq

bq query コマンドを使用して次のクエリを入力します。

bq --location=location query --use_legacy_sql=false '
SELECT
  _PARTITIONTIME as pt
FROM
  `dataset.table`
GROUP BY 1'

ここで

location はロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
dataset は、テーブルが含まれているデータセットです。
table はテーブルの名前です。

API

jobs.insert メソッドを呼び出し、テーブルの _PARTITIONTIME 擬似列をクエリする query ジョブを構成します。

ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。

レガシー SQL:

Console

Cloud Console で BigQuery ウェブ UI を開きます。
BigQuery ウェブ UI に移動
[クエリを新規作成] ボタンをクリックします。
[クエリエディタ] ボックスに次のテキストを入力して、__PARTITIONS_SUMMARY__ メタテーブルをクエリします。
```
#legacySQL
SELECT
  partition_id
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]
```
ここで
- dataset は、テーブルが含まれているデータセットです。
- table はテーブルの名前です。
[展開] をクリックして、[クエリの設定] を選択します。
[処理を行うロケーション] で [自動選択] をクリックし、データのロケーションを選択します。データが US または EU マルチリージョンロケーションに存在する場合、処理を行うロケーションを自動選択のままにしておくことができます。データが US または EU に存在する場合は、処理を行うロケーションが自動的に検出されます。
[実行] をクリックします。

従来の UI

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

BigQuery ウェブ UI に移動
[Compose query] ボタンをクリックします。
[New Query] ボックスに次のテキストを入力し、テーブルの __PARTITIONS_SUMMARY__ メタテーブルをクエリします。
```
#legacySQL
SELECT
   partition_id
 FROM
   [dataset.table$__PARTITIONS_SUMMARY__]
```
ここで
- dataset は、テーブルが含まれているデータセットです。
- table はテーブルの名前です。
[Show Options] をクリックします。
（省略可）[Processing Location] で [Unspecified] をクリックし、データのロケーションを選択します。
[RUN QUERY] をクリックします。

bq

bq query コマンドを使用して次のクエリを入力します。

bq --location=location query --use_legacy_sql=true '
SELECT
   partition_id
 FROM
   [dataset.table$__PARTITIONS_SUMMARY__]'

ここで

location はロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
dataset は、テーブルが含まれているデータセットです。
table はテーブルの名前です。

API

jobs.insert メソッドを呼び出し、テーブルの __PARTITIONS_SUMMARY__ メタテーブルをクエリする query ジョブを構成します。

ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。

メタテーブルを使用してテーブルメタデータを取得する

メタテーブルと呼ばれる特殊なテーブルを使用して、パーティション分割テーブルに関する情報を取得できます。メタテーブルには、データセット内のテーブルとビューのリストなどのメタデータが格納されます。メタテーブルは読み取り専用です。

メタテーブルを使用したパーティションメタデータの取得

__PARTITIONS_SUMMARY__ メタテーブルは、その内容が時間パーティション分割テーブル内のパーティションに関するメタデータを表す特殊なテーブルです。__PARTITIONS_SUMMARY__ メタテーブルは読み取り専用です。

時間パーティション分割テーブル内のパーティションに関するメタデータにアクセスするには、クエリの SELECT ステートメントで __PARTITIONS_SUMMARY__ メタテーブルを使用します。次の方法でクエリを実行できます。

Cloud Console または従来の BigQuery ウェブ UI を使用する
コマンドラインツールの bq query コマンドを使用する
jobs.insert API メソッドを呼び出して query ジョブを構成する
クライアントライブラリを使用する

現時点では、標準 SQL ではパーティションデコレータセパレータ（$）がサポートされていないため、標準 SQL では __PARTITIONS_SUMMARY__ をクエリできません。__PARTITIONS_SUMMARY__ メタテーブルを使用するレガシー SQL クエリは、次のようになります。

SELECT
  column
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]

ここで

dataset は、データセットの名前です。
table は時間パーティション分割テーブルの名前です。
column は次のいずれかです。

値	説明
`project_id`	プロジェクトの名前。
`dataset_id`	データセットの名前。
`table_id`	時間パーティション分割テーブルの名前。
`partition_id`	パーティションの名前（日付）。
`creation_time`	パーティションが作成された日時（UTC 1970 年 1 月 1 日からのミリ秒数）。
`last_modified_time`	パーティションが最後に変更された日時（UTC 1970 年 1 月 1 日からのミリ秒数）。

パーティションメタテーブルの権限

__PARTITIONS_SUMMARY__ メタテーブルを使用するクエリジョブを実行するには、少なくとも bigquery.jobs.create 権限が付与されている必要があります。bigquery.jobs.create 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

bigquery.tables.getData 権限も必要です。bigquery.tables.getData 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.dataViewer
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

BigQuery での Cloud IAM の役割については、アクセス制御をご覧ください。

パーティションメタテーブルの例

次のクエリは、mydataset.mytable という名前の時間パーティション分割テーブルのすべてのパーティションメタデータを取得します。

Console

#legacySQL
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

従来の UI

#legacySQL
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

CLI

bq query --use_legacy_sql=true '
SELECT
  *
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

出力は次のようになります。

+----------------+------------+----------------+--------------+---------------+--------------------+
|   project_id   | dataset_id |    table_id    | partition_id | creation_time | last_modified_time |
+----------------+------------+----------------+--------------+---------------+--------------------+
| myproject      | mydataset  | mytable        | 20160314     | 1517190224120 | 1517190224997      |
| myproject      | mydataset  | mytable        | 20160315     | 1517190224120 | 1517190224997      |
+----------------+------------+----------------+--------------+---------------+--------------------+

次のクエリは、mydataset.mytable のパーティションが最後に変更された時間を一覧表示します。

Console

#legacySQL
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

従来の UI

#legacySQL
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]

CLI

bq query --use_legacy_sql=true '
SELECT
  partition_id,
  last_modified_time
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

出力は次のようになります。

+--------------+--------------------+
| partition_id | last_modified_time |
+--------------+--------------------+
| 20160102     |      1471632556179 |
| 20160101     |      1471632538142 |
| 20160103     |      1471632570463 |
+--------------+--------------------+

人が読める形式で last_modified_time フィールドを表示するには、FORMAT_UTC_USEC 関数を使用します。例:

Console

#legacySQL
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.table1$__PARTITIONS_SUMMARY__]

従来の UI

#legacySQL
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.table1$__PARTITIONS_SUMMARY__]

CLI

bq query --use_legacy_sql=true '
SELECT
  partition_id,
  FORMAT_UTC_USEC(last_modified_time*1000) AS last_modified
FROM
  [mydataset.mytable$__PARTITIONS_SUMMARY__]'

出力は次のようになります。

+--------------+----------------------------+
| partition_id |       last_modified        |
+--------------+----------------------------+
| 20160103     | 2016-08-19 18:49:30.463000 |
| 20160102     | 2016-08-19 18:49:16.179000 |
| 20160101     | 2016-08-19 18:48:58.142000 |
+--------------+----------------------------+

例: クエリ結果を使用した取り込み時間パーティション分割テーブルの作成

この例では、コマンドラインツールを使用して取り込み時間パーティション分割テーブルを作成し、クエリ結果を使用して 3 つのパーティションにデータを追加します。テーブルには、2016 年の最初の 3 日間の気象データが、日付別に分割されて含まれます。

この例では、2016 年の最初の 3 日間の気温について NOAA GSOD 気象データセットをクエリし、その結果をパーティション分割テーブルに書き込みます。

ステップ 1. mydataset というデータセット内に temps という名前で、日付でパーティション分割した空の取り込み時間テーブルを作成します。このテーブルのスキーマを指定する必要はありません。クエリ結果からのスキーマが、テーブルのスキーマ定義として使用されます。

bq mk --time_partitioning_type=DAY mydataset.temps

構成の設定を表示するには、bq show コマンドを使用します。

bq show --format=prettyjson mydataset.temps

bq show コマンド出力の timePartitioning エントリを特定します。

{
  ...
  "timePartitioning": {
    "type": "DAY"
  },
  "type": "TABLE"
}

ステップ 2. NOAA GSOD 気象データセットに対して 2016 年の最初の 3 日間の気温を照会するクエリを実行し、その結果を temps テーブル内の対応するパーティションに書き込みます。次のクエリでは、--destination_table オプションと標準 SQL 構文を使用して、パーティションごとにクエリ結果の 100 行を書き込みます。

次のクエリを実行して、2016 年 1 月 1 日の気温をパーティション mydataset.temps$20160101 に書き込みます。

bq query --use_legacy_sql=false \
--destination_table 'mydataset.temps$20160101' \
'SELECT
   stn,
   temp
 FROM
   `bigquery-public-data`.noaa_gsod.gsod2016
 WHERE
   mo="01"
   AND da="01"
 LIMIT
   100'

次のクエリを実行して、2016 年 1 月 2 日の気温をパーティション mydataset.temps$20160102 に書き込みます。

bq --location=US query --use_legacy_sql=false \
--destination_table 'mydataset.temps$20160102' \
'SELECT
   stn,
   temp
 FROM
   `bigquery-public-data`.noaa_gsod.gsod2016
 WHERE
   mo="01"
   AND da="02"
 LIMIT
   100'

次のクエリを実行して、2016 年 1 月 3 日の気温をパーティション mydataset.temps$20160103 に書き込みます。

bq --location=US query --use_legacy_sql=false \
--destination_table 'mydataset.temps$20160103' \
'SELECT
   stn,
   temp
 FROM
   `bigquery-public-data`.noaa_gsod.gsod2016
 WHERE
   mo="01"
   AND da="03"
 LIMIT
   100'

ステップ 3bq show コマンドを実行して、テーブルの行数が 300 行であることを確認します。

bq show mydataset.temps

コマンドの出力に、スキーマと総行数が表示されます。

  Last modified        Schema       Total Rows   Total Bytes     Expiration      Time Partitioning   Labels   kmsKeyName
 ----------------- ---------------- ------------ ------------- ----------------- ------------------- -------- ------------
  28 Jan 15:03:45   |- stn: string   300          4800          29 Jan 15:00:32   DAY
                    |- temp: float

次のステップ

BigQuery でのパーティション分割テーブルのサポートの概要については、パーティション分割テーブルの概要をご覧ください。
パーティション分割テーブルの管理方法と更新方法については、パーティション分割テーブルの管理をご覧ください。
パーティション分割テーブルをクエリする方法については、パーティション分割テーブルのクエリをご覧ください。
日付 / タイムスタンプパーティション分割テーブルについては、日付 / タイムスタンプパーティション分割テーブルの作成と使用をご覧ください。
整数範囲のパーティション分割テーブルについては、パーティション分割テーブルの作成と使用をご覧ください。

取り込み時間パーティション分割テーブルの作成と使用

取り込み時間パーティション分割テーブルの作成

テーブルの命名

必要な権限

スキーマ定義を持つ空の取り込み時間パーティション分割テーブルの作成

Console

従来の UI

bq

API

クエリ結果から取り込み時間パーティション分割テーブルを作成する

Console

従来の UI

bq

API

データを読み込むときの取り込み時間パーティション分割テーブルの作成

日付別テーブルの取り込み時間パーティション分割テーブルへの変換

時間パーティション分割テーブルへのアクセスの制御

取り込み時間パーティション分割テーブルの使用

取り込み時間パーティション分割テーブルに関する情報の取得

必要な権限

取り込み時間パーティション分割テーブルの情報の取得

Console

従来の UI

bq

API

データセット内の取り込み時間パーティション分割テーブルの一覧表示

必要な権限

パーティション分割テーブルの一覧表示

Console

従来の UI

bq

API

取り込み時間パーティション分割テーブル内のパーティションの一覧表示

必要な権限

取り込み時間パーティション分割テーブル内のパーティションの一覧表示

Console

従来の UI

bq

API

Console

従来の UI

bq

API

メタテーブルを使用してテーブル メタデータを取得する

メタテーブルを使用したパーティション メタデータの取得

パーティション メタテーブルの権限

パーティション メタテーブルの例

Console

従来の UI

CLI

Console

従来の UI

CLI

Console

従来の UI

CLI

例: クエリ結果を使用した取り込み時間パーティション分割テーブルの作成

次のステップ

メタテーブルを使用してテーブルメタデータを取得する

メタテーブルを使用したパーティションメタデータの取得

パーティションメタテーブルの権限

パーティションメタテーブルの例