スキーマの指定

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

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

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

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

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

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

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

列名

列名には、英字（a～z、A～Z）、数字（0～9）、アンダースコア（_）を使用できます。列名の先頭は英字またはアンダースコアにする必要があります。柔軟な列名を使用する場合、BigQuery では列名の先頭に数字を使用できます。BigQuery Storage Read API または BigQuery Storage Write API で柔軟な列名を使用するには、特別な処理が必要となるため、数字で列を開始する場合は注意してください。柔軟な列名のサポートについて詳しくは、柔軟な列名をご覧ください。

列名の最大文字数は 300 文字です。列名には、次のいずれの接頭辞も使用できません。

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

大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、Column1 という列は column1 という列と同じとみなされます。列の命名規則の詳細については、GoogleSQL リファレンスの列名をご覧ください。

テーブル名（test など）が列名（test など）のいずれかと同一である場合、SELECT 式は、他のすべてのテーブル列を含む STRUCT として test 列を解釈します。この競合を回避するには、次のいずれかの方法を使用します。

  • テーブルとその列に同じ名前を使用しない。

  • テーブルに別のエイリアスを割り当てる。たとえば、次のクエリでは、テーブル エイリアス t をテーブル project1.dataset.test に割り当てます。

    SELECT test FROM project1.dataset.test AS t;

  • 列を参照する際にテーブル名を含める。次に例を示します。

    SELECT test.test FROM project1.dataset.test;

柔軟な列名

英語以外の言語の文字へのアクセスの拡張、記号の追加など、列名の柔軟性が向上しました。

柔軟な列名では、次の文字がサポートされています。

  • Unicode 正規表現 \p{L} で表される任意の言語の任意の文字。
  • Unicode 正規表現 \p{N} で表される任意の言語の任意の数字。
  • Unicode 正規表現 \p{Pc} で表される任意の連結用句読記号文字（アンダースコアを含む）。
  • Unicode 正規表現 \p{Pd} で表されるハイフンまたはダッシュ。
  • Unicode 正規表現 \p{M} で表される、別の文字に付随して使用するための任意のマーク（アクセント記号、傘、囲み記号など）。
  • 次の特殊文字:
    • Unicode 正規表現 \u0026 で表されるアンパサンド（&）。
    • Unicode 正規表現 \u0025 で表されるパーセント記号（%）。
    • Unicode 正規表現 \u003D で表される等号（=）。
    • Unicode 正規表現 \u002B で表されるプラス記号（+）。
    • Unicode 正規表現 \u003A で表されるコロン（:）。
    • Unicode 正規表現 \u0027 で表されるアポストロフィ（'）。
    • Unicode 正規表現 \u003C で表される小なり記号（<）。
    • Unicode 正規表現 \u003E で表される大なり記号（>）。
    • Unicode 正規表現 \u0023 で表されるナンバー記号（#）。
    • Unicode 正規表現 \u007c で表される縦線（|）。
    • 空白文字。

