semantic-layer-usage

Keboola セマンティックレイヤーを安全に使用する

Keboola MCP のシステムプロンプトには、セマンティックレイヤーのワークフローがすでに記載されています （search_semantic_context で検索し、get_semantic_context で確認し、 validate_semantic_query で検証してから、query_data を実行します）。このスキルでは、そのワークフローで 明示されていない失敗パターンを 1 つ補足します。

セマンティックレイヤーには物理マッピングがすでに含まれています。これを使い、迂回しないでください。 semantic-dataset は tableId と fqn を返し、semantic-metric は SQL を返します。ビジネス向けの表示名（Total Revenue というラベルのフィールドや、Trips というエンティティ）は、物理列ではありません。定義の上に付けられたラベルです。ツールがすでに返した定義を使わず、これらのラベルから SQL を書いてしまうことが失敗の原因です。

唯一のルール

アプリ、トランスフォーメーション、レポートのコードに SQL を組み込む前に、Keboola MCP で実際の列名を確認してください。たとえば、データセットの tableId に対して get_table を実行します。また、メトリックの SQL は再考案せず、そのまま使用してください。search_semantic_context で関連情報が見つからない場合、参照できるモデルはありません。その旨を伝え、未加工の Storage を対象に作業してください。これらの確認をどのようにまとめて実行するかは任意です。

使用例 — このスキルで防げる失敗

ユーザーは Kai に、out.c-nyc-aggregations-duckdb.rpt_* テーブルを使い、セマンティックレイヤーを基にダッシュボードを作成するよう依頼しました。Kai はセマンティックコンテキストを確認しましたが、物理列を確認せず、セマンティック表示名からダッシュボードの SQL を作成しました。表示名は rpt_* のスキーマと一致しなかったため、すべてのクエリが失敗しました。コンテナは「実行中」だったにもかかわらず、ダッシュボードには何も表示されず、Kai は検証せずに成功を報告しました。

代わりに根拠とするものは次のとおりです。

search_semantic_context(patterns=["nyc trips", "daily revenue"])
  → metric "daily_revenue", dataset with tableId out.c-nyc-aggregations-duckdb.rpt_daily
get_semantic_context(...)  → metric SQL + dataset tableId + fqn (the physical mapping)
get_table(table_id="out.c-nyc-aggregations-duckdb.rpt_daily")
  → real columns: pickup_date, fare_total, trip_count  (NOT the display labels)

ユーザーが考えるラベル（「revenue」）に対応する物理列は fare_total です。セマンティック定義に記載されているので、推測せずに定義を読んでください。

関連情報

• dataapp-development スキル — アプリのライフサイクル全体を扱います。../dataapp-development/references/storage-access.md ではバックエンドごとの FQN の引用方法を、../dataapp-development/references/dev-workflow.md では検証を先に行う手順を説明しています。データソースがセマンティックモデルの場合は、このスキルと併せて読み込んでください。