クラスタ化テーブルの作成と使用

このドキュメントでは、BigQuery でクラスタ化テーブルを作成および使用する方法について説明します。BigQuery でのクラスタ化テーブルに対するサポートの概要については、クラスタ化テーブルの概要をご覧ください。

制限事項

BigQuery のクラスタ化テーブルには、次の制限があります。

• クラスタ化テーブルのクエリと、クラスタ化テーブルに対するクエリ結果の書き込みについては、標準 SQL のみがサポートされています。

• クラスタリング列は最上位の繰り返しでない列であることが必要です。データ型は次のいずれかでなければなりません。

  • DATE
  • BOOL
  • GEOGRAPHY
  • INT64
  • NUMERIC
  • BIGNUMERIC
  • STRING
  • TIMESTAMP
  • DATETIME

  データ型の詳細については、標準 SQL のデータ型をご覧ください。

• 最大 4 つのクラスタリング列を指定できます。

• クラスタリングに STRING 型の列を使用する場合、BigQuery は最初の 1,024 文字のみを使用してデータをクラスタリングします。列の値自体は 1,024 文字を超える場合があります。

クラスタ化テーブルを作成する

次の方法でクラスタ化テーブルを作成できます。

• クエリ結果を使用してテーブルを作成します。

  • DDL CREATE TABLE AS SELECT ステートメントを実行します。
  • クラスタ化された宛先テーブルを作成するクエリを実行します。

• CLUSTER BY ステートメントに clustering_column_list を指定した DDL CREATE TABLE ステートメントを使用します。

• bq コマンドライン ツールの bq mk コマンドを実行します。

• tables.insert API メソッドを呼び出します。

• BigQuery へデータを読み込みます。

• クライアント ライブラリの使用

テーブルの命名

BigQuery でテーブルを作成するとき、テーブル名はデータセットごとに一意である必要があります。テーブル名の要件は次のとおりです。

• 1,024 文字以内。
• カテゴリ L（文字）、M（マーク）、N（数字）、Pc（コネクタ、アンダースコアを含む）、Pd（ダッシュ）、Zs（スペース）の Unicode 文字を含む。詳しくは、一般カテゴリをご覧ください。

有効なテーブル名のすべての例を次に示します: table 01、ग्राहक、00_お客様、étudiant-01。

注意点

• 一部のテーブル名とテーブル名の接頭辞は予約済みです。テーブル名または接頭辞が予約されているというエラーが表示された場合は、別の名前を選択して、もう試してください。

• 複数のドット演算子（.）を連続して含めると、重複する演算子が暗黙的に削除されます。

  たとえば、以下は、project_name....datasest_name..table_name

  次のようになります。project_name.dataset_name.table_name

必要な権限

テーブルを作成するには、次の 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 でテーブルを作成するときにクラスタリング列を指定します。テーブルが作成されたら、クラスタリング列を変更できます。詳細については、クラスタリング仕様の変更をご覧ください。

クラスタリング列は最上位の非繰り返し列で、そのデータ型は次のシンプルなデータ型のいずれかでなければなりません。

• DATE
• BOOLEAN
• GEOGRAPHY
• INTEGER
• NUMERIC
• BIGNUMERIC
• STRING
• TIMESTAMP

最大 4 つのクラスタリング列を指定できます。複数の列を指定する場合、列の順序によってデータの並べ替え方法が決まります。たとえば、テーブルが列 a、b、c によってクラスタ化されている場合、データは同じ順序（列 a、列 b、列 c の順）で並べ替えられます。ベスト プラクティスとして、最も頻繁にフィルタリングまたは集計される列を最初に置いてください。

クラスタリング列の順序は、クエリのパフォーマンスと料金にも影響します。クラスタ化テーブルのクエリのベスト プラクティスについては、クラスタ化テーブルのクエリをご覧ください。

スキーマ定義を使用して空のクラスタ化テーブルを作成するには:

Console

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

   BigQuery に移動

