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

このページでは、BigQuery でパーティション分割テーブルを作成する方法について説明します。パーティション分割テーブルの概要については、分割テーブルの概要をご覧ください。

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management（IAM）のロールを付与します。

必要な権限

テーブルを作成するには、次の IAM 権限が必要です。

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

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

次の IAM 事前定義ロールには、テーブルの作成に必要な権限が含まれています。

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin（bigquery.jobs.create 権限を含む）
  • roles/bigquery.user（bigquery.jobs.create 権限を含む）
  • roles/bigquery.jobUser（bigquery.jobs.create 権限を含む）

また、bigquery.datasets.create 権限がある場合は、自分が作成したデータセット内のテーブルを作成および更新できます。

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

空のパーティション分割テーブルを作成する

BigQuery でパーティション分割テーブルを作成する手順は、任意のテーブル オプションに加えてパーティショニング オプションを指定する点を除き、標準テーブルを作成する手順と同様です。

時間単位列パーティション分割テーブルを作成する

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

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
  3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
  4. [テーブルを作成] パネルで、次の詳細を指定します。
    1. [ソース] セクションの [テーブルの作成元] リストで [空のテーブル] を選択します。
    2. [宛先] セクションで、次の詳細を指定します。
      1. [データセット] で、テーブルを作成するデータセットを選択します。
      2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
      3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
    3. [スキーマ] セクションでスキーマ定義を入力します。スキーマには、パーティショニング列に DATE、TIMESTAMP、DATETIME 列を含める必要があります。詳細については、スキーマの指定をご覧ください。スキーマ情報は、次のいずれかの方法で手動で入力できます。
      • オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
            bq show --format=prettyjson dataset.table
      • オプション 2: [フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの名前、型、モードを指定します。
    4. [パーティションとクラスタの設定] セクションの [パーティショニング] リストで、[フィールドにより分割] を選択してから、パーティショニングする列を選択します。このオプションは、スキーマに DATE、TIMESTAMP、または DATETIME 列が含まれている場合にのみ使用できます。
    5. 省略可: このテーブルのすべてのクエリでパーティション フィルタを必須にするには、[パーティション フィルタを要求] チェックボックスをオンにします。パーティション フィルタを使用すると、費用が低減され、パフォーマンスが向上する場合があります。詳細については、パーティション フィルタの要件を設定するをご覧ください。
    6. [パーティショニング タイプ] を選択して、1 日ごと、1 時間ごと、月別、年別のいずれかのパーティショニングを選択します。
    7. 省略可: [詳細オプション] セクションで、顧客管理の暗号鍵を使用する場合は、[顧客管理の暗号鍵（CMEK）を使用] オプションを選択します。BigQuery はデフォルトで、Google が所有し Google が管理する鍵を使用して、保存されているお客様のコンテンツを暗号化します。
    8. [テーブルを作成] をクリックします。

SQL

時間単位列パーティション分割テーブルを作成するには、PARTITION BY 句を指定した CREATE TABLE DDL ステートメントを使用します。

次の例では、transaction_date 列に基づいた 1 日ごとのパーティションを含むテーブルが作成されます。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

    CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY
  transaction_date
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

    OPTIONS 句を使用して、パーティションの有効期限やパーティション フィルタ要件などのテーブル オプションを設定します。

  3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

DATE 列のデフォルトのパーティショニング タイプは 1 日ごとのパーティショニングです。別のパーティショニング タイプを指定するには、PARTITION BY 句に DATE_TRUNC 関数を含めます。たとえば、次のクエリは月別のパーティションを含むテーブルを作成します。

CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY
  DATE_TRUNC(transaction_date, MONTH)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

また、パーティショニング列として TIMESTAMP 列または DATETIME 列を指定することもできます。その場合は、PARTITION BY 句に TIMESTAMP_TRUNC 関数または DATETIME_TRUNC 関数を含めて、パーティション タイプを指定します。たとえば、次のステートメントは TIMESTAMP 列に基づいて 1 日ごとのパーティションを含むテーブルを作成します。

CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_ts TIMESTAMP)
PARTITION BY
  TIMESTAMP_TRUNC(transaction_ts, DAY)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. --table フラグ（または -t ショートカット）を指定して、bq mk コマンドを使用します。

    bq mk \
   --table \
   --schema SCHEMA \
   --time_partitioning_field COLUMN \
   --time_partitioning_type UNIT_TIME \
   --time_partitioning_expiration EXPIRATION_TIME \
   --require_partition_filter=BOOLEAN
   PROJECT_ID:DATASET.TABLE

    次のように置き換えます。

    • SCHEMA: column:data_type,column:data_type 形式のスキーマ定義、またはローカルマシン上の JSON スキーマ ファイルのパス。詳細については、スキーマの指定をご覧ください。
    • COLUMN: パーティショニング列の名前。テーブル スキーマでは、この列は TIMESTAMP 型、DATETIME 型、または DATE 型である必要があります。
    • UNIT_TIME: パーティショニング タイプ。サポートされる値は、DAY、HOUR、MONTH、または YEAR です。
    • EXPIRATION_TIME: テーブルのパーティションの有効期限（秒単位）。--time_partitioning_expiration フラグは省略可能です。詳細については、パーティションの有効期限の設定をご覧ください。
    • BOOLEAN: true の場合、このテーブルのクエリにはパーティション フィルタを含める必要があります。--require_partition_filter フラグは省略可能です。詳細については、パーティション フィルタの要件を設定するをご覧ください。
    • PROJECT_ID: プロジェクト ID。省略した場合は、デフォルトのプロジェクトが使用されます。
    • DATASET: プロジェクト内のデータセットの名前。
    • TABLE: 作成するテーブルの名前。

    他のコマンドライン オプションについては、bq mk をご覧ください。

    次の例では、1 時間ごとのパーティショニングを使用して ts 列でパーティション分割された mytable という名前のテーブルを作成します。パーティションの有効期限は 259,200 秒（3 日間）です。

    bq mk \
   -t \
   --schema 'ts:TIMESTAMP,qtr:STRING,sales:FLOAT' \
   --time_partitioning_field ts \
   --time_partitioning_type HOUR \
   --time_partitioning_expiration 259200  \
   mydataset.mytable

