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

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

整数範囲パーティションの詳細については、整数範囲パーティション分割テーブルを参照してください。

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

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

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

制限事項

整数範囲パーティション分割テーブルには次の制限があります。

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

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

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

  • Cloud Console または従来のウェブ UI を使用する
  • PARTITION BY RANGE_BUCKET 句に partition expression を指定した DDL CREATE TABLE ステートメントを使用する
  • 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 のロールと権限について詳しくは、事前定義されたロールと権限をご覧ください。

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

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

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

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

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

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

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

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

Console

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

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

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

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

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

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

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

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

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

  7. [パーティションとクラスタの設定] で、[パーティション] プルダウン リストから、タイプが INTEGER の列を選択します。

  8. [開始]、[終了]、[間隔] の値を指定します。

    • [開始] は範囲パーティショニングの開始値です。パーティションにはこの値も含まれます。
    • [終了] は範囲パーティショニングの終了値です。パーティションにこの値は含まれません。
    • [間隔] はパーティション内の各範囲の幅です。
  9. (省略可)クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[パーティショニング フィルタ] で [パーティション フィルタを要求] ボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。

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

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

DDL

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

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

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

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

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

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

    次のクエリでは、customer_id 列に start 0、end 100、interval 10 の整数範囲パーティションを持つ newtable という名前のテーブルが作成されます。

     CREATE TABLE
       mydataset.newtable
     PARTITION BY
       RANGE_BUCKET(customer_id, GENERATE_ARRAY(0, 100, 10))
     AS SELECT 1 AS customer_id, DATE "2019-10-01" AS date1
     

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

bq

--range_partitioning フラグを指定して mk コマンドを使用します。

bq mk \
--range_partitioning=column_name,start,end,interval \
project_id:dataset.table \
"column_name:integer,value:integer"

ここで

  • column_name は整数範囲パーティションを作成するために使用される列です。
  • start は範囲パーティショニングの開始値です。パーティションにはこの値も含まれます。
  • end は範囲パーティショニングの終了値です。パーティションにこの値は含まれません。
  • interval はパーティション内の各範囲の幅です。
  • project_id はプロジェクト ID です。
  • dataset は、プロジェクトのデータセットです。
  • table は、作成するパーティション分割テーブルの名前です。

例:

次のコマンドを入力して、デフォルトのプロジェクトの mydataset に、mypartitionedtable という名前の整数範囲パーティション分割テーブルを作成します。start 0、end 100、interval 10 のそれぞれの値を基にパーティショニングされます。

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

bq mk \
--require_partition_filter \
--range_partitioning=customer_id,0,100,10 \
mydataset.mypartitionedtable \
"customer_id:integer,value:integer"

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

API

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

Java

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.RangePartitioning;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a range partitioned table
public class CreateRangePartitionedTable {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("integerField", StandardSQLTypeName.INT64),
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL),
            Field.of("dateField", StandardSQLTypeName.DATE));
    createRangePartitionedTable(datasetName, tableName, schema);
  }

  public static void createRangePartitionedTable(
      String datasetName, String tableName, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      // Note: The field must be a top- level, NULLABLE/REQUIRED field.
      // The only supported type is INTEGER/INT64
      RangePartitioning partitioning =
          RangePartitioning.newBuilder()
              .setField("integerField")
              .setRange(
                  RangePartitioning.Range.newBuilder()
                      .setStart(1L)
                      .setInterval(2L)
                      .setEnd(10L)
                      .build())
              .build();

      StandardTableDefinition tableDefinition =
          StandardTableDefinition.newBuilder()
              .setSchema(schema)
              .setRangePartitioning(partitioning)
              .build();
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Range partitioned table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Range partitioned table was not created. \n" + e.toString());
    }
  }
}

