スキーマの指定

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

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

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

  • 手動でスキーマを指定する。
    • Google Cloud コンソールの使用
    • bq コマンドライン ツールを使用してインライン化する。
    • CREATE TABLE SQL ステートメントを使用する。
  • JSON 形式のスキーマ ファイルを作成する。
  • jobs.insert メソッドを呼び出し、load ジョブ構成の schema プロパティを設定する。
  • tables.insert メソッドを呼び出し、テーブル リソースで schema プロパティを使用してスキーマを構成する。

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

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

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

列名

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

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER

大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、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 をご覧ください。

手動でのスキーマの指定

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

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

コンソール

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

  1. Google Cloud コンソールで、BigQuery ページを開きます。

    BigQuery に移動

  2. [エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。

  3. アクション オプションを開いて、[開く] をクリックします。

  4. 詳細パネルで [テーブルを作成] をクリックします。

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

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

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

      データセットの選択。

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

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

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

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

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

SQL

CREATE TABLE ステートメントを使用します。 columnオプションを使用してスキーマを指定します。 次の例では、それぞれ整数型、文字列型、ブール値型の x、y、z 列からなる newtable という名前の新しいテーブルを作成します。

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    BigQuery に移動

  2. クエリエディタで次のステートメントを入力します。

    CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRING, z BOOL)
  OPTIONS(
    description = 'My example table');

  3. [ 実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリの実行をご覧ください。

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#

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


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

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

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
}

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

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

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

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

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

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 プロパティを構成します。

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 プロパティを構成します。

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 スキーマ ファイルの指定

必要に応じて、インライン スキーマ定義の代わりに 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 コマンドライン ツールで指定できます。Google Cloud コンソール または 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 でテーブルへのアクセスを制御するには、テーブルのアクセス制御の概要をご覧ください。

次のステップ