スキーマの指定

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

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

テーブルのスキーマは次の方法で指定できます。

手動でスキーマを指定する。
- Cloud Console を使用する。
- bq コマンドラインツールを使用してインライン化する。
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 では、スキーマで次のデータ型を使用できます。データ型は必須です。

名前	データ型	説明
整数	`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] ページを開きます。

[BigQuery] ページに移動
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。

注: デフォルトではプレビューの Cloud Console が表示されます。[PREVIEW 機能を非表示] をクリックして一般提供の Cloud Console に移動した場合は、ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。
詳細パネルで [テーブルを作成] をクリックします。
[テーブルの作成] ページの [ソース] セクションで、[空のテーブル] を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、適切なデータセットを選択します。
- [テーブル名] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。
- オプション 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#

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

GitHub で表示


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}");
    }
}

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

GitHub で表示


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

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

GitHub で表示

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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())
	}
	return nil
}

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

GitHub で表示

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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
	}
	return nil
}

Java

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

GitHub で表示

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCS {

  public static void runLoadJsonFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Json from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

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

GitHub で表示

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

Python

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

GitHub で表示

from google.cloud import bigquery

# 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"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    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,
    table_id,
    location="US",  # Must match the destination dataset location.
    job_config=job_config,
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

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

GitHub で表示

from google.cloud import bigquery

# 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"

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

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

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

スキーマを手動で指定したくない場合は、bq コマンドラインツールで使用する 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 配列は基本的なテーブルスキーマとなります。このスキーマには、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 へのデータの読み込みについて学習する。
テーブルの作成と使用について学習する。

スキーマの指定

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

列名

列の説明

標準 SQL データ型

モード

手動でのスキーマの指定

Console

bq

C#

Go

Java

Python

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

JSON スキーマ ファイルの作成

JSON スキーマ ファイルの使用

データを読み込むときにスキーマ ファイルを指定する

テーブルを作成するときにスキーマ ファイルを指定する

API でのスキーマの指定

次のステップ

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

JSON スキーマファイルの作成

JSON スキーマファイルの使用

データを読み込むときにスキーマファイルを指定する

テーブルを作成するときにスキーマファイルを指定する