Manage an Index

Read index health, query semantic and metadata results, inspect index jobs, update documents, and manage index configuration.

5 min read

Open Data → Indexes to see every index in the project.

The Indexes list with status, folder, document, and part counts

The list shows:

Column	Meaning
Name	Opens the index.
Status	Current index or vector-store state.
Folder	Source folder for a standard index.
Documents	Number of source documents represented by the index.
Document Parts	Number of searchable chunks created from those documents.
Last Indexed	Time of the latest successful index update.

Use All, search, column, density, and full-screen controls to focus the list. Select rows to archive indexes in bulk.

Read index health

The top line shows the embedding model, vector dimensions, and text-splitter type, size, and overlap. The health cards mean:

Card	Meaning
Folder	Project folder selected by the index.
Documents	Documents currently selected from that folder.
Indexed	Documents with a live indexed version.
Need Embeddings	Documents whose parts have not yet received embeddings.
Out of Sync	Documents whose stored index version no longer matches the current document.
Errors	Documents that failed indexing.

The document table identifies each file’s index status, content type, dates, and full path. Select rows and then Index Selected Item when only specific documents need another attempt. With no row selected, the same button reads Run Index Update and processes the index’s pending work.

Edit settings

Select Edit.

You can change:

Index Name
Auto Index when documents are added or modified
Materialized Columns, including typed columns and column indexes, through Configure

The folder, embedding model, dimensions, chunk size, and chunk overlap are shown for reference. Changes to materialized column definitions require a rebuild.

See Materialized Columns for typed-column expressions, column indexes, query examples, and rebuild behavior.

Index actions

Action	What it does
Edit	Opens editable index settings and materialized column configuration.
Query	Opens semantic search and metadata SQL in a side panel.
Index Jobs	Shows related indexing, auto-index, download, removal, provisioning, update, and rebuild jobs.
Run Index Update	Processes pending document changes. With selected rows, the label changes to Index Selected Item.
More actions	Opens less frequent maintenance actions such as Test Index, rebuild, full sync, download, and delete when they apply.
Rebuild Index	Recreates the searchable relation after a materialized-column schema or projection change.
Full Sync Index	Synchronizes all vector and metadata rows. This can take longer than a normal update.
Download Index	Starts an export job for the index.
Delete Index	Archives the index after confirmation. This does not delete the source documents.

Maintenance actions appear only when they apply. Update and maintenance buttons are disabled while a conflicting index job is active.

Query an index

Select Query to open the Query panel. It has two modes.

Semantic Search

Use Semantic Search to test the same kind of retrieval a flow or agent performs.

Setting	What it does
Search text	Text that BotDojo embeds and compares with indexed document parts.
Results	Maximum number of matching parts to return, from 1 to 100.
WHERE	Optional SQL `WHERE` expression. Enter only the condition, not `SELECT` or `WHERE`.
JSON	Optional complete JSON filter object. Use `{}` for no filter.
Run Semantic Search	Returns ranked parts with score, text, metadata, document ID, and part ID.

Start without a filter and ask a question whose answer you know. Inspect the returned text and metadata, not only the score. A useful result contains enough surrounding context to answer the question and metadata that identifies its source.

Materialized columns are available in the WHERE editor with their col_ names. For example:

col_department = 'support' AND col_published_at >= '2026-01-01'

Metadata Query

Use Metadata Query to inspect stored rows, JSON metadata, and materialized columns through the virtual table name index_table. The default query selects id, configured col_ columns, and meta.

select id, col_department, col_priority, meta
from index_table
where col_department = 'support'
order by col_priority desc
limit 25

Select Run Query or press Command/Ctrl+Enter. Use this mode to confirm field names, check converted values and null rows, develop filters, and verify a materialized column before using it in semantic search.

View index jobs

Select Index Jobs to open the job history scoped to the current index. The summary shows active, completed, and error counts together with the index’s current health.

The Index Jobs dialog with health, job counts, status, and progress

The table includes:

Column	How to use it
View	Opens the full job record, including its updates and error details.
Job Type	Identifies indexing, auto-index, download, removal, provisioning, update, rebuild, or related work.
Status	Shows the current state, progress percentage, and latest update message.
Modified / Created	Helps correlate a job with a document change or configuration update.
Error	Shows the failure summary. Open the job for the complete detail.
ID	Identifies the job when troubleshooting logs or support cases.

Select Refresh when a running job has not updated yet. When Need Embeddings, Out of Sync, or Errors is nonzero, use this view to find the relevant job before rerunning the affected documents.

Diagnose common states

Need Embeddings is greater than zero: run an index update and check that the embedding connection is available.
Out of Sync is greater than zero: documents changed after their indexed version; run an update.
Errors is greater than zero: open Index Jobs, inspect the failed job, correct the document or configuration, and index the selected items again.
Document count is lower than expected: verify the source folder, loader destination, and any projection or metadata filter.
Search results are too broad: reduce chunk size, add better metadata filters, or create a purpose-specific projection.
Search results lack context: increase chunk size or overlap, or use a custom chunker.