クラスタ化テーブルを作成する
BigQuery でクラスタ化されたテーブルを使用すると、クエリで処理されるデータ量を削減できます。
クラスタ化テーブルでは、テーブルデータは指定された列の値(クラスタ列)に基づいて整理されます。BigQuery は、クラスタ列でデータを並べ替え、類似した値を持つ行を同じ物理ブロックまたは近くの物理ブロックに保存します。クエリがクラスタ列でフィルタリングする場合、BigQuery は関連するブロックのみを効率的にスキャンし、フィルタに一致しないデータをスキップします。
詳しくは以下をご覧ください。
- BigQuery のクラスタ化テーブルの詳細については、クラスタ化テーブルの概要をご覧ください。
- クラスタ化テーブルの操作とアクセス制御については、クラスタ化テーブルを管理するをご覧ください。
始める前に
必要なロール
テーブルの作成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
-
データを読み込んでテーブルを作成する場合、またはクエリ結果をテーブルに保存する場合は、プロジェクトに対する BigQuery ジョブユーザー(
roles/bigquery.jobUser)。 -
テーブルを作成するデータセットに対する BigQuery データ編集者(
roles/bigquery.dataEditor)。
ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。
これらの事前定義ロールには、テーブルの作成に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
テーブルを作成するには、次の権限が必要です。
-
テーブルを作成するデータセットに対する
bigquery.tables.create。 -
クエリ結果をテーブルとして保存する場合は、クエリが参照するすべてのテーブルとビューに対する
bigquery.tables.getData。 -
データを読み込んでテーブルを作成する場合、またはクエリ結果をテーブルに保存する場合は、プロジェクトに対する
bigquery.jobs.create。 -
クエリ結果を使用してテーブルに追加または上書きする場合は、テーブルに対する
bigquery.tables.updateData。
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
テーブルの命名要件
BigQuery でテーブルを作成するとき、テーブル名はデータセットごとに一意である必要があります。テーブル名の要件は次のとおりです。
- UTF-8 バイトの文字を合計で 1,024 バイト以下にする。
- カテゴリ L(文字)、M(マーク)、N(数字)、Pc(コネクタ、アンダースコアを含む)、Pd(ダッシュ)、Zs(スペース)の Unicode 文字を含む。詳しくは、一般カテゴリをご覧ください。
table 01、ग्राहक、00_お客様、étudiant-01 などが有効なテーブル名です。
注意点:
- テーブル名では、デフォルトで大文字と小文字が区別されます。
mytableとMyTableは、大文字と小文字を区別しないデータセットでない限り、同じデータセット内に共存できます。 - 一部のテーブル名とテーブル名の接頭辞は予約済みです。テーブル名または接頭辞が予約されているというエラーが表示された場合は、別の名前を選択して、もう試してください。
ドット演算子(
.)を連続して含めると、重複する演算子が暗黙的に削除されます。たとえば、
project_name....dataset_name..table_nameはproject_name.dataset_name.table_nameのようになります。
クラスタ列の要件
BigQuery でテーブルを作成するときに、クラスタ化テーブルの作成に使用する列を指定できます。テーブルを作成した後、クラスタ化テーブルの作成に使用する列を変更できます。詳細については、クラスタリング仕様を変更するをご覧ください。
クラスタ列は最上位の非繰り返し列で、そのデータ型は次のデータ型のいずれかでなければなりません。
BIGNUMERICBOOLDATEDATETIMEGEOGRAPHYINT64NUMERICRANGESTRINGTIMESTAMP
最大 4 つのクラスタリング列を指定できます。複数の列を指定する場合、列の順序によってデータの並べ替え方法が決まります。たとえば、テーブルが列 a、b、c によってクラスタ化されている場合、データは同じ順序(列 a、列 b、列 c の順)で並べ替えられます。ベスト プラクティスとして、最も頻繁にフィルタリングまたは集計される列を最初に置いてください。
クラスタリング列の順序は、クエリのパフォーマンスと料金にも影響します。クラスタ化テーブルのクエリのベスト プラクティスについては、クラスタ化テーブルのクエリをご覧ください。
スキーマ定義を使用して空のクラスタ化テーブルを作成する
スキーマ定義を使用して空のクラスタ化テーブルを作成するには:
コンソール
Cloud de Confiance コンソールで、[BigQuery] ページに移動します。
- 左側のペインで、 [エクスプローラ] をクリックします。
- [エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] ペインで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [空のテーブル] を選択します。
- [宛先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [スキーマ] セクションでスキーマ定義を入力します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
- オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
bq show --format=prettyjson dataset.table
- オプション 2: [フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの名前、型、モードを指定します。
- オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
- [クラスタリング順序] で、1~4 個のフィールド名をカンマで区切って入力します。
- 省略可: [詳細オプション] セクションで、顧客管理の暗号鍵を使用する場合は、[顧客管理の暗号鍵(CMEK)を使用] オプションを選択します。デフォルトでは、BigQuery は Google Cloud-powered encryption keyを使用して保存されているお客様のコンテンツを暗号化します。
- [テーブルを作成] をクリックします。
SQL
CREATE TABLE DDL ステートメント コマンドと CLUSTER BY オプションを使用します。次の例では、myclusteredtable という名前のクラスタ化テーブルを mydataset に作成します。
Cloud de Confiance コンソールで、[BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
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
Terraform
google_bigquery_table リソースを使用します。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
次の例では、ID 列と Created 列でクラスタ化される mytable というテーブルを作成します。
Cloud de Confiance プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。
Cloud Shell を準備する
- Cloud Shell を起動します。
-
Terraform 構成を適用するデフォルトの Cloud de Confiance プロジェクトを設定します。
このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。
ディレクトリを準備する
Terraform 構成ファイルには独自のディレクトリ(ルート モジュールとも呼ばれます)が必要です。
-
Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は
.tfにする必要があります(例:main.tf)。このチュートリアルでは、このファイルをmain.tfとします。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。
新しく作成した
main.tfにサンプルコードをコピーします。必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。
- 環境に適用するサンプル パラメータを確認し、変更します。
- 変更を保存します。
-
Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
terraform init
最新バージョンの Google プロバイダを使用する場合は、
-upgradeオプションを使用します。terraform init -upgrade
変更を適用する
-
構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
terraform plan
必要に応じて構成を修正します。
-
次のコマンドを実行します。プロンプトで「
yes」と入力して、Terraform 構成を適用します。terraform apply
Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。
- Cloud de Confiance プロジェクトを開いて結果を表示します。 Cloud de Confiance コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。
API
clustering.fields プロパティと schema プロパティを指定する定義済みのテーブル リソースを使用して tables.insert メソッドを呼び出します。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。
クエリ結果からクラスタ化テーブルを作成する
クエリ結果からクラスタ化テーブルを作成するには、次の 2 つの方法があります。
- 結果を新しい宛先テーブルに書き込み、クラスタリング列を指定する。
- DDL
CREATE TABLE AS SELECTステートメントを使用する。この方法の詳細については、データ定義言語ステートメントの使用のページにあるクエリ結果からクラスタ化テーブルを作成するをご覧ください。
パーティション分割テーブル、パーティション分割されていないテーブルのいずれのクエリからでも、クラスタ化テーブルを作成できます。クエリ結果を使用して、既存のテーブルをクラスタ化テーブルに変更することはできません。
クエリ結果からクラスタ化テーブルを作成する場合、標準 SQL を使用する必要があります。クラスタ化テーブルをクエリする場合や、クエリ結果をクラスタ化テーブルに書き込む場合に、レガシー SQL はサポートされていません。
SQL
クエリ結果からクラスタ化テーブルを作成するには、CLUSTER BY オプションを指定して CREATE TABLE DDL ステートメントを使用します。次の例では、クラスタ化されていない既存のテーブルに対してクエリを実行し、customer_id でクラスタ化された新しいテーブルを作成します。
Cloud de Confiance コンソールで、[BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
CREATE TABLE mydataset.clustered_table ( customer_id STRING, transaction_amount NUMERIC ) CLUSTER BY customer_id AS ( SELECT * FROM mydataset.unclustered_table );
[実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
次のコマンドを入力して、クエリ結果から新しいクラスタ化テーブルを作成します。
bq --location=LOCATION query \ --use_legacy_sql=false 'QUERY'
次のように置き換えます。
LOCATION: ロケーションの名前。--locationフラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。QUERY: GoogleSQL 構文のクエリ。レガシー SQL を使用して、クラスタ化テーブルをクエリすることや、クエリ結果をクラスタ化テーブルに書き込むことはできません。クエリには、クラスタ化テーブルを作成するためのオプションを指定したCREATE TABLEDDL ステートメントを含めることができます。個々のコマンドライン フラグを指定するのではなく、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 へのデータの読み込みの概要をご覧ください。
読み込みジョブを定義するときにクラスタリングを定義するには:
SQL
LOAD DATA ステートメントを使用します。次の例では、AVRO データを読み込んで transaction_date フィールドで分割されたテーブルを作成し、customer_id フィールドでクラスタ化しています。また、パーティションが 3 日後に期限切れになるように構成します。
Cloud de Confiance コンソールで、[BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
LOAD DATA INTO mydataset.mytable PARTITION BY transaction_date CLUSTER BY customer_id OPTIONS ( partition_expiration_days = 3) FROM FILES( format = 'AVRO', uris = ['gs://bucket/path/file.avro']);
[実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
API
読み込みジョブを介してテーブルを作成する際にクラスタリング構成を定義するには、テーブルの Clustering プロパティをテーブルに入力します。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。
次のステップ
- クラスタ化テーブルの操作については、クラスタ化テーブルを管理するをご覧ください。
- クラスタ化テーブルのクエリについては、クラスタ化テーブルのクエリをご覧ください。
- BigQuery でのパーティション分割テーブルのサポートの概要については、パーティション分割テーブルの概要をご覧ください。
- パーティション分割テーブルの作成方法については、パーティション分割テーブルの作成をご覧ください。
INFORMATION_SCHEMAの概要については、BigQueryINFORMATION_SCHEMAの概要をご覧ください。