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

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

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

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

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

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

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

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

テーブルの命名

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

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

必要な権限

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

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

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

次の事前定義済みの IAM ロールには bigquery.tables.create 権限と bigquery.tables.updateData 権限の両方が含まれています。

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

次の事前定義済みの IAM ロールには bigquery.jobs.create 権限が含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

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

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

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

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

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

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

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

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

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

Console

ナビゲーションパネルの [リソース] セクションで、データセットを選択します。ウィンドウの右側にある [テーブルを作成] をクリックします。
[テーブルの作成] ページの [ソース] セクションで、[Create empty table] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。
- スキーマ情報を手動で入力します。
  - [テキストとして編集] を有効にし、テーブルスキーマを JSON 配列として入力します。
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、bq コマンドラインツールに 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 形式で表示するには、bq コマンドラインツールに 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

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

テーブルとビューへのアクセスを構成するには、エンティティに次のレベルで IAM ロールを付与します。以下に、それぞれのレベルを許可されるリソースの範囲が大きい順にリストします。

Google Cloud リソース階層の上位レベル（プロジェクト、フォルダ、組織レベルなど）
データセットレベル
テーブル / ビューレベル

IAM で保護されているリソースを使用したアクセスは追加型です。たとえば、エンティティにプロジェクトなどの上位レベルのアクセス権がない場合は、データセットレベルでアクセス権を付与すると、データセット内のテーブルとビューにアクセスできます。同様に、エンティティに高レベルまたはデータセットレベルでのアクセス権がない場合は、ビューレベルでエンティティにアクセス権を付与できます。

プロジェクト、フォルダ、組織レベルなど、Google Cloud リソース階層の上位レベルで IAM ロールを付与すると、エンティティは幅広いリソースのセットにアクセスできるようになります。たとえば、プロジェクトレベルでエンティティにロールを付与すると、そのエンティティには、プロジェクトに含まれるすべてのデータセットに適用される権限が付与されます。

データセットレベルでロールを付与すると、そのエンティティが上位レベルでアクセスできない場合でも、そのデータセットのテーブルとビューで実行できるオペレーションが指定されます。データセットレベルのアクセス制御を構成する方法については、データセットへのアクセスの制御をご覧ください。

テーブルまたはビューレベルでロールを付与すると、エンティティに上位レベルのアクセスがない場合でも、特定のテーブルやビューに対してエンティティが実行できるオペレーションが特定されます。テーブルレベルのアクセス制御の構成については、テーブルおよびビューへのアクセスの制御をご覧ください。

また、IAM カスタムロールを作成することもできます。カスタムロールを作成する場合、エンティティに実行を許可する特定のオペレーションによって、付与する権限は異なります。

IAM で保護されているリソースに「拒否」権限を設定することはできません。

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

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

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

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

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

必要な権限

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

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

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

BigQuery での 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 コマンドラインツールの bq ls コマンドを使用するか、あるいは tables.list API メソッドを呼び出します。

必要な権限

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

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 権限が付与されている必要があります。次の定義済みの IAM ロールには bigquery.jobs.create 権限が含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

bigquery.tables.getData 権限も必要です。次の定義済みの IAM ロールには bigquery.tables.getData 権限が含まれています。

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

BigQuery での 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 コマンドラインツールの 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 権限が付与されている必要があります。次の事前定義済みの IAM ロールには bigquery.jobs.create 権限が含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

bigquery.tables.getData 権限も必要です。次の事前定義済みの IAM ロールには bigquery.tables.getData 権限が含まれています。

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

BigQuery での IAM ロールの詳細については、アクセス制御をご覧ください。

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

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

Console

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

従来の UI

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

bq

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__]

bq

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__]

bq

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 |
+--------------+----------------------------+

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

この例では、bq コマンドラインツールを使用して取り込み時間パーティション分割テーブルを作成し、クエリ結果を使用して 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'

ステップ 3 bq 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

bq

Console

従来の UI

bq

Console

従来の UI

bq

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

次のステップ

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

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

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

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