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

このドキュメントでは、BigQuery で取り込み時間パーティション分割テーブルを作成および使用する方法について説明します。パーティション分割テーブルの詳細については、パーティション分割テーブルの作成と使用をご覧ください。

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

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

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

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

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

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

テーブルの命名

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 役割と権限については、アクセス制御をご覧ください。

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

スキーマ定義が存在する空の取り込み時間パーティション分割テーブルを作成するときは、次の方法を使用できます。

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

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

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

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

スキーマ定義を持つ空の時間パーティション分割テーブルを作成するには:

Console

ナビゲーションパネルの [リソース] セクションで、データセットを選択します。ウィンドウの右側にある [テーブルを作成] をクリックします。
[テーブルを作成] ページの [ソース] セクションで、[空のテーブル] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] フィールドに、BigQuery で作成するテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。
- スキーマ情報を手動で入力します。
  - [テキストとして編集] を有効にし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --format=prettyjson [DATASET].[TABLE] を入力します。
  - [フィールドを追加] を使用して、スキーマを手動で入力します。
[パーティションとクラスタの設定] セクションで、次の操作を行います。
- [パーティショニング] で [パーティショニングなし] をクリックし、[取り込み時間により分割] を選択します。
（省略可）[詳細オプション] をクリックします。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] をクリックします。

CLI

mk コマンドを使用し、--table フラグ（または -t ショートカット）および --time_partitioning_type=DAY フラグを指定します。現時点では、--time_partitioning_type でサポートされている値は DAY のみです。テーブルのスキーマ定義をインラインで、または 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=DAY \
--time_partitioning_expiration [INTEGER2] \
--description "[DESCRIPTION]" \
-label [KEY:VALUE, KEY:VALUE] \
[PROJECT_ID]:[DATASET].[TABLE] \
[SCHEMA]

ここで:

[INTEGER1] はテーブルのデフォルトの存続期間（秒）です。最小値は 3,600 秒（1 時間）です。現在の UTC 時間にこの整数値を足した値が、有効期限になります。パーティション分割テーブルの作成時に有効期限を設定した場合、データセットのデフォルトのテーブル有効期限設定は無視されます。この値を設定すると、指定した時間が経過したときにテーブルとすべてのパーティションは削除されます。
[INTEGER2] は、テーブルのパーティションのデフォルトの存続期間（秒）です。最小値はありません。パーティションの日付にこの整数値を足した値が有効期限になります。パーティションの有効期限はテーブルの有効期限とは無関係であり、それをオーバーライドしません。テーブルの有効期限より長いパーティション有効期限を設定すると、テーブルの有効期限が優先されます。
[DESCRIPTION] はテーブルの説明です。引用符で囲みます。
[KEY:VALUE] は、ラベルを表す Key-Value ペアです。カンマ区切りリストを使用して複数のラベルを入力できます。
[PROJECT_ID] はプロジェクト ID です。
[DATASET] は、プロジェクトのデータセットです。
[TABLE] は、作成する時間パーティション分割テーブルの名前です。
[SCHEMA] は、[FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] の形式のインラインスキーマ定義か、ローカルマシン上の JSON スキーマファイルのパスです。

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

例:

デフォルトプロジェクトにある mydataset 内に mytable という名前の取り込み時間パーティション分割テーブルを作成するには、次のコマンドを入力します。パーティショニングの有効期限は 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 という名前の時間パーティション分割テーブルを作成するには、次のコマンドを入力します。パーティショニングの有効期限は 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 を使用してデータのクエリを実行する場合、宛先テーブルのパーティショニングオプションを指定できません。

CLI

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

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

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

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

    bq --location=[LOCATION] query \
    --destination_table [PROJECT_ID]:[DATASET].[TABLE] \
    --time_partitioning_type=DAY \
    --use_legacy_sql=false \
    '[QUERY]'

ここで:

