スキーマの指定

BigQuery を使用すると、データをテーブルに読み込むときや空のテーブルを作成するときに、テーブルのスキーマを指定できます。あるいは、サポートされるデータ形式に関するスキーマ自動検出を使用することもできます。Avro、Parquet、ORC、Cloud Firestore エクスポート ファイル、Cloud Datastore エクスポート ファイルを読み込むときに、自己記述型のソースデータからスキーマが自動的に取得されます。

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

  • 手動でスキーマを指定する:
    • GCP Console の使用
    • 従来の BigQuery ウェブ UI
    • CLI を使用したインライン
  • JSON 形式のスキーマ ファイルを作成する。
  • jobs.insert メソッドを呼び出し、configuration.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 値は許可されません
反復 列に指定された型の値の配列が含まれます

モードの詳細については、API リファレンスの schema.fields.mode をご覧ください。

手動でのスキーマの指定

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

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

従来の 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 配列として追加する

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

コマンドライン

以下を使用して、スキーマを手動で [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 ファイルを使用してロケーションのデフォルト値を設定できます。
  • [FORMAT]NEWLINE_DELIMITED_JSON または CSV です。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] は、データの読み込み先となるテーブルを含むデータセットです。
  • [TABLE] は、データの読み込み先となるテーブル名です。
  • [PATH_TO_SOURCE] は、Cloud Storage またはローカルマシン上の CSV または JSON データファイルの場所です。
  • [SCHEMA] はインライン スキーマ定義です。

例:

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

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

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

bq --location=asia-northeast1 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#

このサンプルを試す前に、クライアント ライブラリを使用する BigQuery Quickstart の C# の設定手順に従ってください。 詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。

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

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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の設定手順に従ってください。 詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。

テーブルにデータを読み込むときにテーブルのスキーマを指定するには:
// 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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の設定手順に従ってください。 詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

テーブルにデータをロードする際にテーブルのスキーマを指定するには、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
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

schema = [
    bigquery.SchemaField('full_name', 'STRING', mode='REQUIRED'),
    bigquery.SchemaField('age', 'INTEGER', mode='REQUIRED'),
]
table_ref = dataset_ref.table('my_table')
table = bigquery.Table(table_ref, schema=schema)
table = client.create_table(table)  # API request

assert table.table_id == 'my_table'

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 ファイルを使用してロケーションのデフォルト値を設定できます。
  • [FORMAT]NEWLINE_DELIMITED_JSON または CSV です。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] は、データの読み込み先となるテーブルを含むデータセットです。
  • [TABLE] は、データの読み込み先となるテーブル名です。
  • [PATH_TO_DATA_FILE] は、ローカルマシンまたは Google Cloud Storage 上の CSV または JSON データファイルの場所です。
  • [SCHEMA_FILE] は、ローカルマシン上のスキーマ ファイルのパスです。

例:

次のコマンドを入力すると、myfile.csv というローカルの CSV ファイルから、デフォルト プロジェクトの mydataset.mytable というテーブルにデータを読み込みます。mydatasetUS マルチリージョン ロケーションで作成されています。スキーマは myschema.json で指定しています。

bq --location=US load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

次のコマンドを入力すると、myfile.csv というローカルの CSV ファイルから、デフォルト プロジェクトの mydataset.mytable というテーブルにデータを読み込みます。mydatasetasia-northeast1 リージョンで作成されています。スキーマは myschema.json で指定しています。

bq --location=asia-northeast1 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 メソッドを呼び出して configuration.load.schema プロパティを構成します。jobReference セクションの location プロパティでリージョンを指定します。
  • テーブルを作成するときにスキーマを指定するには、tables.insert メソッドを呼び出し、テーブル リソースで schema プロパティを使用してスキーマを構成します。

API の使用によるスキーマの指定は、JSON スキーマ ファイルの作成プロセスと同様です。

次のステップ

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

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

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