Node.js

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function createTableRangePartitioned() {
  // Creates a new integer range partitioned table named "my_table"
  // in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  const schema = [
    {name: 'fullName', type: 'STRING'},
    {name: 'city', type: 'STRING'},
    {name: 'zipcode', type: 'INTEGER'},
  ];

  // To use integer range partitioning, select a top-level REQUIRED or
  // NULLABLE column with INTEGER / INT64 data type. Values that are
  // outside of the range of the table will go into the UNPARTITIONED
  // partition. Null values will be in the NULL partition.
  const rangePartition = {
    field: 'zipcode',
    range: {
      start: 0,
      end: 100000,
      interval: 10,
    },
  };

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    rangePartitioning: rangePartition,
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created with integer range partitioning: `);
  console.log(table.metadata.rangePartitioning);
}

Python

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING"),
    bigquery.SchemaField("city", "STRING"),
    bigquery.SchemaField("zipcode", "INTEGER"),
]

table = bigquery.Table(table_id, schema=schema)
table.range_partitioning = bigquery.RangePartitioning(
    # To use integer range partitioning, select a top-level REQUIRED /
    # NULLABLE column with INTEGER / INT64 data type.
    field="zipcode",
    range_=bigquery.PartitionRange(start=0, end=100000, interval=10),
)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

テーブルが整数列でパーティション分割されていることを確認するには、スキーマを調べます。たとえば、次のコマンドを実行します。

bq show --format=prettyjson mydataset.mytable

整数列がパーティション分割されている場合、bq show からの出力には rangePartitioning データが含まれます。

...
  "rangePartitioning": {
    "field": "customer_id",
    "range": {
      "end": "100",
      "interval": "10",
      "start": "0"
    }
  },
...

整数範囲パーティション分割テーブルへの書き込み

整数範囲パーティション分割テーブルに書き込まれたデータは、自動的にパーティション分割されます。これには、読み込みジョブ、クエリ、ストリーミングを介したテーブルへの書き込みも含まれます。

ストリーミングの場合、ストリーミング バッファ内のデータはパーティション分割されていないパーティションに置かれます。抽出されたデータは、まずパーティション分割されていないパーティションに蓄積されます。パーティション分割されていないデータが十分蓄積されると、特定のパーティションに再分割されます。

次の例では、クエリ結果を整数範囲パーティション分割テーブルに保存する方法を紹介します。

bq query --nouse_legacy_sql \
--destination_table=mydataset.mytable \
'SELECT value AS customer_id, value+1 AS value FROM UNNEST(GENERATE_ARRAY(-5, 110, 5)) AS value'

整数範囲パーティション分割テーブルに対するクエリの実行

整数範囲パーティション分割テーブルには、標準 SQL によってのみクエリを実行できます。整数範囲パーティション分割テーブルにクエリを実行するときに、整数パーティション分割列にフィルタがかかっていれば、パーティションがプルーニングされ、クエリの費用を抑えられます。

次のクエリは、30、40、50 で始まる 3 つのパーティションをスキャンします。

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.mytable WHERE customer_id BETWEEN 30 AND 50'

bq query コマンドからの出力の例は次のとおりです。

Waiting on bqjob_r4fce65fa3381528e_000001670994aeb6_1 ... (0s) Current status: DONE
+---------+-------+
| customer_id | value |
+---------+-------+
|      40 |    41 |
|      45 |    46 |
|      30 |    31 |
|      35 |    36 |
|      50 |    51 |
+---------+-------+

この例では、各パーティションに 2 つの行があり、各行に 2 つの整数列があります。そのため、クエリは 3 × 2 × 2 × 8 = 96 バイトをスキャンします。ジョブの情報を調べることができます。

bq show -j bqjob_r4fce65fa3381528e_000001670994aeb6_1

bq show コマンドからの出力の例は次のとおりです。

Job myproject:bqjob_r4fce65fa3381528e_000001670994aeb6_1

  Job Type    State      Start Time      Duration       User Email        Bytes Processed   Bytes Billed   Billing Tier   Labels
 ---------- --------- ----------------- ---------- --------------------- ----------------- -------------- -------------- --------
  query      SUCCESS   24 Sep 12:19:58   0:00:01    joe@google.com       96                10485760       1

DML ステートメントがサポートされています。例:

bq query --nouse_legacy_sql \
'DELETE FROM mydataset.mytable WHERE customer_id = 30'

現在、整数範囲パーティション分割列の関数に対するパーティションのプルーニングはサポートされていません。たとえば、次のクエリはテーブル全体をスキャンします。

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.mytable WHERE customer_id+1 BETWEEN 30 AND 50'

整数範囲パーティション分割テーブルのテーブル デコレータ

日付 / タイムスタンプ パーティショニングと同様に、整数範囲パーティション分割テーブルのパーティションを処理するテーブル デコレータを使用できます。範囲パーティションを処理する際、範囲の開始値が重要となります。

次の例では、0 で始まる範囲パーティションをクエリします。0 と 5 の 2 つの値があります。

bq query 'SELECT * FROM mydataset.mytable$0'

+---------+-------+
| customer_id | value |
+---------+-------+
|       0 |     1 |
|       5 |     6 |
+---------+-------+

クラスタリングを使用した整数範囲パーティショニング

整数範囲パーティショニングでは、クラスタリングを使用できます。まず整数範囲パーティション分割列でデータが分割されてから、クラスタリング列ごとに各パーティションのデータがクラスタ化されます。

たとえば、このコマンドは整数範囲の列とクラスタを持つテーブルを作成します。

bq mk \
--range_partitioning=customer_id,0,100,10 \
--clustering_fields=value \
mydataset.mytable_2 \
"customer_id:integer,value:integer"

テーブルの形式を取得すると、範囲パーティショニングとクラスタリングの両方が有効になります。

...
  "clustering": {
    "fields": [
      "value"
    ]
  },
...
  "rangePartitioning": {
    "field": "customer_id",
    "range": {
      "end": "100",
      "interval": "10",
      "start": "0"
    }
  },
...

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

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

Console

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

bq

bq query コマンドを入力します。クエリ結果に基づいて永続テーブルを作成することを --destination_table フラグによって指定し、作成するテーブルがパーティション分割テーブルであることを --range_partitioning フラグによって指定します。

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

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

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

bq --location=location query \
--destination_table project_id:dataset.table \
--range_partitioning column,start,end,interval \
--use_legacy_sql=false \
'query'

ここで

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

例:

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

bq query \
--destination_table mydataset.mypartitionedtable \
--use_legacy_sql=false \
--range_partitioning provider_id,10000,700000,10000 \
'SELECT
   provider_id, total_discharges, average_covered_charges
 FROM
   `bigquery-public-data`.medicare.inpatient_charges_2011
 LIMIT
   300'

API

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

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

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

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

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

パーティション デコレータを使用してデータを特定のパーティションに読み込むことができます。たとえば、start 0、end 100、interval 10 の値が指定された、customer_id 列で整数範囲パーティション分割されたテーブルを想定します。0~9 の範囲の customer ID のデータをすべて読み込むには、次の $0 パーティション デコレータを使用します。

table_name$0

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

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

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

テーブルとビューへのアクセスを構成するには、エンティティに次のレベルで 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

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

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

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

    テーブルの詳細

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

bq

すべてのテーブル情報を表示するには、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": "1569429717657",
  "etag": "AcSEmWFQdbYEGT0auTE9NA==",
  "id": "myproject:mydataset.newtable",
  "kind": "bigquery#table",
  "lastModifiedTime": "1569429717657",
  "location": "US",
  "numBytes": "16",
  "numLongTermBytes": "0",
  "numRows": "1",
  "rangePartitioning": {
    "field": "customer_id",
    "range": {
      "end": "100",
      "interval": "10",
      "start": "0"
    }
  },
  "schema": {
    "fields": [
      {
        "name": "customer_id",
        "type": "INTEGER"
      },
      {
        "name": "date1",
        "type": "DATE"
      }
    ]
  },
  "selfLink": "https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets/mydataset/tables/newtable",
  "tableReference": {
    "datasetId": "mydataset,
    "projectId": "myproject",
    "tableId": "newtable"
  },
  "type": "TABLE"
}

API

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.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

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

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

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

Console

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

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

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

API

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

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

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

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

必要な権限

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

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

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

Console

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

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

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

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

    ここで

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

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 ジョブを構成します。

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

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

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

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

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

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

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

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

SELECT
  column
FROM
  [dataset.table$__PARTITIONS_SUMMARY__]

ここで

  • dataset は、データセットの名前です。
  • table は、時間パーティション分割テーブルの名前です。
  • column は、次のいずれかです。
説明
project_id プロジェクトの名前。
dataset_id データセットの名前。
table_id 時間パーティション分割テーブルの名前。
partition_id パーティションの名前(日付)。
creation_time パーティションが作成された日時(UTC 1970 年 1 月 1 日からのミリ秒数)。
last_modified_time パーティションが最後に変更された日時(UTC 1970 年 1 月 1 日からのミリ秒数)。

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

__PARTITIONS_SUMMARY__ メタテーブルを使用するクエリジョブを実行するには、少なくとも bigquery.jobs.create 権限が付与されている必要があります。次の事前定義済みの 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__]

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        | 10000        | 1517190224120 | 1517190224997      |
| myproject      | mydataset  | mytable        | 20000        | 1517190224120 | 1517190224997      |
+----------------+------------+----------------+--------------+---------------+--------------------+

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

Console

#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 |
+--------------+--------------------+
| 100000       |      1471632556179 |
| 20000        |      1471632538142 |
| 30000        |      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__]

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        |
+--------------+----------------------------+
| 10000        | 2016-08-19 18:49:30.463000 |
| 20000        | 2016-08-19 18:49:16.179000 |
| 30000        | 2016-08-19 18:48:58.142000 |
+--------------+----------------------------+

次のステップ