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

は、

ベータ版 です。

これは、BigQuery でのテーブル クラスタリングのサポート のベータ版リリースです。 この機能は下位互換性のない方法で変更される可能性があり、と は、SLA または非推奨ポリシーの対象ではありません。

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

制限事項

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

• 現在、クラスタリングは分割テーブルに対してのみサポートされています。
• クラスタ化テーブルのクエリと、クラスタ化テーブルに対するクエリ結果の書き込みでは、標準 SQL のみがサポートされています。
• テーブルの作成時にはクラスタリング列のみを指定できます。
• クラスタ化テーブルを作成した後、クラスタリング列を変更することはできません。
• クラスタリング列はトップレベルの非反復型の列である必要があります。また、INT64、STRING、DATE、TIMESTAMP、BOOL、NUMERIC のいずれかの型である必要があります。データ型の詳細については、標準 SQL データ型をご覧ください。
• 最大 4 つのクラスタリング列を指定できます。

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

現在、クラスタ化できるのは分割テーブルのみです。これには、取り込み時間分割テーブルと分割テーブル（TIMESTAMP 列や DATE 列によって分割されたテーブル）の両方が含まれます。

BigQuery では次のようにしてクラスタ化テーブルを作成できます。

• クエリ結果から作成
  • DDL の CREATE TABLE AS SELECT ステートメントを使用
  • クラスタ化テーブルを作成するクエリを実行
• DDL の CREATE TABLE ステートメントを使用、CLUSTER BY 句に clustering_column_list を指定
• コマンドライン ツールの bq mk コマンドを使用して手動で作成
• プログラムで tables.insert API メソッドを呼び出して作成
• データを読み込むときに作成

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

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

必要な権限

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

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

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

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

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

BigQuery でテーブルを作成するときにクラスタリング列を指定します。テーブルを作成した後、クラスタリング列を変更することはできません。現時点では、クラスタリング列を指定できるのは分割テーブルのみです。

クラスタリング列はトップレベルの非反復型の列である必要があります。また、INTEGER、STRING、DATE、TIMESTAMP、BOOLEAN、NUMERIC のいずれかの単純な型である必要があります。

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

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

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

従来の UI

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

   従来の BigQuery ウェブ UI に移動

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

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

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

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

5. [Schema] セクションに、スキーマ定義を手動で入力します。

   • スキーマ情報は次の方法で手動で入力できます。

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

       注: 既存のテーブルのスキーマを JSON 形式で表示するには、コマンド bq show --schema --format=prettyjson [PROJECT_ID]:[DATASET].[TABLE] を入力します。

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

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

   • [Partitioning Type] で、[None] をクリックして [Day] を選択します。
   • [Partitioning Field] で、次のいずれかを選択します。
     • DATE 列または TIMESTAMP 列で分割されたテーブルを作成するには、timestamp を選択します。
     • 取り込み時間分割テーブルを作成するには、_PARTITIONTIME を選択します。
   • [Clustering columns] で、1 つから 4 つまでのフィールド名を入力します。

   • [Encryption Type] は Default オプションのままにします。このプロパティは、顧客管理の暗号鍵用です。デフォルトでは、BigQuery は保存されている顧客コンテンツを暗号化します。

     

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

注: BigQuery ウェブ UI を使用して空のクラスタ化テーブルを作成する場合は、ラベル、説明、テーブルの有効期限、パーティションの有効期限は追加できません。これらのオプションのプロパティは、CLI または API を使用してテーブルを作成する際に追加できます。

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

コマンドライン

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

• --table（または -t ショートカット）。
• --schema: テーブルのスキーマ定義をインラインで、または JSON スキーマ ファイルを使用して指定できます。
• --time_partitioning_type（取り込み時間分割テーブルの場合）、または --time_partitioning_field（分割テーブルの場合）。現時点では、--time_partitioning_type でサポートされている値は DAY のみです。
• --clustering_fields: 最大 4 つのクラスタリング列を指定します。

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

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

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

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

bq mk --table --expiration [INTEGER1] --schema [SCHEMA] --time_partitioning_type=DAY --time_partitioning_field [COLUMN] --clustering_fields [COLUMNS] --time_partitioning_expiration [INTEGER2] --description "[DESCRIPTION]" --label [KEY:VALUE, KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE]

ここで

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

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

例:

デフォルト プロジェクトの mydataset 内に myclusteredtable という名前のクラスタ化テーブルを作成するには、次のコマンドを入力します。テーブルは（TIMESTAMP 列で分割された）分割テーブルです。パーティションの有効期限は 86,400 秒（1 日）に設定され、テーブルの有効期限は 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' --time_partitioning_field timestamp --clustering_fields customer_id --time_partitioning_expiration 86400  --description "This is my clustered table" --label org:dev mydataset.myclusteredtable

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

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

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

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

