Semantic aliases v7

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.

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

Each entry in the params JSONB array has:

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

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

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

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 text-to-SQL workflow.
• Walk through aliases and search together in the example.