Semantic aliases#

A semantic alias is a named, parameterized SQL query paired with a natural-language description. The description is embedded, so an alias can be found by meaning — the same way schema metadata is. Aliases are the reusable, governed layer of text-to-SQL: instead of generating fresh SQL for every question, a recurring question resolves to a query you’ve already written and reviewed.

Each alias is a member of every semantic KB that owns the schema its SQL reads — not just one. AIDB infers the owning KB(s) from the query and embeds the alias’s description once per KB, using that KB’s model, so each embedding stays comparable to that KB’s schema vectors. A schema owned by two KBs yields two embeddings, and the alias is then findable — with aidb.semantic_kb_search() — from either KB.

!!!note Semantic aliases are managed and run with the aidb SQL functions below. Unlike the KB search functions, alias functions are not exposed as agent tools — by product decision, an agent discovers and reads schema, but doesn’t create or execute aliases itself.

Creating an alias#

aidb.create_semantic_alias() takes a unique name, a description to embed, the SQL query text, and its parameter definitions. Placeholders in the query use ${name} syntax. The query must be a single read-only 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	—	Unique alias name.
description	text	—	Human-readable description — this is what gets embedded for search.
query_text	text	—	A single read-only SELECT, with ${name} placeholders for parameters.
params	jsonb	NULL	Array of parameter definitions (see below).
kb_name	text	NULL	Optional; narrows the alias to just this KB. Omit to embed it for every KB that owns the query's schema(s).

Each entry in the params JSONB array has:

Field	Required	Description
name	Yes	Matches a ${name} placeholder in query_text.
param_type	Yes	PostgreSQL type: text, integer, numeric, date, and so on.
description	No	Human-readable description of the parameter.
enum_values	No	Allowed values, when the parameter is constrained to a set.

If the query’s schema maps to more than one KB, the alias is embedded once for each of them — creation never fails on ambiguity; pass kb_name only to narrow it to a single KB. A schema not yet owned by any KB leaves the alias unembedded, until a KB covering it is created or adopts it later.

Finding an alias#

aidb.search_semantic_aliases() searches aliases by natural-language query. Without kb_name , it searches default_semkb — the name a KB gets when created without an explicit one — if that KB exists, or every KB with stored alias embeddings otherwise; the query is embedded once per distinct model among those KBs, so the search stays dimension-safe, and results are de-duplicated to the best match per alias.

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	—	Natural-language query.
min_similarity	double precision	NULL	Optional similarity floor.
top_k	int	10	Maximum results.
offset	int	0	Paging offset.
kb_name	text	NULL	Optional; narrows the search to this KB. Omit to resolve default_semkb, or all KBs with alias embeddings, per the precedence above.

It returns name , query_text , and similarity . Aliases also appear in aidb.semantic_kb_search() results with source_type = 'alias' , so a single composite search finds both schema and aliases at once.

Running an alias#

aidb.execute_semantic_alias() runs an alias by name, substituting its parameters. It returns a set of result rows, each a JSONB object:

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

Parameter	Type	Default	Description
alias_name	text	—	Alias to run.
args	jsonb	NULL	Object of parameter values keyed by name.
execute_role	text	NULL	PostgreSQL role to run the query as — requires the appropriate SET ROLE grants.

Use execute_role to run an alias under a least-privilege reporting role rather than the connecting user. Because every alias is validated as a single read-only SELECT at creation and re-validated at execution, an alias can’t be used to run writes.

Managing aliases#

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.

Deleting a KB removes only that KB’s embedding of each alias — the alias definition, and its embeddings in any other owning KBs, survive. A later KB covering the same schema adopts the alias, adding a fresh embedding for it, even if the alias is already embedded for other KBs.

Next steps#

See how an agent combines schema search and aliases into an end-to-end Example: a text-to-SQL agent workflow.
Walk through aliases and search together in the Examples .

Semantic aliases

Contents