このページは Cloud Translation API によって翻訳されました。

テーブルスキーマの変更

このドキュメントでは、既存の BigQuery テーブルのスキーマ定義を変更する方法について説明します。

このドキュメントで説明するスキーマの変更は、SQL データ定義言語（DDL）ステートメントを使用して行えます。これらのステートメントには料金が発生しません。

このページで説明されているすべての方法でテーブルスキーマを変更できます。テーブルデータを Cloud Storage にエクスポートし、変更されたスキーマ定義を使用して新しいテーブルにデータを読み込みます。BigQuery の読み込みジョブと抽出ジョブは無料ですが、エクスポートしたデータを Cloud Storage に保存するには料金が発生します。以降のセクションでは、さまざまなスキーマの変更を行うその他の方法について説明します。

列の追加

次のいずれかの方法で、既存のテーブルのスキーマ定義に列を追加できます。

新しい空の列を追加します。
読み込みジョブまたはクエリジョブでテーブルを上書きします。
読み込みジョブまたはクエリジョブを使用してテーブルにデータを追加します。

追加する列は、BigQuery の列名の規則に準拠している必要があります。スキーマコンポーネントの作成の詳細については、スキーマの指定をご覧ください。

空の列を追加する

既存のテーブルスキーマに新しい列を追加する場合、その列は NULLABLE または REPEATED である必要があります。REQUIRED 列を既存のテーブルスキーマに追加することはできません。API または bq コマンドラインツールで既存のテーブルスキーマに REQUIRED 列を追加すると、エラーが発生します。ネストされた REQUIRED 列は、新しい RECORD フィールドの一部として作成します。REQUIRED 列を追加できるのは、データの読み込み中にテーブルを作成する場合、またはスキーマ定義を持つ空のテーブルを作成する場合だけです。

テーブルのスキーマ定義に空の列を追加するには:

コンソール

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

BigQuery に移動
左側のペインで、 [エクスプローラ] をクリックします。

左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。
[概要 > テーブル] をクリックし、テーブルを選択します。
詳細ペインで [スキーマ] タブをクリックします。
[スキーマを編集] をクリックします。このボタンを表示するには、スクロールが必要な場合があります。
[現在のスキーマ] ページの [新しいフィールド] で、[フィールドを追加] をクリックします。
- [名前] に列名を入力します。
- [タイプ] で、データ型を選択します。
- [モード] で、NULLABLE または REPEATED を選択します。
列の追加が完了したら、[保存] をクリックします。

SQL

ALTER TABLE ADD COLUMN DDL ステートメントを使用します。

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

[BigQuery] に移動
クエリエディタで次のステートメントを入力します。
```
ALTER TABLE mydataset.mytable
ADD COLUMN new_column STRING;
```
[実行] をクリックします。

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

bq

bq update コマンドを発行し、JSON スキーマファイルを指定します。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。

bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

PROJECT_ID: プロジェクト ID。
DATASET: 更新するテーブルを含むデータセットの名前。
TABLE: 更新するテーブルの名前。
SCHEMA: ローカルマシン上の JSON スキーマファイルへのパス

インラインスキーマを指定する場合は、列の説明、モード、RECORD（STRUCT）型を指定することはできません。すべての列モードはデフォルトで NULLABLE になります。そのため、ネストされた新しい列を RECORD に追加する場合は、JSON スキーマファイルを指定する必要があります。

インラインスキーマ定義を使用して列を追加しようとする場合は、新しい列を含めてスキーマ定義全体を指定する必要があります。インラインスキーマ定義を使用して列モードを指定することができないため、既存の REPEATED 列を NULLABLE に変更すると、BigQuery error in update operation: Provided Schema does not match Table PROJECT_ID:dataset.table. Field field has changed mode from REPEATED to NULLABLE. というエラーが発生します。

bq コマンドラインツールを使用して既存のテーブルに列を追加する場合に推奨される方法は、JSON スキーマファイルを指定することです。

JSON スキーマファイルを使用して、テーブルのスキーマに列を追加するには:

まず、--schema フラグを指定した bq show コマンドを発行して、既存のテーブルスキーマをファイルに書き込みます。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。
```
bq show \
--schema \
--format=prettyjson \
PROJECT_ID:DATASET.TABLE > SCHEMA
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET: 更新するテーブルを含むデータセットの名前。
- TABLE: 更新するテーブルの名前。
- SCHEMA: ローカルマシンに書き込まれるスキーマ定義ファイル。
たとえば、mydataset.mytable のスキーマ定義をファイルに書き込むには、次のコマンドを入力します。mydataset.mytable はデフォルトプロジェクトにあります。
```
   bq show \
   --schema \
   --format=prettyjson \
   mydataset.mytable > /tmp/myschema.json
```

スキーマファイルをテキストエディタで開きます。スキーマは次のようになっています。

[
  {
    "mode": "REQUIRED",
    "name": "column1",
    "type": "STRING"
  },
  {
    "mode": "REQUIRED",
    "name": "column2",
    "type": "FLOAT"
  },
  {
    "mode": "REPEATED",
    "name": "column3",
    "type": "STRING"
  }
]

スキーマ定義の末尾に新しい列を追加します。新しい列を配列内の別の場所に追加しようとすると、BigQuery error in update operation: Precondition Failed というエラーが返されます。

JSON ファイルを使用して、新しい列の説明、NULLABLE または REPEATED モード、RECORD 型を指定できます。たとえば、前の手順のスキーマ定義を使用すると、新しい JSON 配列は次のようになります。この例では、新しい NULLABLE 列が column4 という名前で追加されています。column4 に説明が含まれています。
```
  [
    {
      "mode": "REQUIRED",
      "name": "column1",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "column2",
      "type": "FLOAT"
    },
    {
      "mode": "REPEATED",
      "name": "column3",
      "type": "STRING"
    },
    {
      "description": "my new column",
      "mode": "NULLABLE",
      "name": "column4",
      "type": "STRING"
    }
  ]
  
```
JSON スキーマファイルの操作の詳細については、JSON スキーマファイルの指定をご覧ください。
スキーマファイルを更新したら、次のコマンドを発行してテーブルのスキーマを更新します。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。
```
bq update PROJECT_ID:DATASET.TABLE SCHEMA
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET: 更新するテーブルを含むデータセットの名前。
- TABLE: 更新するテーブルの名前。
- SCHEMA: ローカルマシンに書き込まれるスキーマ定義ファイル。
たとえば、次のコマンドを入力すると、デフォルトプロジェクトにある mydataset.mytable のスキーマ定義が更新されます。ローカルマシン上にあるスキーマファイルへのパスは /tmp/myschema.json です。
```
bq update mydataset.mytable /tmp/myschema.json
```

API

tables.patch メソッドを呼び出して、schema プロパティを使用して空の列をスキーマ定義に追加します。tables.update メソッドはテーブルリソース全体を置き換えるため、tables.patch メソッドの方が適切です。

Go

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

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