Terraform

google_bigquery_table リソースを使用します。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

次の例では、日付によってパーティション分割された mytable という名前のテーブルを作成します。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  time_partitioning {
    type          = "DAY"
    field         = "Created"
    expiration_ms = 432000000 # 5 days
  }
  require_partition_filter = true

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Created",
    "type": "TIMESTAMP",
    "description": "Record creation timestamp"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

  1. Cloud Shell を起動します。

  2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

    このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

  1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

    新しく作成した main.tf にサンプルコードをコピーします。

    必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

  3. 環境に適用するサンプル パラメータを確認し、変更します。
  4. 変更を保存します。
  5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
    terraform init

    最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

    terraform init -upgrade

変更を適用する

  1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
    terraform plan

    必要に応じて構成を修正します。

  2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
    terraform apply

    Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

  3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

API

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

Go

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTablePartitioned demonstrates creating a table and specifying a time partitioning configuration.
func createTablePartitioned(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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
	}
	return nil
}

Java

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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.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;
import com.google.cloud.bigquery.TimePartitioning;

// Sample to create a partition table
public class CreatePartitionedTable {

  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("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING),
            Field.of("date", StandardSQLTypeName.DATE));
    createPartitionedTable(datasetName, tableName, schema);
  }

  public static void createPartitionedTable(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);

      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date") //  name of column to use for partitioning
              .setExpirationMs(7776000000L) // 90 days
              .build();

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

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

Node.js

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

async function createTablePartitioned() {
  // Creates a new 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:string, Post_Abbr:string, Date:date';

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
    timePartitioning: {
      type: 'DAY',
      expirationMS: '7776000000',
      field: 'date',
    },
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);
  console.log(`Table ${table.id} created with partitioning: `);
  console.log(table.metadata.timePartitioning);
}

Python

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

from google.cloud import bigquery

client = bigquery.Client()