API

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

Go

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

GitHub で表示 フィードバック

// 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: "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
}

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

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

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

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

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

従来の UI

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

CLI

bq query コマンドを入力し、次のフラグを指定します。

• 標準 SQL 構文を使用するには、use_legacy_sql=false フラグを指定します。
• --location フラグを指定し、その値を該当するロケーションに設定します。

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

    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 --location=US 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

読み込みジョブを介してテーブルを作成するときにクラスタリング構成を定義するには、configuration.load.clustering メッセージを使用して configuration.load.clustering.Fields プロパティに最大 4 つのクラスタリング列を優先順位の高い順に指定します。

Go

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

GitHub で表示 フィードバック

// 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")
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())
}

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

クラスタ化テーブルまたはパーティションにアクセス制御を直接割り当てることはできません。データセット レベルまたはプロジェクト レベルでアクセス制御を構成することにより、テーブル アクセスを制御できます。

データセット レベルのアクセス制御では、特定のデータセット内のテーブルに対してユーザー、グループ、サービス アカウントが実行できるオペレーションを指定します。データセット レベルの権限のみを割り当てる場合は、プロジェクトへのアクセス権を与える基本の役割または事前定義されたプロジェクト レベルの役割（例: bigquery.user）も割り当てる必要があります。

個々のデータセットへのアクセス権を付与する代わりに、事前定義されたプロジェクト レベルの IAM 役割を割り当てると、プロジェクトに含まれるすべてのデータセットのすべてのテーブルデータへのアクセス権を付与できます。

また、IAM カスタム役割を作成することもできます。カスタム役割を作成する場合、付与する権限は、ユーザー、グループ、サービス アカウントにどのテーブル オペレーションを許可するかによって異なります。

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

• IAM ドキュメントの役割について
• BigQuery のアクセス制御
• データセットへのアクセスの制御

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

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

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

• GCP Console または従来の BigQuery ウェブ UI の使用
• bq show CLI コマンドの使用
• tables.get API メソッドの呼び出し
• INFORMATION_SCHEMA ビューへのクエリ（ベータ版）

必要な権限

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

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

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

クラスタ化テーブルの情報の取得

クラスタ化テーブルに関する情報を表示するには:

従来の UI

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

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

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

   

コマンドライン

すべてのテーブル情報を表示するには、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 メソッドを呼び出し、必要な関連パラメータを指定します。

INFORMATION_SCHEMA を使用したクラスタ化テーブル情報の取得（ベータ版）

INFORMATION_SCHEMA は、データセット、テーブル、ビューに関するメタデータへのアクセスを提供する一連のビューです。

INFORMATION_SCHEMA.TABLES および INFORMATION_SCHEMA.TABLE_OPTIONS ビューにクエリを実行し、プロジェクト内のテーブルとビューに関するメタデータを取得できます。INFORMATION_SCHEMA.COLUMNS および INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューにクエリを実行し、テーブル内の列（フィールド）に関するメタデータを取得することもできます。

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

TABLES ビュー

INFORMATION_SCHEMA.TABLES ビューにクエリを実行すると、クエリ結果として、データセット内のテーブルまたはビューごとに 1 行が表示されます。

INFORMATION_SCHEMA.TABLES ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルまたはビューの格納先であるデータセットへのアクセス権が必要です。

INFORMATION_SCHEMA.TABLES ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトの名前
TABLE_SCHEMA	STRING	テーブルまたはビューを含むデータセットの名前（datasetId）
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId）
TABLE_TYPE	STRING	次のテーブルタイプ: BASE TABLE: BigQuery のテーブル VIEW: BigQuery のビュー EXTERNAL: 外部データソースを参照するテーブル
IS_INSERTABLE_INTO	STRING	YES または NO（テーブルが DML INSERT ステートメントをサポートしているかどうかによる）
IS_TYPED	STRING	値は常に NO
CREATION_TIME	TIMESTAMP	テーブルの作成時間

例

例 1:

次の例では、将来用に予約されている is_typed を除き、すべての列を INFORMATION_SCHEMA.TABLES ビューから取得します。デフォルト プロジェクト（myproject）にある mydataset のすべてのテーブルに対するメタデータが返されます。

mydataset には、次のテーブルが含まれています。

• mytable1: 標準の BigQuery テーブル
• myview1: BigQuery ビュー

