A semantic knowledge base (semantic KB) indexes your database's schema (tables, views, columns, and their comments) into a searchable vector store, so an agent can find the right relations and columns by meaning instead of guessing from column names. This is the foundation for accurate text-to-SQL: turning a natural-language question into a correct SQL query grounded in your actual schema. You can run the same searches yourself too.
Semantic KB vs. vector knowledge base
A semantic KB and a vector knowledge base 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 KnowledgeBase step | 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.
Indexing your schema
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 — see Descriptions and curation for writing those comments in a governed way.
A semantic KB also crawls your foreign keys into relationships — which tables join, on which columns, and how much that claim can be trusted — so it can answer not just "what tables exist" but "how do they connect." See Relationships.
In this section
| Page | What it covers |
|---|---|
| Searching a semantic KB | The schema-search functions: semantic_kb_search, get_metadata, comment search, and filters |
| Relationships | How tables join: the foreign-key crawl, join-path finding, manually added relationships, and drift detection |
| Descriptions and curation | Writing object descriptions with add_comment_to_object, concurrency, auditing, and an optional review queue |
| Semantic aliases | Named, parameterized SQL queries with vectorized descriptions, enabling reusable, governed text-to-SQL |
| Text-to-SQL | How an AIDB agent uses the KB's search tools to discover schema and generate correct SQL |
| Example | A worked end-to-end example over a sample schema |
Getting started
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. auto_processing controls how the KB reacts to schema changes after this — Disabled (the default), Live, or Background.
When exactly one semantic KB exists, you can omit name/kb_name from every semantic KB function, and the call resolves to that KB. An omitted name at creation registers it under the fixed name default_semkb.
For every management function's full parameters, the auto_processing modes, and every search, relationship, and curation function, see the Semantic knowledge bases reference.
Using a semantic KB
- Directly, in SQL: call the search functions (
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 text-to-SQL.
- Through saved queries: capture recurring questions as semantic aliases, parameterized SQL with a natural-language description that search can find by meaning.
Related documentation
- Agents, which covers building the in-database agents that call semantic KB search functions as tools.
- Semantic knowledge base tools, which lists the native tool catalog entries for the KB functions.
- Knowledge bases, which covers vector knowledge bases for semantic and hybrid search over your data.
- Semantic knowledge bases reference, the full API reference for every semantic KB function.