In-Product Search System Spec Template

For most SaaS products, a managed search service (Algolia, Typesense, Meilisearch, or Elasticsearch/OpenSearch) is the right choice. Building search from scratch requires expertise in text analysis, ranking algorithms, and index management. If your database has fewer than 100K searchable records and simple query needs, PostgreSQL full-text search may be sufficient. Beyond that, a dedicated search engine saves months of engineering time.

Two approaches work well. First, a unified index where all content types share a single index with a `type` field for filtering. This gives the best cross-type relevance but requires careful field mapping. Second, separate indices per content type with results merged and re-ranked at query time. This is simpler to manage but harder to get consistent ranking across types. Most products start with a unified index.

Show suggestions after 2-3 characters. Include three sources: content titles (most useful), recent searches (personalized), and popular queries (social proof). Limit to 5-8 suggestions. Always include a "Search for [full query]" option at the bottom so users can proceed even if no suggestion matches. Debounce autocomplete requests by 150-200ms to avoid hammering the API on fast typers.

Track three metrics. Click-through rate on the first result (target: 40%+). Mean Reciprocal Rank, which measures how far down the results page users go to find what they need (closer to 1.0 is better). Zero-result rate (target: < 5% of queries). Combine quantitative metrics with qualitative feedback from user interviews.

Respect permissions by default. Showing results users cannot access creates frustration ("I can see it exists but cannot open it") and potential security concerns. Filter results at query time so users only see content they have permission to view. The one exception is admin search tools for debugging, which may show all content with clear "admin-only" indicators. ---