パーティション分割テーブルの作成と使用

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

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

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

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

制限事項

分割テーブルには次の制限事項があります。

  • 分割する列は、スカラー DATE 列または TIMESTAMP 列のいずれかである必要があります。 列のモードは REQUIRED または NULLABLE にできますが、REPEATED(配列ベース)にすることはできません。
  • 分割する列はトップレベル フィールドである必要があります。分割する列として RECORDSTRUCT)のリーフ フィールドは使用できません。
  • レガシー SQL を使用して、パーティション分割テーブルにクエリを実行することはできません。また、クエリ結果をパーティション分割テーブルに書き込むこともできません。

パーティション分割テーブルの作成

BigQuery では、次の方法でパーティション分割テーブルを作成できます。

  • GCP Console または従来のウェブ UI を使用する
  • DDL の CREATE TABLE ステートメントを使用して、PARTITION BY 句に partition expression を指定して作成する
  • コマンドライン ツールの 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 役割と権限については、アクセス制御をご覧ください。

スキーマ定義を持つ空のパーティション分割テーブルの作成

スキーマ定義を持たない空のパーティション分割テーブルを作成することはできません。パーティションの作成に使用される列を識別するためには、スキーマが必要です。

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

  • CLI を使用してインラインでスキーマを指定する
  • CLI を使用して JSON スキーマ ファイルを指定する
  • API の tables.insert メソッドを呼び出すときに、テーブル リソースでスキーマを指定する

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

分割テーブルを作成すると、次の操作を行えるようになります。

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

スキーマ定義を持つ空の分割テーブルを作成するには:

Console

  1. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。

  2. ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。

  3. [テーブルの作成] パネルの [ソース] セクションで、次の操作を行います。

    • [テーブルの作成元] で [空のテーブル] を選択します。
  4. [送信先] で次の操作を行います。

    • [データセット名] で該当するデータセットを選択し、作成するテーブルの名前を [テーブル名] フィールドに入力します。
    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
  5. [スキーマ] セクションにスキーマ定義を入力します。

    • スキーマ情報を手動で入力します。

      • [テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。

      • [フィールドを追加] を使用して、スキーマを手動で入力します。

  6. [パーティションとクラスタの設定] で [パーティショニングなし] をクリックし、[フィールドにより分割] を選択して DATE 列または TIMESTAMP 列を選択します。スキーマに DATE 列または TIMESTAMP 列が含まれていない場合、このオプションは使用できません。

  7. (省略可)クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[パーティショニング フィルタ] で [パーティション フィルタを要求] ボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。

  8. (省略可)[詳細オプション] をクリックします。Cloud Key Management Service 鍵を使用する場合は、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。

  9. [テーブルを作成] をクリックします。

DDL

データ定義言語(DDL)ステートメントを使用すると、標準 SQL クエリ構文を使用してテーブルとビューを作成および変更できます。

データ定義言語ステートメントの使用をご覧ください。

GCP Console で、DDL ステートメントを使用してパーティション分割テーブルを作成するには:

  1. GCP Console で BigQuery ウェブ UI を開きます。
    GCP Console に移動する

  2. [クエリを新規作成] をクリックします。

  3. [クエリエディタ] テキスト領域に、CREATE TABLE DDL ステートメントを入力します。

    次のクエリでは、transaction_date DATE 列で分割されていて、パーティション有効期限が 3 日である newtable という名前のテーブルが作成されます。

     CREATE TABLE
       mydataset.newtable (transaction_id INT64,
         transaction_date DATE)
     PARTITION BY
       transaction_date
     OPTIONS
       ( partition_expiration_days=3,
         description="a table partitioned by transaction_date" )

  4. [実行] をクリックします。クエリが完了すると、テーブルが [リソース] ペインに表示されます。

従来の 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 配列として入力します。

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

  5. [Options] セクションで次の操作を行います。

    • [Partitioning Type] で、[None] をクリックして [Day] を選択します。
    • [Partitioning Field] で、TIMESTAMP または DATE を選択します。デフォルト値は _PARTITIONTIME で、取り込み時間パーティション分割テーブルを作成します。
    • (省略可)クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[Require partition filter] ボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。
    • (省略可)Cloud Key Management Service 鍵を使用してテーブルを暗号化するには、[Destination encryption] で [Customer-managed encryption] を選択します。Default 設定をそのまま使用すると、BigQuery は Google が管理する鍵を使用して保存されているデータを暗号化します。
  6. [Create Table] をクリックします。

CLI

mk コマンドを使用し、--table フラグ(または -t ショートカット)、--schema フラグ、--time_partitioning_field フラグを指定します。テーブルのスキーマ定義をインラインで、または JSON スキーマ ファイルを使用して指定できます。

オプションのパラメータには、--expiration--description--time_partitioning_expiration--destination_kms_key--require_partition_filter--label があります。現時点では、--time_partitioning_type でサポートされている値は DAY のみであるため、このフラグを指定する必要はありません。

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

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

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

bq mk --table \
--expiration integer1 \
--schema schema \
--time_partitioning_field column \
--time_partitioning_expiration integer2 \
--[no]require_partition_filter \
--description "description" \
--label key:value, key:value \
project_id:dataset.table

ここで

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

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

例:

デフォルト プロジェクトにある mydataset 内に mypartitionedtable という名前の分割テーブルを作成するには、次のコマンドを入力します。パーティションの有効期限は 86,400 秒(1 日)に設定され、テーブルの有効期限は 2,592,000 秒(1 か月、つまり 30 日)に設定され、説明は This is my partitioned table に設定され、ラベルは organization:development に設定されます。このコマンドでは --table ではなく -t ショートカットを使用しています。

クエリを実行するパーティションを指定するために WHERE 句の使用を必須にする場合は、--require_partition_filter フラグを使用します。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。

スキーマはインラインで ts:TIMESTAMP,column1:STRING,column2:INTEGER,coumn4:STRING と指定されています。指定された TIMESTAMP 型のフィールド ts を使用して、パーティションが作成されます。

bq mk -t \
--expiration 2592000 \
--schema 'ts:TIMESTAMP,column1:STRING,column2:INTEGER,coumn4:STRING' \
--time_partitioning_field ts \
--time_partitioning_expiration 86400  \
--require_partition_filter \
--description "This is my partitioned table" \
--label org:dev \
mydataset.mypartitionedtable

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

スキーマは、/tmp/myschema.json というローカル JSON ファイルで定義されています。このスキーマ定義には、パーティションの作成に使用される ts という TIMESTAMP フィールドがあります。

bq mk -t \
--expiration 2592000 \
--schema /tmp/myschema.json \
--time_partitioning_field ts \
--time_partitioning_expiration 86400  \
--description "This is my partitioned table" \
--label org:dev \
myotherproject:mydataset.mypartitionedtable

テーブルを作成した後に、CLI を使用してパーティション分割テーブルのテーブル有効期限パーティション有効期限説明ラベルを更新できます。

API

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

Go

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある Go 向けの手順に沿って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
sampleSchema := bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.IntegerFieldType},
	{Name: "date", Type: bigquery.DateFieldType},
}
metadata := &bigquery.TableMetadata{
	TimePartitioning: &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	},
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metadata); err != nil {
	return err
}

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある Python の設定手順に沿って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

