取り込み時間分割テーブルの作成と使用

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

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

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

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

取り込み時間分割テーブルの作成

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

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

BigQuery で取り込み時間分割テーブルを作成する場合、テーブル名はデータセット内で一意である必要があります。テーブル名の要件は次のとおりです。

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

必要な権限

取り込み時間分割テーブルを作成するには、データセット レベルで WRITER アクセス権が付与されているか、bigquery.tables.create 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。次の事前定義されたプロジェクト レベルの IAM 役割には、bigquery.tables.create 権限が含まれています。

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

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

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

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

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

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

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

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

スキーマ定義が存在する空の時間分割テーブルを作成するには:

従来の UI

  1. ナビゲーション内のデータセット名の横にある下矢印アイコン 下矢印アイコン をクリックし、[Create new table] をクリックします。

  2. [Create Table] ページの [Source Data] セクションで、[Create empty table] をクリックします。

  3. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。

    • [Table name] で適切なデータセットを選択し、作成するテーブルの名前をテーブル名のフィールドに入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  4. [Schema] セクションに、スキーマ定義を手動で入力します。

    • スキーマ情報を手動で入力するには、以下のようにします。

      • [Edit as text] をクリックし、テーブル スキーマを JSON 配列として入力します。

        スキーマを JSON 配列として追加する

      • [Add Field] を使用してスキーマを入力します。

        [Add Field] を使用してスキーマを追加する

  5. [Options] セクションで:

  6. [Create Table] をクリックします。

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

コマンドライン

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 はここでは説明しません。このフラグの使用方法の詳細については、顧客管理の暗号鍵をご覧ください。

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

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

コマンドラインでスキーマを指定する場合、RECORDSTRUCT)型と列の説明を含めることはできません。また、列のモードの指定もできません。モードはすべてデフォルトで 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 メソッドを呼び出します。

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

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

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

従来の 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 --location=US 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 --location=US 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 ジョブを構成して configuration.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--time_partitioning_type があります。現時点でサポートされている値は --time_partitioning_type=DAY のみであるため、このパラメータは省略できます。ソーステーブルまたは宛先テーブルがデフォルト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセット名に追加します。

--location フラグを指定して、その値を該当するロケーションに設定します。

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

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] は、テーブルのパーティションのデフォルトの存続期間(秒)です。最小値はありません。パーティションの日付にこの整数値を足した値が有効期限になります。パーティションの有効期限はテーブルの有効期限とは無関係であり、それをオーバーライドしません。テーブルの有効期限より長いパーティション有効期限を設定すると、テーブルの有効期限が優先されます。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] は、プロジェクトのデータセットです。
  • [SOURCE_TABLE]_ は、日付別テーブルの接頭辞です。
  • [DESTINATION_TABLE] は、作成する分割テーブルの名前です。

例:

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

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

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

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

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

次のコマンドを入力すると、デフォルト プロジェクトの mydataset 内に mytable_partitioned という名前の取り込み時間分割テーブルが作成されます。mydatasetasia-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 コマンドを使用するか、tables.get API メソッドを呼び出します。

必要な権限

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

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

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

取り込み時間分割テーブルの情報の取得

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

従来の UI

  1. ナビゲーション パネルで、データセットの左側にある下矢印アイコン 下矢印アイコン をクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。

  2. テーブル名をクリックします。

  3. [Details] をクリックします。[Table Details] ページに、テーブルの説明とテーブル情報が表示されます。

    分割テーブルの詳細

  4. [Schema] タブをクリックすると、テーブルのスキーマ定義が表示されます。分割テーブルには _PARTITIONTIME という疑似列があり、この列に、テーブルに読み込まれたデータの日付別のタイムスタンプが格納されていることがわかります。

    分割テーブルのスキーマ

コマンドライン

すべてのテーブル情報を表示するには、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 メソッドを呼び出します。

必要な権限

データセット内のテーブルを一覧表示するユーザーには、データセットに対する READER の役割が割り当てられているか、bigquery.tables.list 権限を含むプロジェクト レベルの IAM 役割が割り当てられている必要があります。プロジェクト レベルで bigquery.tables.list 権限が付与されているユーザーは、そのプロジェクトの任意のデータセット内のテーブルを一覧表示できます。事前定義されているプロジェクト レベルの IAM 役割のうち、bigquery.jobUser を除く役割のすべてに bigquery.tables.list 権限が含まれています。

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

分割テーブルの一覧表示

データセット内のテーブル(分割テーブルを含む)を一覧表示するには:

従来の UI

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

  2. リストをスクロールして、データセット内のテーブルを表示します。テーブルとビューは別々のアイコンで識別されます。

    テーブルの表示

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 権限を含むものは以下のとおりです。

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

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

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

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

標準 SQL:

従来の UI

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

    BigQuery ウェブ UI に移動

  2. [COMPOSE QUERY] ボタンをクリックします。

  3. [New Query] ボックスに次のテキストを入力して、テーブルの _PARTITIONTIME 疑似列をクエリします。

    #standardSQL
    SELECT
      _PARTITIONTIME as pt
    FROM
      `[DATASET].[TABLE]`
    GROUP BY 1
    

    ここで:

    • [DATASET] は、テーブルが含まれているデータセットです。
    • [TABLE] はテーブルの名前です。
  4. [Show Options] をクリックします。

  5. (省略可)[Processing Location] で [Unspecified] をクリックし、データのロケーションを選択します。

  6. [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:

従来の UI

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

    BigQuery ウェブ UI に移動

  2. [COMPOSE QUERY] ボタンをクリックします。

  3. [New Query] ボックスに次のテキストを入力し、テーブルの __PARTITIONS_SUMMARY__ メタテーブルをクエリします。

    #legacySQL
    SELECT
       partition_id
     FROM
       [[DATASET].[TABLE]$__PARTITIONS_SUMMARY__]
    

    ここで:

    • [DATASET] は、テーブルが含まれているデータセットです。
    • [TABLE] はテーブルの名前です。
  4. [Show Options] をクリックします。

  5. (省略可)[Processing Location] で [Unspecified] をクリックし、データのロケーションを選択します。

  6. [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__ メタテーブルを使用します。このクエリは、Console、従来の BigQuery ウェブ UI、コマンドライン ツールの bq query コマンドを使用するか、jobs.insert API メソッドを呼び出してクエリジョブを構成して実行します。

現時点では、標準 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 権限を含むものは以下のとおりです。

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

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

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

従来の UI

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

コマンドライン

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 のパーティションが最後に変更された時間を一覧表示します。

従来の UI

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

コマンドライン

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 関数を使用します。次に例を示します。

従来の UI

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

コマンドライン

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 気象データセットをクエリし、その結果を分割テーブルに書き込みます。この例では、一般公開データセットをクエリするため、--location=US フラグを使用しています。BigQuery の一般公開データセットは、US マルチリージョンに保存されています。一般公開データセットは米国内に格納されているため、一般公開データのクエリ結果を別のリージョンにあるテーブルに書き込むことも、一般公開データセット内のテーブルを別のリージョンのテーブルと結合することもできません。

ステップ 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 行を書き込みます。

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

    bq --location=US 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'
    
  2. 次のクエリを実行して、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'
    
  3. 次のクエリを実行して、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

次のステップ

このページは役立ちましたか?評価をお願いいたします。

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

ご不明な点がありましたら、Google のサポートページをご覧ください。