[LOCATION] は、該当するロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
[PROJECT_ID] はプロジェクト ID です。
[DATASET] は、新しい時間パーティション分割テーブルが組み込まれるデータセットの名前です。
[TABLE] は、クエリ結果を使用して作成する時間パーティション分割テーブルの名前です。
[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 データの一般公開データセット）からデータを取得します。

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 プロパティの値を含めます。

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

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

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

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

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

[TABLE_NAME]$20160501

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

日付別テーブルを取り込み時間パーティション分割テーブルに変換する

以前に日付別テーブルを作成している場合は、bq コマンドラインツールの partition コマンドを使用して、関連する一連のテーブル全体を単一の取り込み時間パーティション分割テーブルに変換できます。日付別テーブルでは、[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] は、プロジェクトのデータセットです。
[SOURCE_TABLE]_ は、日付別テーブルの接頭辞です。
[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

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

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

データセットレベルのアクセス制御では、特定のデータセット内のテーブルに対してユーザー、グループ、サービスアカウントが実行できるオペレーションを指定します。データセットレベルの権限のみを割り当てる場合は、プロジェクトへのアクセス権を付与する基本の役割または事前定義されたプロジェクトレベルの役割（例: bigquery.user）も割り当てる必要があります。

個々のデータセットへのアクセス権を付与する代わりに、事前定義されたプロジェクトレベルの IAM 役割を割り当てることにより、プロジェクトに含まれるすべてのデータセットのすべてのテーブルデータに対する権限を付与できます。

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

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

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

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

テーブルに関する情報を取得するには、GCP Console、従来の BigQuery ウェブ UI、CLI の bq show コマンドを使用するか、API の tables.get メソッドを呼び出します。

必要な権限

テーブルに関する情報を取得するユーザーには、データセットに対する READER 役割が割り当てられているか、bigquery.tables.get 権限を含むプロジェクトレベルの IAM 役割が割り当てられている必要があります。プロジェクトレベルで bigquery.tables.get 権限が付与されているユーザーは、そのプロジェクト内のすべてのテーブルに関する情報を取得できます。bigquery.tables.get は、次の定義済みの Cloud IAM 役割に含まれます。

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

また、bigquery.user 役割が割り当てられているユーザーには bigquery.datasets.create 権限もあります。そのため、bigquery.user 役割が割り当てられているユーザーは、自分が作成した任意のデータセット内のテーブルに関する情報を取得できます。bigquery.user 役割に割り当てられているユーザーがデータセットを作成すると、そのユーザーにはそのデータセットへの OWNER アクセス権が付与されます。データセットへの OWNER アクセス権を付与されたユーザーは、そのデータセットとその中のすべてのテーブルを完全に制御できます。

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

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

取り込み時間パーティション分割テーブルに関する情報を表示するには:

Console

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

従来の UI

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

CLI

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

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

bq show --schema --format=prettyjson [PROJECT_ID]:[DATASET].[TABLE]

ここで

[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 メソッドを呼び出し、関連パラメータを指定します。

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

データセット内のテーブル（パーティション分割テーブルを含む）を一覧表示するには、GCP Console、従来の BigQuery ウェブ UI、CLI の bq ls コマンドを使用するか、API の tables.list メソッドを呼び出します。

必要な権限

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

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

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

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

データセット内のテーブル（パーティション分割テーブルを含む）を一覧表示するには:

Console

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

従来の UI

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

CLI

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 の場合）をクエリすることによって、取り込み時間パーティション分割テーブル内のパーティションを一覧表示できます。

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

必要な権限

__PARTITIONS_SUMMARY__ メタテーブルまたは _PARTITIONTIME 疑似列を使用するクエリジョブを実行するには、bigquery.jobs.create 権限が必要です。次の事前定義されたプロジェクトレベルの IAM 役割には、bigquery.jobs.create 権限が含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

また、ユーザーには、データセットレベルで READER 役割が付与されているか、bigquery.tables.getData 権限を含むプロジェクトレベルの IAM 役割が割り当てられている必要があります。事前定義されているプロジェクトレベルの IAM 役割のうち、bigquery.user、bigquery.jobUser、bigquery.metadataViewer 以外の役割にはすべて bigquery.tables.getData 権限が含まれています。

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

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

標準 SQL:

Console

GCP 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] をクリックします。

CLI

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

bq --location=[LOCATION] query --use_legacy_sql=false '
SELECT
  _PARTITIONTIME as pt
FROM
  `[DATASET].[TABLE]`
GROUP BY 1'

Where:

  + `[LOCATION]` is the name of your location. The `--location` flag is
    optional. For example, if you are using BigQuery in
    the Tokyo region, you can set the flag's value to `asia-northeast1`.
    You can set a default value for the location using the
    [.bigqueryrc file](/bigquery/docs/bq-command-line-tool#setting_default_values_for_command-line_flags).
  + `[DATASET]` is the dataset that contains the table.
  + `[TABLE]` is the name of the table.

API

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

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

レガシー SQL:

Console

GCP 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] をクリックします。

CLI

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

bq --location=[LOCATION] query --use_legacy_sql=true '
SELECT
   partition_id
 FROM
   [[DATASET].[TABLE]$__PARTITIONS_SUMMARY__]'

Where:

  + `[LOCATION]` is the name of your location. The `--location` flag is
    optional. For example, if you are using BigQuery in
    the Tokyo region, you can set the flag's value to `asia-northeast1`.
    You can set a default value for the location using the
    [.bigqueryrc file](/bigquery/docs/bq-command-line-tool#setting_default_values_for_command-line_flags).
  + `[DATASET]` is the dataset that contains the table.
  + `[TABLE]` is the name of the table.

API

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

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

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

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

メタテーブルを使用してパーティションメタデータを取得する

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

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

GCP Console または従来の BigQuery ウェブ UI を使用する
コマンドラインツールの bq query コマンドを使用する
API の jobs.insert メソッドを呼び出して 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'

ステップ 3. bq show コマンドを使用して、テーブルに 300 行書き込まれていることを確認します。

bq show mydataset.temps

コマンドの出力に、Schema と Total Rows が表示されます。

  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

CLI

API

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

Console

従来の UI

CLI

API

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

日付別テーブルを取り込み時間パーティション分割テーブルに変換する

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

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

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

必要な権限

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

Console

従来の UI

CLI

API

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

必要な権限

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

Console

従来の UI

CLI

API

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

必要な権限

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

Console

従来の UI

CLI

API

Console

従来の UI

CLI

API

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

メタテーブルを使用してパーティション メタデータを取得する

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

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

Console

従来の UI

CLI

Console

従来の UI

CLI

Console

従来の UI

CLI

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

次のステップ

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

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

メタテーブルを使用してパーティションメタデータを取得する

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

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