スキーマの指定

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

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

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

  • 手動でスキーマを指定する。
    • Cloud 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 では、スキーマで次のデータ型を使用できます。データ型は必須です。

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

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

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

モード

BigQuery では、列に対して次のモードがサポートされます。モードは省略可能です。モードが指定されていない場合、列はデフォルトの NULLABLE に設定されます。

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

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

手動でのスキーマの指定

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

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

Console

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

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

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

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

    テーブルの作成

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

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

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

      データセットの選択

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

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

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

    • オプション 1: [フィールドを追加] を使用して、各フィールドの [名前]、[]、[モード] を指定します。Cloud 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 でフィールドの説明を手動で追加できます。

        追加フィールドを使用してスキーマを追加する

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

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

    • [Create Table] をクリックします。

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

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

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

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

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

	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
}

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

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

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

スキーマを手動で指定したくない場合は、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 スキーマ ファイルを作成した後、コマンドラインでそれを指定できます。Cloud 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

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

次のコマンドを使用すると、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 のサポートページをご覧ください。