スキーマの指定

BigQuery を使用すると、データをテーブルに読み込むときや空のテーブルを作成するときに、テーブルのスキーマを指定できます。あるいは、サポートされるデータ形式に関するスキーマ自動検出を使用することもできます。

Avro、Parquet、ORC、Cloud Firestore エクスポート ファイル、Cloud Datastore エクスポート ファイルを読み込むときに、自己記述型のソースデータからスキーマが自動的に取得されます。

次のいずれかの方法で表のスキーマを指定できます。

  • 手動でスキーマを指定する:
    • GCP Console の使用
    • 従来の BigQuery ウェブ UI
    • CLI を使用したインライン
  • JSON 形式のスキーマ ファイルを作成する。
  • jobs.insert メソッドを呼び出し、load ジョブの構成で schema プロパティを構成する。
  • tables.insert メソッドを呼び出し、schema プロパティを使用してテーブル リソースでスキーマを構成する。

データを読み込んだ後、または空のテーブルを作成した後に、テーブルのスキーマ定義を変更できます。

スキーマのコンポーネント

テーブルのスキーマを指定するときに、各列の名前とデータ型を指定する必要があります。オプションとして、列の説明とモードを指定することもできます。

列名

列名には、英字(a-z、A-Z)、数字(0-9)、アンダースコア(_)のみを使用できます。先頭文字は英字またはアンダースコアにする必要があります。列名の最大長は 128 文字です。列名には、次のいずれの接頭辞も使用できません。

  • _TABLE_
  • _FILE_
  • _PARTITION

大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、Column1 という列は column1 という列と同じとみなされます。

列の説明

各列にオプションの説明を含めることができます。説明は最大長 1,024 文字の文字列です。

標準 SQL データ型

BigQuery の標準 SQL では、スキーマに次のデータ型を指定できます。データ型は必須です。

データ型 説明
整数 小数部分のない数値
浮動小数点数 小数部分のある近似数値
数値 小数部分のある正確な数値
ブール値 「true」または「false」(大文字と小文字は区別されない)
文字列 可変長文字(Unicode)データ
バイト 可変長バイナリデータ
日付 論理カレンダー日
日時 年、月、日、時、分、秒、およびサブ秒
時刻 特定の日付に関係のない時刻
タイムスタンプ マイクロ秒の精度の、時間単位で絶対的な時刻
構造体(レコード) データ型(必須)とフィールド名(オプション)が記載された順序付きフィールドのコンテナ
地域 地表上のポイントセット(測地線エッジを持つ WGS84 基準回転楕円体の点、線、ポリゴンのセット)

標準 SQL のデータ型の詳細については、標準 SQL のデータ型をご覧ください。

また、データを照会するときに配列型を宣言することもできます。詳細については、配列の操作をご覧ください。

モード

BigQuery では、列に対して次のモードがサポートされます。モードはオプションです。モードが指定されていない場合、列はデフォルトの NULLABLE に設定されます。

モード 説明
Nullable 列で NULL 値が許可されます(デフォルト)
必須 NULL 値は許可されません
反復 列に指定された型の値の配列が含まれます

モードの詳細については、TableFieldSchemamode をご覧ください。

手動でのスキーマの指定

データを読み込んだり空のテーブルを作成したりする際に、GCP Console、BigQuery ウェブ UI、またはコマンドライン ツールを使用して、テーブルのスキーマを手動で指定できます。CSV ファイルおよび JSON(改行で区切られた)ファイルを読み込む際に、手動によるスキーマの指定がサポートされます。Avro、Parquet、ORC、Cloud Firestore エクスポート データ、Cloud Datastore エクスポート データを読み込むときに、自己記述型のソースデータからスキーマが自動的に取得されます。

手動でテーブル スキーマを指定するには:

Console

GCP Console で、[フィールドを追加] オプションまたは [テキストとして編集] オプションを使用してスキーマを指定できます。

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

  2. ナビゲーション パネルの [リソース] セクションからデータセットを選択します。

  3. ウィンドウの右側にある [テーブルを作成] をクリックします。

    テーブルを作成

  4. [テーブルの作成] ページの [ソース] セクションで、[空のテーブル] を選択します。

    テーブルを作成(ソース)

  5. [テーブルを作成] ページの [送信先] セクションで、次の操作を行います。

    • [データセット名] で、適切なデータセットを選択します。

      データセットを選択

    • [テーブル名] フィールドに、作成するテーブルの名前を入力します。

    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

  6. [スキーマ] セクションにスキーマ定義を入力します。

    • オプション 1: [フィールドを追加] を使用して、各フィールドの [名前]、[]、[モード] を指定します。GCP Console では、[フィールドを追加] オプションを使用するときにフィールドの説明を追加できませんが、データを読み込んだ後、UI でフィールドの説明を手動で追加できます。
    • オプション 2: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。
  7. [テーブルを作成] をクリックします。

従来の UI