table_ref = dataset_ref.table("my_partitioned_table")
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
    bigquery.SchemaField("date", "DATE"),
]
table = bigquery.Table(table_ref, schema=schema)
table.time_partitioning = bigquery.TimePartitioning(
    type_=bigquery.TimePartitioningType.DAY,
    field="date",  # name of column to use for partitioning
    expiration_ms=7776000000,
)  # 90 days

table = client.create_table(table)

print(
    "Created table {}, partitioned on column {}".format(
        table.table_id, table.time_partitioning.field
    )
)

クエリ結果からパーティション分割テーブルを作成する

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

クエリ結果から分割テーブルを作成する場合、標準 SQL を使用する必要があります。現時点では、分割テーブルをクエリする場合や、クエリ結果を分割テーブルに書き込む場合に、レガシー SQL はサポートされていません。

パーティション デコレータを使用すると、クエリ結果を特定のパーティションに書き込むことができます。たとえば、2016 年 5 月 1 日のパーティションに結果を書き込むには、次のパーティション デコレータを使用します。

table_name$20160501

パーティション デコレータを使用してクエリ結果を特定のパーティションに書き込む場合、パーティションに書き込まれるデータは、テーブルのパーティショニング スキームに準拠している必要があります。パーティションに書き込まれるすべての行は、パーティションの日付内に収まる値を持つ必要があります。

例:

次のクエリは、2018 年 2 月 1 日以降のデータを取得し、テーブル mytable$20180201 パーティションにデータを書き込みます。テーブルには、TS という名前の TIMESTAMP 列と a という名前の INT64 列の 2 つの列があります。

bq query \
--nouse_legacy_sql  \
--destination_table=mytable$20180201 \
'SELECT
   TIMESTAMP("2018-02-01") AS TS,
   2 AS a'

