BigQuery 新たにGAになったステートメントオプションまとめ

はじめに

2026/1/6 に CREATE EXTERNAL TABLE and LOAD DATA ステートメントで、いくつかのオプションが GA になりました！
この記事では GA になったオプションの動作検証まとめになります。

検証

タイムゾーン指定 time_zone

timestamp 型データについて、ロード時に使用するタイムゾーンを指定できます。
前処理としてタイムゾーンを変換する必要がなくなります！

以下のようなデータがあるとします。

statement_source.csv

1,2026-01-16 12:34:56

このファイルを time_zone を指定せずにロードすると

LOAD DATA INTO test.statement_test
FROM FILES (
  format='CSV',
  uris=['gs://<Cloud Storage Bucket>/statement_source.csv']
)

ロード結果は画像の通りになります。

time_zone を指定してロードすると

LOAD DATA INTO test.statement_test
FROM FILES (
  format='CSV',
  time_zone='Asia/Tokyo',
  uris=['gs://<Cloud Storage Bucket>/statement_source.csv']
)

指定したタイムゾーンから UTC へ変換されました！

指定できるタイムゾーンフォーマットは以下ドキュメントに記述があります。

フォーマット方法の定義 date_format datetime_format time_format timestamp_format

日付・日時型データについて、ロードデータのフォーマットを指定できます。
これも前処理で変換する必要がなくなります。

今回は timestamp_format で試します。
以下のデータを用意します。日時データのフォーマットは DD.MM.YYYY HH24.MI.SS です。

statement_source.csv

id,timestamp
1,16.01.2026 12.34.56

ロードオプションで timestamp_format を指定すると

LOAD DATA INTO test.statement_test_format
FROM FILES (
  format='CSV',
  timestamp_format='DD.MM.YYYY HH24.MI.SS',
  uris=['gs://<Cloud Storage Bucket>/statement_source.csv']
)

指定フォーマット通りにロードされました！

余談

指定するフォーマットを DD.MM.YYYY HH.MI.SS にすると、エラーが発生しました。

Invalid format for option 'timestamp_format': Format element in category MERIDIAN_INDICATOR is required when format element 'HH' exists

HH は12時間制を表すため、12時間表記か24時間表記を明示的にする必要がありました。
フォーマット規約は公式ドキュメントがあります。

NULL を表す文字リスト null_markers

ロードするデータ内の「NULL」を表す文字列を指定できます。
null_marker で同様の指定を行えますが、null_marker は一つの文字列、null_markers は複数の文字列を指定できるようになりました。

以下のようなデータを用意します。

id,value1,value2
1,abc,NULL
2,345,def
3,N/A,678

null_markers オプションで、NULL と N/A を「NULL」と扱うように指定してロードします。

LOAD DATA INTO test.statement_test_null
FROM FILES (
  format='CSV',
  null_markers=['NULL','N/A'],
  uris=['gs://<Cloud Storage Bucket>/statement_source.csv']
)

実行の結果、オプションの指定通り「NULL」扱いになっています。

列とスキーマの一致方法指定 source_column_match

列とスキーマを、列名（ヘッダー行の値）で一致させるか順番で一致させるかを指定できます。
自動検出機能が有効になっている場合は列名で一致させる NAME が、無効の場合は順番で一致させる POSITION がデフォルトの動作になります。
NAME 指定時、列名とヘッダー行の値の一致をみるので、ロードデータの列順をテーブルと一致させる必要がなくなります。
デフォルトと逆（例えば自動検出機能が有効で source_column_match に POSITION を指定する）の指定を行うとエラーが発生します。

source_column_match cannot be set to POSITION when using autodetect.

さいごに

今日検証したオプションは bq コマンドでも使用可能でした！（執筆時点ではプレビュー）

SDK への展開も期待しています！

以上、どなたかの参考になれば幸いです。