Semantic aliases#

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

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

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

エイリアスを作成する#

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

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"}
    ]
);

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

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

Field	Required	Description
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回埋め込まれるため、検索はディメンションセーフなままで、結果はエイリアスごとに最も一致するように重複排除されます。

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
);

Parameter	Type	Default	Description
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' の promoteb.semantic_kb_search() 結果にも表示されるため、1つの複合検索で一度にスキーマとエイリアスの両方が検出されます。

エイリアスを実行する#

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

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

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

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

エイリアスの管理#

Function	Purpose
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に既に埋め込まれている場合でも、そのエイリアスを採用し、その新しい埋め込みを追加します。

次のステップ#

エージェントがスキーマ検索とエイリアスをエンドツーエンドの例 text-to- SQLエージェントワークフローに組み合わせる方法を確認します。
エイリアスをウォークスルーし、 Examples で一緒に検索します。

Semantic aliases

目次