2. [エクスプローラ] ペインでプロジェクトを展開し、データセットを選択します。
3. [データセット情報] セクションで、 [テーブルを作成] をクリックします。
4. [テーブルの作成] パネルで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [空のテーブル] を選択します。
2. [送信先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでスキーマ定義を入力します。 スキーマ情報は、次のいずれかの方法で手動で入力できます。
   • オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。

         bq show --format=prettyjson dataset.table
         

   • オプション 2: [フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの [名前]、[型]、[モード] を指定します。
4. [クラスタリング順序] で、1～4 個のフィールド名をカンマで区切って入力します。
5. 省略可: [詳細オプション] セクションで、顧客管理の暗号鍵を使用する場合は、[顧客管理の暗号鍵（CMEK）を使用する] オプションを選択します。デフォルトでは、BigQuery は Google が管理する鍵を使用して、保存されているお客様のコンテンツを暗号化します。
6. [テーブルを作成] をクリックします。
7. [テーブルを作成] をクリックします。

SQL

CLUSTER BY オプションを指定して CREATE TABLE コマンドを使用します。次の例では、myclusteredtable という名前のクラスタ化テーブルを mydataset 内に作成します。

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
OPTIONS (
  description="a table clustered by customer_id"
)

bq

次のフラグを指定して、bq mk コマンドを使用します。

• --table（または -t ショートカット）。
• --schema。テーブルのスキーマ定義をインラインで、または JSON スキーマ ファイルを使用して指定できます。
• --clustering_fields。最大 4 つのクラスタリング列を指定できます。

オプション パラメータには --expiration、--description、--time_partitioning_type、--time_partitioning_field、--time_partitioning_expiration、--destination_kms_key、--label があります。

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

--destination_kms_key はここでは説明しません。--destination_kms_key の使用方法の詳細については、顧客管理の暗号鍵をご覧ください。

次のコマンドを入力して、スキーマ定義を指定して空のクラスタ化テーブルを作成します。

bq mk \
--table \
--expiration INTEGER1 \
--schema SCHEMA \
--clustering_fields CLUSTER_COLUMNS \
--description "DESCRIPTION" \
--label KEY:VALUE,KEY:VALUE \
PROJECT_ID:DATASET.TABLE

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

• INTEGER1: テーブルのデフォルトの存続期間（秒）です。最小値は 3,600 秒（1 時間）です。現在の UTC 時間にこの整数値を足した値が有効期限になります。テーブルの作成時に有効期限を設定した場合、データセットのデフォルトのテーブル有効期限設定は無視されます。この値を設定すると、指定した時間が経過したときにテーブルは削除されます。
• SCHEMA: COLUMN:DATA_TYPE,COLUMN:DATA_TYPE の形式のインライン スキーマ定義か、ローカルマシン上の JSON スキーマ ファイルのパスです。
• CLUSTER_COLUMNS: 最大 4 つのクラスタリング列のカンマ区切りリスト。リストには、スペースを含めることはできません。
• DESCRIPTION: テーブルの説明です。引用符で囲みます。
• KEY:VALUE: ラベルを表す Key-Value ペアです。カンマ区切りのリストを使用して複数のラベルを入力できます。
• PROJECT_ID: プロジェクト ID。
• DATASET: プロジェクト内のデータセット。
• TABLE: 作成するテーブルの名前。

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

例:

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

スキーマはインラインで timestamp:timestamp,customer_id:string,transaction_amount:float と指定されています。指定されたクラスタリング フィールド customer_id は、テーブルをクラスタ化するために使用されます。

bq mk -t \
--expiration 2592000 \
--schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
--clustering_fields customer_id \
--description "This is my clustered table" \
--label org:dev \
mydataset.myclusteredtable

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

スキーマは、/tmp/myschema.json というローカル JSON ファイルで定義されています。customer_id フィールドは、テーブルをクラスタ化するために使用されます。

bq mk -t \
--expiration 2592000 \
--schema /tmp/myschema.json \
--clustering_fields=customer_id \
--description "This is my clustered table" \
--label org:dev \
myotherproject:mydataset.myclusteredtable

テーブルの作成後に、テーブルの説明とラベルを更新できます。

API

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

Python

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

GitHub で表示 フィードバック

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.clustering_fields = ["city", "zipcode"]
table = client.create_table(table)  # Make an API request.
print(
    "Created clustered table {}.{}.{}".format(
        table.project, table.dataset_id, table.table_id
    )
)

Go

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

GitHub で表示 フィードバック

import (
	"context"
	"fmt"
	"time"

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

// createTableClustered demonstrates creating a BigQuery table with advanced properties like
// partitioning and clustering features.
func createTableClustered(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: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	metaData := &bigquery.TableMetadata{
		Schema: sampleSchema,
		TimePartitioning: &bigquery.TimePartitioning{
			Field:      "timestamp",
			Expiration: 90 * 24 * time.Hour,
		},
		Clustering: &bigquery.Clustering{
			Fields: []string{"origin", "destination"},
		},
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

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

GitHub で表示 フィードバック

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
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;
import com.google.common.collect.ImmutableList;

public class CreateClusteredTable {
  public static void runCreateClusteredTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createClusteredTable(datasetName, tableName);
  }

  public static void createClusteredTable(String datasetName, String tableName) {
    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.of(TimePartitioning.Type.DAY);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

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

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

クエリ結果からクラスタ化テーブルを作成する

クエリ結果からクラスタ化テーブルを作成するには、次の 2 つの方法があります。

• 結果を新しい宛先テーブルに書き込み、クラスタリング列を指定する。
• DDL CREATE TABLE AS SELECT ステートメントを使用する。この方法の詳細については、データ定義言語ステートメントの使用のページにあるクエリ結果からクラスタ化テーブルを作成するをご覧ください。

パーティション分割テーブル、パーティション分割されていないテーブルのいずれのクエリからでも、クラスタ化テーブルを作成できます。クエリ結果を使用して、既存のテーブルをクラスタ化テーブルに変更することはできません。

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

Console

Cloud Console を使用してデータをクエリする場合は、DDL ステートメントを使用する場合を除き、宛先テーブルのクラスタリング オプションを指定することはできません。詳細については、データ定義言語ステートメントの使用をご覧ください。

bq

次のコマンドを入力して、クエリ結果から新しいクラスタ化テーブルを作成します。

bq --location=LOCATION query \
--use_legacy_sql=false 'QUERY'

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

• LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
• QUERY: 標準 SQL 構文のクエリ。現時点では、レガシー SQL を使用して、クラスタ化テーブルをクエリすることや、クエリ結果をクラスタ化テーブルに書き込むことはできません。クエリには、クラスタ化テーブルを作成するためのオプションを指定した CREATE TABLE DDL ステートメントを含めることができます。個々のコマンドライン フラグを指定するのではなく、DDL を使用できます。

例:

次のコマンドを入力すると、mydataset 内の myclusteredtable というクラスタ化テーブルにクエリ結果が書き込まれます。mydataset はデフォルト プロジェクトにあります。このクエリは、パーティション分割されていないテーブル（mytable）からデータを取得します。このテーブルの customer_id 列は、テーブルのクラスタ化に使用されます。このテーブルの timestamp 列は、パーティション分割テーブルの作成に使用されます。

bq query --use_legacy_sql=false \
'CREATE TABLE
   mydataset.myclusteredtable
 PARTITION BY
   DATE(timestamp)
 CLUSTER BY
   customer_id AS
 SELECT
   *
 FROM
   `mydataset.mytable`'

API

クエリ結果をクラスタ化テーブルに保存するには、jobs.insert メソッドを呼び出し、query ジョブを構成して、クラスタ化テーブルを作成する CREATE TABLE DDL ステートメントを含めます。

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

データ読み込み時にクラスタ化テーブルを作成する

新しいテーブルにデータを読み込むときに、クラスタリング列を指定することによってクラスタ化テーブルを作成できます。データを読み込む前に空のテーブルを作成する必要はありません。クラスタ化テーブルを作成すると同時にデータを読み込むことができます。

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

読み込みジョブを定義するときにクラスタリングを定義するには:

API

読み込みジョブを介してテーブルを作成する際にクラスタリング構成を定義するには、テーブルの Clustering プロパティをテーブルに入力します。

Go

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

GitHub で表示 フィードバック

import (
	"context"
	"fmt"

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

// importClusteredTable demonstrates creating a table from a load job and defining partitioning and clustering
// properties.
func importClusteredTable(projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field: "timestamp",
	}
	loader.Clustering = &bigquery.Clustering{
		Fields: []string{"origin", "destination"},
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

GitHub で表示 フィードバック

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class LoadTableClustered {

  public static void runLoadTableClustered() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadTableClustered(datasetName, tableName, sourceUri);
  }

  public static void loadTableClustered(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();

      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into clustered table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Data not loaded into clustered table during load job \n" + e.toString());
    }
  }
}

Python

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

GitHub で表示 フィードバック

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"

job_config = bigquery.LoadJobConfig(
    skip_leading_rows=1,
    source_format=bigquery.SourceFormat.CSV,
    schema=[
        bigquery.SchemaField("timestamp", bigquery.SqlTypeNames.TIMESTAMP),
        bigquery.SchemaField("origin", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("destination", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("amount", bigquery.SqlTypeNames.NUMERIC),
    ],
    time_partitioning=bigquery.TimePartitioning(field="timestamp"),
    clustering_fields=["origin", "destination"],
)

job = client.load_table_from_uri(
    ["gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv"],
    table_id,
    job_config=job_config,
)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

クラスタ化テーブルへのアクセスを制御する

テーブルとビューへのアクセスを構成するには、エンティティに次のレベルで IAM ロールを付与します。以下に、各レベルを許可されるリソースの範囲が大きい順に一覧で示します。

• Google Cloud リソース階層の上位レベル（プロジェクト、フォルダ、組織レベルなど）
• データセット レベル
• テーブル / ビューレベル

次の方法で、テーブル内のデータアクセスを制限することもできます。

• 列レベルのセキュリティ
• 列データのマスキング（プレビュー）
• 行レベルのセキュリティ

IAM で保護されているリソースを使用したアクセスは追加型です。たとえば、エンティティにプロジェクトなどの上位レベルのアクセス権がない場合は、データセット レベルでアクセス権を付与すると、データセット内のテーブルとビューにアクセスできます。同様に、エンティティに高レベルまたはデータセット レベルでのアクセス権がない場合は、テーブルまたはビューレベルでエンティティにアクセス権を付与できます。

プロジェクト、フォルダ、組織レベルなど、Google Cloud リソース階層の上位レベルで IAM ロールを付与すると、エンティティは幅広いリソースのセットにアクセスできるようになります。たとえば、プロジェクト レベルでエンティティにロールを付与すると、そのエンティティには、プロジェクトに含まれるすべてのデータセットに適用される権限が付与されます。

データセット レベルでロールを付与すると、そのエンティティが上位レベルでアクセスできない場合でも、そのデータセットのテーブルとビューで実行できるオペレーションが指定されます。データセット レベルのアクセス制御を構成する方法については、データセットへのアクセスの制御をご覧ください。

テーブルまたはビューレベルでロールを付与すると、エンティティに上位レベルのアクセスがない場合でも、特定のテーブルやビューに対してエンティティが実行できるオペレーションが特定されます。テーブルレベルのアクセス制御の構成については、テーブルおよびビューへのアクセスの制御をご覧ください。

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

IAM で保護されているリソースに「拒否」権限を設定することはできません。

ロールと権限の詳細については、IAM のドキュメント内のロールについてと BigQuery の IAM のロールと権限をご覧ください。

クラスタ化テーブルを使用する

クラスタ化テーブルに関する情報を取得する

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

• Cloud Console の使用
• bq コマンドライン ツールの bq show コマンドを使用する。
• tables.get API メソッドを呼び出す。
• INFORMATION_SCHEMA ビューのクエリを実行する。

必要な権限

テーブルに関する情報を取得するには、少なくとも 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. Google Cloud Console で、[リソース] ペインに移動します。データセット名をクリックして展開し、表示するテーブル名をクリックします。

2. [詳細] をクリックします。このページには、クラスタリング列を含むテーブルの詳細情報が表示されます。

   

bq

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

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

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

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

• PROJECT_ID: プロジェクト ID
• DATASET: データセットの名前。
• TABLE: テーブルの名前。

例:

次のコマンドを入力して、mydataset にある myclusteredtable に関するすべての情報を表示します。mydataset はデフォルトのプロジェクトにあります。

bq show --format=prettyjson mydataset.myclusteredtable

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

{
  "clustering": {
    "fields": [
      "customer_id"
    ]
  },
...
}

API

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

SQL

クラスタ化テーブルの場合、INFORMATION_SCHEMA.COLUMNS ビュー内の CLUSTERING_ORDINAL_POSITION 列をクエリして、テーブルのクラスタリング列に関する情報を取得できます。

-- Set up a table with clustering.
CREATE TABLE myDataset.data (column1 INT64, column2 INT64)
PARTITION BY _PARTITIONDATE
CLUSTER BY column1, column2;

-- This query returns 1 for column1 and 2 for column2.
SELECT column_name, clustering_ordinal_position
FROM myDataset.INFORMATION_SCHEMA.COLUMNS;

テーブルに関するその他のメタデータは INFORMATION_SCHEMA の TABLES、TABLE_OPTIONS、COLUMNS、COLUMN_FIELD_PATH の各ビューで取得できます。

データセット内のクラスタ化テーブルを一覧表示する

データセット内のクラスタ化テーブルは、次の方法で一覧表示できます。

• Cloud Console の使用
• bq コマンドライン ツールの bq ls コマンドを使用する。
• tables.list API メソッドを呼び出す。
• クライアント ライブラリを使用する。
• INFORMATION_SCHEMA.COLUMNS ビューで CLUSTERING_ORDINAL_POSITION 列をクエリする。

クラスタ化テーブルを一覧表示するために必要な権限と、それらを一覧表示する手順は、標準テーブルの場合と同じです。テーブルの一覧表示の詳細については、データセット内のテーブルの一覧表示をご覧ください。

クラスタリング仕様を変更する

テーブルのクラスタリング仕様の変更や削除を行うことができます。また、クラスタ化テーブル内のクラスタ化列のセットを変更することもできます。クラスタリング列セットを更新するこの方法は、継続的ストリーミング挿入を使用するテーブルに対して有効です。これらのテーブルは他の方法では簡単に入れ替えできません。

クラスタリング仕様は次の方法で変更できます。

• tables.update または tables.patch の API メソッドを呼び出します。

• --clustering_fields フラグを指定して bq コマンドライン ツールの bq update コマンドを呼び出します。

非クラスタ化テーブルがクラスタ化テーブルに変換、またはクラスタ化列セットが変更された場合、自動再クラスタリングはその時間以降にのみ使用できます。たとえば、tables.update を使用してクラスタ化テーブルに変換された 1 PB の非クラスタ化テーブルには、1 PB の非クラスタ化データが含まれたままです。自動再クラスタリングは、更新後にテーブルに保存された新しいデータにのみ適用されます。

テーブルのセキュリティ

BigQuery でテーブルへのアクセスを制御するには、テーブルのアクセス制御の概要をご覧ください。

次のステップ

• クラスタ化テーブルのクエリについては、クラスタ化テーブルのクエリをご覧ください。
• BigQuery でのパーティション分割テーブルのサポートの概要については、パーティション分割テーブルの概要をご覧ください。
• パーティション分割テーブルの作成方法については、パーティション分割テーブルの作成をご覧ください。
• INFORMATION_SCHEMA の概要については、BigQuery INFORMATION_SCHEMA の概要をご覧ください。