次のクエリは、2018 年 1 月 31 日以降のデータを取得し、mytable$20180201 パーティションにデータを書き込みます。書き込もうとしているデータ値がパーティションの日付内に収まらないため、このクエリは失敗します。

bq query \
--nouse_legacy_sql  \
--destination_table=T$20180201 \
'SELECT
   TIMESTAMP("2018-01-31") as TS,
   2 as a'

パーティション分割テーブル内のデータに対する追加または修正(置換)の詳細については、パーティション分割テーブルデータに対する追加および上書きをご覧ください。パーティション分割テーブルに対するクエリの詳細については、パーティション分割テーブルのクエリをご覧ください。

クエリ結果からのパーティション分割テーブルの作成

クエリ結果からパーティション分割テーブルを作成するには:

Console

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

従来の UI

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

CLI

bq query コマンドを入力し、クエリ結果に基づいて永続テーブルを作成するために --destination_table フラグを指定します。また、宛先のパーティション分割テーブルを作成するために --time_partitioning_field フラグを指定します。現時点では、--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_field column \
--use_legacy_sql=false \
'query'

ここで

  • location は、ロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
  • project_id はプロジェクト ID です。
  • dataset は、新しいパーティション分割テーブルを配置するデータセットの名前です。
  • table は、クエリ結果を使用して作成するパーティション分割テーブルの名前です。
  • query は、標準 SQL 構文のクエリです。現時点では、レガシー SQL を使用して、パーティション分割テーブルをクエリすることや、クエリ結果をパーティション分割テーブルに書き込むことはできません。

例:

次のコマンドを入力すると、mydataset 内の mypartitionedtable というパーティション分割テーブルにクエリ結果が書き込まれます。mydataset はデフォルト プロジェクトにあります。このクエリは、パーティション分割されていないテーブルである NHTSA Traffic Fatality 一般公開データセットからデータを取得します。このテーブルの timestamp_of_crash TIMESTAMP 列を使用してパーティションが作成されます。

bq query \
--destination_table mydataset.mypartitionedtable \
--time_partitioning_field timestamp_of_crash \
--use_legacy_sql=false \
'SELECT
   state_number,
   state_name,
   day_of_crash,
   month_of_crash,
   year_of_crash,
   latitude,
   longitude,
   manner_of_collision,
   number_of_fatalities,
   timestamp_of_crash
 FROM
   `bigquery-public-data`.nhtsa_traffic_fatalities.accident_2016
 LIMIT
   100'

次のコマンドを入力すると、mydataset 内の mypartitionedtable というパーティション分割テーブルにクエリ結果が書き込まれます。mydataset はデフォルト プロジェクトではなく myotherproject にあります。このクエリは、パーティション分割されていないテーブルである NHTSA Traffic Fatality 一般公開データセットからデータを取得します。このテーブルの timestamp_of_crash TIMESTAMP 列を使用してパーティションが作成されます。

bq query \
--destination_table myotherproject:mydataset.mypartitionedtable \
--time_partitioning_field timestamp_of_crash \
--use_legacy_sql=false \
'SELECT
   state_number,
   state_name,
   day_of_crash,
   month_of_crash,
   year_of_crash,
   latitude,
   longitude,
   manner_of_collision,
   number_of_fatalities,
   timestamp_of_crash
 FROM
   `bigquery-public-data`.nhtsa_traffic_fatalities.accident_2016
 LIMIT
   100'

API

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

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

データを読み込むときの分割テーブルの作成

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

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

パーティション デコレータを使用してデータを特定のパーティションに読み込むことができます。たとえば、2016 年 5 月 1 日に生成されたすべてのデータを 20160501 パーティションに読み込むには、次のパーティション デコレータを使用します。

table_name$20160501

パーティション デコレータを使用してデータを特定のパーティションに読み込む場合、パーティションに読み込まれるデータは、テーブルのパーティショニング スキームに準拠している必要があります。パーティションに書き込まれるすべての行は、パーティションの日付内に収まる値を持つ必要があります。

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

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

テーブルやビューにアクセス制御を直接割り当てることはできません。アクセス権を付与できる BigQuery リソースの最下位レベルは、データセット レベルです。テーブルやビューへのアクセス権を構成するには、データセット レベル以上のエンティティに Cloud IAM の役割を付与します。

データセット レベルで役割を付与すると、そのデータセットに含まれるテーブルやビューに対してエンティティが実行できるオペレーションが特定されます。データセット レベルのアクセス制御を構成する方法については、データセットへのアクセスの制御をご覧ください。

