It is easy to get a search page on screen, and easy to ship one that finds almost nothing, serves one visitor's results to the next, or works on a development site and not on production. This guide covers the model behind site search so that none of those happen: what the platform indexes and when, how a search view shapes each search, how to build the results page in Smarty or Twig, how product facets work, when a plain listing is the better answer, and what to do when the built-in index is not enough.

Who it is for, and what it assumes

Theme developers building a search page or a product finder, content modellers deciding what should be searchable, and integrations engineers connecting an external engine. It is written at the fluent level: it assumes you can render a record in your site's template engine (Template languages: Smarty and Twig), know layouts and areas (Input types, layouts, components and images), and know how content types, categories and tags are modelled (Content types and custom entities). The last unit also assumes jobs (Automation, jobs and integration).

What the platform gives you

  • Two indices per site. The Site Search index ("master" in the code) holds pages, blogs, blog posts, FAQ questions and product descriptions, and books after release 2026.8.1. The Faceted Search index holds product and variant descriptions, with the facet values you choose.
  • Automatic indexing in the background when a record is saved, published, unpublished or deleted, and when a scheduled publish date passes.
  • Search views, admin records that fix what one search covers and how it behaves: the index, the fields matched and their weights, filters, sorting, page size, highlighting and facets.
  • Three ways to run a view: the page /search/<view slug>, the $_search helper in any template, and the API at /cdna-api/search/<view slug>.
  • The Search menu in the admin: Views, Indices (Reindex, Rebuild and the facets mapping template, for administrators), Fields (search fields) and Facets.

What you build: the template search/search.html, which the framework does not ship, the mapping of your layouts' areas to search fields, and any script that updates the page without a reload.

The order of the units

Indexing and search views comes first, because most surprises come from assuming the index holds more than it does. The search page builds the results page and its empty states. Faceted navigation for product finders covers facets and their filter interface. Listings without the index shows when a filtered listing is the better answer. Relevance, mixed results and external engines is for when the basics work and the site needs more.

Eight things to know first

  1. Layout area content is not searchable until you map it. Out of the box a record is found by its name, URL, tags, categories and author, not by what is written in its layout areas (Indexing is opt-in).
  2. Members-only records are never indexed. The indexer reads as a signed-out visitor, so anything restricted to a group stays out of the index, for members too (What gets indexed).
  3. Declare every parameter a search page reads. The page cache stores one copy per combination of declared parameters: q, page, the sort and each filter. Declaring them keeps the cache from serving one visitor's results to the next (Caching).
  4. Visitors can change a view's settings from the URL unless the view says otherwise: the fields searched, fuzziness, sorting and every filter (What a visitor can change).
  5. Keep Fuzzy search off on a Match phrase view. The two settings cannot be combined (How the query is matched).
  6. An empty query and a missing query are different searches. No q lists everything the view covers; an empty q finds nothing (Empty and zero-result states).
  7. A failed search renders the zero-result state. If Elasticsearch is down or refuses the query, the page still answers with HTTP 200, so monitor for it separately (A failed search).
  8. Filters only take exact values. There are no range filters, so a price facet is built from bands computed when indexing (Price ranges become bands).