テーブルの作成と使用
このドキュメントでは、BigQuery で標準(組み込み)テーブルを作成して使用する方法について説明します。他のタイプのテーブルを作成する方法については、以下をご覧ください。
テーブルを作成した後は、以下の操作を行うことができます。
- テーブルデータへのアクセスを制御する
- テーブルに関する情報を取得する
- データセット内のテーブルを一覧表示する
- テーブル メタデータの取得
テーブルのプロパティの更新、テーブルのコピー、テーブルの削除などのテーブルの管理の詳細については、テーブルの管理をご覧ください。
始める前に
BigQuery でテーブルを作成する前に、まず次のことを行います。
- BigQuery スタートガイドに従ってプロジェクトを設定します。
- BigQuery データセットを作成します。
- 必要に応じて、テーブルの概要でテーブルの制限事項、割り当て、料金を把握します。
テーブルの命名
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 では、次の方法でテーブルを作成できます。
- Google Cloud コンソールまたは bq コマンドライン ツールの
bq mk
コマンドを使用して手動で作成する。 - プログラムで
tables.insert
API メソッドを呼び出して作成する。 - クライアント ライブラリを使用する。
- クエリ結果から作成する。
- 外部データソースを参照するテーブルを定義する。
- データを読み込むときに作成する。
CREATE TABLE
データ定義言語(DDL)ステートメントを使用する。
必要な権限
テーブルを作成するには、次の 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 のロールと権限については、事前定義ロールと権限をご覧ください。
スキーマ定義を含む空のテーブルを作成する
次の方法でスキーマ定義を含む空のテーブルを作成できます。
- Google Cloud コンソールを使用してスキーマを入力する。
- bq コマンドライン ツールを使用してインラインでスキーマを指定する。
- bq コマンドライン ツールを使用して JSON スキーマ ファイルを送信する。
- API の
tables.insert
メソッドを呼び出すときに、テーブル リソースでスキーマを指定する。
テーブル スキーマの指定方法については、スキーマの指定をご覧ください。
テーブルを作成した後、そのテーブルへデータを入力するにはデータの読み込みまたはクエリ結果の書き込みを行います。
スキーマ定義を含む空のテーブルを作成するには:
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [空のテーブル] を選択します。
- [宛先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [スキーマ] セクションでスキーマ定義を入力します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
- オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
bq show --format=prettyjson dataset.table
- オプション 2: [型、モードを指定します。 フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの名前、
- オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
- 省略可: 顧客管理の暗号鍵を使用する場合は、[詳細オプション] セクションで [顧客管理の暗号鍵(CMEK)を使用] オプションを選択します。BigQuery はデフォルトで、Google が所有し Google が管理する鍵を使用して、保存されているお客様のコンテンツを暗号化します。
- [テーブルを作成] をクリックします。
SQL
次の例では、2023 年 1 月 1 日まで有効の、newtable
という名前のテーブルを作成します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
CREATE TABLE mydataset.newtable ( x INT64 OPTIONS (description = 'An optional INTEGER field'), y STRUCT < a ARRAY <STRING> OPTIONS (description = 'A repeated STRING field'), b BOOL > ) OPTIONS ( expiration_timestamp = TIMESTAMP '2023-01-01 00:00:00 UTC', description = 'a table that expires in 2023', labels = [('org_unit', 'development')]);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
-
In the Google Cloud console, 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.
--table
または-t
フラグを指定したbq mk
コマンドを使用します。テーブル スキーマ情報は、インラインで、または JSON スキーマ ファイルを使用して指定できます。パラメータの一覧については、bq mk --table
リファレンスをご覧ください。オプション パラメータには、次のようなものがあります。--expiration
--description
--time_partitioning_field
--time_partitioning_type
--range_partitioning
--clustering_fields
--destination_kms_key
--label
--time_partitioning_field
、--time_partitioning_type
、--range_partitioning
、--clustering_fields
、--destination_kms_key
については、ここでは説明しません。これらのオプション パラメータの詳細については、次のリンクをご覧ください。--time_partitioning_field
、--time_partitioning_type
、--range_partitioning
の詳細については、パーティション分割テーブルをご覧ください。--clustering_fields
の詳細については、クラスタ化テーブルをご覧ください。--destination_kms_key
の詳細については、顧客管理の暗号鍵をご覧ください。
デフォルト以外のプロジェクトでテーブルを作成する場合は、
project_id:dataset
の形式でプロジェクト ID をデータセットに追加します。既存のデータセット内にスキーマ定義を持つ空のテーブルを作成するには、以下を入力します。
bq mk \ --table \ --expiration=integer \ --description=description \ --label=key_1:value_1 \ --label=key_2:value_2 \ --add_tags=key_3:value_3[,...] \ project_id:dataset.table \ schema
次のように置き換えます。
- integer はテーブルのデフォルトの存続期間(秒)です。最小値は 3,600 秒(1 時間)です。現在の UTC 時間にこの整数値を足した値が、有効期限になります。テーブルの作成時に有効期限を設定した場合、データセットのデフォルトのテーブル有効期限設定は無視されます。
- description はテーブルの説明です。引用符で囲みます。
- key_1:value_1 と key_2:value_2 は、ラベルを指定する Key-Value ペアです。
- key_3:value_3 は、タグを指定する Key-Value ペアです。同じフラグで、各 Key-Value ペアをカンマで区切って複数のタグを追加できます。
- project_id はプロジェクト ID です。
- dataset は、プロジェクトのデータセットです。
- table は、作成するテーブルの名前です。
- schema は、field:data_type,field:data_type 形式のインライン スキーマ定義、またはローカルマシン上の JSON スキーマ ファイルへのパスです。
コマンドラインでスキーマを指定する場合、
RECORD
(STRUCT
)型や列の説明を含めることはできません。また、列モードも指定できません。すべてのモードはデフォルトのNULLABLE
になります。説明、モード、RECORD
型を含めるには、JSON スキーマ ファイルを指定します。例:
インライン スキーマ定義を使用してテーブルを作成するには、以下のコマンドを入力します。このコマンドは、デフォルト プロジェクトにある
mydataset
内にmytable
という名前のテーブルを作成します。テーブルの存続期間は 3,600 秒(1 時間)、説明はThis is my table
、ラベルはorganization:development
に設定されます。このコマンドでは--table
ではなく-t
ショートカットを使用しています。スキーマはインラインでqtr:STRING,sales:FLOAT,year:STRING
と指定されています。bq mk \ -t \ --expiration 3600 \ --description "This is my table" \ --label organization:development \ mydataset.mytable \ qtr:STRING,sales:FLOAT,year:STRING
次のコマンドを入力し、JSON スキーマ ファイルを使用してテーブルを作成します。このコマンドは、デフォルト プロジェクトにある
mydataset
内にmytable
という名前のテーブルを作成します。テーブルの存続期間は 3,600 秒(1 時間)、説明はThis is my table
、ラベルはorganization:development
に設定されます。スキーマ ファイルのパスは/tmp/myschema.json
です。bq mk \ --table \ --expiration 3600 \ --description "This is my table" \ --label organization:development \ mydataset.mytable \ /tmp/myschema.json
JSON スキーマ ファイルを使用してテーブルを作成するには、次のコマンドを入力します。このコマンドは、
myotherproject
プロジェクトにあるmydataset
内にmytable
という名前のテーブルを作成します。テーブルの存続期間は 3,600 秒(1 時間)、説明はThis is my table
、ラベルはorganization:development
に設定されます。スキーマ ファイルのパスは/tmp/myschema.json
です。bq mk \ --table \ --expiration 3600 \ --description "This is my table" \ --label organization:development \ myotherproject:mydataset.mytable \ /tmp/myschema.json
Terraform
google_bigquery_table
リソースを使用します。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
テーブルを作成する
次の例では、mytable
という名前のテーブルが作成されます。
テーブルを作成してアクセス権を付与する
次の例では、mytable
という名前のテーブルを作成し、google_bigquery_table_iam_policy
リソースを使用してそのテーブルへのアクセス権を付与します。このステップは、テーブルが存在するデータセットへのアクセス権を持たないプリンシパルにテーブルへのアクセス権を付与する場合にのみ行います。
顧客管理の暗号鍵を使用してテーブルを作成する
次の例では、mytable
という名前のテーブルを作成します。また、google_kms_crypto_key
と google_kms_key_ring
リソースを使用し、テーブルに Cloud Key Management Service の鍵を指定します。この例を実行する前に、Cloud Key Management Service API を有効にする必要があります。
Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。
Cloud Shell を準備する
- Cloud Shell を起動します。
-
Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。
このコマンドは、プロジェクトごとに 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!」というメッセージが表示されるまで待ちます。
- Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。
API
定義済みのテーブル リソースを使用して tables.insert
メソッドを呼び出します。
C#
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある C# の設定手順を完了してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
PHP
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある PHP の設定手順を完了してください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Ruby
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Ruby の設定手順を完了してください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
スキーマ定義を含まない空のテーブルを作成する
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
クエリ結果からテーブルを作成する
クエリ結果からテーブルを作成するには、結果を宛先テーブルに書き込みます。
コンソール
Google Cloud コンソールで [BigQuery] ページを開きます。
[エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。
有効な SQL クエリを入力します。
[展開] をクリックして、[クエリ オプション] を選択します。
[クエリ結果の宛先テーブルを設定する] オプションを選択します。
[送信先] セクションで、テーブルを作成するデータセットを選択し、テーブル ID を選択します。
[宛先テーブルの書き込み設定] セクションで、次のいずれかを選択します。
- [空の場合に書き込む] - テーブルが空の場合にのみ、クエリ結果をテーブルに書き込みます。
- [テーブルに追加する] - クエリ結果を既存のテーブルに追加します。
- [テーブルを上書きする] - 既存のテーブルにクエリ結果を同じ名前で上書きします。
省略可: [データのロケーション] で、ロケーションを選択します。
クエリの設定を更新するには、[保存] をクリックします。
[実行] をクリックします。これにより、指定したテーブルにクエリ結果を書き込むクエリジョブが作成されます。
宛先テーブルを指定せずにクエリを実行した場合は、エディタの下にある [結果を保存する] ボタンをクリックすると、キャッシュに保存された結果テーブルを永続テーブルにコピーできます。
SQL
次の例では、CREATE TABLE
ステートメントを使用して、一般公開 bikeshare_trips
テーブルのデータから trips
テーブルを作成します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
CREATE TABLE mydataset.trips AS ( SELECT bike_id, start_time, duration_minutes FROM bigquery-public-data.austin_bikeshare.bikeshare_trips );
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
詳細については、既存のテーブルから新しいテーブルを作成するをご覧ください。
bq
-
In the Google Cloud console, 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.
クエリ結果に基づいて永続テーブルを作成するには、
bq query
コマンドを入力して、--destination_table
フラグを指定します。GoogleSQL 構文を使用するには、use_legacy_sql=false
フラグを指定します。デフォルト プロジェクト以外のプロジェクトにあるテーブルにクエリ結果を書き込むには、project_id:dataset
の形式でプロジェクト ID をデータセット名に追加します。省略可:
--location
フラグを指定して、その値を使用するロケーションに設定します。既存の宛先テーブルに対する書き込み処理を制御するには、次のオプション フラグのいずれかを指定します。
--append_table
: 宛先テーブルが存在する場合、クエリ結果がそのテーブルに追加されます。--replace
: 宛先テーブルが存在する場合、そのテーブルはクエリ結果で上書きされます。bq --location=location query \ --destination_table project_id:dataset.table \ --use_legacy_sql=false 'query'
次のように置き換えます。
location
は、クエリの処理に使用するロケーションの名前です。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。ロケーションのデフォルト値は、.bigqueryrc
ファイルを使用して設定できます。project_id
はプロジェクト ID です。dataset
は、クエリ結果を書き込むテーブルを含むデータセットの名前です。table
は、クエリ結果を書き込むテーブルの名前です。query
は、GoogleSQL 構文のクエリです。書き込み処理フラグが指定されていない場合は、デフォルトの動作として、テーブルが空の場合にのみ結果が書き込まれます。テーブルが存在していて空でない場合は、「BigQuery error in query operation: Error processing job
project_id:bqjob_123abc456789_00000e1234f_1': Already Exists: Table project_id:dataset.table
」というエラーが返されます。例:
次のコマンドを入力すると、
mydataset
内のmytable
という宛先テーブルにクエリ結果が書き込まれます。このデータセットはデフォルト プロジェクトにあります。コマンドに書き込み処理フラグは指定されていないため、宛先テーブルは新規または空である必要があります。それ以外の場合は、Already exists
エラーが返されます。このクエリは、USA Name Data 一般公開データセットからデータを取得します。bq query \ --destination_table mydataset.mytable \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
クエリ結果を使用して
mydataset
内のmytable
という名前の宛先テーブルを上書きするには、次のコマンドを入力します。このデータセットはデフォルト プロジェクトにあります。このコマンドには--replace
フラグが指定されているため、宛先テーブルが上書きされます。bq query \ --destination_table mydataset.mytable \ --replace \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
mydataset
内のmytable
という名前の宛先テーブルにクエリ結果を追加するには、次のコマンドを入力します。このデータセットはデフォルト プロジェクトではなくmy-other-project
にあります。このコマンドには--append_table
フラグが指定されているため、クエリ結果が宛先テーブルに追加されます。bq query \ --append_table \ --use_legacy_sql=false \ --destination_table my-other-project:mydataset.mytable \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
上記のそれぞれの例では、次のような出力が生成されます。読みやすくするために、出力の一部のみを示します。
Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE +---------+--------+ | name | number | +---------+--------+ | Robert | 10021 | | John | 9636 | | Robert | 9297 | | ... | +---------+--------+