Google Cloud Platform リソース階層でデータセットよりも高位のレベル(プロジェクト レベル、フォルダレベル、組織レベルなど)で Cloud IAM の役割を付与することもできます。高位のレベルで役割を付与すると、より広範なリソースへのアクセス権がエンティティに付与されます。たとえば、プロジェクト レベルでエンティティに役割を付与すると、そのエンティティには、プロジェクトに含まれるすべてのデータセットに適用される権限が付与されます。リソースへのアクセス権を付与する方法については、Cloud IAM ドキュメントのリソースへのアクセス権の付与、変更、取り消しをご覧ください。

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

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

パーティション分割テーブルの使用

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

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

  • GCP 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

  1. GCP Console で BigQuery ウェブ UI を開きます。
    BigQuery ウェブ UI に移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、リスト内のテーブル名をクリックします。

  3. [クエリエディタ] の下にある [詳細] をクリックします。このタブには、テーブルの説明と表の情報が表示されます。

    テーブルの詳細

  4. [スキーマ] タブをクリックすると、テーブルのスキーマ定義が表示されます。分割テーブルには _PARTITIONTIME 疑似列が含まれていないことがわかります。

従来の UI

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

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

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

  4. [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

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

{
  "creationTime": "1563236533535",
  "description": "This is my partitioned table",
  "etag": "/ABcDEo7f8GHijKL2mnOpQr==",
  "expirationTime": "1565828533000",
  "id": "myproject:mydataset.mypartitionedtable",
  "kind": "bigquery#table",
  "labels": {
    "org": "dev"
  },
  "lastModifiedTime": "1563236533576",
  "location": "US",
  "numBytes": "0",
  "numLongTermBytes": "0",
  "numRows": "0",
  "requirePartitionFilter": true,
  "schema": {
    "fields": [
      {
        "name": "ts",
        "type": "TIMESTAMP"
      },
      {
        "name": "column1",
        "type": "STRING"
      },
      {
        "name": "column2",
        "type": "INTEGER"
      },
      {
        "name": "column3",
        "type": "STRING"
      }
    ]
  },
  "selfLink": "https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets/mydataset/tables/mypartitionedtable",
  "tableReference": {
    "datasetId": "mydataset",
    "projectId": "myproject",
    "tableId": "mypartitionedtable"
  },
  "timePartitioning": {
    "expirationMs": "86400000",
    "field": "ts",
    "requirePartitionFilter": true,
    "type": "DAY"
  },
  "type": "TABLE"
}

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

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

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

[
  {
    "name": "ts",
    "type": "TIMESTAMP"
  },
  {
    "name": "column1",
    "type": "STRING"
  },
  {
    "name": "column2",
    "type": "INTEGER"
  },
  {
    "name": "column3",
    "type": "STRING"
  }
]

API

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

データセット内のパーティション分割テーブルの一覧表示

データセット内のテーブル(パーティション分割テーブルを含む)を一覧表示するには、次の方法を使用します。

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

必要な権限

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

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

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

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

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

Console

  1. GCP Console で BigQuery ウェブ UI を開きます。
    BigQuery ウェブ UI に移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットをクリックします。

  3. リストをスクロールして、データセット内のテーブルを表示します。テーブル、パーティション分割テーブル、モデル、ビューは、別々のアイコンで区別できます。

従来の UI

  1. BigQuery ウェブ 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 (field: source_date, expirationMs: 86400000) |
| myview                  | VIEW  |                      |                                                   |
+-------------------------+-------+----------------------+---------------------------------------------------+

例:

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

bq ls --format=pretty mydataset

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

bq ls --format=pretty myotherproject:mydataset

API

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

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

パーティション分割テーブル内のパーティションを一覧表示するには、レガシー SQL を使用して __PARTITIONS_SUMMARY__ メタテーブルをクエリします。

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

必要な権限

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

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

レガシー SQL を使用して、分割テーブル内のパーティションを一覧表示できます。分割テーブル内のパーティションを一覧表示するには、次のようにします。

Console

  1. GCP Console で BigQuery ウェブ UI を開きます。
    GCP Console に移動

  2. [クエリを新規作成] ボタンをクリックします。

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

    #legacySQL
    SELECT
      partition_id
    FROM
      [dataset.table$__PARTITIONS_SUMMARY__]
    

    ここで

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

従来の 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. [Run query] をクリックします。

CLI

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 は、テーブルが含まれているデータセットです。
  • dataset.table は、テーブルの名前です。

API

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

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

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

現在、INFORMATION_SCHEMA サービスを使用してパーティション分割テーブルのメタデータを取得することはできません。

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

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

次のステップ

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

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

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