BigQuery の BigLake テーブルで JSON のネストされた日本語キーを参照できるか確認してみた
2025.06.10データ事業本部のはんざわです。
先日、Cloud Storage 上のネストされた日本語のキーを含む JSON データを BigQuery で参照したいケースがありました。
例として、以下のような JSON データです。
{"json_data": {"キー1": "これはキー1のデータです。", "鍵2": "これは鍵2のデータです。"}}
今回のブログでは、このようなデータを BigQuery の BigLake テーブルで参照できるかを確認してみたいと思います。
前提
- Cloud Storage 上にある JSONL ファイルを BigLake テーブルで参照する
- JSONL 内のネストされたキーに日本語や漢字が含まれている
結論
さっそくですが、結論を紹介します。
該当のカラムを JSON 型で定義し、アクセスしたいキーをバッククォート（`）で囲むことで参照できます。
イメージとして、以下のような SQL になります。
CREATE EXTERNAL TABLE test.json_table
(
json_data JSON
)
WITH CONNECTION `asia-northeast1.biglake-connection`
OPTIONS (
format = "JSON",
uris = ["gs://cm-hanzawa-yuya-json/test1/*"]
);
SELECT
STRING(json_data.`キー1`) AS `キー1`,
STRING(json_data.`鍵2`) AS `鍵2`
FROM
test.json_table
注意点
利用する際にいくつか注意点があるので紹介します。
1. ルートキーに日本語が含まれる場合はNG
BigLake で Cloud Storage のデータを読み込む場合、ルートキーに日本語が含まれるとエラーになってしまいます。
具体的には、以下のような例です。
{"json_data": {"キー1": "これはキー1のデータです。", "鍵2": "これは鍵2のデータです。"}}
{"トップキー": {"キー1": "これはキー1のデータです。", "鍵2": "これは鍵2のデータです。"}}
これは BigLake の制約によるもので、日本語などの柔軟な列名は外部テーブルでサポートされていません。
（BigQuery の通常のテーブルであれば、問題ありません。）
BigLake テーブルには、外部テーブルの制限がすべて適用されます。
外部テーブルでは柔軟な列名はサポートされていません。
実際に DDL を実行しようとすると、次のようなエラーになります。
CREATE EXTERNAL TABLE test.json_table_ng
(
`トップキー` JSON
)
WITH CONNECTION `asia-northeast1.biglake-connection`
OPTIONS (
format ="JSON",
uris = ["gs://cm-hanzawa-yuya-json/test2/*"]
);
Invalid field name "トップキー". Fields must contain only letters, numbers, and underscores, start with a letter or underscore, and be at most 300 characters long.
2. STRUCT型での定義はNG（JSON型のみOK）
STRUCT 型では、フィールド名を DDL で定義する必要があるため、日本語を使うことができません。
そのため、日本語キーを含むデータを扱いたい場合は、JSON 型を使う必要があります。
STRUCT 型で定義しようとすると、以下のように 1 と同じエラーになります。
CREATE EXTERNAL TABLE test.json_table_ng
(
json_data STRUCT <
`キー1` STRING,
`鍵2` STRING
>
)
WITH CONNECTION `asia-northeast1.biglake-connection`
OPTIONS (
format ="JSON",
uris = ["gs://cm-hanzawa-yuya-json/test1/*"]
);
Invalid field name "キー1". Fields must contain only letters, numbers, and underscores, start with a letter or underscore, and be at most 300 characters long.
まとめ
今回のブログでは、BigLake テーブルで JSON のネストされた日本語キーを参照してみました。
かなり珍しいケースだとは思いますが、参考になれば幸いです。
BigQuery の通常テーブルで日本語カラムがサポートされていることを知っている人は多いと思いますが、外部テーブルで利用できないのは盲点でした。
