Documentation Index
Fetch the complete documentation index at: https://nikita-shkoda.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Method & sources
- Primary: Official Typesense docs (API reference + feature guides), favoring versioned pages. Inline citations use bracketed labels (e.g., [TS‑SearchParams]). See Sources for URLs.
- Cross‑checks: When behavior seemed ambiguous, we verified across Search Parameters, Faceting, and Feature pages.
- Versioning: When docs do not specify version gates, we mark as TBD.
Capability tables
Each table lists exact server parameter names, constraints, interactions, proposed DSL shape (additive/back‑compat), compiler mapping, and ship bucket.
1) Union (logical OR across collections/queries)
| Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket | |
|---|
| Union across collections/queries | multi_search endpoint with searches: [...] payload; each search has its own collection, q, query_by, etc [TS‑MultiSearch] | TBD | Results are independent per search; no native cross‑collection dedupe/merge. Response size/latency grows with N searches. | Pagination, sorting, and faceting are per‑search. | N/A | `union(queries:, merge: :append | :interleave, dedupe_by: nil)` | Compile to a Multi‑search request; perform merge/dedupe client‑side (respect sort orders). | Back‑compatible; purely additive. Clarify that ranking is not recomputed across collections. | M | Later |
2) Synonyms / Stopwords (management + query‑time switches)
| Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket |
|---|
| Synonym sets (per collection) | Synonyms API: CRUD at /collections/{collection}/synonyms [TS‑Synonyms] | TBD | Stored per collection; large sets affect index size and build times. | Affects token expansion and recall; interacts with typo tolerance. | Applied if present; no per‑query override documented. | manage_synonyms(add:[], upsert:[], delete:[]) | Use client to call Synonyms API (out of band from Relation). | Management is orthogonal to query DSL; document CLI/doctor checks. | M | Later |
| Stopword lists (per collection) | Stopwords API: CRUD at /collections/{collection}/stopwords [TS‑Stopwords] | TBD | Excessive stopwords can reduce recall. | Interacts with token dropping thresholds. | Applied if present; no per‑query override documented. | manage_stopwords(add:[], upsert:[], delete:[]) | Use client to call Stopwords API (out of band). | Same as synonyms; ensure indexer/docs cover precedence. | M | Later |
3) Highlighting controls
| Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket |
|---|
| Highlighting | highlight_fields, highlight_full_fields, highlight_affix_num_tokens, highlight_start_tag, highlight_end_tag [TS‑SearchParams] | TBD | Increasing affix tokens inflates payload size. | Interacts with include_fields/exclude_fields. | Start/end tags default to <mark>/</mark>; affix tokens default commonly to 4. | highlight(fields:, full_fields: nil, affix_tokens: 4, start_tag: "<mark>", end_tag: "</mark>") | Map 1:1 to highlight_* params; validate field presence against schema; redact highlighted text in logs via DX helpers. | Additive; default off maintains current behavior. | L | Now |
include_fields and exclude_fields hiding all highlighted fields; hint with [Error UX] to enable specific fields. [TS‑SearchParams]
4) Advanced faceting
| Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket |
|---|
| Facets (basic + query) | facet_by, max_facet_values, facet_query [TS‑Faceting] | TBD | Large facet cardinalities increase response size and compute. | Interacts with filters and grouping; per‑page/page do not affect facet counts. | max_facet_values default commonly 10. | facet(by:, max_values: nil, query: nil) | Map 1:1; split multi‑field lists by comma; validate fields are facetable in schema. | Additive; aligns with existing Typesense semantics. | M | Now |
| Nested/combined facets; sampling; custom facet sort | Not documented as first‑class features [TS‑Faceting] | — | Treat as unsupported server‑side for now. | — | — | facet_nested(...), facet_sample(...), facet_sort(...) (shapes reserved) | N/A (intentionally not compiled) | Document as deferred; capture use‑cases. | M | Later |
5) Geo — Shipped
| Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket |
|---|
| Geo filters & distance sort | filter_by with geopoint expressions; sort_by with distance for a geopoint field [TS‑Geo] [TS‑FieldTypes] | 30.1 | Requires geopoint field in schema; precision depends on indexing. | Interacts with other filters and sorts; grouping unaffected. | N/A | where_geo(field, within_radius: / within_polygon:), order_geo(field, from:), order_eval(expr) | Compile to filter_by geo predicate and sort_by distance/eval tokens; validate schema geopoint type and coordinates. | Additive; no effect unless used. | Resolved | Shipped |
Geo search is now fully implemented. See the Geo Search guide for DSL reference, configuration, and examples. 6) Vectors / AI (vector fields, ANN params, hybrid) — Shipped
| Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket |
|---|
| Vector search | vector_query with syntax field:([vector], k:N, alpha:0.8, ...); schema float[] field with embed block or num_dim [TS‑Vector] | 30.1 | Vector dimensionality must match schema; high k affects latency. | Hybrid with keyword search uses rank fusion (alpha); embedding field auto-appended to query_by. | Embedding field auto-excluded from response. | embedding macro (schema), vector_search(field, k:, alpha:, ...), find_similar(id, field:) | Compile to vector_query string; auto query_by in hybrid mode; auto exclude_fields; order(vector_distance:) sort alias. | Additive; no effect unless used. | Resolved | Shipped |
Vector search is now fully implemented. See the Vector Search guide for DSL reference, configuration, and examples. | Capability | Typesense params (authoritative names) | Since | Constraints & limits | Interactions | Defaults (server) | Proposed DSL surface (back‑compat) | Compiler mapping (Relation → params) | Migration notes | Risk | Ship bucket |
|---|
| Pagination & caps | per_page, page, group_by, group_limit, exhaustive_search, search_cutoff_ms [TS‑Pagination] [TS‑Grouping] [TS‑SearchParams] | TBD | Large per_page inflates payloads; exhaustive_search:false can truncate recall under cutoff. | Grouping limits apply within groups; affects perceived per‑page. | page=1, per_page=10 typical defaults. | limit(per_page:, page: 1), group(by:, limit:), exhaustive(on:), cutoff_ms(ms:) | Map 1:1; validate positive integers; hint when group_limit * groups < per_page. | Additive; preserves current defaults when unset. | L | Now |
Recommendations
-
Now (ship in this bucket)
- Highlighting controls: 1:1 param mapping; low risk; straightforward compile‑time validation. Add DX redaction for highlighted snippets in logs. Minimal DSL:
highlight(fields:, full_fields:, affix_tokens:, start_tag:, end_tag:).
- Basic faceting controls:
facet_by, max_facet_values, facet_query. Minimal DSL: facet(by:, max_values:, query:). Tests: compile mapping + param validation.
- Hit limits & pagination:
per_page, page, group_by, group_limit, exhaustive_search, search_cutoff_ms. Minimal DSL: limit, group, exhaustive, cutoff_ms. Tests: pagination math + grouping interactions.
-
Later (defer)
- Union across collections: requires client‑side merge/dedupe policy and observability; define deterministic interleaving before shipping. Prereq: merge policy & perf guardrails. Unknowns: cross‑search ranking.
- Synonyms/Stopwords management: scope belongs to admin/CLI; wire separately from Relation DSL. Add doctor checks and docs; no query‑time flag exposed in docs today.
Geo: Shipped. See Geo Search.Vectors/Hybrid: Shipped. See Vector Search.- Advanced faceting extras (nested/sampling/custom sort): out of scope until server primitives exist.
-
- Config kill‑switches:
config.features.highlighting, config.features.faceting, config.features.grouping, config.features.exhaustive_search (default off for new features).
- Presets: ship safe defaults aligned with server (e.g.,
affix_tokens=4, max_facet_values=10, page=1, per_page=10).
- Observability: when active, log feature flags and normalized params into our instrumentation events (see Observability).
Open questions & risk register
Per capability:
-
- Open: How do we interleave/dedupe results deterministically across searches? What’s the pagination model? [TS‑MultiSearch]
- Risk: M — correctness/perf of client‑side merge. Mitigation: stable policy + benchmarks + feature flag.
-
- Open: Any per‑query enable/disable flags? If not, should we simulate via presets? [TS‑Synonyms] [TS‑Stopwords]
- Risk: M — admin surface creep in query DSL. Mitigation: keep in CLI/admin; add doctor checks.
-
- Open: Confirm defaults per server version for
highlight_affix_num_tokens. [TS‑SearchParams]
- Risk: L — payload size/perf. Mitigation: conservative defaults and size logging.
-
- Open: Are nested/sampled facets planned server‑side? [TS‑Faceting]
- Risk: M — API churn if we guess semantics. Mitigation: reserve DSL names; do not compile until server supports.
-
Geo — Resolved. Shipped with full DSL:
where_geo, order_geo, order_eval, geo_distance_meters, :geopoint schema type. See Geo Search.
-
Vectors/Hybrid — Resolved. Shipped with full DSL:
embedding macro, vector_search, find_similar, hybrid alpha weighting, auto‑exclude, redaction. See Vector Search.
-
- Open: Interactions between
group_limit, group_by, and per_page across edge cases; clarify exhaustive_search semantics with search_cutoff_ms. [TS‑Pagination]
- Risk: L — UX confusion. Mitigation: compile‑time hints and cookbook examples.
Migration & documentation plan
- YARD earmarks: add short docstrings for new public DSL entry points (
highlight, facet, limit, group, exhaustive, cutoff_ms) describing param mapping and defaults.
- Docs: link this memo from project index; add anchors in Relation Guide and examples in Cookbook Queries for highlighting/faceting/pagination.
- CLI/doctor: add checks that surface misconfigurations (e.g., requesting highlight on non‑indexed fields;
group_limit > per_page).
- Observability: extend event payload to include normalized feature flags and redacted values.
Sources