Semantic knowledge bases#

A semantic knowledge base (semantic KB) indexes your database’s schema (tables, views, columns, and their comments) into a searchable vector store, so you or an Agents reference can find the right relations and columns by meaning rather than by exact name. It’s the foundation for text-to-SQL: turning a natural-language question into a correct SQL query against your own schema.

Semantic KB vs. vector knowledge base#

A semantic KB and a Knowledge bases reference both store embeddings and answer similarity searches, but they index different things and solve different problems.

	Vector knowledge base	Semantic knowledge base
What it embeds	Your data (rows, documents, images)	Your schema (table, view, and column metadata)
What you search	Content, by meaning	Schema structure, by meaning
Created by	aidb.create_pipeline() with a AI pipelines	aidb.create_semantic_kb()
Typical use	Retrieval-augmented generation, semantic search	Natural-language schema discovery, agent tools, text-to-SQL

If you want to search what’s in your database, use a vector knowledge base. If you want to search how your database is shaped, to find the tables and columns a question maps to, use a semantic KB.

What a semantic KB indexes#

When a semantic KB crawls its schemas, it embeds one entry per structural element:

Tables contribute their table definition and any table comment.
Views contribute their view definition and any view comment.
Columns contribute each column’s definition (name, type, nullability, default) and any column comment.

Each entry has an entity_type of Table , View , or Column . Comments matter: a well-commented schema produces a far more useful semantic KB, because the natural-language intent in COMMENT ON statements is embedded alongside the structural definition and can be matched directly.

Create and manage a semantic KB#

Create a semantic KB over one or more schemas with aidb.create_semantic_kb() . It embeds the schema metadata with the model you pass, builds the KB’s internal vector table, and crawls the schemas immediately:

SELECT aidb.create_semantic_kb(
    name    => analytics_kb,
    model   => my_embedding_model,
    schemas => ARRAY[sales],
    auto_processing => Live
);

model is the embedding model and is always required. A semantic KB uses a single embedding model for all of its metadata (and for any Semantic aliases that are members of it), so search always compares vectors in the same space.

The management functions are:

Function	Purpose
aidb.create_semantic_kb(name, model, schemas, auto_processing, bypass_triggers, vector_index)	Create a KB over one or more schemas. Returns the KB name.
aidb.list_semantic_kbs()	List every KB with its model, schemas, and processing mode.
aidb.refresh_semantic_kb(name)	Re-crawl the KB's schemas from scratch to pick up structural changes.
aidb.update_semantic_kb_auto_processing(name, auto_processing)	Change how the KB keeps itself current.
aidb.semantic_kb_stats(kb_name)	Return entity counts (total, tables, views, columns) and the number of pending schema changes.
aidb.delete_semantic_kb(name)	Delete a KB and its indexed metadata.

The single-KB shortcut#

When exactly one semantic KB exists, you can omit name /kb_name from every function, and the call resolves to that KB. An omitted name at creation registers the KB under the fixed name default_semkb . Once a second KB exists, calls that omit the name fail with an ambiguity error, so pass the name explicitly from then on.

Keeping a KB current#

The auto_processing mode controls how a KB reacts to schema changes:

Mode	Behavior
Disabled (default)	No automatic updates. Call aidb.refresh_semantic_kb() when the schema changes.
Live	DDL triggers re-crawl affected relations as soon as the schema changes.
Background	A background worker processes queued DDL events, so re-indexing happens off the write path.

Internally, Background mode is driven by AIDB’s pipeline machinery, where a SemanticKB pipeline step consumes the queued schema-change events. You don’t create or manage that pipeline yourself; aidb.create_semantic_kb() sets it up.

How you use a semantic KB#

Directly, in SQL. Call the Searching a semantic knowledge base (aidb.semantic_kb_search() and friends) to find the schema entities a question maps to.
From an agent. The KB search functions are registered as native agent tools , so an AIDB agent can discover schema and answer questions with Example: a text-to-SQL agent .
Through saved queries. Capture recurring questions as Semantic aliases : parameterized SQL with a natural-language description that search can find by meaning.

In this section#

Page	What it covers
Searching a semantic knowledge base	The schema-search functions: semantic_kb_search, get_metadata, comment search, and filters
Semantic aliases	Named, parameterized SQL queries with vectorized descriptions, enabling reusable, governed text-to-SQL
Example: a text-to-SQL agent	How an AIDB agent uses the KB's search tools to discover schema and generate correct SQL
Examples	A worked end-to-end example over a sample schema

Semantic knowledge bases

Contents