BigQuery では、データをテーブルに読み込むとき、および空のテーブルを作成するときにテーブルのスキーマを指定できます。あるいは、サポートされているデータ形式についてスキーマの自動検出を使用することもできます。
Avro、Parquet、ORC、Firestore エクスポート ファイル、Datastore エクスポート ファイルのいずれかを読み込むとき、スキーマは自己記述型のソースデータから自動的に取得されます。
テーブルのスキーマは次の方法で指定できます。
- 手動でスキーマを指定する。
- Cloud Console を使用する。
bq
コマンドライン ツールを使用してインライン化する。
- JSON 形式のスキーマ ファイルを作成する。
jobs.insert
メソッドを呼び出し、load
ジョブ構成のschema
プロパティを設定する。tables.insert
メソッドを呼び出し、テーブル リソースでschema
プロパティを使用してスキーマを構成する。
データを読み込んだ後、または空のテーブルを作成した後に、テーブルのスキーマ定義を変更できます。
スキーマのコンポーネント
テーブルのスキーマを指定するときに、各列の名前とデータ型を指定する必要があります。列の説明とモードを指定することもできます。
列名
列名には、英字(a~z、A~Z)、数字(0~9)、アンダースコア(_)のみを含める必要があり、英字またはアンダースコアで始まる必要があります。列名の最大長は 300 文字です。列名には、次のいずれの接頭辞も使用できません。
_TABLE_
_FILE_
_PARTITION
大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、Column1
という列は column1
という列と同じとみなされます。
列の説明
各列にオプションの説明を含めることができます。説明は 1,024 文字以内の文字列です。
標準 SQL データ型
BigQuery 標準 SQL では、スキーマで次のデータ型を使用できます。データ型は必須です。
名前 | データ型 | 説明 |
---|---|---|
整数 | INT64 |
小数部分のない数値 |
浮動小数点 | FLOAT64 |
小数部分のある近似数値 |
数値 | NUMERIC |
小数部分のある正確な数値 |
BigNumeric | BIGNUMERIC |
小数部分のある正確な数値 |
ブール値 | BOOL |
「true」または「false」(大文字と小文字は区別されない) |
文字列 | STRING |
可変長文字(Unicode)データ |
バイト | BYTES |
可変長バイナリデータ |
日付 | DATE |
論理カレンダー日 |
日時 | DATETIME |
年、月、日、時、分、秒、サブ秒 |
時間 | TIME |
特定の日付に依存しない時刻 |
タイムスタンプ | TIMESTAMP |
マイクロ秒精度の絶対的な時点 |
構造体(レコード) | STRUCT |
データ型(必須)とフィールド名(オプション)が記載された順序付きフィールドのコンテナ |
地域 | GEOGRAPHY |
地表上のポイントセット(測地線エッジを持つ WGS84 基準回転楕円体の点、線、ポリゴンのセット) |
標準 SQL のデータ型の詳細については、標準 SQL のデータ型をご覧ください。
また、データを照会するときに配列型を宣言することもできます。詳細については、配列の操作をご覧ください。
モード
BigQuery では、列に対して次のモードがサポートされます。モードは省略可能です。モードが指定されていない場合、列はデフォルトの NULLABLE
に設定されます。
モード | 説明 |
---|---|
Nullable | 列で NULL 値が許可されます(デフォルト)。 |
必須 | NULL 値は許可されません。 |
反復 | 列に指定された型の値の配列が含まれます |
モードの詳細については、TableFieldSchema
の mode
をご覧ください。
手動でのスキーマの指定
データを読み込むか空のテーブルを作成するときに、Cloud Console または bq
コマンドライン ツールを使用してテーブルのスキーマを手動で指定できます。スキーマの手動での指定は、CSV と JSON(改行で区切られた)ファイルを読み込む際にサポートされます。Avro、Parquet、ORC、Firestore エクスポート データ、Datastore エクスポート データを読み込むときに、自己記述型のソースデータからスキーマが自動的に取得されます。
手動でテーブル スキーマを指定するには:
Console
Cloud Console では、[フィールドを追加] オプションまたは [テキストとして編集] オプションを使用してスキーマを指定できます。
Cloud Console で、[BigQuery] ページを開きます。
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。
詳細パネルで [テーブルを作成] をクリックします。
[テーブルの作成] ページの [ソース] セクションで、[空のテーブル] を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、適切なデータセットを選択します。
[テーブル名] フィールドに、作成するテーブルの名前を入力します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。
- オプション 1: [フィールドを追加] を使用して、各フィールドの [名前]、[型]、[モード] を指定します。Cloud Console では、[フィールドを追加] オプションを使用するときにフィールドの説明を追加できませんが、データの読み込み後にフィールドの説明を手動で追加できます。
- オプション 2: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。
[テーブルを作成] をクリックします。
bq
次のいずれかのコマンドを使用して、スキーマを field:data_type,field:data_type
の形式でインラインで入力します。
- データを読み込む場合は、
bq load
コマンドを使用します。 - 空のテーブルを作成する場合は、
bq mk
コマンドを使用します。
コマンドラインでスキーマを指定する場合、RECORD
(STRUCT
)型と列の説明を含めることはできません。また、列のモードも指定できません。すべてのモードはデフォルトの NULLABLE
になります。説明、モード、RECORD
型を含めるには、JSON スキーマ ファイルを指定します。
インラインのスキーマ定義を使用してテーブルにデータを読み込むには、load
コマンドで --source_format
フラグを使用してデータ形式を指定します。デフォルト プロジェクト以外のプロジェクトのデータをテーブルに読み込む場合は、project_id:dataset.table_name
の形式でプロジェクト ID を含めます。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
bq --location=location load \ --source_format=format \ project_id:dataset.table_name \ path_to_source \ schema
次のように置き換えます。
location
: ロケーションの名前。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。format
:NEWLINE_DELIMITED_JSON
またはCSV
。project_id
: プロジェクト ID。dataset
: データの読み込み先のテーブルを含むデータセット。table_name
: データの読み込み先のテーブル名。path_to_source
: Cloud Storage またはローカルマシン上の CSV または JSON データファイルの場所。schema
: インライン スキーマの定義。
例:
次のコマンドを入力して、myfile.csv
という名前のローカルの CSV ファイルから、デフォルト プロジェクトの mydataset.mytable
にデータを読み込みます。スキーマは手動でインラインで指定します。
bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING
BigQuery へのデータの読み込みの詳細については、データの読み込みの概要をご覧ください。
空のテーブルを作成するときにインライン スキーマ定義を指定するには、--table
フラグまたは -t
フラグを指定して bq mk
コマンドを入力します。デフォルト以外のプロジェクトでテーブルを作成する場合は、project_id:dataset.table
の形式でプロジェクト ID をコマンドに追加します。
bq mk --table project_id:dataset.table schema
次のように置き換えます。
project_id
: プロジェクト ID。dataset
: プロジェクト内のデータセット。table
: 作成するテーブルの名前。schema
: インライン スキーマの定義。
たとえば、次のコマンドは、デフォルトのプロジェクトに mytable
という名前の空のテーブルを作成します。スキーマは手動でインラインで指定します。
bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING
空のテーブルの作成の詳細については、スキーマ定義を含む空のテーブルの作成をご覧ください。
C#
テーブルにデータを読み込むときにテーブルのスキーマを指定するには:
空のテーブルを作成するときにスキーマを指定するには:
Go
テーブルにデータを読み込むときにテーブルのスキーマを指定するには:
空のテーブルを作成するときにスキーマを指定するには:
Java
テーブルにデータを読み込むときにテーブルのスキーマを指定するには:
空のテーブルを作成するときにスキーマを指定するには:
Python
テーブルにデータを読み込む前にテーブルのスキーマを指定するには、LoadJobConfig.schema プロパティを構成します。
空のテーブルを作成する際にスキーマを指定するには、Table.schema プロパティを構成します。
JSON スキーマ ファイルの指定
必要に応じて、インライン スキーマ定義を使用する代わりに、JSON スキーマ ファイルを使用してスキーマを指定することもできます。JSON スキーマ ファイルは、以下を含む JSON 配列で構成されます。
JSON スキーマ ファイルの作成
JSON スキーマ ファイルを作成するには、適切なテキスト エディタを使用して次のように入力します。
[ { "description": "[DESCRIPTION]", "name": "[NAME]", "type": "[TYPE]", "mode": "[MODE]" }, { "description": "[DESCRIPTION]", "name": "[NAME]", "type": "[TYPE]", "mode": "[MODE]" } ]
JSON 配列は、角かっこ([]
)で囲んで示されます。各列のエントリは、カンマ(},
)で区切る必要があります。
次のコマンドを入力して、既存のテーブル スキーマをローカル ファイルに書き込むことができます。
bq show \ --schema \ --format=prettyjson \ project_id:dataset.table > path_to_file
出力ファイルは、独自の JSON スキーマ ファイルの開始点として使用できます。この方法を使用する場合は、ファイルにテーブルのスキーマを表す JSON 配列のみが含まれていることを確認してください。
たとえば、次の JSON 配列は基本的なテーブル スキーマとなります。このスキーマには、qtr
(REQUIRED
STRING
)、rep
(NULLABLE
STRING
)、sales
(NULLABLE
FLOAT
)の 3 つの列があります。
[ { "description": "quarter", "mode": "REQUIRED", "name": "qtr", "type": "STRING" }, { "description": "sales representative", "mode": "NULLABLE", "name": "rep", "type": "STRING" }, { "description": "total sales", "mode": "NULLABLE", "name": "sales", "type": "FLOAT" } ]
JSON スキーマ ファイルの使用
JSON スキーマ ファイルを作成したら、bq
コマンドライン ツールで指定できます。Cloud Console または API でスキーマ ファイルを使用することはできません。
スキーマ ファイルを手動で指定します。
- データを読み込む場合は、
bq load
コマンドを使用します。 - 空のテーブルを作成する場合は、
bq mk
コマンドを使用します。
JSON スキーマ ファイルを指定するときは、ローカルの読み取り可能な場所に保存する必要があります。Cloud Storage またはドライブに保存されている JSON スキーマ ファイルは指定できません。
データを読み込むときにスキーマ ファイルを指定する
次のコマンドでは、JSON ファイルのスキーマ定義を使用してデータをテーブルに読み込みます。
bq --location=location load \ --source_format=format \ project_id:dataset.table \ path_to_data_file \ path_to_schema_file
次のように置き換えます。
location
: ロケーションの名前。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。format
:NEWLINE_DELIMITED_JSON
またはCSV
。project_id
: プロジェクト ID。dataset
: データの読み込み先のテーブルを含むデータセット。table
: データの読み込み先のテーブル名。path_to_data_file
: Cloud Storage またはローカルマシン上の CSV または JSON データファイルの場所。path_to_schema_file
: ローカルマシン上のスキーマ ファイルのパス。
例:
次のコマンドを入力して、myfile.csv
という名前のローカルの CSV ファイルから、デフォルト プロジェクトの mydataset.mytable
にデータを読み込みます。スキーマは myschema.json
で指定します。
bq load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json
テーブルを作成するときにスキーマ ファイルを指定する
次のコマンドでは、JSON ファイルのスキーマ定義を使用して、既存のデータセットに空のテーブルを作成します。
bq mk --table project_id:dataset.table path_to_schema_file
次のように置き換えます。
project_id
: プロジェクト ID。dataset
: プロジェクト内のデータセット。table
: 作成するテーブルの名前。path_to_schema_file
: ローカルマシン上のスキーマ ファイルのパス。
たとえば、次のコマンドは、デフォルト プロジェクトの mydataset
に mytable
という名前のテーブルを作成します。スキーマは myschema.json
で指定します。
bq mk --table mydataset.mytable ./myschema.json
API でのスキーマの指定
API を使用してテーブル スキーマを指定するには:
データを読み込むときにスキーマを指定するには、
jobs.insert
メソッドを呼び出し、JobConfigurationLoad
リソースのschema
プロパティを構成します。テーブルを作成するときにスキーマを指定するには、
tables.insert
メソッドを呼び出し、Table
リソースのschema
プロパティを構成します。
API でのスキーマの指定は、JSON スキーマ ファイルの作成プロセスと似ています。
次のステップ
- スキーマ定義でネストされた列と繰り返し列を指定する方法を学習する。
- スキーマの自動検出について学習する。
- BigQuery へのデータの読み込みについて学習する。
- テーブルの作成と使用について学習する。