柔軟な列名は、次の特殊文字をサポートしていません。

  • Unicode 正規表現 \u0021 で表される感嘆符（!）。
  • Unicode 正規表現 \u0022 で表される引用符（"）。
  • Unicode 正規表現 \u0024 で表されるドル記号（$）。
  • Unicode 正規表現 \u0028 で表される左かっこ（(）。
  • Unicode 正規表現 \u0029 で表される右かっこ（)）。
  • Unicode 正規表現 \u002A で表されるアスタリスク（*）。
  • Unicode 正規表現 \u002C で表されるカンマ（,）。
  • Unicode 正規表現 \u002E で表されるピリオド（.）。
  • Unicode 正規表現 \u002F で表されるスラッシュ（/）。
  • Unicode 正規表現 \u003B で表されるセミコロン（;）。
  • Unicode 正規表現 \u003F で表される疑問符（?）。
  • Unicode 正規表現 \u0040 で表されるアットマーク（@）。
  • Unicode 正規表現 \u005B で表される左角かっこ（[）。
  • Unicode 正規表現 \u005C で表されるバックスラッシュ（\）。
  • Unicode 正規表現 \u005D で表される、右角かっこ（]）。
  • Unicode 正規表現 \u005E で表される曲折アクセント（^）。
  • Unicode 正規表現 \u0060 で表される抑音アクセント（`）。
  • Unicode 正規表現 \u007B で表される左波かっこ（{）。
  • Unicode 正規表現 \u007D で表される右波かっこ（}）。
  • Unicode 正規表現 \u007E で表されるチルダ（~）。

追加のガイドラインについては、列名をご覧ください。

拡張された列の文字は、BigQuery Storage Read API と BigQuery Storage Write API の両方でサポートされています。BigQuery Storage Read API で Unicode 文字の拡張リストを使用するには、フラグを設定する必要があります。displayName 属性を使用すると列名を取得できます。次の例では、Python クライアントでフラグを設定する方法を示します。

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

BigQuery Storage Write API で Unicode 文字の拡張リストを使用するには、JsonStreamWriter ライター オブジェクトを使用している場合を除き、column_name 表記でスキーマを指定する必要があります。次の例では、スキーマの指定方法を示します。

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

この例では、item_name_column と item_description_column はプレースホルダ名で、プロトコル バッファの命名規則に準拠する必要があります。column_name アノテーションは、常にプレースホルダ名よりも優先されます。

制限事項

柔軟な列名は、外部テーブルではサポートされていません。

列の説明

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

デフォルト値

列のデフォルト値は、リテラルまたは次のいずれかの関数にする必要があります。

GoogleSQL のデータ型

GoogleSQL では、スキーマで次のデータ型を指定できます。データ型は必須です。

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

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

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

モード

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

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

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

丸めモード

列が NUMERIC 型または BIGNUMERIC 型の場合、rounding_mode 列オプションを設定できます。これにより、テーブルへの書き込み時のその列の値の丸め方を決定できます。rounding_mode オプションは、トップレベルの列または STRUCT フィールドで設定できます。次の丸めモードがサポートされています。

  • "ROUND_HALF_AWAY_FROM_ZERO": このモード（デフォルト）では、中間の値の場合はゼロから遠ざかるように丸めます。
  • "ROUND_HALF_EVEN": このモードでは、中間の値の場合は、最も近い偶数に丸めます。

NUMERIC 型または BIGNUMERIC 型ではない列の場合、rounding_mode オプションは設定できません。これらの型の詳細については、小数型をご覧ください。

次の例では、テーブルを作成し、列の丸めモードに基づいて丸められた値を挿入します。

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

テーブル mytable は次のようになります。

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

詳細については、TableFieldSchema の roundingMode をご覧ください。

スキーマを指定する

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

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

コンソール

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

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

    [BigQuery] に移動

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

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

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

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

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

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

      データセットの選択。

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

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

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

    • オプション 1: [フィールドを追加] を使用して、各フィールドの名前、型、モードを指定します。
    • オプション 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）型と RANGE 型を含めることはできません。また、列の説明を含めることはできません。さらに、列のモードを指定することもできません。すべてのモードはデフォルトの NULLABLE になります。説明、モード、RECORD 型、RANGE 型を含めるには、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#

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

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。


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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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;

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 のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

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

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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 になります）
  • 省略可: 列のフィールド（STRUCT 型の場合）
  • 省略可: 列の説明
  • 省略可: 列のポリシータグ。フィールド レベルのアクセス制御に使用される
  • 省略可: STRING 型または BYTES 型の列の値の最大長
  • 省略可: NUMERIC 型または BIGNUMERIC 型の列の精度
  • 省略可: NUMERIC 型または BIGNUMERIC 型の列のスケール
  • 省略可: STRING 型の列の照合順序
  • 省略可: 列のデフォルト値
  • 省略可: 列の丸めモード（列が NUMERIC 型または BIGNUMERIC 型の場合）

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

JSON スキーマ ファイルを作成するには、各列に TableFieldSchema を入力します。name フィールドと type フィールドは必須です。それ以外のフィールドはすべて省略可能です。

[
  {
    "name": string,
    "type": string,
    "mode": string,
    "fields": [
      {
        object (TableFieldSchema)
      }
    ],
    "description": string,
    "policyTags": {
      "names": [
        string
      ]
    },
    "maxLength": string,
    "precision": string,
    "scale": string,
    "collation": string,
    "defaultValueExpression": string,
    "roundingMode": string
  },
  {
    "name": string,
    "type": string,
    ...
  }
]

列が RANGE<T> 型の場合は、rangeElementType フィールドを使用して、T の説明を取得します。ここで、T は DATE、DATETIME、または TIMESTAMP のいずかにする必要があります。

[
  {
    "name": "duration",
    "type": "RANGE",
    "mode": "NULLABLE",
    "rangeElementType": {
      "type": "DATE"
    }
  }
]

JSON 配列は、角かっこ（[]）で囲んで示されます。各列のエントリは、カンマ（},）で区切る必要があります。

既存のテーブル スキーマをローカル ファイルに書き込むには、次の手順を行います。

bq

bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

次のように置き換えます。

  • project_id: プロジェクト ID。
  • dataset: プロジェクト内のデータセット。
  • table: 既存のテーブル スキーマの名前。
  • path_to_file: テーブル スキーマを書き込むローカル ファイルの場所。

Python

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

Python クライアント ライブラリを使用してテーブルからスキーマ JSON ファイルを書き込むには、Client.schema_to_json メソッドを呼び出します。 
from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change the table_id variable to the full name of the
# table you want to get schema from.
table_id = "your-project.your_dataset.your_table_name"

# TODO(dev): Change schema_path variable to the path
# of your schema file.
schema_path = "path/to/schema.json"
table = client.get_table(table_id)  # Make an API request.

# Write a schema file to schema_path with the schema_to_json method.
client.schema_to_json(table.schema, schema_path)

with open(schema_path, "r", encoding="utf-8") as schema_file:
    schema_contents = schema_file.read()

# View table properties
print(f"Got table '{table.project}.{table.dataset_id}.{table.table_id}'.")
print(f"Table schema: {schema_contents}")

出力ファイルは、独自の JSON スキーマ ファイルの開始点として使用できます。この方法を使用する場合は、ファイルにテーブルのスキーマを表す JSON 配列のみが含まれていることを確認してください。

たとえば、次の JSON 配列は基本的なテーブル スキーマとなります。このスキーマには、qtr（REQUIRED STRING）、rep（NULLABLE STRING）、sales（NULLABLE FLOAT）の 3 つの列があります。

[
  {
    "name": "qtr",
    "type": "STRING",
    "mode": "REQUIRED",
    "description": "quarter"
  },
  {
    "name": "rep",
    "type": "STRING",
    "mode": "NULLABLE",
    "description": "sales representative"
  },
  {
    "name": "sales",
    "type": "FLOAT",
    "mode": "NULLABLE",
    "defaultValueExpression": "2.55"
  }
]

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

JSON スキーマ ファイルを作成したら、bq コマンドライン ツールでそのファイルを指定できます。Google Cloud コンソールまたは API でスキーマ ファイルを使用することはできません。

スキーマ ファイルを指定します。

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

JSON スキーマ ファイルを指定するときは、ローカルの読み取り可能な場所に保存する必要があります。Cloud Storage または Google ドライブに保存されている JSON スキーマ ファイルは指定できません。

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

JSON スキーマ定義を使用してテーブルにデータを読み込む手順は、次のとおりです。

bq

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

Python

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

Python クライアント ライブラリを使用して JSON ファイルからテーブル スキーマを読み込むには、schema_from_json メソッドを呼び出します。 
from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change uri variable to the path of your data file.
uri = "gs://your-bucket/path/to/your-file.csv"
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

job_config = bigquery.LoadJobConfig(
    # To use the schema you loaded pass it into the
    # LoadJobConfig constructor.
    schema=schema,
    skip_leading_rows=1,
)

# Pass the job_config object to the load_table_from_file,
# load_table_from_json, or load_table_from_uri method
# to use the schema on a new table.
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

destination_table = client.get_table(table_id)  # Make an API request.
print(f"Loaded {destination_table.num_rows} rows to {table_id}.")

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

JSON スキーマ ファイルを使用して、既存のデータセットに空のテーブルを作成する手順は、次のとおりです。

bq

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

Python

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

Python クライアント ライブラリを使用して JSON ファイルからテーブル スキーマを読み込むには、schema_from_json メソッドを呼び出します。 
from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

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

API でのスキーマの指定

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

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

  • テーブルを作成するときにスキーマを指定するには、tables.insert メソッドを呼び出し、Table リソースの schema プロパティを構成します。

API でのスキーマの指定は、JSON スキーマ ファイルの作成プロセスと似ています。

テーブルのセキュリティ

BigQuery でテーブルへのアクセスを制御するには、テーブルのアクセス制御の概要をご覧ください。

次のステップ