Deferred Typesense Features

Catalog Typesense capabilities relevant to deferred features. Capability tables, proposed DSL shapes, compiler mappings, and recommendations.

Related links

• Multi-search
• Presets
• Ranking
• Faceting
• Highlighting
• Observability
• DX
• Hit Limits

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

Notes: In Typesense, “union” is not a first‑class server feature; client must aggregate multi‑search responses. [TS‑MultiSearch]

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

Notes: Per‑query enable/disable flags for synonyms/stopwords are not documented; treat as index‑time configuration. [TS‑Synonyms] [TS‑Stopwords]

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

Validation: disallow both 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.

7) Hit limits (caps, per‑group limits, pagination interactions)

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

• [TS‑SearchParams] Typesense — Search Parameters (versioned): https://typesense.org/docs/29.0/api/search.html
• [TS‑Faceting] Typesense — Faceting (on Search Parameters page): https://typesense.org/docs/29.0/api/search.html#faceting
• [TS‑Highlight] Typesense — Highlighting (on Search Parameters page): https://typesense.org/docs/29.0/api/search.html#highlighting
• [TS‑Pagination] Typesense — Pagination (on Search Parameters page): https://typesense.org/docs/29.0/api/search.html#pagination
• [TS‑Grouping] Typesense — Grouping results: https://typesense.org/docs/29.0/api/search.html#grouping
• [TS‑MultiSearch] Typesense — Multi‑Search API: https://typesense.org/docs/29.0/api/multi-search.html
• [TS‑Synonyms] Typesense — Synonyms API: https://typesense.org/docs/29.0/api/synonyms.html
• [TS‑Stopwords] Typesense — Stopwords API: https://typesense.org/docs/29.0/api/stopwords.html
• [TS‑FieldTypes] Typesense — Field types (geopoint): https://typesense.org/docs/29.0/api/field-types.html
• [TS‑Geo] Typesense — Geo search (see Search Parameters and guides): https://typesense.org/docs/29.0/api/search.html#geosearch
• [TS‑Vector] Typesense — Vector Search: https://typesense.org/docs/29.0/api/vector-search.html