import (
	"context"
	"fmt"

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

// updateTableAddColumn demonstrates modifying the schema of a table to append an additional column.
func updateTableAddColumn(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()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	newSchema := append(meta.Schema,
		&bigquery.FieldSchema{Name: "phone", Type: bigquery.StringFieldType},
	)
	update := bigquery.TableMetadataToUpdate{
		Schema: newSchema,
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

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

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.FieldList;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.Table;
import java.util.ArrayList;
import java.util.List;

public class AddEmptyColumn {

  public static void runAddEmptyColumn() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableId = "MY_TABLE_NAME";
    String newColumnName = "NEW_COLUMN_NAME";
    addEmptyColumn(newColumnName, datasetName, tableId);
  }

  public static void addEmptyColumn(String newColumnName, String datasetName, String tableId) {
    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();

      Table table = bigquery.getTable(datasetName, tableId);
      Schema schema = table.getDefinition().getSchema();
      FieldList fields = schema.getFields();

      // Create the new field/column
      Field newField = Field.of(newColumnName, LegacySQLTypeName.STRING);

      // Create a new schema adding the current fields, plus the new one
      List<Field> fieldList = new ArrayList<Field>();
      fields.forEach(fieldList::add);
      fieldList.add(newField);
      Schema newSchema = Schema.of(fieldList);

      // Update the table with the new schema
      Table updatedTable =
          table.toBuilder().setDefinition(StandardTableDefinition.of(newSchema)).build();
      updatedTable.update();
      System.out.println("Empty column successfully added to table");
    } catch (BigQueryException e) {
      System.out.println("Empty column was not added. \n" + e.toString());
    }
  }
}

Node.js

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


// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function addEmptyColumn() {
  // Adds an empty column to the schema.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';
  const column = {name: 'size', type: 'STRING'};

  // Retrieve current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Update table schema
  const schema = metadata.schema;
  const new_schema = schema;
  new_schema.fields.push(column);
  metadata.schema = new_schema;

  const [result] = await table.setMetadata(metadata);
  console.log(result.schema.fields);
}

Python

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

新しい SchemaField オブジェクトを Table.schema のコピーに付加し、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 add an empty column.
# table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # Make an API request.

original_schema = table.schema
new_schema = original_schema[:]  # Creates a copy of the schema.
new_schema.append(bigquery.SchemaField("phone", "STRING"))

table.schema = new_schema
table = client.update_table(table, ["schema"])  # Make an API request.

if len(table.schema) == len(original_schema) + 1 == len(new_schema):
    print("A new column has been added.")
else:
    print("The column has not been added.")

ネストされた列を `RECORD` 列に追加する

新しい列をテーブルのスキーマに追加するだけでなく、ネストされた列を RECORD 列に追加することもできます。ネストされた列を追加する方法は、新しい列を追加する場合と非常によく似ています。

コンソール

新しくネストされたフィールドを既存の RECORD 列に追加することは、 Google Cloud コンソールでサポートされていません。

SQL

SQL DDL ステートメントを使用して新しくネストされたフィールドを既存の RECORD 列に追加できません。

bq

bq update コマンドを発行して、ネストされたフィールドを既存の RECORD 列のスキーマ定義に追加する JSON スキーマファイルを指定します。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。

bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

PROJECT_ID: プロジェクト ID。
DATASET: 更新するテーブルを含むデータセットの名前。
TABLE: 更新するテーブルの名前。
SCHEMA: ローカルマシン上の JSON スキーマファイルへのパス

JSON スキーマファイルを使用して、ネストされた列を RECORD に追加するには:

まず、--schema フラグを指定した bq show コマンドを発行して、既存のテーブルスキーマをファイルに書き込みます。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET.TABLE の形式でプロジェクト ID をデータセット名に追加します。
```
bq show \
--schema \
--format=prettyjson \
PROJECT_ID:DATASET.TABLE > SCHEMA
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET: 更新するテーブルを含むデータセットの名前。
- TABLE: 更新するテーブルの名前。
- SCHEMA: ローカルマシンに書き込まれるスキーマ定義ファイル。
たとえば、mydataset.mytable のスキーマ定義をファイルに書き込むには、次のコマンドを入力します。mydataset.mytable はデフォルトプロジェクトにあります。
```
bq show \
--schema \
--format=prettyjson \
mydataset.mytable > /tmp/myschema.json
```

スキーマファイルをテキストエディタで開きます。スキーマは次のようになっています。この例では、column3 はネストされた繰り返し列です。ネストされた列は nested1 と nested2 です。fields 配列には、column3 内にネストされたフィールドが入ります。

[
  {
    "mode": "REQUIRED",
    "name": "column1",
    "type": "STRING"
  },
  {
    "mode": "REQUIRED",
    "name": "column2",
    "type": "FLOAT"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "nested1",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "nested2",
        "type": "STRING"
      }
    ],
    "mode": "REPEATED",
    "name": "column3",
    "type": "RECORD"
  }
]

新しくネストされた列を fields 配列の末尾に追加します。この例では、nested3 が新しくネストされた列です。

  [
    {
      "mode": "REQUIRED",
      "name": "column1",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "column2",
      "type": "FLOAT"
    },
    {
      "fields": [
        {
          "mode": "NULLABLE",
          "name": "nested1",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "nested2",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "nested3",
          "type": "STRING"
        }
      ],
      "mode": "REPEATED",
      "name": "column3",
      "type": "RECORD"
    }
  ]

JSON スキーマファイルの操作の詳細については、JSON スキーマファイルの指定をご覧ください。

スキーマファイルを更新したら、次のコマンドを発行してテーブルのスキーマを更新します。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。
```
bq update PROJECT_ID:DATASET.TABLE SCHEMA
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET: 更新するテーブルを含むデータセットの名前。
- TABLE: 更新するテーブルの名前。
- SCHEMA: ローカルマシン上の JSON スキーマファイルへのパス
たとえば、次のコマンドを入力すると、デフォルトプロジェクトにある mydataset.mytable のスキーマ定義が更新されます。ローカルマシン上にあるスキーマファイルへのパスは /tmp/myschema.json です。
```
bq update mydataset.mytable /tmp/myschema.json
```

API

tables.patch メソッドを呼び出して、schema プロパティを使用してネストされた列をスキーマ定義に追加します。tables.update メソッドはテーブルリソース全体を置き換えるため、tables.patch メソッドの方が適切です。

データを上書きまたは追記するときの列の追加

既存のテーブルにデータを読み込んで上書きする際、そのテーブルに新しい列を追加できます。上書きする既存のテーブルのスキーマは、読み込んでいるデータのスキーマを使用して上書きされます。読み込みジョブを使用してテーブルを上書きする方法については、データの形式に関するドキュメントをご覧ください。

読み込み追加ジョブで列を追加する

読み込みジョブでデータをテーブルに追加するときに、テーブルに列を追加できます。新しいスキーマは、次のいずれかによって決まります。

自動検出（CSV ファイルと JSON ファイルの場合）
JSON スキーマファイル（CSV ファイルおよび JSON ファイル用）で指定されたスキーマ
Avro、ORC、Parquet、Datastore エクスポートファイルの自己記述型ソースデータ

JSON ファイルでスキーマを指定する場合は、その中で新しい列を定義する必要があります。新しい列定義がない場合、データを追記しようとするとエラーが返されます。