INFORMATION_SCHEMA.TABLES ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

デフォルト プロジェクト以外のプロジェクトにクエリを実行する場合は、次の形式でプロジェクト ID をデータセットに追加します。`[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] （例: `myproject`.mydataset.INFORMATION_SCHEMA.TABLES）

クエリを実行するには:

Console

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

   BigQuery ウェブ UI に移動

2. [クエリエディタ] ボックスに、次の標準 SQL クエリを入力します。 INFORMATION_SCHEMA では標準 SQL 構文が必要です。標準 SQL は GCP Console のデフォルトの構文です。

   SELECT
    * EXCEPT(is_typed)
   FROM
    mydataset.INFORMATION_SCHEMA.TABLES
   

   注: INFORMATION_SCHEMA ビュー名では大文字と小文字が区別されます。

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

コマンドライン

query コマンドラインで、--nouse_legacy_sql または --use_legacy_sql=false フラグを使用して標準 SQL 構文を指定します。INFORMATION_SCHEMA クエリには標準 SQL 構文が必要です。

クエリを実行するには、次のように入力します。

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES'

結果は次のようになります。

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 |
  | myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  

例 2:

次の例では、INFORMATION_SCHEMA.TABLES ビューからタイプが BASE TABLE のすべてのテーブルを取得します。is_typed 列は除外されます。デフォルト プロジェクト（myproject）にある mydataset のテーブルに対するメタデータが返されます。

INFORMATION_SCHEMA.TABLES ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

デフォルト プロジェクト以外のプロジェクトにクエリを実行する場合は、次の形式でプロジェクト ID をデータセットに追加します。`[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] （例: `myproject`.mydataset.INFORMATION_SCHEMA.TABLES）

クエリを実行するには:

Console

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

   BigQuery ウェブ UI に移動

2. [クエリエディタ] ボックスに、次の標準 SQL クエリを入力します。 INFORMATION_SCHEMA では標準 SQL 構文が必要です。標準 SQL は GCP Console のデフォルトの構文です。

   SELECT
    * EXCEPT(is_typed)
   FROM
    mydataset.INFORMATION_SCHEMA.TABLES
   WHERE
    table_type="BASE TABLE"
   

   注: INFORMATION_SCHEMA ビュー名では大文字と小文字が区別されます。

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

コマンドライン

query コマンドラインで、--nouse_legacy_sql または --use_legacy_sql=false フラグを使用して標準 SQL 構文を指定します。INFORMATION_SCHEMA クエリには標準 SQL 構文が必要です。

クエリを実行するには、次のように入力します。

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES
WHERE table_type="BASE TABLE"'

結果は次のようになります。

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | NO                 | 2018-10-31 22:40:05 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  

TABLE_OPTIONS ビュー

INFORMATION_SCHEMA.TABLE_OPTIONS ビューにクエリを実行すると、クエリ結果として、データセット内のテーブルまたはビューごとに 1 行が表示されます。

INFORMATION_SCHEMA.TABLE_OPTIONS ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルまたはビューの格納先であるデータセットへのアクセス権が必要です。

INFORMATION_SCHEMA.TABLE_OPTIONS ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトの名前
TABLE_SCHEMA	STRING	テーブルまたはビューを含むデータセットの名前（datasetId）
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId）
OPTION_NAME	STRING	options テーブル内の名前値の 1 つ
OPTION_TYPE	STRING	options テーブルのデータ型値の 1 つ
OPTION_VALUE	STRING	options テーブルの値オプションの 1 つ

options テーブル

OPTION_NAME	OPTION_TYPE	OPTION_VALUE
partition_expiration_days	FLOAT64	分割テーブルのすべてのパーティションのデフォルトの存続期間（日数）
expiration_timestamp	FLOAT64	テーブルのデフォルトの存続期間（日数）
kms_key_name	STRING	テーブルの暗号化に使用される Cloud KMS キーの名前
friendly_name	STRING	テーブルのわかりやすい名前
description	STRING	テーブルの説明
labels	ARRAY<STRUCT<STRING, STRING>>	テーブルのラベルを表す STRUCT の配列

例

例 1:

次の例では、INFORMATION_SCHEMATA.TABLE_OPTIONS ビューにクエリを実行して、デフォルト プロジェクト（myproject）にある mydataset の全テーブルのデフォルトのテーブル有効期限を取得します。

INFORMATION_SCHEMA.TABLE_OPTIONS ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

デフォルト プロジェクト以外のプロジェクトにクエリを実行する場合は、次の形式でプロジェクト ID をデータセットに追加します。`[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] （例: `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS）

