CREATE OR REPLACE でテーブルを更新すると Genie がアホになる

こちらの記事は、Databricks Advent Calendar 2025 の6日目の記事です。

TL;DR

• Genie は Unity Catalog のテーブル / カラムコメントなどのメタデータを見て SQL を組み立てる
• 特に CREATE OR REPLACE TABLE ... AS SELECT ... でテーブルを更新すると、カラムコメントが消えて Genie の性能が落ちることがある
• INSERT OVERWRITE か、CREATE OR REPLACE TABLE ... AS SELECT ... + ALTER TABLE の運用で回避しましょう

---

1. 前提・検証環境

• 対象:
  • Unity Catalog 管理テーブル
  • AI/BI Genie
• 検証環境
  • クラウド: AWS
  • Runtime: Serverless Environment 4
  • 検証日: 2025-12-03 時点

※この記事の内容は上記環境での観測結果であり、仕様は今後変わる可能性があります。

---

2. Genie は Unity Catalog のコメントをコンテキストに使う

Genie Space は、以下のような情報を基に SQL を生成します（https://docs.databricks.com/aws/ja/genie/#-genieはどのように応答を生成しますか）：

• Unity Catalog のテーブルメタデータ（テーブル名・説明・PK/FK など）
• カラム名・カラム説明
• サンプルクエリ

また、カラム名・カラム説明は Unity Catalog と同期しており、ソーステーブルのカラムコメントが更新されると、Genie Space のカラム名・カラム説明も更新されます。

Genie Space 固有で列説明を付与することも可能であり、その場合は Unity Catalog 側の同期変更は適用されません。

---

3. CREATE OR REPLACE を使うと、カラムコメントが消える

Genie のソーステーブルを全件洗い替え更新することを考えます。
Databricks において、テーブルの更新には CREATE OR REPLACE 句を使用することが推奨されています。

https://docs.databricks.com/aws/ja/sql/language-manual/sql-ref-syntax-ddl-create-table-using

Databricks strongly recommends using REPLACE instead of dropping and re-creating tables.

これは、テーブルの更新履歴や権限、行フィルターや列マスクといったメタ情報が保存されるためです。
しかし、特に CREATE OR REPLACE TABLE ... AS SELECT ... のような CTAS 形式 でテーブルを作り直すと、元テーブルに付与していたカラムコメントは引き継がれず、消えてしまいます。

検証用のクエリと結果

3.1 コメント付きテーブルを作る

CREATE SCHEMA IF NOT EXISTS t_kamei.advent_calendar_2025;

CREATE TABLE IF NOT EXISTS t_kamei.advent_calendar_2025.metadata_verification (
  col1 STRING COMMENT '氏名',
  col2 STRING COMMENT '住所'
);

コメントがついていることを確認：

DESC TABLE t_kamei.advent_calendar_2025.metadata_verification;

3.2 CREATE OR REPLACE TABLE ... AS SELECT ... で更新

-- CREATE OR REPLACE TABLE による洗い替え
CREATE OR REPLACE TABLE t_kamei.advent_calendar_2025.metadata_verification AS
SELECT 'hoge' AS col1, 'fuga' AS col2;

→ コメントが消えていることがわかります。

-- メタデータを再度確認
DESC TABLE t_kamei.advent_calendar_2025.metadata_verification;

---

4. CREATE OR REPLACE TABLE で更新すると Genie の応答品質が落ちて見える

上記の結果をまとめると、CREATE OR REPLACE TABLE ... AS SELECT ... でテーブルを更新すると、
（Genie にとって重要なコンテキスト情報である）カラムコメントが消えてしまい、
その結果として Genie の応答性能が落ちたように見えます。

テーブル更新前

カラムコメントを読んで、それを踏まえた説明を返してくれます。

テーブル更新後

同じ質問をしても、もうカラムコメントは参照されません。

今回は、挙動をわかりやすくするためにあえてシンプルで情報量の少ないカラム名にしています。
例えばカラム名を user_name のようにしておけば、カラム名から推察して「このカラムには名前が入っている」とある程度推論してくれる可能性があります。

---

5. 代替案

コメントが消えないようにテーブルの洗い替え更新をする方法を 2 つ紹介します。

案1: INSERT OVERWRITE

INSERT OVERWRITE TABLE t_kamei.advent_calendar_2025.metadata_verification
SELECT col1, col2
FROM some_source_table;

INSERT OVERWRITE は、Delta テーブルに対して truncate + insert をアトミックに実行できる SQL コマンドです。 （ドキュメント: https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-dml-insert-into ）
テーブル定義（コメント含む）を変えずにデータだけ入れ替えるので、メタデータが維持されます。

案2: CREATE OR REPLACE + ALTER TABLE

-- スキーマを変えたいタイミングだけ実行（CTAS）
CREATE OR REPLACE TABLE t_kamei.advent_calendar_2025.metadata_verification AS
SELECT col1, col2
FROM some_source_table;

-- ALTER TABLE にてコメントを再付与
ALTER TABLE t_kamei.advent_calendar_2025.metadata_verification
  ALTER COLUMN col1 COMMENT '氏名';

ALTER TABLE t_kamei.advent_calendar_2025.metadata_verification
  ALTER COLUMN col2 COMMENT '住所';

CREATE OR REPLACE TABLE ... AS SELECT ... でテーブルを作り直したあと、
ALTER TABLE ... ALTER COLUMN ... COMMENT でカラムコメントを付け直す方法です。
スキーマ変更を伴う場面で CTAS を使いたい場合のパターンとして使えます。

---

6. まとめ

• Genie は Unity Catalog のテーブル / カラムコメントなどのメタデータを見て SQL を組み立てる

• CREATE OR REPLACE TABLE ... AS SELECT ... でテーブルを更新すると、カラムコメントが消えて Genie の性能が落ちることがある

• 日々の洗い替え更新は INSERT OVERWRITE を使い、どうしても CTAS が必要な場合は CREATE OR REPLACE TABLE ... AS SELECT ... + ALTER TABLE でコメントを補完する運用にしておくと、安全に Genie 用テーブルを保守できます