従来の BigQuery ウェブ UI では、[Add Field] オプションまたは [Edit as Text] オプションを使用してスキーマを指定できます。

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

    BigQuery ウェブ UI に移動

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

  3. [Create table] ページで:

    • [Source Data] で、データを読み込む場合は [Create from source] をクリックします。または [Create empty table] をクリックします。
    • [Destination Table] で、データセットを選択し、[Destination table name] フィールドにテーブル名を入力します。
    • [Schema] で、次のいずれかのオプションを選択して、スキーマを手動で指定します。

      • オプション 1: [Add Field] を使用して、各フィールドの [Name]、[Type]、[Mode] を指定します。BigQuery ウェブ UI では、[Add Field] オプションを使用するときにフィールドの説明を追加できませんが、データを読み込んだ後、UI でフィールドの説明を手動で追加できます。

        [Add Field] を使用してスキーマを追加する

      • オプション 2: [Edit as Text] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。

        スキーマを JSON 配列として追加する

    • [テーブルを作成] をクリックします。

CLI

以下を使用して、スキーマを手動で field:data_type,field:data_type の形式でインラインで入力します。

  • データを読み込む場合は load コマンドを使用します
  • 空のテーブルを作成する場合は mk コマンドを使用します

コマンドラインでスキーマを指定する場合、RECORDSTRUCT)型と列の説明を含めることはできません。また、列のモードも指定できません。デフォルトでは、モードはすべて 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 ファイルを使用してロケーションのデフォルト値を設定できます。
  • formatNEWLINE_DELIMITED_JSON または CSV です。
  • project_id:dataset.table_name はプロジェクト ID です。
  • project_id:dataset.table_name は、データの読み込み先となるテーブルを含むデータセットです。
  • project_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

次のコマンドを入力すると、myfile.csv というローカルの CSV ファイルから、デフォルト プロジェクトの mydataset.mytable というテーブルにデータを読み込みます。スキーマは手動でインラインで指定します。

bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING

BigQuery へのデータの読み込みについて、詳しくはデータの読み込みの概要をご覧ください。

空のテーブルを作成するときにインライン スキーマ定義を指定するには、--table フラグまたは -t フラグを指定して 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#

テーブルにデータを読み込むときにテーブルのスキーマを指定するには:


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

空のテーブルを作成するときにスキーマを指定するには:


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

テーブルにデータを読み込むときにテーブルのスキーマを指定するには:

// 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/us-states/us-states.json")
gcsRef.SourceFormat = bigquery.JSON
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
}
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
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())
}

空のテーブルを作成するときにスキーマを指定するには:

// 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: "full_name", Type: bigquery.StringFieldType},
	{Name: "age", Type: bigquery.IntegerFieldType},
}

metaData := &bigquery.TableMetadata{
	Schema:         sampleSchema,
	ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metaData); err != nil {
	return err
}

Python

テーブルにデータを読み込む前にテーブルのスキーマを指定するには、LoadJobConfig.schema プロパティを構成します。

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table("us_states"),
    location="US",  # Location must match that of the destination dataset.
    job_config=job_config,
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

空のテーブルを作成する際にスキーマを指定するには、Table.schema プロパティを構成します。

from google.cloud import bigquery

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create
# table_id = "your-project.your_dataset.your_table_name"

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

JSON スキーマ ファイルの指定

スキーマを手動で指定したくない場合は、CLI で使用する JSON スキーマ ファイルを作成できます。JSON スキーマ ファイルは、次を含む JSON 配列で構成されています。

  • (オプション)列の説明
  • 列の名前
  • 列のデータ型
  • (省略可)列のモード(指定しない場合、モードはデフォルトの NULLABLE になります)

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 配列は基本的なテーブル スキーマを表します。このスキーマには、qtrREQUIRED STRING)、repNULLABLE STRING)、および salesNULLABLE 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 スキーマ ファイルを作成した後、コマンドラインでそれを指定できます。GCP Console、従来の BigQuery ウェブ UI、API ではスキーマ ファイルを使用できません。

次のコマンドを使用して、スキーマ ファイルを手動で入力します。

  • データを読み込む場合は load コマンドを使用します
  • 空のテーブルを作成する場合は mk コマンドを使用します

JSON スキーマ ファイルを指定するときは、ローカルの読み取り可能な場所に保存する必要があります。Cloud Storage または Google ドライブに保存されている 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 ファイルを使用してロケーションのデフォルト値を設定できます。
  • formatNEWLINE_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

次のコマンドを入力すると、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 は、ローカルマシン上のスキーマ ファイルへのパスです。

たとえば、次のコマンドでは、デフォルト プロジェクト内の mydatasetmytable という名前のテーブルを作成します。スキーマは myschema.json で指定されます。

bq mk --table mydataset.mytable ./myschema.json

API でのスキーマの指定

API を使用してテーブル スキーマを指定するには:

  • データを読み込むときにスキーマを指定するには、jobs.insert メソッドを呼び出し、load ジョブの構成で schema プロパティを構成します。
  • テーブルを作成するときにスキーマを指定するには、tables.insert メソッドを呼び出し、テーブル リソースschema プロパティを構成します。

API を使用してスキーマを指定する操作は、JSON スキーマ ファイルの作成プロセスと似ています。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。