Skip to main content

​
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)

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Union across collections/queriesmulti_search endpoint with searches: [...] payload; each search has its own collection, q, query_by, etc [TS‑MultiSearch]TBDResults 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.MLater
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)

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Synonym sets (per collection)Synonyms API: CRUD at /collections/{collection}/synonyms [TS‑Synonyms]TBDStored 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.MLater
Stopword lists (per collection)Stopwords API: CRUD at /collections/{collection}/stopwords [TS‑Stopwords]TBDExcessive 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.MLater
Notes: Per‑query enable/disable flags for synonyms/stopwords are not documented; treat as index‑time configuration. [TS‑Synonyms] [TS‑Stopwords]

​
3) Highlighting controls

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Highlightinghighlight_fields, highlight_full_fields, highlight_affix_num_tokens, highlight_start_tag, highlight_end_tag [TS‑SearchParams]TBDIncreasing 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.LNow
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

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Facets (basic + query)facet_by, max_facet_values, facet_query [TS‑Faceting]TBDLarge 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.MNow
Nested/combined facets; sampling; custom facet sortNot 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.MLater

​
5) Geo

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Geo filters & distance sortfilter_by with geopoint expressions; sort_by with distance for a geopoint field [TS‑Geo] [TS‑FieldTypes]TBDRequires geopoint field in schema; precision depends on indexing.Interacts with other filters and sorts; grouping unaffected.N/Awhere_geo(within_radius: {field:, lat:, lng:, radius_m:}), sort_geo(by_distance: {field:, from:[lat,lng]})Compile to filter_by geo predicate and sort_by: "<field>:asc(_distance from)" or doc‑accurate grammar; validate schema and units.Additive; keep off by default.MLater
Notes: Exact filter_by grammar for geo is versioned; validate at compile‑time with doc‑linked hints. [TS‑Geo]

​
6) Vectors / AI (vector fields, ANN params, hybrid) — Shipped

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Vector searchvector_query with syntax field:([vector], k:N, alpha:0.8, ...); schema float[] field with embed block or num_dim [TS‑Vector]30.1Vector 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.ResolvedShipped
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)

CapabilityTypesense params (authoritative names)SinceConstraints & limitsInteractionsDefaults (server)Proposed DSL surface (back‑compat)Compiler mapping (Relation → params)Migration notesRiskShip bucket
Pagination & capsper_page, page, group_by, group_limit, exhaustive_search, search_cutoff_ms [TS‑Pagination] [TS‑Grouping] [TS‑SearchParams]TBDLarge 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.LNow

​
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: finalize grammar coverage and unit handling; add compiler validations tied to schema geopoint. Prereq: stable grammar reference per server version.
    • 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.
    • Open: Exact filter_by grammar variants for geo across versions; supported distance sort notations. [TS‑Geo]
    • Risk: M — incorrect compile grammar. Mitigation: strict compile‑time validation and doc‑linked hints.
  • 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