追記オペレーション中に新しい列を追加する場合、既存の行の新しい列の値は NULL に設定されます。

読み込みジョブ中にテーブルにデータを追記するときに新しい列を追加するには、次のいずれかのオプションを使用します。

bq

bq load コマンドを使用してデータを読み込み、--noreplace フラグを指定して、データを既存のテーブルに追記していることを示します。

付加するデータが CSV 形式または改行区切りの JSON 形式である場合は、--autodetect フラグを指定してスキーマの自動検出を使用するか、JSON スキーマファイルでスキーマを指定します。追加された列は、Avro または Datastore エクスポートファイルから自動的に推定されます。

--schema_update_option フラグを ALLOW_FIELD_ADDITION に設定して、追記しているデータに新しい列が含まれていることを示します。

追記するテーブルがデフォルト以外のプロジェクトのデータセットにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

load コマンドを次のように入力します。

bq --location=LOCATION load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

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

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
FORMAT: スキーマの形式。NEWLINE_DELIMITED_JSON、CSV、AVRO、PARQUET、ORC、DATASTORE_BACKUP。
PROJECT_ID: プロジェクト ID。
DATASET: テーブルを含むデータセットの名前。
TABLE: 追記するテーブルの名前。
PATH_TO_SOURCE: 完全修飾の Cloud Storage URI、URI のカンマ区切りのリスト、またはローカルマシン上のデータファイルのパス。
SCHEMA: ローカルの JSON スキーマファイルのパス。--autodetect を指定していない場合、スキーマファイルは CSV ファイルおよび JSON ファイルに対してのみ必要です。Avro と Datastore のスキーマはソースデータから推定されます。

例:

次のコマンドを入力して、ローカル Avro データファイル /tmp/mydata.avro を mydataset.mytable に、読み込みジョブを使用して追記します。スキーマは Avro データから自動的に推定できるため、--autodetect フラグを使用する必要はありません。mydataset はデフォルトプロジェクトにあります。

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=AVRO \
mydataset.mytable \
/tmp/mydata.avro

次のコマンドを入力して、Cloud Storage の改行区切りの JSON データファイルを mydataset.mytableに、読み込みジョブを使用して追記します。--autodetect フラグは、新しい列を検出するために使用します。mydataset はデフォルトプロジェクトにあります。

bq load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json

次のコマンドを入力して、Cloud Storage の改行区切りの JSON データファイルを mydataset.mytableに、読み込みジョブを使用して追記します。新しい列を含むスキーマは、ローカルの JSON スキーマファイル /tmp/myschema.json で定義されています。mydataset はデフォルトプロジェクトではなく myotherproject にあります。

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
myotherproject:mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json

API

jobs.insert メソッドを呼び出します。load ジョブを構成し、次のプロパティを設定します。

sourceUris プロパティを使用して、Cloud Storage 内のデータを参照します。
sourceFormat プロパティを設定して、データ形式を指定します。
schema プロパティでスキーマを指定します。
schemaUpdateOptions プロパティを使用して、スキーマ更新オプションを指定します。
writeDisposition プロパティを使用して、宛先テーブルの書き込み処理を WRITE_APPEND に設定します。

Go

