Core Concepts

Collections

A collection is a named, tenant-scoped set of documents sharing a definition: which fields exist, which are searchable, how each is searched, and which backend stores them.

Collections are the unit of everything else — a query targets one, a backend serves one, and access is scoped per tenant at the collection boundary.

Fields

A field declaration says what a value is and how it should be findable:

Field kind	Behaviour
Property	A stored value from your document
Computed	Derived at index time from other fields
Searchable	Included in the lexical index
Embedded	Vectorised for semantic search
Facet	Available for filtering and aggregation

A field can be several of these at once. A product description is typically searchable and embedded — found by keyword when someone types an exact phrase, and by meaning when they describe what they want.

Computed fields are worth reaching for more often than people do: concatenating title, summary and tags into one embedded field usually retrieves better than embedding three fields separately and merging results, because the embedding captures the relationship between them.

Embeddings

Embeddings are vector representations that place semantically similar content near each other. They are what makes “my connection keeps dropping” retrieve a page titled “Troubleshooting intermittent disconnects”, which shares no keywords with the query.

Two properties matter operationally:

The model is part of the index. Vectors from different embedding models are not comparable. Changing the model means reindexing the collection — this is the main reason reindexing exists as an operation, and the main thing to plan for before you pick a model.

Dimensionality is a storage and latency decision. Larger vectors capture more nuance and cost more to store and search. The default is usually right; change it deliberately.

Hybrid ranking

Hybrid search runs the lexical and semantic queries, then fuses the two result sets into a single ranking.

The reason this beats either alone is that the two fail differently. Lexical search has perfect precision on exact tokens and no recall on paraphrase. Semantic search has good recall on meaning and can rank a thematically-related document above an exact match — which is infuriating when the user typed a product code. Fusing them lets each cover the other’s blind spot.

query: "ERR_CONN_4021 keeps happening"
        │
        ├─▶ lexical   ──▶ the exact error-code page, rank 1
        └─▶ semantic  ──▶ intermittent-disconnect guides, ranks 1-3
                    │
                    ▼
              fused ranking: error-code page first, guides behind it

Start with hybrid. Move to pure lexical or pure semantic only when you can point at queries where fusion demonstrably hurts.

Choosing a mode

If the query is…	Use
An identifier, code, or exact name	Lexical
A natural-language question	Semantic
Mixed, or you do not know	Hybrid
A lookup over structured records you already model	Entity
Filtered by attributes as well as matched	Any mode, plus facets

Facets and filters

Facets narrow a result set by attribute — category, status, date range, owner — and are applied alongside the match rather than after it. This matters for correctness as much as speed: filtering after ranking means a limit: 10 can return two results once the filter applies, while filtering during the search returns ten matching ones.

Tenancy

Every document, collection and query carries tenant identity. Isolation is at the storage layer, not a filter applied on the way out — one tenant’s corpus is not reachable from another’s queries, including by a malformed or hostile one.

Next

• Configuration — declaring collections, fields and backends
• Operations — indexing, reindexing and monitoring