このドキュメントでは、BigQuery でクラスタ化テーブルを作成および使用する方法について説明します。BigQuery でのクラスタ化テーブルに対するサポートの概要については、クラスタ化テーブルの概要をご覧ください。
制限事項
BigQuery のクラスタ化テーブルには、次の制限があります。
- クラスタ化テーブルのクエリと、クラスタ化テーブルに対するクエリ結果の書き込みについては、標準 SQL のみがサポートされています。
クラスタリング列は最上位の繰り返しでない列であることが必要です。データ型は次のいずれかでなければなりません。
DATE
BOOL
GEOGRAPHY
INT64
NUMERIC
STRING
TIMESTAMP
データ型の詳細については、標準 SQL のデータ型をご覧ください。
最大 4 つのクラスタリング列を指定できます。
クラスタリングに
STRING
型の列を使用する場合、BigQuery は最初の 1,024 文字のみを使用してデータをクラスタリングします。列の値自体は 1,024 文字を超える場合があります。
クラスタ化テーブルの作成
クラスタ化テーブルは次の方法で作成できます。
- クエリ結果から作成する。
- DDL
CREATE TABLE AS SELECT
ステートメントを使用する。 - クラスタ化テーブルを作成するクエリを実行する。
- DDL
CLUSTER BY
句にclustering_column_list
を指定した DDLCREATE TABLE
ステートメントを使用する。bq
コマンドライン ツールのbq mk
コマンドを手動で使用する。- プログラムで
tables.insert
API メソッドを呼び出す。 - データを読み込むときに作成する。
- クライアント ライブラリを使用する。
テーブルの命名
BigQuery でテーブルを作成するとき、テーブル名はデータセットごとに一意である必要があります。テーブル名の要件は次のとおりです。
- 1,024 文字以内。
- カテゴリ L(文字)、M(マーク)、N(数字)、Pc(コネクタ、アンダースコアを含む)、Pd(ダッシュ)、Zs(スペース)の Unicode 文字を含む。詳しくは、一般カテゴリをご覧ください。
たとえば、table-01
、ग्राहक
、00_お客様
、étudiant
はすべて有効なテーブル名です。
必要な権限
テーブルを作成するには、少なくとも次の権限が付与されている必要があります。
bigquery.tables.create
(テーブルを作成する権限)bigquery.tables.updateData
(読み込みジョブ、クエリジョブ、コピージョブを使用してテーブルにデータを書き込む権限)bigquery.jobs.create
(テーブルにデータを書き込むクエリジョブ、読み込みジョブ、コピージョブを実行する権限)
テーブルに書き込むデータにアクセスするには、bigquery.tables.getData
などの追加の権限が必要になる場合があります。
次の事前定義済みの IAM ロールには bigquery.tables.create
権限と bigquery.tables.updateData
権限の両方が含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
次の事前定義済みの IAM ロールには bigquery.jobs.create
権限が含まれています。
bigquery.user
bigquery.jobUser
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権があれば、データセット内でテーブルを作成および更新できます。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
スキーマ定義を使用して空のクラスタ化テーブルを作成する
BigQuery でテーブルを作成するときにクラスタリング列を指定します。テーブルが作成されたら、クラスタリング列を変更できます。詳細については、クラスタリング仕様の変更をご覧ください。
クラスタリング列は最上位の非繰り返し列で、そのデータ型は次のシンプルなデータ型のいずれかでなければなりません。
DATE
BOOLEAN
GEOGRAPHY
INTEGER
NUMERIC
STRING
TIMESTAMP
最大 4 つのクラスタリング列を指定できます。複数の列を指定する場合、列の順序によってデータの並べ替え方法が決まります。たとえば、テーブルが列 a、b、c によってクラスタ化されている場合、データは同じ順序(列 a、列 b、列 c の順)で並べ替えられます。ベスト プラクティスとして、最も頻繁にフィルタリングまたは集計される列を最初に置いてください。
クラスタリング列の順序は、クエリのパフォーマンスと料金にも影響します。クラスタ化テーブルのクエリのベスト プラクティスについては、クラスタ化テーブルのクエリをご覧ください。
スキーマ定義を使用して空のクラスタ化テーブルを作成するには:
Console
Google Cloud Console で、[BigQuery] ページに移動します。
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。
詳細パネルで [テーブルを作成]
をクリックします。[テーブルの作成] ページの [ソース] に移動し、[テーブルの作成元] で [空のテーブル] を選択します。
[送信先] で次の操作を行います。
- [データセット名] で該当するデータセットを選択し、作成するテーブルの名前を [テーブル名] フィールドに入力します。
- [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[スキーマ] にスキーマ定義を入力します。
スキーマ情報を手動で入力します。
[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。
[フィールドを追加] を使用して、スキーマを手動で入力します。
(省略可)[パーティションとクラスタの設定] で [フィールドにより分割] を選択し、
DATE
列またはTIMESTAMP
列を選択します。スキーマにDATE
列またはTIMESTAMP
列が含まれていない場合、このオプションは使用できません。取り込み時間パーティション分割テーブルを作成するには、[取り込み時間により分割] を選択します。
(省略可)クエリを実行するパーティショニングを指定する
WHERE
句の使用を必須にするには、[パーティショニング フィルタ] で [パーティション フィルタを要求] チェックボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。[クラスタリング順序] で、1~4 個のフィールド名をカンマで区切って入力します。
(省略可)[詳細オプション] をクリックします。Cloud Key Management Service 鍵を使用する場合は、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存データを暗号化します。
[テーブルを作成] をクリックします。
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 \ --time_partitioning_type=DAY \ --time_partitioning_field PARTITION_COLUMN \ --clustering_fields CLUSTER_COLUMNS \ --time_partitioning_expiration INTEGER2 \ --description "DESCRIPTION" \ --label KEY:VALUE,KEY:VALUE \ PROJECT_ID:DATASET.TABLE
次のように置き換えます。
INTEGER1
: テーブルのデフォルトの存続期間(秒)です。最小値は 3,600 秒(1 時間)です。現在の UTC 時間にこの整数値を足した値が有効期限になります。時間パーティション分割テーブルの作成時に有効期限を設定した場合、データセットのデフォルトのテーブル有効期限の設定は無視されます。この値を設定すると、指定した時間が経過したときにテーブルとすべてのパーティションは削除されます。SCHEMA
:COLUMN:DATA_TYPE,COLUMN:DATA_TYPE
の形式のインライン スキーマ定義か、ローカルマシン上の JSON スキーマ ファイルのパスです。PARTITION_COLUMN
: パーティション分割テーブルの作成に使用されるTIMESTAMP
列またはDATE
列の名前です。パーティション分割テーブルを作成する場合は、--time_partitioning_type=DAY
フラグを指定する必要はありません。CLUSTER_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 日で期限切れになります。
スキーマは、/tmp/myschema.json
というローカル 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
メソッドを呼び出します。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
クエリ結果からクラスタ化テーブルを作成する
クエリ結果からクラスタ化テーブルを作成するには、次の 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 のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
クラスタ化テーブルへのアクセスの制御
テーブルとビューへのアクセスを構成するには、エンティティに次のレベルで IAM ロールを付与します。以下に、各レベルを許可されるリソースの範囲が大きい順に一覧で示します。
- Google Cloud リソース階層の上位レベル(プロジェクト、フォルダ、組織レベルなど)
- データセット レベル
- テーブル / ビューレベル
IAM で保護されているリソースを使用したアクセスは追加型です。たとえば、エンティティにプロジェクトなどの上位レベルのアクセス権がない場合は、データセット レベルでアクセス権を付与すると、データセット内のテーブルとビューにアクセスできます。同様に、エンティティに高レベルまたはデータセット レベルでのアクセス権がない場合は、テーブルまたはビューレベルでエンティティにアクセス権を付与できます。
プロジェクト、フォルダ、組織レベルなど、Google Cloud リソース階層の上位レベルで IAM ロールを付与すると、エンティティは幅広いリソースのセットにアクセスできるようになります。たとえば、プロジェクト レベルでエンティティにロールを付与すると、そのエンティティには、プロジェクトに含まれるすべてのデータセットに適用される権限が付与されます。
データセット レベルでロールを付与すると、そのエンティティが上位レベルでアクセスできない場合でも、そのデータセットのテーブルとビューで実行できるオペレーションが指定されます。データセット レベルのアクセス制御を構成する方法については、データセットへのアクセスの制御をご覧ください。
テーブルまたはビューレベルでロールを付与すると、エンティティに上位レベルのアクセスがない場合でも、特定のテーブルやビューに対してエンティティが実行できるオペレーションが特定されます。テーブルレベルのアクセス制御の構成については、テーブルおよびビューへのアクセスの制御をご覧ください。
また、IAM カスタムロールを作成することもできます。カスタムロールを作成する場合、エンティティに実行を許可する特定のオペレーションによって、付与する権限は異なります。
IAM で保護されているリソースに「拒否」権限を設定することはできません。
ロールと権限の詳細については、以下をご覧ください。
- IAM ドキュメントにおけるロールについて
- BigQuery の事前定義ロールと権限
- データセットへのアクセスの制御
- テーブルおよびビューへのアクセスの制御
- BigQuery の列レベルのセキュリティによるアクセスの制限
クラスタ化テーブルの使用
クラスタ化テーブルに関する情報の取得
テーブルに関する情報は、次の方法で取得できます。
- 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
Google Cloud Console で、[リソース] ペインに移動します。データセット名をクリックして展開し、表示するテーブル名をクリックします。
[詳細] をクリックします。このページには、クラスタリング列を含むテーブルの詳細情報が表示されます。
bq
すべてのテーブル情報を表示するには、bq show
コマンドを発行します。テーブルのスキーマ情報のみを表示するには、--schema
フラグを使用します。--format
フラグを使用して出力を制御できます。
デフォルト以外のプロジェクトにあるテーブルの情報を取得する場合は、project_id:dataset
の形式でプロジェクト ID をデータセットに追加します。
bq show \ --schema \ --format=prettyjson \ PROJECT_ID:DATASET.TABLE
次のように置き換えます。
PROJECT_ID
: プロジェクト IDDATASET
: データセットの名前。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
メソッドを呼び出すと、テーブル クラスタリングの仕様を変更または削除できます。クラスタ化テーブル内のクラスタ化列のセットは、別の列のセットに変更することもできます。クラスタリング列セットを更新するこの方法は最も、継続的ストリーミング挿入を使用するテーブルに利用できます。その他の方法では簡単に入れ替えできません。
非クラスタ化テーブルがクラスタ化テーブルに変換、またはクラスタ化列セットが変更された場合、自動再クラスタリングはその時間以降にのみ使用できます。たとえば、tables.update
を使用してクラスタ化テーブルに変換された 1 PB の非クラスタ化テーブルには、1 PB の非クラスタ化データが含まれたままです。自動再クラスタリングは、更新後にテーブルに保存された新しいデータにのみ適用されます。
次のステップ
- クラスタ化テーブルのクエリについては、クラスタ化テーブルのクエリをご覧ください。
- BigQuery でのパーティション分割テーブルのサポートの概要については、パーティション分割テーブルの概要をご覧ください。
- 取り込み時間パーティション分割テーブルの作成方法と使用方法については、取り込み時間パーティション分割テーブルの作成と使用をご覧ください。
- パーティション分割テーブルを作成して使用する方法については、パーティション分割テーブルの作成と使用をご覧ください。
INFORMATION_SCHEMA
の概要については、BigQueryINFORMATION_SCHEMA
の概要をご覧ください。