meatabase 連携まで：おすすめ工程（常に動く / 途中でも価値が出る）

目的：/nlq/execute が rows を返しつつ、shape判定も返す（Metabaseはまだ繋がない）

app/services/shape/
- base.py：ShapeAdapter interface（id/describe/match/normalize）
- registry.py：登録・選択（まずルールで確定、ダメならtable.generic）
- adapters/time_series.py, ranking.py, scalar.py, table.py（最低4つ）
/nlq/execute のレスポンスに 後方互換で追加
- shape: {adapter_id, confidence, params} を meta かトップレベルに追加（どっちでもOK。あなたのAPI規約に合わせる）

✅ この時点で「固定shapeの拡張方式」が確定して、実装が前に進みます。

目的：rowsをキャッシュテーブルへ保存して、run_idで参照できる

ここがキモで、汎用テーブルにJSONBで突っ込むより、**shapeごとに“安定した縦持ちテーブル”**にすると後がラクです。

例（おすすめ）：

time_series 用：nlq_cache_timeseries
- run_id, bucket_date, metric_name, metric_value_num, metric_value_text
ranking 用：nlq_cache_ranking
- run_id, rank, dimension, metric_name, metric_value_num
scalar 用：nlq_cache_scalar
- run_id, key, value_num, value_text, value_date
table.generic 用：nlq_cache_kv（最後の逃げ道）
- run_id, row_idx, col_name, value_text, value_num, value_date

Adapter側に write_cache(normalized) -> cache_ref を持たせる（＝プラグインの責務）と拡張が綺麗です。

✅ この時点で「Metabaseカードはrun_idパラメータで引く」が成立します。

目的：shapeに応じて “固定カードID” を選び、run_idを渡して埋め込む

MetabaseSpec（shape→カード/パラメータ名の対応）を追加
MetabaseEmbed を呼んで signed/public URL を生成
/nlq/execute の stats.metabase / stats.metabase_items をちゃんと埋める
（今は null のままなのでここで初めて繋がる）

✅ フロントは「Metabase iframe で表示」が完成します。

目的：拡張性UP。ただし LLMは最終決定者にしない。

✅ ここで「ShapeAdapterを追加しやすい」が完成します。

目的：routeがCYPHER系ならMetabaseではなくGraph表示にできる足場

GraphAdapter registry（まずは graph.placeholder だけ）
/nlq/execute のレスポンスに execution_kind: "graph" と graph: {nodes, edges, meta} を出すだけ

✅ DeciKG未実装でも、UI側は切り替え可能になります。

「一気に」やる場合の現実

一気にやるなら 工程1〜3は同時に触ることになるので、落とし穴はこの3つです：

なので、やるなら 最低でも 1→2→3 の順で動作確認しながらが安全です。

Comments