クエリを実行するには:

Console

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

   BigQuery ウェブ UI に移動

2. [クエリエディタ] ボックスに、次の標準 SQL クエリを入力します。 INFORMATION_SCHEMA では標準 SQL 構文が必要です。標準 SQL は GCP Console のデフォルトの構文です。

   SELECT
    *
   FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
   WHERE
    option_name="expiration_timestamp"
   

   注: INFORMATION_SCHEMA ビュー名では大文字と小文字が区別されます。

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

コマンドライン

query コマンドラインで、--nouse_legacy_sql または --use_legacy_sql=false フラグを使用して標準 SQL 構文を指定します。INFORMATION_SCHEMA クエリには標準 SQL 構文が必要です。

クエリを実行するには、次のように入力します。

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="expiration_timestamp"'

結果は次のようになります。

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  

注: 有効期限のないテーブルはクエリ結果から除外されます。

例 2:

次の例では、mydataset 内のすべてのテーブルから、テストデータを含むテーブルを絞り込んでそのメタデータを取得します。クエリでは、説明に「test」が含まれているテーブルを見つけるために description オプションの値を使用します。mydataset はデフォルト プロジェクト（myproject）内にあります。

デフォルト プロジェクト以外のプロジェクトにクエリを実行する場合は、次の形式でプロジェクト ID をデータセットに追加します。`[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] （例: `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS）

クエリを実行するには:

Console

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

   BigQuery ウェブ UI に移動

2. [クエリエディタ] ボックスに、次の標準 SQL クエリを入力します。 INFORMATION_SCHEMA では標準 SQL 構文が必要です。標準 SQL は GCP Console のデフォルトの構文です。

   SELECT
    *
   FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
   WHERE
    option_name="description" AND option_value LIKE "%test%"
   

   注: INFORMATION_SCHEMA ビュー名では大文字と小文字が区別されます。

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

コマンドライン

query コマンドラインで、--nouse_legacy_sql または --use_legacy_sql=false フラグを使用して標準 SQL 構文を指定します。INFORMATION_SCHEMA クエリには標準 SQL 構文が必要です。

クエリを実行するには、次のように入力します。

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="description" AND option_value LIKE "%test%"'

結果は次のようになります。

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+
  

COLUMNS ビュー

INFORMATION_SCHEMA.COLUMNS ビューにクエリを実行すると、クエリ結果として、テーブル内の列（フィールド）ごとに 1 行が表示されます。

INFORMATION_SCHEMA.COLUMNS ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

INFORMATION_SCHEMA.COLUMNS ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトの名前
TABLE_SCHEMA	STRING	テーブルを含むデータセットの名前（datasetId）
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId）
COLUMN_NAME	STRING	列の名前
ORDINAL_POSITION	INT64	テーブル内の列の 1 から始まるオフセット。_PARTITIONTIME や _PARTITIONDATE などの疑似列の場合、値は NULL
IS_NULLABLE	STRING	YES または NO（列のモードが NULL 値を許可するかどうかによる）
DATA_TYPE	STRING	列の標準 SQL データ型
IS_GENERATED	STRING	値は常に NEVER
GENERATION_EXPRESSION	STRING	値は常に NULL
IS_STORED	STRING	値は常に NULL
IS_HIDDEN	STRING	YES または NO（列が _PARTITIONTIME や _PARTITIONDATE などの疑似列であるかどうかによる）
IS_UPDATABLE	STRING	値は常に NULL
IS_SYSTEM_DEFINED	STRING	YES または NO（列が _PARTITIONTIME や _PARTITIONDATE などの疑似列であるかどうかによる）
IS_PARTITIONING_COLUMN	STRING	YES または NO（列がパーティショニング列かどうかによる）
CLUSTERING_ORDINAL_POSITION	STRING	テーブルのクラスタリング列内にネストされている列の 1 から始まるオフセット。テーブルがクラスタ化テーブルでない場合、値は NULL

例

次の例では、census_bureau_usa データセット内の population_by_zip_2010 テーブルの INFORMATION_SCHEMA.COLUMNS ビューからメタデータを取得します。このデータセットは、BigQuery の一般公開データセット プログラムの一部です。

このテーブルは bigquery-public-data プロジェクトにあるため、次の形式でプロジェクト ID をデータセットに追加します。`[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] （例: `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES）

次の列は現時点で将来用に予約されているため、クエリ結果から除外されます。

• IS_GENERATED
• GENERATION_EXPRESSION
• IS_STORED
• IS_UPDATABLE

INFORMATION_SCHEMA.COLUMNS ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