import (
	"context"
	"fmt"
	"os"

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

// createTableAndWidenLoad demonstrates augmenting a table's schema to add a new column via a load job.
func createTableAndWidenLoad(projectID, datasetID, tableID, filename 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, import data from a local file, but specify field additions are allowed.
	// Because the data has a second column (age), the schema is amended as part of
	// the load.
	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
	loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); 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.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.TableId;
import com.google.common.collect.ImmutableList;
import java.util.UUID;

public class AddColumnLoadAppend {

  public static void runAddColumnLoadAppend() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    addColumnLoadAppend(datasetName, tableName, sourceUri);
  }

  public static void addColumnLoadAppend(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      // Add a new column to a BigQuery table while appending rows via a load job.
      // 'REQUIRED' fields cannot  be added to an existing schema, so the additional column must be
      // 'NULLABLE'.
      Schema newSchema =
          Schema.of(
              Field.newBuilder("name", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.REQUIRED)
                  .build(),
              // Adding below additional column during the load job
              Field.newBuilder("post_abbr", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build());

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setSchema(newSchema)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_ADDITION))
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Column successfully added during load append job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function addColumnLoadAppend() {
  // Adds a new column to a BigQuery table while appending rows via a load job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const fileName = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // In this example, the existing table contains only the 'Name', 'Age',
  // & 'Weight' columns. 'REQUIRED' fields cannot  be added to an existing
  // schema, so the additional column must be 'NULLABLE'.
  const schema = 'Name:STRING, Age:INTEGER, Weight:FLOAT, IsMagic:BOOLEAN';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // Set load job options
  const options = {
    schema: schema,
    schemaUpdateOptions: ['ALLOW_FIELD_ADDITION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
  };

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(fileName, options);

  console.log(`Job ${job.id} completed.`);
  console.log(`New Schema:`);
  console.log(job.configuration.load.schema.fields);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, 'my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the length of the schema
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
print("Table {} contains {} columns.".format(table_id, len(table.schema)))

# Configures the load job to append the data to the destination table,
# allowing field addition
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION
]
# In this example, the existing table contains only the 'full_name' column.
# 'REQUIRED' fields cannot be added to an existing schema, so the
# additional column must be 'NULLABLE'.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="NULLABLE"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated length of the schema
table = client.get_table(table)
print("Table {} now contains {} columns.".format(table_id, len(table.schema)))

クエリ追加ジョブで列を追加する

クエリ結果をテーブルに追加するときに、テーブルに列を追加できます。

クエリジョブで追記オペレーションを使用して列を追加すると、クエリ結果のスキーマが使用されて宛先テーブルのスキーマが更新されます。ある場所のテーブルにクエリを実行して、別の場所のテーブルに結果を書き込むことはできません。

クエリジョブ中にテーブルにデータを追加する際に新しい列を追加するには、次のいずれかのオプションを選択します。

bq

bq query コマンドを使用してデータに対するクエリを実行し、--destination_table フラグを指定してどのテーブルを追記しているかを示します。

クエリ結果を既存の宛先テーブルに追記していることを指定するには、--append_table フラグを指定します。

--schema_update_option フラグを ALLOW_FIELD_ADDITION に設定して、追記しているクエリ結果に新しい列が含まれていることを示します。

クエリに GoogleSQL 構文を使用するには、use_legacy_sql=false フラグを指定します。

追記するテーブルがデフォルト以外のプロジェクトのデータセットにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。クエリを実行するテーブルと宛先テーブルは同じ場所にある必要があります。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

bq --location=LOCATION query \
--destination_table PROJECT_ID:DATASET.TABLE \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'QUERY'

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

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。クエリ結果は、別のロケーションのテーブルに追記できません。
PROJECT_ID: プロジェクト ID。
dataset: 追記するテーブルを含むデータセットの名前。
TABLE: 追記するテーブルの名前。
QUERY: GoogleSQL 構文のクエリ。

例:

次のコマンドを入力して、デフォルトプロジェクトで mydataset.mytable のクエリを実行したり、クエリ結果をmydataset.mytable2 に（デフォルトプロジェクトでも同様）追記したりできます。

bq query \
--destination_table mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

次のコマンドを入力して、デフォルトプロジェクトで mydataset.mytable のクエリを実行できます。また、クエリ結果を myotherproject の mydataset.mytable2 に追記することもできます。

bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

API

jobs.insert メソッドを呼び出します。query ジョブを構成し、次のプロパティを設定します。

destinationTable プロパティを使用して宛先テーブルを指定します。
writeDisposition プロパティを使用して、宛先テーブルの書き込み処理を WRITE_APPEND に設定します。
schemaUpdateOptions プロパティを使用して、スキーマ更新オプションを指定します。
query プロパティを使用して GoogleSQL クエリを指定します。

Go

import (
	"context"
	"fmt"

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

// createTableAndWidenQuery demonstrates how the schema of a table can be modified to add columns by appending
// query results that include the new columns.
func createTableAndWidenQuery(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()

	// First, we create a sample table.
	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	original := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, original); err != nil {
		return err
	}
	// Our table has two columns.  We'll introduce a new favorite_color column via
	// a subsequent query that appends to the table.
	q := client.Query("SELECT \"Timmy\" as full_name, 85 as age, \"Blue\" as favorite_color")
	q.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	q.WriteDisposition = bigquery.WriteAppend
	q.Location = "US"
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	_, err = job.Wait(ctx)
	if 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.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;

public class RelaxTableQuery {

  public static void runRelaxTableQuery() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    relaxTableQuery(projectId, datasetName, tableName);
  }

  // To relax all columns in a destination table when you append data to it during a query job
  public static void relaxTableQuery(String projectId, String datasetName, String tableName)
      throws Exception {
    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);

      String sourceTable = "`" + projectId + "." + datasetName + "." + tableName + "`";
      String query = "SELECT word FROM " + sourceTable + " WHERE word like '%is%'";

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setDestinationTable(tableId)
              .build();

      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).build());

      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new Exception("Job no longer exists");
      } else if (queryJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(queryJob.getStatus().getError().toString());
      }

      // Get the results.
      TableResult results = queryJob.getQueryResults();

      // Print all pages of the results.
      results
          .iterateAll()
          .forEach(
              rows -> {
                rows.forEach(row -> System.out.println("row: " + row.toString()));
              });

      System.out.println("Successfully relaxed all columns in destination table during query job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Columns not relaxed during query job \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function addColumnQueryAppend() {
  // Adds a new column to a BigQuery table while appending rows via a query job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // In this example, the existing table contains only the 'name' column.
  // 'REQUIRED' fields cannot  be added to an existing schema,
  // so the additional column must be 'NULLABLE'.
  const query = `SELECT name, year
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 10`;

  // Set load job options
  const options = {
    query: query,
    schemaUpdateOptions: ['ALLOW_FIELD_ADDITION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();
  console.log(`Job ${job.id} completed.`);

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

Python

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Retrieves the destination table and checks the length of the schema.
table = client.get_table(table_id)  # Make an API request.
print("Table {} contains {} columns".format(table_id, len(table.schema)))

# Configures the query to append the results to a destination table,
# allowing field addition.
job_config = bigquery.QueryJobConfig(
    destination=table_id,
    schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION],
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
)

# Start the query, passing in the extra configuration.
client.query_and_wait(
    # In this example, the existing table contains only the 'full_name' and
    # 'age' columns, while the results of this query will contain an
    # additional 'favorite_color' column.
    'SELECT "Timmy" as full_name, 85 as age, "Blue" as favorite_color;',
    job_config=job_config,
)  # Make an API request and wait for job to complete.

# Checks the updated length of the schema.
table = client.get_table(table_id)  # Make an API request.
print("Table {} now contains {} columns".format(table_id, len(table.schema)))

列の名前を変更する

テーブルの列の名前を変更するには、ALTER TABLE RENAME COLUMN DDL ステートメントを使用します。次の例では、mytable の列 old_name の名前を new_name に変更します。

ALTER TABLE mydataset.mytable
  RENAME COLUMN old_name TO new_name;

ALTER TABLE RENAME COLUMN ステートメントの詳細については、DDL の詳細をご覧ください。

列のデータ型を変更する

Google Cloud コンソール、bq コマンドラインツール、BigQuery API では列のデータ型を変更できません。列の新しいデータ型を指定するスキーマを適用してテーブルを更新しようとすると、次のようなエラーが返されます。

DDL ステートメントを使用して列のデータ型を変更する

GoogleSQL を使用して、列のデータ型に特定の変更を加えることができます。サポートされているデータ型の変換の詳細と完全なリストについては、ALTER COLUMN SET DATA TYPE DDL ステートメントをご覧ください。

次の例では、INT64 型の列を持つテーブルを作成してから、型を NUMERIC に更新します。

CREATE TABLE mydataset.mytable(c1 INT64);

ALTER TABLE mydataset.mytable
ALTER COLUMN c1 SET DATA TYPE NUMERIC;

次の例では、2 つのフィールドにネストされた列が配置されているテーブルを作成し、一方の列の型を INT から NUMERIC に更新しています。

CREATE TABLE mydataset.mytable(s1 STRUCT<a INT64, b STRING>);

ALTER TABLE mydataset.mytable ALTER COLUMN s1
SET DATA TYPE STRUCT<a NUMERIC, b STRING>;

ネストされた列の型を変更する

STRUCT の配列内のフィールドの変更など、複雑なネストされたスキーマ変更の場合、ALTER TABLE DDL ステートメントはサポートされていません。回避策として、SELECT ステートメントで CREATE OR REPLACE TABLE ステートメントを使用して、ネストされたスキーマ変更を変換できます。

次の例は、STRUCTS の配列内の列を変換する方法を示しています。

次のスキーマとデータがあるテーブル samples.test について考えてみます。

CREATE OR REPLACE TABLE
  samples.test(D STRUCT <L ARRAY<STRUCT<R STRING, U STRING, V STRING>>, F STRING>);

INSERT INTO
  samples.test(D)
VALUES
  (STRUCT([STRUCT("r1", "u1", "v1"), STRUCT("r2", "u2", "v2")], "f1"));

結果は次のようになります。

+----------------------------------------------------------------------------+
|                                     D                                      |
+----------------------------------------------------------------------------+
| {"L":[{"R":"r1","U":"u1","V":"v1"},{"R":"r2","U":"u2","V":"v2"}],"F":"f1"} |
+----------------------------------------------------------------------------+

STRUCT のネストされた配列内のフィールド U の型を STRUCT<W STRING> に変更するとします。次の SQL ステートメントは、この方法を示しています。

CREATE OR REPLACE TABLE
  samples.new_table AS
SELECT
  STRUCT(ARRAY(
    SELECT
      STRUCT(tmp.R,
        STRUCT(tmp.U AS W) AS U,
        tmp.V)
    FROM
      UNNEST(t.D.L) AS tmp) AS L,
    t.D.F) AS D
FROM
  samples.test AS t

このステートメントは、ターゲットスキーマを使用して新しいテーブル samples.new_table を作成します。UNNEST 関数は、t.D.L 内の STRUCT の配列を展開します。式 STRUCT(tmp.U AS W) AS U は、フィールド W がある新しい STRUCT を構築し、元の U フィールドの値で入力します。結果のテーブル samples.new_table のスキーマとデータは次のとおりです。

+----------------------------------------------------------------------------------------+
|                                           D                                            |
+----------------------------------------------------------------------------------------+
| {"L":[{"R":"r1","U":{"W":"u1"},"V":"v1"},{"R":"r2","U":{"W":"u2"},"V":"v2"}],"F":"f1"} |
+----------------------------------------------------------------------------------------+

列のデータ型をキャストする

列のデータ型をキャスト可能型に変更するには、SQL クエリを使用してテーブルデータを選択し、関連する列のキャストを行い、テーブルを上書きします。テーブル全体のスキャンが必要になるため、非常に大きなテーブルではキャストと上書きはおすすめしません。

次の例は、mydataset.mytable の column_two と column_three のすべてのデータを選択し、column_one を DATE から STRING にキャストする SQL クエリを示しています。クエリ結果を使用して、既存のテーブルを上書きします。上書きされたテーブルには、column_one が STRING データ型として保存されます。

CAST を使用したときに、BigQuery がキャストできない場合はクエリが失敗します。GoogleSQL でのキャストルールの詳細については、キャスティングをご覧ください。

コンソール

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

[BigQuery] に移動
[クエリエディタ] で次のクエリを入力して、mydataset.mytable の column_two と column_three のすべてのデータが選択され、column_one が DATE から STRING にキャストされるようにします。クエリでは、エイリアスを使用して column_one を同じ名前でキャストします。mydataset.mytable はデフォルトプロジェクトにあります。
```
SELECT
 column_two,
 column_three,
 CAST(column_one AS STRING) AS column_one
FROM
 mydataset.mytable;
```
[展開] をクリックして、[クエリの設定] を選択します。
[送信先] セクションで、次の操作を行います。
1. [クエリ結果の宛先テーブルを設定する] を選択して、
2. [プロジェクト名] の値は、デフォルトのプロジェクトのままにします。これは mydataset.mytable を含むプロジェクトです。
3. [Dataset] で [mydataset] を選択します。
4. [テーブル ID] フィールドに「mytable」と入力します。
5. [宛先テーブルの書き込み設定] で、[テーブルを上書きする] を選択します。このオプションにより、クエリ結果を使用して mytable が上書きされます。
必要に応じて、データの [ロケーション] を選択します。
設定を更新するには、[保存] をクリックします。
[実行] をクリックします。

クエリジョブが完了すると、column_one のデータ型は STRING になります。

bq

次の bq query コマンドを入力して、mydataset.mytable の column_two と column_three のすべてのデータが選択され、column_one が DATE から STRING にキャストされるようにします。クエリでは、エイリアスを使用して column_one を同じ名前でキャストします。mydataset.mytable はデフォルトプロジェクトにあります。

--destination_table フラグを使用してクエリ結果を mydataset.mytable に書き込み、--replace フラグを使用して mytable を上書きします。GoogleSQL 構文を使用するには、use_legacy_sql=false フラグを指定します。

必要に応じて、--location フラグを指定して、その値をロケーションに設定します。

bq query \
    --destination_table mydataset.mytable \
    --replace \
    --use_legacy_sql=false \
'SELECT
  column_two,
  column_three,
  CAST(column_one AS STRING) AS column_one
FROM
  mydataset.mytable'

API

mydataset.mytable の column_two と column_three のすべてのデータを選択し、column_one を DATE から STRING にキャストするには、jobs.insert メソッドを呼び出して query ジョブを構成します。（省略可）jobReference セクションにある location プロパティでロケーションを指定します。

クエリジョブで使用される SQL クエリは、SELECT column_two, column_three, CAST(column_one AS STRING) AS column_one FROM mydataset.mytable のようになります。クエリでは、エイリアスを使用して column_one を同じ名前でキャストします。

mytable をクエリ結果で上書きするには、configuration.query.destinationTable プロパティに mydataset.mytable を含め、configuration.query.writeDisposition プロパティに WRITE_TRUNCATE を指定します。

列のモードを変更する

現在、列のモードに対してサポートされている唯一の変更は、REQUIRED から NULLABLE に変更することです。列のモードを REQUIRED から NULLABLE に変更することは、列緩和とも呼ばれます。データを読み込んで既存のテーブルを上書きするときや、既存のテーブルにデータを追加するときにも、列を緩和できます。列のモードを NULLABLE から REQUIRED に変更することはできません。

既存のテーブルに列 `NULLABLE` を作成する

列のモードを REQUIRED から NULLABLE に変更するには、次のいずれかのオプションを選択します。

コンソール

[BigQuery] ページに移動します。

BigQuery に移動
左側のペインで、 [エクスプローラ] をクリックします。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。
[概要 > テーブル] をクリックし、テーブルを選択します。
詳細パネルで [スキーマ] タブをクリックします。
[スキーマを編集] をクリックします。このボタンを表示するには、スクロールが必要な場合があります。
[現在のスキーマ] ページで、変更するフィールドを特定します。
そのフィールドの [モード] プルダウンリストで、NULLABLE を選択します。
設定を更新するには、[保存] をクリックします。

SQL

ALTER COLUMN DROP NOT NULL DDL ステートメントを使用します。次の例では、列 mycolumn のモードを REQUIRED から NULLABLE に変更します。

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

[BigQuery] に移動

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

ALTER TABLE mydataset.mytable
ALTER COLUMN mycolumn
DROP NOT NULL;

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

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

bq

まず、--schema フラグを指定した bq show コマンドを発行して、既存のテーブルスキーマをファイルに書き込みます。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。
```
bq show \
--schema \
--format=prettyjson \
PROJECT_ID:DATASET.TABLE > SCHEMA_FILE
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET: 更新するテーブルを含むデータセットの名前。
- TABLE: 更新するテーブルの名前。
- SCHEMA_FILE: ローカルマシンに書き込まれるスキーマ定義ファイル。
たとえば、mydataset.mytable のスキーマ定義をファイルに書き込むには、次のコマンドを入力します。mydataset.mytable はデフォルトプロジェクトにあります。
```
  bq show \
  --schema \
  --format=prettyjson \
  mydataset.mytable > /tmp/myschema.json
```

スキーマファイルをテキストエディタで開きます。スキーマは次のようになっています。

[
  {
    "mode": "REQUIRED",
    "name": "column1",
    "type": "STRING"
  },
  {
    "mode": "REQUIRED",
    "name": "column2",
    "type": "FLOAT"
  },
  {
    "mode": "REPEATED",
    "name": "column3",
    "type": "STRING"
  }
]

既存の列のモードを REQUIRED から NULLABLE に変更します。この例では、column1 のモードを緩和しています。
```
[
  {
    "mode": "NULLABLE",
    "name": "column1",
    "type": "STRING"
  },
  {
    "mode": "REQUIRED",
    "name": "column2",
    "type": "FLOAT"
  },
  {
    "mode": "REPEATED",
    "name": "column3",
    "type": "STRING"
  }
]
```
JSON スキーマファイルの操作の詳細については、JSON スキーマファイルの指定をご覧ください。
スキーマファイルを更新したら、次のコマンドを発行してテーブルのスキーマを更新します。更新するテーブルがデフォルト以外のプロジェクトにある場合は、PROJECT_ID:DATASET の形式でプロジェクト ID をデータセット名に追加します。
```
bq update PROJECT_ID:DATASET.TABLE SCHEMA
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET: 更新するテーブルを含むデータセットの名前。
- TABLE: 更新するテーブルの名前。
- SCHEMA: ローカルマシン上の JSON スキーマファイルへのパス
たとえば、次のコマンドを入力すると、デフォルトプロジェクトにある mydataset.mytable のスキーマ定義が更新されます。ローカルマシン上にあるスキーマファイルへのパスは /tmp/myschema.json です。
```
  bq update mydataset.mytable /tmp/myschema.json
```

API

tables.patch を呼び出し、schema プロパティを使用してスキーマ定義の中の REQUIRED 列を NULLABLE に変更します。tables.update メソッドはテーブルリソース全体を置き換えるため、tables.patch メソッドの方が適切です。

Go

import (
	"context"
	"fmt"

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

// relaxTableAPI demonstrates modifying the schema of a table to remove the requirement that columns allow
// no NULL values.
func relaxTableAPI(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()

	// Setup: We first create a table with a schema that's restricts NULL values.
	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	original := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	if err := client.Dataset(datasetID).Table(tableID).Create(ctx, original); err != nil {
		return err
	}

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	// Iterate through the schema to set all Required fields to false (nullable).
	var relaxed bigquery.Schema
	for _, v := range meta.Schema {
		v.Required = false
		relaxed = append(relaxed, v)
	}
	newMeta := bigquery.TableMetadataToUpdate{
		Schema: relaxed,
	}
	if _, err := tableRef.Update(ctx, newMeta, meta.ETag); 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.LegacySQLTypeName;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.Table;

public class RelaxColumnMode {

  public static void runRelaxColumnMode() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableId = "MY_TABLE_NAME";
    relaxColumnMode(datasetName, tableId);
  }

  public static void relaxColumnMode(String datasetName, String tableId) {
    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();

      Table table = bigquery.getTable(datasetName, tableId);

      // Create new relaxed schema based on the existing table schema
      Schema relaxedSchema =
          Schema.of(
              // The only supported modification you can make to a column's mode is changing it from
              // REQUIRED to NULLABLE
              // Changing a column's mode from REQUIRED to NULLABLE is also called column relaxation
              // INFO: LegacySQLTypeName will be updated to StandardSQLTypeName in release 1.103.0
              Field.newBuilder("word", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("word_count", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("corpus", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("corpus_date", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build());

      // Update the table with the new schema
      Table updatedTable =
          table.toBuilder().setDefinition(StandardTableDefinition.of(relaxedSchema)).build();
      updatedTable.update();
      System.out.println("Table schema successfully relaxed.");
    } catch (BigQueryException e) {
      System.out.println("Table schema not relaxed \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function relaxColumn() {
  /**
   * Changes columns from required to nullable.
   * Assumes existing table with the following schema:
   * [{name: 'Name', type: 'STRING', mode: 'REQUIRED'},
   * {name: 'Age', type: 'INTEGER'},
   * {name: 'Weight', type: 'FLOAT'},
   * {name: 'IsMagic', type: 'BOOLEAN'}];
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const newSchema = [
    {name: 'Name', type: 'STRING', mode: 'NULLABLE'},
    {name: 'Age', type: 'INTEGER'},
    {name: 'Weight', type: 'FLOAT'},
    {name: 'IsMagic', type: 'BOOLEAN'},
  ];

  // Retrieve current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Update schema
  metadata.schema = newSchema;
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(apiResponse.schema.fields);
}

Python

mode プロパティを 'NULLABLE' に設定した SchemaField オブジェクトのリストで、Table.schema プロパティを上書きします。

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"

table = client.get_table(table_id)
new_schema = []
for field in table.schema:
    if field.mode != "REQUIRED":
        new_schema.append(field)
    else:
        # SchemaField properties cannot be edited after initialization.
        # To make changes, construct new SchemaField objects.
        new_field = field.to_api_repr()
        new_field["mode"] = "NULLABLE"
        relaxed_field = bigquery.SchemaField.from_api_repr(new_field)
        new_schema.append(relaxed_field)

table.schema = new_schema
table = client.update_table(table, ["schema"])

print(f"Updated {table_id} schema: {table.schema}.")

追記の読み込みジョブを使用して列を `NULLABLE` にする

読み込みジョブでテーブルにデータを追記するときに、列のモードを緩和できます。ファイルの種類に応じて、次のいずれかを選択します。

CSV ファイルと JSON ファイルのデータを追加するときに、JSON スキーマファイルを指定して個々の列のモードを緩和します。
Avro、ORC、Parquet のファイルからデータを追記するときは、スキーマ内の NULL に列を緩和し、緩和された列がスキーマ推論によって検出されるようにします。

読み込みジョブ中にテーブルにデータを追記する際に列を REQUIRED から NULLABLE に緩和するには、次のいずれかのオプションを選択します。

コンソール

Google Cloud コンソールを使用して列のモードを緩和することはできません。

bq

bq load コマンドを使用してデータを読み込み、--noreplace フラグを指定して、データを既存のテーブルに追記していることを示します。

追記するデータが CSV 形式または改行区切りの JSON 形式である場合は、ローカル JSON スキーマファイルで緩和した列を指定します。あるいは、緩和した列がソースデータ内で検出されるように、--autodetect フラグでスキーマの検出を使用します。

Avro、ORC、Parquet ファイルから読み込む場合、緩和した列は自動的に推定されます。列緩和は、Datastore エクスポートの追記には適用されません。Datastore エクスポートファイルの読み込みによって作成されたテーブル内の列は常に NULLABLE です。

--schema_update_option フラグを ALLOW_FIELD_RELAXATION に設定して、追記しているデータに緩和した列が含まれていることを示します。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

load コマンドを次のように入力します。

bq --location=LOCATION load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

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

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
FORMAT: NEWLINE_DELIMITED_JSON、CSV、PARQUET、ORC、AVRO。DATASTORE_BACKUP ファイルでは列緩和は必要ありません。Datastore エクスポートファイルから作成されたテーブルの列は常に NULLABLE です。
PROJECT_ID: プロジェクト ID。
dataset は、テーブルを含むデータセットの名前です。
TABLE: 追記するテーブルの名前。
PATH_TO_SOURCE: 完全修飾の Cloud Storage URI、URI のカンマ区切りのリスト、またはローカルマシン上のデータファイルのパス。
SCHEMA: ローカルの JSON スキーマファイルのパス。このオプションは、CSV ファイルと JSON ファイルに対してのみ使用します。Avro ファイルから読み込まれたデータでは、緩和した列は自動的に推定されます。

例:

次のコマンドを入力して、ローカル Avro データファイル /tmp/mydata.avro を mydataset.mytable に、読み込みジョブを使用して追記します。緩和された列は Avro データから自動的に推定できるため、スキーマファイルを指定する必要はありません。mydataset はデフォルトプロジェクトにあります。

bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --source_format=AVRO \
    mydataset.mytable \
    /tmp/mydata.avro

次のコマンドを入力して、Cloud Storage の改行区切りの JSON ファイルのデータを mydataset.mytable に、読み込みジョブを使用して追記します。緩和された列を含むスキーマは、ローカル JSON スキーマファイル /tmp/myschema.json 内にあります。mydataset はデフォルトプロジェクトにあります。

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json

次のコマンドを入力して、ローカルマシン上の CSV ファイルのデータを mydataset.mytable に、読み込みジョブを使用して追記します。このコマンドは、スキーマの自動検出機能を使用して、ソースデータ内の緩和した列を検出します。mydataset はデフォルトプロジェクトではなく myotherproject にあります。

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=CSV \
--autodetect \
myotherproject:mydataset.mytable \
mydata.csv

API

jobs.insert メソッドを呼び出します。load ジョブを構成し、次のプロパティを設定します。

sourceUris プロパティを使用して、Cloud Storage 内のデータを参照します。
sourceFormat プロパティを設定して、データ形式を指定します。
schema プロパティでスキーマを指定します。
schemaUpdateOptions プロパティを使用して、スキーマ更新オプションを指定します。
writeDisposition プロパティを使用して、宛先テーブルの書き込み処理を WRITE_APPEND に設定します。

Go

import (
	"context"
	"fmt"
	"os"

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

// relaxTableImport demonstrates amending the schema of a table to relax columns from
// not allowing NULL values to allowing them.
func relaxTableImport(projectID, datasetID, tableID, filename 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, import data from a local file, but specify relaxation of required
	// fields as a side effect while the data is appended.
	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
	loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); 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.CsvOptions;
import com.google.cloud.bigquery.Field;
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.Table;
import com.google.cloud.bigquery.TableId;
import com.google.common.collect.ImmutableList;

// Sample to append relax column in a table.
public class RelaxColumnLoadAppend {

  public static void main(String[] args) {
    // 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.csv";
    relaxColumnLoadAppend(datasetName, tableName, sourceUri);
  }

  public static void relaxColumnLoadAppend(String datasetName, String tableName, String sourceUri) {
    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();

      // Retrieve destination table reference
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));

      // column as a 'REQUIRED' field.
      Field name =
          Field.newBuilder("name", StandardSQLTypeName.STRING).setMode(Field.Mode.REQUIRED).build();
      Field postAbbr =
          Field.newBuilder("post_abbr", StandardSQLTypeName.STRING)
              .setMode(Field.Mode.REQUIRED)
              .build();
      Schema schema = Schema.of(name, postAbbr);

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      // Set job options
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(table.getTableId(), sourceUri)
              .setSchema(schema)
              .setFormatOptions(csvOptions)
              .setSchemaUpdateOptions(
                  ImmutableList.of(JobInfo.SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_APPEND)
              .build();

      // Create a load job and wait for it to complete.
      Job job = bigquery.create(JobInfo.of(loadConfig));
      job = job.waitFor();
      // Check the job's status for errors
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Relax column append 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());
    }
  }
}

Node.js

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function relaxColumnLoadAppend() {
  // Changes required column to nullable in load append job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const fileName = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // In this example, the existing table contains the 'Name'
  // column as a 'REQUIRED' field.
  const schema = 'Age:INTEGER, Weight:FLOAT, IsMagic:BOOLEAN';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // Set load job options
  const options = {
    schema: schema,
    schemaUpdateOptions: ['ALLOW_FIELD_RELAXATION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
  };

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(fileName, options);

  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, 'my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the number of required fields
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
# In this example, the existing table has 3 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the load job to append the data to a destination table,
# allowing field relaxation
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION
]
# In this example, the existing table contains three required fields
# ('full_name', 'age', and 'favorite_color'), while the data to load
# contains only the first two fields.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated number of required fields
table = client.get_table(table)
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

追加ジョブですべての列を `NULLABLE` にする

クエリ結果をテーブルに追加するときに、そのテーブル内のすべての列を緩和できます。--schema_update_option フラグを ALLOW_FIELD_RELAXATION に設定すると、宛先テーブル内のすべての必須フィールドを緩和できます。クエリ追記を使用して宛先テーブル内の個々の列を緩和することはできません。読み込み追加ジョブで個々の列を緩和するには、追加ジョブで列を NULLABLE にするをご覧ください。

宛先テーブルにクエリ結果を追記するときにすべての列を緩和するには、次のいずれかのオプションを選択します。

コンソール

Google Cloud コンソールを使用して列のモードを緩和することはできません。

bq

bq query コマンドを使用してデータに対するクエリを実行し、--destination_table フラグを指定してどのテーブルを追記しているかを示します。

クエリ結果を既存の宛先テーブルに追記していることを指定するには、--append_table フラグを指定します。

--schema_update_option フラグを ALLOW_FIELD_RELAXATION に設定して、追記しているテーブル内のすべての REQUIRED 列を NULLABLE に変更するように指示します。

クエリに GoogleSQL 構文を使用するには、use_legacy_sql=false フラグを指定します。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

bq --location=LOCATION query \
--destination_table PROJECT_ID:DATASET.TABLE \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'QUERY'

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

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
PROJECT_ID: プロジェクト ID。
DATASET: 追記するテーブルを含むデータセットの名前。
TABLE: 追記するテーブルの名前。
QUERY: GoogleSQL 構文のクエリ。

例:

次のコマンドを入力して、デフォルトプロジェクトで mydataset.mytable のクエリを実行し、クエリ結果を mydataset.mytable2（およびデフォルトプロジェクト）に追記します。このコマンドは、宛先テーブル内のすべての REQUIRED 列を NULLABLE に変更します。

bq query \
    --destination_table mydataset.mytable2 \
    --append_table \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --use_legacy_sql=false \
    'SELECT
       column1,column2
     FROM
       mydataset.mytable'

次のコマンドを入力して、デフォルトプロジェクトで mydataset.mytable のクエリを実行でき、クエリ結果を myotherproject の mydataset.mytable2 に追記できます。このコマンドは、宛先テーブル内のすべての REQUIRED 列を NULLABLE に変更します。

bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

API

jobs.insert メソッドを呼び出します。query ジョブを構成し、次のプロパティを設定します。

destinationTable プロパティを使用して宛先テーブルを指定します。
writeDisposition プロパティを使用して、宛先テーブルの書き込み処理を WRITE_APPEND に設定します。
schemaUpdateOptions プロパティを使用して、スキーマ更新オプションを指定します。
query プロパティを使用して GoogleSQL クエリを指定します。

Go

import (
	"context"
	"fmt"

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

// relaxTableQuery demonstrates relaxing the schema of a table by appending query results to
// enable the table to allow NULL values.
func relaxTableQuery(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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, append a query result that includes nulls, but allow the job to relax
	// all required columns.
	q := client.Query("SELECT \"Beyonce\" as full_name")
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	q.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
	q.WriteDisposition = bigquery.WriteAppend
	q.Location = "US"
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	_, err = job.Wait(ctx)
	if 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.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;

public class RelaxTableQuery {

  public static void runRelaxTableQuery() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    relaxTableQuery(projectId, datasetName, tableName);
  }

  // To relax all columns in a destination table when you append data to it during a query job
  public static void relaxTableQuery(String projectId, String datasetName, String tableName)
      throws Exception {
    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);

      String sourceTable = "`" + projectId + "." + datasetName + "." + tableName + "`";
      String query = "SELECT word FROM " + sourceTable + " WHERE word like '%is%'";

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setDestinationTable(tableId)
              .build();

      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).build());

      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new Exception("Job no longer exists");
      } else if (queryJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(queryJob.getStatus().getError().toString());
      }

      // Get the results.
      TableResult results = queryJob.getQueryResults();

      // Print all pages of the results.
      results
          .iterateAll()
          .forEach(
              rows -> {
                rows.forEach(row -> System.out.println("row: " + row.toString()));
              });

      System.out.println("Successfully relaxed all columns in destination table during query job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Columns not relaxed during query job \n" + e.toString());
    }
  }
}

Python

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Retrieves the destination table and checks the number of required fields.
table = client.get_table(table_id)  # Make an API request.
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)

# In this example, the existing table has 2 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the query to append the results to a destination table,
# allowing field relaxation.
job_config = bigquery.QueryJobConfig(
    destination=table_id,
    schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION],
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
)

# Start the query, passing in the extra configuration.
client.query_and_wait(
    # In this example, the existing table contains 'full_name' and 'age' as
    # required columns, but the query results will omit the second column.
    'SELECT "Beyonce" as full_name;',
    job_config=job_config,
)  # Make an API request and wait for job to complete

# Checks the updated number of required fields.
table = client.get_table(table_id)  # Make an API request.
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

列のデフォルト値を変更する

列のデフォルト値を変更するには、次のいずれかのオプションを選択します。

コンソール

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

BigQuery に移動
左側のペインで、 [エクスプローラ] をクリックします。

左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。
[概要 > テーブル] をクリックし、テーブルをクリックします。
[スキーマ] タブをクリックします。
[スキーマを編集] をクリックします。このボタンを表示するには、スクロールが必要な場合があります。
[現在のスキーマ] ページで、変更するトップレベルフィールドを見つけます。
そのフィールドのデフォルト値を入力します。
[保存] をクリックします。

SQL

ALTER COLUMN SET DEFAULT DDL ステートメントを使用します。

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

[BigQuery] に移動

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

ALTER TABLE mydataset.mytable
ALTER COLUMN column_name SET DEFAULT default_expression;

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

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

列の説明を変更する

列の説明を変更するには、次のいずれかのオプションを選択します。

コンソール

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

BigQuery に移動
左側のペインで、 [エクスプローラ] をクリックします。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。
[概要 > テーブル] をクリックし、テーブルを選択します。
詳細パネルで [スキーマ] タブをクリックします。
[スキーマを編集] をクリックします。このボタンを表示するには、スクロールが必要な場合があります。
[現在のスキーマ] ページで、変更するフィールドを特定します。
そのフィールドの説明を入力します。
[保存] をクリックします。

SQL

ALTER COLUMN SET OPTIONS DDL ステートメントを使用します。

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

[BigQuery] に移動

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

ALTER TABLE mydataset.mytable
ALTER COLUMN column_name
SET OPTIONS (description = 'This is a column description.');

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

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

Gemini

データ分析情報を使用して、Gemini in BigQuery で列の説明を生成できます。データ分析情報を使用すると、データを自動的に探索、理解、キュレートできます。

データ分析情報の詳細（設定手順、必要な IAM ロール、生成された分析情報の精度を高めるためのベストプラクティスなど）については、BigQuery でデータ分析情報を生成するをご覧ください。

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

BigQuery に移動
左側のペインで、 [エクスプローラ] をクリックします。
[エクスプローラ] ペインで、プロジェクトとデータセットを開いて、テーブルを選択します。
詳細パネルで [スキーマ] タブをクリックします。
[生成] をクリックします。

注: [生成] ボタンが表示されない場合は、[データを説明する] をクリックします。このボタンを表示するには、スクロールが必要な場合があります。
Gemini は、列の説明とテーブルに関する分析情報を生成します。情報が入力されるまで数分かかります。生成された分析情報は、テーブルの [分析情報] タブで確認できます。
生成された列の説明を編集して保存する手順は次のとおりです。
1. [列の説明を表示] をクリックします。
2. [列の説明] セクションで、[スキーマに保存] をクリックします。
  
  生成された列の説明は、各列の [新しい説明] フィールドに入力されます。
3. 必要に応じて列の説明を編集し、[保存] をクリックします。
  
  列の説明はすぐに更新されます。
4. [プレビューの説明] パネルを閉じるには、[閉じる] をクリックします。

列を削除する

既存のテーブルから列を削除するには、ALTER TABLE DROP COLUMN DDL ステートメントを使用します。

このステートメントは、削除された列に関連付けられているストレージをすぐには解放しません。ストレージに関する列を削除するときにストレージが受ける影響については、ALTER TABLE DROP COLUMN ステートメントの詳細をご覧ください。ストレージをすぐに再利用するには、次の 2 つの方法があります。

SELECT * EXCEPT クエリを使用してテーブルを上書きします。

CREATE OR REPLACE TABLE mydataset.mytable AS (
  SELECT * EXCEPT (column_to_delete) FROM mydataset.mytable
);

データを Cloud Storage にエクスポートし、不要な列を削除してから、正しいスキーマを持つ新しいテーブルにデータを読み込みます。

テーブル スキーマの変更

列の追加

空の列を追加する

コンソール

SQL

bq

API

Go

Java

Node.js

Python

ネストされた列を RECORD 列に追加する

コンソール

SQL

bq

API

データを上書きまたは追記するときの列の追加

読み込み追加ジョブで列を追加する

bq

API

Go

Java

Node.js

Python

クエリ追加ジョブで列を追加する

bq

API

Go

Java

Node.js

Python

列の名前を変更する

列のデータ型を変更する

DDL ステートメントを使用して列のデータ型を変更する

ネストされた列の型を変更する

列のデータ型をキャストする

コンソール

bq

API

列のモードを変更する

既存のテーブルに列 NULLABLE を作成する

コンソール

SQL

bq

API

Go

Java

Node.js

Python

追記の読み込みジョブを使用して列を NULLABLE にする

コンソール

bq

API

Go

Java

Node.js

Python

追加ジョブですべての列を NULLABLE にする

コンソール

bq

API

Go

Java

Python

列のデフォルト値を変更する

コンソール

SQL

列の説明を変更する

コンソール

SQL

Gemini

列を削除する

テーブルスキーマの変更

ネストされた列を `RECORD` 列に追加する

既存のテーブルに列 `NULLABLE` を作成する

追記の読み込みジョブを使用して列を `NULLABLE` にする

追加ジョブですべての列を `NULLABLE` にする