Full-Text Search Rules

Search quality is measured by relevance, not by whether a query returns results at all — a search that returns 10,000 technically-matching but poorly-ranked results is worse than one that returns the 5 right ones, so tune ranking deliberately instead of treating "it returns something" as done.

Analyzers and tokenizers

• Choose an analyzer deliberately per field and per language, not the engine's raw default everywhere — lowercase-folding, stemming, and stopword removal all change what counts as a match, and the right choice differs between a product title field and a free-text description field.
• Apply language-specific stemming and stopword lists only when the field's content is actually in that language — running an English stemmer over multilingual or code-like content (SKUs, usernames) produces confidently wrong matches.
• Keep a separate keyword (unanalyzed, exact-match) mapping alongside the analyzed text field for anything that also needs exact filtering or sorting (a category name used both for full-text search and for an exact-match facet filter) — one field mapping can't serve both needs well.

Exact vs. fuzzy matching

• Rank exact and phrase matches above fuzzy/partial matches by default — fuzzy matching exists to catch typos and near-misses, not to compete on equal footing with a query that matched exactly.
• Enable fuzzy matching (edit-distance tolerance) deliberately and boundedly (e.g. max edit distance of 1-2), not as a blanket default on every query — unbounded fuzziness on short query terms produces a flood of barely-related matches.
• Prefer "did you mean" / fuzzy suggestions as a secondary path shown alongside zero or low-confidence exact results, rather than silently substituting a fuzzy match for what the user actually typed.

Relevance tuning

• Boost fields by their actual importance to the result (a title match should outrank a body-text match for the same query) — an unweighted multi-field search treats a match in a footnote the same as a match in the title, which rarely reflects what users mean by "relevant."
• Incorporate signals beyond text match where available (recency, popularity, a quality score) as an explicit part of the ranking function, not just raw text-match score — pure text relevance frequently ties many documents together with no signal to break the tie sensibly.
• Test relevance changes against a fixed set of representative real queries with known-good expected results before shipping a ranking change — relevance tuning that "looks right" on one manual query can silently regress dozens of others; a repeatable eval set is what catches that.

Pagination

• Paginate search results with a bounded page size and prefer search_after/cursor-based pagination over deep offset pagination — deep offset pagination (from: 10000) is expensive for most search engines because it still has to compute and discard everything before the offset.
• Cap how deep pagination is allowed to go (most engines have a hard default limit, e.g. 10,000 results) rather than assuming a user or API client can page arbitrarily far into result sets.

Index sync

• Keep the search index in sync with the source of truth through an explicit, monitored pipeline (change-data-capture, a write-path hook, or scheduled reindex), and alert on sync lag or failure — a search index that silently drifts from the source produces results referencing deleted or stale records, which erodes trust in search faster than almost any other bug class.
• Reindex idempotently (an update-or-create operation keyed by the source record's ID), so a replayed or duplicate sync event doesn't create duplicate search entries.

Highlighting and zero results

• Return highlighted snippets showing the matched terms in context for text results — a bare list of titles with no indication of why each result matched leaves the user unable to judge relevance at a glance.
• Handle zero-result queries as a first-class case: log them for review (they reveal missing content or a tokenizer/analyzer gap), and show the user a fallback (broadened search, popular results, spelling suggestions) instead of a bare empty state.