クエリを実行するには:

Console

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

   BigQuery ウェブ UI に移動

2. [クエリエディタ] ボックスに、次の標準 SQL クエリを入力します。 INFORMATION_SCHEMA では標準 SQL 構文が必要です。標準 SQL は GCP Console のデフォルトの構文です。

   SELECT
    * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
   FROM
    `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
   WHERE
    table_name="population_by_zip_2010"
   

   注: INFORMATION_SCHEMA ビュー名では大文字と小文字が区別されます。

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

コマンドライン

query コマンドラインで、--nouse_legacy_sql または --use_legacy_sql=false フラグを使用して標準 SQL 構文を指定します。INFORMATION_SCHEMA クエリには標準 SQL 構文が必要です。

クエリを実行するには、次のように入力します。

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
FROM `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
WHERE table_name="population_by_zip_2010"'

結果は次のようになります。読みやすくするために、table_catalog と table_schema は結果から除外されています。

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
  

COLUMN_FIELD_PATHS ビュー

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューにクエリを実行すると、クエリ結果として、RECORD（または STRUCT）列内のネストされた列ごとに 1 行が表示されます。

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトの名前
TABLE_SCHEMA	STRING	テーブルを含むデータセットの名前（datasetId）
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId）
COLUMN_NAME	STRING	列の名前
FIELD_PATH	STRING	「RECORD」（または「STRUCT」）列内にネストされた列のパス
DATA_TYPE	STRING	列の標準 SQL データ型
DESCRIPTION	STRING	列の説明

例

次の例では、github_repos データセット内にある commits テーブルの INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューからメタデータを取得します。このデータセットは、BigQuery の一般公開データセット プログラムの一部です。

このテーブルは bigquery-public-data プロジェクトにあるため、次の形式でプロジェクト ID をデータセットに追加します。`[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW]（例: `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS）

commits テーブルには、次のネストされた列と、ネストされて繰り返された列があります。

• author: ネストされた RECORD 列
• committer: ネストされた RECORD 列
• trailer: ネストされて繰り返された RECORD 列
• difference: ネストされて繰り返された RECORD 列

クエリでは、author および difference 列に関するメタデータを取得します。

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューに対するクエリでは、データセット修飾子を指定する必要があります。また、クエリを発行するには、テーブルの格納先であるデータセットへのアクセス権が必要です。

クエリを実行するには:

Console

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

   BigQuery ウェブ UI に移動

2. [クエリエディタ] ボックスに、次の標準 SQL クエリを入力します。 INFORMATION_SCHEMA では標準 SQL 構文が必要です。標準 SQL は GCP Console のデフォルトの構文です。

   SELECT
    *
   FROM
    `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
   WHERE
    table_name="commits"
    AND column_name="author"
    OR column_name="difference"
   

   注: INFORMATION_SCHEMA ビュー名では大文字と小文字が区別されます。

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

コマンドライン

query コマンドラインで、--nouse_legacy_sql または --use_legacy_sql=false フラグを使用して標準 SQL 構文を指定します。INFORMATION_SCHEMA クエリには標準 SQL 構文が必要です。

クエリを実行するには、次のように入力します。

bq query --nouse_legacy_sql \
'SELECT * FROM `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE table_name="commits" AND column_name="author" OR column_name="difference"'

結果は次のようになります。読みやすくするために、table_catalog と table_schema は結果から除外されています。

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  

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

データセット内のクラスタ化テーブルを一覧表示するには、GCP Console、従来の BigQuery ウェブ UI、bq ls CLI コマンドのいずれかを使用するか、tables.list API メソッドを呼び出します。

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

開発中の機能

次の機能は開発中ですが、現時点のアルファ版では利用できません。

• ネイティブ（分割されていない）テーブルのクラスタリングのサポート。
• クラスタリング列でフィルタを使用する特定の種類のクエリのコストの削減。

次のステップ

• BigQuery でのクラスタ化テーブルのサポートの概要については、クラスタ化テーブルの概要をご覧ください。
• クラスタ化テーブルのクエリについては、クラスタ化テーブルのクエリをご覧ください。
• BigQuery での分割テーブルのサポートの概要については、分割テーブルの概要をご覧ください。
• 取り込み時間分割テーブルを作成して使用する方法については、取り込み時間分割テーブルの作成と使用をご覧ください。
• 分割テーブルの作成方法と使用方法については、分割テーブルの作成と使用をご覧ください。
• INFORMATION_SCHEMA の概要については、BigQuery INFORMATION_SCHEMA の概要をご覧ください。