Semantic aliases
================

**セマンティックエイリアス**
は、自然言語の説明とペアになった名前付けのパラメーター化SQLクエリーです。説明が埋め込まれているため、スキーマのメタデータと同じように、意味からエイリアスを見つけることができます。エイリアスは、text-to-
SQLの再利用可能な管理レイヤーです。質問ごとに新しいSQLを生成する代わりに、繰り返しの質問は、既に作成およびレビューしたクエリに解決されます。

各エイリアスは、 SQLが読み取るスキーマを所有する *すべての*
セマンティックKBのメンバーです。1つだけではなく。
AIDBは、クエリから所有するKBを推論し、そのKBのモデルを使用してKBごとに1回エイリアスの説明を埋め込むため、各埋め込みはそのKBのスキーマベクトルと比較可能なままです。
2つのKBが所有するスキーマは2つのエンベディングを生成し、エイリアスは :ref:`promoteb.semantic_kb_search() <promoteb.semantic_kb_search()>` を使用してどちらのKBからでも見つけられます。

!!!note セマンティックエイリアスは、以下の\ ``aidb``
SQLファンクションで管理および実行されます。 KB
*search*\ ファンクションとは異なり、エイリアスファンクションは :ref:`agent tools <Knowledge bases reference>` として公開されません*\*
。製品の決定により、エージェントはスキーマを検出および読み取りますが、エイリアス自分自身を作成または実行しません。

エイリアスを作成する
--------------------

``aidb.create_semantic_alias()`` は、一意の名前、埋め込む説明、
SQLクエリテキスト、およびそのパラメーター定義を取得します。クエリーのプレースホルダーは\ ``${name}``
構文を使用します。クエリーは単一の読み取り専用の\ ``SELECT``
である必要があります。

.. code:: sql

   SELECT aidb.create_semantic_alias(
       name        => monthly_revenue,
       description => Total revenue for a given month and year,
       query_text  => $$
           SELECT SUM(amount) AS total
           FROM sales.orders
           WHERE EXTRACT(MONTH FROM order_date) = ${month}
             AND EXTRACT(YEAR  FROM order_date) = ${year}
       $$,
       params => [
           {"name": "month", "param_type": "integer", "description": "Month number (1-12)"},
           {"name": "year",  "param_type": "integer", "description": "Four-digit year"}
       ]
   );

.. csv-table::
  :header: Parameter,Type,Default,Description
  :widths: 15,12,12,20
  :align: left
  :class: longtable

  `name`,`text`,—,一意のエイリアス名。
  `description`,`text`,—,人間が読める説明 — これは検索のために埋め込まれるものです。
  `query_text`,`text`,—,単一の読み取り専用の`SELECT`と、パラメーターの`${name}`プレースホルダー。
  `params`,`jsonb`,`NULL`,パラメーター定義の配列以下を参照してください。
  `kb_name`,`text`,`NULL`,オプショナル。エイリアスをこのKBのみに絞り込みます。クエリのスキーマを所有するすべてのKBへの埋め込みを省略します。

``params`` JSONB配列の各エントリは次のとおりです。

.. csv-table::
  :header: Field,Required,Description
  :widths: 12,15,15
  :align: left
  :class: longtable

  `name`,Yes,`query_text`の`${name}`プレースホルダーと一致します。
  `param_type`,Yes,PostgreSQLタイプ `text`、`integer`、`numeric`、`date`など。
  `description`,No,人間が読めるパラメーターの説明。
  `enum_values`,No,パラメーターがセットにコンストレインされている場合、許可される値。

クエリのスキーマが複数のKBにマッピングされている場合、エイリアスはそれぞれに1回埋め込まれます。作成があいまいでも失敗することはありません。
``kb_name`` を渡して単一のKBに絞り込みます。
KBがまだ所有していないスキーマは、それをカバーするKBが作成されるか、後で採用されるまで、エイリアスが埋め込まれないままです。

エイリアスを見つける
--------------------

