How semantic search works
Understand embeddings, similarity, model changes, and reindexing.
What an embedding is
An embedding is a fixed-length numeric vector that represents text or an image. Inputs with similar meaning land close together in the vector space.
Omnio uses IEmbedder to produce embeddings and stores them as Float32Array values in the index.
const object = await omnio.putObject({
key: "notes/a.txt",
data: bytes,
contentType: "text/plain",
description: "The sun setting over the sea",
});
Here, Omnio embeds description and records the model in embeddingModel, the dimensions in embeddingDims, and the source in embeddingSource.
What gets embedded
By default, putObject embeds only description.
- Tags are not embedded.
- Stored file bytes are not embedded, regardless of their content.
- Image queries embed the image and compare it with stored description embeddings.
To search file contents, store a description of those contents.
Similarity
SQL indexes support two similarity metrics.
| Metric | Score | Meaning |
|---|---|---|
cosine |
Cosine similarity | Ranges from -1 to 1; larger is closer. |
l2 |
Negative L2 distance | 0 is closest; smaller values are farther away. |
Omnio.searchObjects does not pass metric, so it always uses cosine similarity. To use L2, call IObjectIndex.search directly.
minScore applies to this score. Because the metric changes what the value means, inspect real scores before choosing a threshold.
Models and dimensions
Stored vectors depend on the model that produced them. Comparing vectors from different models in one search does not produce meaningful results.
Omnio prevents mixing models in several ways.
putObjectrecordsembedder.info.nameinembeddingModel.- Text and image queries in
searchObjectsconsider only rows with the same model name. open()marks rows whose model name or dimensions differ from the current settings as dirty.
After a model change, affected rows are excluded from search until reindexing completes. Metadata reads and listings still return them.
Reindexing
Reindexing embeds the description again with the current embedder.
open()processes dirty rows in the background.reindexObjectprocesses one object explicitly.- Updating a description does not reindex automatically; call
reindexObject.
If an object is updated or deleted during reindexing, Omnio does not write back an old snapshot. It applies the result if the description and entity are unchanged, and otherwise gives up.
How search executes
The current SQL indexes do not create approximate nearest-neighbor vector indexes. Search scans the rows that match the filter and computes exact similarities.
Search time therefore grows with the number of candidates. For large datasets, consider:
- using
filterto reduce candidates; - lowering
topK; - implementing a custom index with approximate nearest-neighbor search.
Reads do not wait for writes. A search uses only embeddings that are complete at that moment. Rows whose background embedding is still running are not included.
Full text versus semantic search
MetadataFilter.fullText is a substring match against the description and key. It does not tokenize or rank.
Semantic search can match inputs with different wording when their meaning is close. Choose according to the task.
// Literal match
await omnio.listObjects({ filter: { fullText: "sunset" } });
// Meaning
await omnio.searchObjects({ query: { text: "dusk by the sea" } });