# Use format "your-project.your_dataset.your_table_name" for table_id
table_id = your_fully_qualified_table_id
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
    bigquery.SchemaField("date", "DATE"),
]
table = bigquery.Table(table_id, schema=schema)
table.time_partitioning = bigquery.TimePartitioning(
    type_=bigquery.TimePartitioningType.DAY,
    field="date",  # name of column to use for partitioning
    expiration_ms=1000 * 60 * 60 * 24 * 90,
)  # 90 days

table = client.create_table(table)

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

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

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

コンソール

  1. Google Cloud コンソールで [BigQuery] ページを開きます。

    [BigQuery] ページに移動

  2. [エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。

  3. アクション オプションを開いて、[開く] をクリックします。

  4. 詳細パネルで [テーブルを作成] をクリックします。

  5. [テーブルの作成] ページの [ソース] セクションで、[空のテーブル] を選択します。

  6. [送信先] で次の操作を行います。

    • [データセット名] で、該当するデータセットを選択します。
    • [テーブル名] フィールドに、テーブルの名前を入力します。
    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

  7. [スキーマ] セクションでスキーマ定義を入力します。

  8. [パーティションとクラスタの設定] セクションの [パーティショニング] で、[取り込み時間により分割] をクリックします。

  9. （省略可）このテーブルのすべてのクエリでパーティション フィルタを要求するには、[パーティション フィルタを要求] チェックボックスをオンにします。パーティション フィルタを要求すると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション フィルタの要件を設定するをご覧ください。

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

SQL

取り込み時間パーティション分割テーブルを作成するには、_PARTITIONDATE でパーティショニングする PARTITION BY 句を指定した CREATE TABLE ステートメントを使用します。

次の例では、1 日ごとのパーティションを含むテーブルを作成しています。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

    CREATE TABLE
  mydataset.newtable (transaction_id INT64)
PARTITION BY
  _PARTITIONDATE
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

    OPTIONS 句を使用して、パーティションの有効期限やパーティション フィルタ要件などのテーブル オプションを設定します。

  3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

取り込み時間パーティショニングのデフォルトのパーティショニング タイプは、1 日ごとのパーティショニングです。別のパーティショニング タイプを指定するには、PARTITION BY 句に DATE_TRUNC 関数を含めます。たとえば、次のクエリは月別のパーティションを含むテーブルを作成します。

CREATE TABLE
  mydataset.newtable (transaction_id INT64)
PARTITION BY
  DATE_TRUNC(_PARTITIONTIME, MONTH)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. --table フラグ（または -t ショートカット）を指定して、bq mk コマンドを使用します。

    bq mk \
   --table \
   --schema SCHEMA \
   --time_partitioning_type UNIT_TIME \
   --time_partitioning_expiration EXPIRATION_TIME \
   --require_partition_filter=BOOLEAN  \
   PROJECT_ID:DATASET.TABLE

    次のように置き換えます。

    • SCHEMA: column:data_type,column:data_type 形式の定義、またはローカルマシン上の JSON スキーマ ファイルのパス。詳細については、スキーマの指定をご覧ください。
    • UNIT_TIME: パーティショニング タイプ。サポートされる値は、DAY、HOUR、MONTH、または YEAR です。
    • EXPIRATION_TIME: テーブルのパーティションの有効期限（秒単位）。--time_partitioning_expiration フラグは省略可能です。詳細については、パーティションの有効期限の設定をご覧ください。
    • BOOLEAN: true の場合、このテーブルのクエリにはパーティション フィルタを含める必要があります。--require_partition_filter フラグは省略可能です。詳細については、パーティション フィルタの要件を設定するをご覧ください。
    • PROJECT_ID: プロジェクト ID。省略した場合は、デフォルトのプロジェクトが使用されます。
    • DATASET: プロジェクト内のデータセットの名前。
    • TABLE: 作成するテーブルの名前。

    他のコマンドライン オプションについては、bq mk をご覧ください。

    次の例では、mytable という名前の取り込み時間パーティション分割テーブルを作成します。このテーブルには 1 日ごとのパーティショニングがあり、パーティションの有効期限が 259,200 秒（3 日間）に設定されています。

    bq mk \
   -t \
   --schema qtr:STRING,sales:FLOAT,year:STRING \
   --time_partitioning_type DAY \
   --time_partitioning_expiration 259200 \
   mydataset.mytable

Terraform

google_bigquery_table リソースを使用します。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

次の例では、取り込み時間によってパーティション分割された mytable という名前のテーブルを作成します。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  time_partitioning {
    type          = "MONTH"
    expiration_ms = 604800000 # 7 days
  }
  require_partition_filter = true

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

  1. Cloud Shell を起動します。

  2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

    このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

  1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

    新しく作成した main.tf にサンプルコードをコピーします。

    必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

  3. 環境に適用するサンプル パラメータを確認し、変更します。
  4. 変更を保存します。
  5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
    terraform init

    最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

    terraform init -upgrade

変更を適用する

  1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
    terraform plan

    必要に応じて構成を修正します。

  2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
    terraform apply

    Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

  3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

API

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

整数範囲パーティション分割テーブルを作成する

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

コンソール

  1. Google Cloud コンソールで [BigQuery] ページを開きます。

    [BigQuery] ページに移動

  2. [エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。

  3. アクション オプションを開いて、[開く] をクリックします。

  4. 詳細パネルで [テーブルを作成] をクリックします。

  5. [テーブルの作成] ページの [ソース] セクションで、[空のテーブル] を選択します。

  6. [送信先] で次の操作を行います。

    • [データセット名] で、該当するデータセットを選択します。
    • [テーブル名] フィールドに、テーブルの名前を入力します。
    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

  7. [スキーマ] セクションでスキーマ定義を入力します。スキーマにパーティショニング列に対する INTEGER 列が含まれていることを確認してください。詳細については、スキーマの指定をご覧ください。

  8. [パーティションとクラスタの設定] セクションの [パーティショニング] プルダウン リストで、[フィールドにより分割] を選択して、パーティショニング列を選びます。このオプションは、スキーマに INTEGER 列が含まれている場合にのみ使用できます。

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

    • [開始] は、最初のパーティション範囲の開始値です（この値は含まれる）。
    • [終了] は、最後のパーティション範囲の終了値です（この値は含まれない）。
    • [間隔] は、各パーティション範囲の幅です。

    この範囲外の値は、特定の __UNPARTITIONED__ パーティションに入ります。

  10. （省略可）このテーブルのすべてのクエリでパーティション フィルタを要求するには、[パーティション フィルタを要求] チェックボックスをオンにします。パーティション フィルタを要求すると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション フィルタの要件を設定するをご覧ください。

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

SQL

整数範囲パーティション分割テーブルを作成するには、PARTITION BY 句を指定した CREATE TABLE DDL ステートメントを使用します。

次の例では、customer_id 列でパーティショニングされた、開始 0、終了 100、間隔 10 のテーブルを作成しています。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

    CREATE TABLE mydataset.newtable (customer_id INT64, date1 DATE)
PARTITION BY
  RANGE_BUCKET(customer_id, GENERATE_ARRAY(0, 100, 10))
  OPTIONS (
    require_partition_filter = TRUE);

    OPTIONS 句を使用して、パーティション フィルタ要件などのテーブル オプションを設定します。

  3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. --table フラグ（または -t ショートカット）を指定して、bq mk コマンドを使用します。

    bq mk \
   --schema schema \
   --range_partitioning=COLUMN_NAME,START,END,INTERVAL \
   --require_partition_filter=BOOLEAN  \
   PROJECT_ID:DATASET.TABLE

    次のように置き換えます。

    • SCHEMA: column:data_type,column:data_type 形式のインライン スキーマ定義、またはローカルマシン上の JSON スキーマ ファイルのパス。詳細については、スキーマの指定をご覧ください。
    • COLUMN_NAME: パーティショニング列の名前。テーブル スキーマでは、この列は INTEGER 型である必要があります。
    • START: 最初のパーティション範囲の開始値（この値は含まれる）。
    • END: 最後のパーティション範囲の終了値（この値は含まれない）。
    • INTERVAL: 各パーティション範囲の幅。
    • BOOLEAN: true の場合、このテーブルのクエリにはパーティション フィルタを含める必要があります。--require_partition_filter フラグは省略可能です。詳細については、パーティション フィルタの要件を設定するをご覧ください。
    • PROJECT_ID: プロジェクト ID。省略した場合は、デフォルトのプロジェクトが使用されます。
    • DATASET: プロジェクト内のデータセットの名前。
    • TABLE: 作成するテーブルの名前。

    パーティション範囲外の値は、特別な __UNPARTITIONED__ パーティションに入ります。

    他のコマンドライン オプションについては、bq mk をご覧ください。

    次の例では、customer_id 列でパーティション分割された mytable という名前のテーブルを作成します。

    bq mk \
   -t \
   --schema 'customer_id:INTEGER,qtr:STRING,sales:FLOAT' \
   --range_partitioning=customer_id,0,100,10 \
   mydataset.mytable

Terraform

google_bigquery_table リソースを使用します。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

次の例では、整数範囲によってパーティション分割された mytable という名前のテーブルを作成します。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  range_partitioning {
    field = "ID"
    range {
      start    = 0
      end      = 1000
      interval = 10
    }
  }
  require_partition_filter = true

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

  1. Cloud Shell を起動します。

  2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

    このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

  1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

    新しく作成した main.tf にサンプルコードをコピーします。

    必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

  3. 環境に適用するサンプル パラメータを確認し、変更します。
  4. 変更を保存します。
  5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
    terraform init

    最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

    terraform init -upgrade

変更を適用する

  1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
    terraform plan

    必要に応じて構成を修正します。

  2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
    terraform apply

    Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

  3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

API

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

Java

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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 のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

// 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 のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

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

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

  • SQL で CREATE TABLE ... AS SELECT ステートメントを使用します。この方法を使用すると、時間単位列または整数範囲でパーティショニングされたテーブルは作成できますが、取り込み時間でパーティショニングされたテーブルは作成できません。
  • bq コマンドライン ツールまたは BigQuery API を使用して、クエリに宛先テーブルを設定します。クエリを実行すると、BigQuery は結果を宛先テーブルに書き込みます。この方法は、どのパーティショニング タイプにも使用できます。

  • jobs.insert API メソッドを呼び出し、timePartitioning または rangePartitioning のいずれかのプロパティでパーティショニングを指定します。

SQL

クエリには SELECT AS 句を指定した CREATE TABLE ステートメントを使用します。パーティショニングを構成するには、PARTITION BY 句を含めます。

次の例では、transaction_date 列でパーティション分割されたテーブルを作成します。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

    CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY
  transaction_date
AS (
  SELECT
    transaction_id, transaction_date
  FROM
    mydataset.mytable
);

    OPTIONS 句を使用して、パーティション フィルタ要件などのテーブル オプションを設定します。

  3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. クエリからパーティション分割テーブルを作成するには、--destination_table フラグと --time_partitioning_type フラグを指定した bq query コマンドを使用します。

    時間単位列パーティショニング:

    bq query \
   --use_legacy_sql=false \
   --destination_table TABLE_NAME \
   --time_partitioning_field COLUMN \
   --time_partitioning_type UNIT_TIME \
   'QUERY_STATEMENT'

    取り込み時間パーティショニング:

    bq query \
   --use_legacy_sql=false \
   --destination_table TABLE_NAME \
   --time_partitioning_type UNIT_TIME \
   'QUERY_STATEMENT'

    整数範囲パーティショニング:

    bq query \
   --use_legacy_sql=false \
   --destination_table PROJECT_ID:DATASET.TABLE \
   --range_partitioning COLUMN,START,END,INTERVAL \
   'QUERY_STATEMENT'

    次のように置き換えます。

    • PROJECT_ID: プロジェクト ID。省略した場合は、デフォルトのプロジェクトが使用されます。
    • DATASET: プロジェクト内のデータセットの名前。
    • TABLE: 作成するテーブルの名前。
    • COLUMN: パーティショニング列の名前。
    • UNIT_TIME: パーティショニング タイプ。サポートされる値は、DAY、HOUR、MONTH、または YEAR です。
    • START: 範囲パーティショニングの開始値（この値は含まれる）。
    • END: 範囲パーティショニングの終了値（この値は含まれない）。
    • INTERVAL: パーティション内の各範囲の幅。
    • QUERY_STATEMENT: テーブルのデータ入力に使用されるクエリ。

    次の例では、月別のパーティショニングを使用して transaction_date 列でパーティショニングされたテーブルを作成しています。

    bq query \
   --use_legacy_sql=false \
   --destination_table mydataset.newtable \
   --time_partitioning_field transaction_date \
   --time_partitioning_type MONTH \
   'SELECT transaction_id, transaction_date FROM mydataset.mytable'

    次の例では、整数範囲パーティショニングを使用して customer_id 列でパーティショニングされたテーブルを作成します。

    bq query \
   --use_legacy_sql=false \
   --destination_table mydataset.newtable \
   --range_partitioning customer_id,0,100,10 \
   'SELECT * FROM mydataset.ponies'

    取り込み時間パーティション分割テーブルの場合は、パーティション デコレータを使用して特定のパーティションにデータを読み込むこともできます。次の例では、新しい取り込み時間パーティション分割テーブルを作成し、20180201（2018 年 2 月 1 日）パーティションにデータを読み込んでいます。

    bq query \
   --use_legacy_sql=false  \
   --time_partitioning_type=DAY \
   --destination_table='newtable$20180201' \
   'SELECT * FROM mydataset.mytable'

API

クエリ結果をパーティション分割テーブルに保存するには、jobs.insert メソッドを呼び出します。query ジョブを構成します。destinationTable に宛先テーブルを指定します。timePartitioning プロパティまたは rangePartitioning プロパティでパーティショニングを指定します。

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

日付別テーブルを以前に作成している場合は、bq コマンドライン ツールで partition コマンドを使用して、関連する一連のテーブル全体を単一の取り込み時間パーティション分割テーブルに変換できます。

bq --location=LOCATION partition \
    --time_partitioning_type=PARTITION_TYPE \
    --time_partitioning_expiration INTEGER \
    PROJECT_ID:SOURCE_DATASET.SOURCE_TABLE \
    PROJECT_ID:DESTINATION_DATASET.DESTINATION_TABLE

次のように置き換えます。

  • LOCATION: ロケーションの名前。--location フラグは省略可能です。
  • PARTITION_TYPE: パーティション タイプ。有効な値は DAY、HOUR、MONTH、または YEAR です。
  • INTEGER: パーティションの有効期限（秒）。最小値はありません。パーティションの日付（UTC）に、この整数値を足した値が有効期限になります。time_partitioning_expiration フラグは省略可能です。
  • PROJECT_ID: プロジェクト ID。
  • SOURCE_DATASET: 日付別テーブルを含むデータセット。
  • SOURCE_TABLE: 日付別テーブルの接頭辞。
  • DESTINATION_DATASET; 新しいパーティション分割テーブルのデータセット。
  • DESTINATION_TABLE; 作成するパーティション分割テーブルの名前。

partition コマンドは --label、--expiration、--add_tags、--description フラグをサポートしていません。ラベル、テーブルの有効期限、タグ、および説明は、テーブルの作成後に追加できます。

partition コマンドを実行すると、BigQuery は、シャーディングしたテーブルからパーティションを生成するコピージョブを作成します。

次の例では、sourcetable_ という接頭辞が付いた一連の日付別テーブルから、mytable_partitioned という名前の取り込み時間パーティション分割テーブルを作成しています。新しいテーブルは毎日パーティション分割され、パーティションの有効期限は 259,200 秒（3 日間）に設定されます。

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 というパーティションを作成します。

パーティション分割テーブルのセキュリティ

パーティション分割テーブルのアクセス制御は、標準テーブルのアクセス制御と同じです。さらに詳しい内容については、テーブル アクセス制御の概要をご覧ください。

次のステップ