``aidb.search_semantic_aliases()``
は、自然言語クエリーによってエイリアスを検索します。 ``kb_name``
がないと、 ``default_semkb`` —
明示的な名前なしで作成されたときにKBが取得する名前 —
そのKBが存在する場合、またはそれ以外の場合は、保存されたエイリアス埋め込みを持つすべてのKBを検索します。クエリは、これらのKBの間の個別のモデルごとに1回埋め込まれるため、検索はディメンションセーフなままで、結果はエイリアスごとに最も一致するように重複排除されます。

.. code:: sql

   SELECT name, query_text, similarity
   FROM aidb.search_semantic_aliases(
       query_text => how much money did we make last month,
       kb_name    => analytics_kb,
       top_k      => 5
   );

.. csv-table::
  :header: Parameter,Type,Default,Description
  :widths: 15,12,12,20
  :align: left
  :class: longtable

  `query_text`,`text`,—,自然言語クエリー。
  `min_similarity`,`double precision`,`NULL`,オプションの類似度フロア。
  `top_k`,`int`,`10`,最大の結果。
  `offset`,`int`,`0`,ページングオフセット。
  `kb_name`,`text`,`NULL`,オプショナル。検索をこのKBに絞り込みます。上記の優先順位に従って、`default_semkb`またはエイリアス埋め込みを含むすべてのKBの解決を省略します。

``name`` 、\ ``query_text`` 、および\ ``similarity``
を結果ます。エイリアスは\ ``source_type = 'alias'``
の :ref:`promoteb.semantic_kb_search() <promoteb.semantic_kb_search()>` 結果にも表示されるため、1つの複合検索で一度にスキーマとエイリアスの両方が検出されます。

エイリアスを実行する
--------------------

``aidb.execute_semantic_alias()``
は、パラメーターを置き換えて、名前でエイリアスを実行します。それぞれがJSONBオブジェクトである\ ``result``
行のセットを結果ます。

.. code:: sql

   SELECT result
   FROM aidb.execute_semantic_alias(
       alias_name => monthly_revenue,
       args       => {"month": 3, "year": 2025}
   );

.. csv-table::
  :header: Parameter,Type,Default,Description
  :widths: 15,12,12,20
  :align: left
  :class: longtable

  `alias_name`,`text`,—,実行するエイリアス。
  `args`,`jsonb`,`NULL`,名前でキー設定されたパラメーター値のオブジェクト。
  `execute_role`,`text`,`NULL`,クエリを実行するPostgreSQLロール — 適切な`SET ROLE`付与が必要です。

``execute_role``
を使用して、接続しているユーザーではなく最小権限のレポートロールでエイリアスを実行します。すべてのエイリアスは作成時に単一の読み取り専用の\ ``SELECT``
として検証され、実行時に再検証されるため、エイリアスを使用して書き込みを実行することはできません。

エイリアスの管理
----------------

.. csv-table::
  :header: Function,Purpose
  :widths: 10,30
  :align: left
  :class: longtable

  `aidb.get_semantic_aliases()`,"List all aliases with `name`, `description`, `query_text`, and `param_count`."
  `aidb.get_semantic_alias(alias_name)`,"Get one alias's `name`, `description`, `query_text`, and `params`."
  "`aidb.update_semantic_alias(name, description, query_text, params, kb_name)`",Update an alias; changing `query_text` or `kb_name` re-infers its owning KB(s) and reconciles embeddings — adding KBs it newly belongs to and dropping ones it no longer does. Changing `description` re-embeds it in every KB it's already in.
  `aidb.delete_semantic_alias(name)`,Delete an alias by name.

KBを削除すると、そのKBの各エイリアスの埋め込みのみが削除されます。エイリアス定義、および他の所有するKBへのその埋め込みは残ります。同じスキーマをカバーする後のKBは、エイリアスが他のKBに既に埋め込まれている場合でも、そのエイリアスを採用し、その新しい埋め込みを追加します。

次のステップ
------------

- エージェントがスキーマ検索とエイリアスをエンドツーエンドの :ref:`例 text-to- SQLエージェント <例 text-to- SQLエージェント>` ワークフローに組み合わせる方法を確認します。

- エイリアスをウォークスルーし、 :ref:`Examples <Examples>` で一緒に検索します。