How To Extend Search Behavior

TABLE OF CONTENTS


Solution Architecture Guidance
  • Use Znode's native search capabilities before proposing storefront customization. Keyword search, facets, sorting, type-ahead, keyword redirects, spelling suggestions, barcode search and SKU-oriented lookups already have established patterns. Type-ahead suggestions depend on the store's type-ahead setting. Catalog attributes configured as facets are the preferred way to introduce filterable product characteristics, because they participate in the existing facet behavior without a custom filtering mechanism. A newly configured facet attribute normally appears in search only after the search index is refreshed (for example, by a catalog publish), not immediately.
  • Separate storefront presentation requirements from search-engine capabilities during discovery. The storefront can select supported sort options and pass search criteria, but adding a storefront sort option does not make a field sortable in the search index, and relevance tuning or SKU boosting belongs to the search index rather than storefront code. Confirm back-end search support before committing to custom ranking or sorting requirements.
  • Treat keyword search, exact SKU lookup and Quick Order SKU search as distinct capabilities, even though they are related. Establish which user journey the client is changing before estimating the solution; assuming one search customization automatically applies to the other lookup experiences can understate scope. Barcode scanning uses the same keyword search, so a keyword-search customization also affects barcode scanning and should be tested with it.
  • Preserve the platform's search data-freshness model. Product search results and real-time pricing or inventory-related search calls are intentionally not cached. However, when the page cache for guest users or a CDN is enabled, guest users may receive a cached search results page for the configured cache time (60 seconds by default). Logged-in users and shoppers with a cart always see live results. Search freshness also depends on the back-end search index being refreshed after catalog changes. If guest users must always see live results, the search page can be excluded from the page cache. Requirements that depend on caching these results should be challenged during solutioning, because catalog state, facets, pricing visibility, pricing and inventory can change frequently.
  • Favor extension of Znode's existing search behavior over parallel custom search mechanisms. The standard search response already combines products, facet counts, pagination and suggestion data, while configured facets provide existing selection and navigation behavior. Rebuilding capabilities that Znode already supplies adds unnecessary implementation and maintenance scope; truly custom filters or search behavior should be treated as an ongoing customization that requires testing as the platform evolves.

Keyword search, facets, sorting, type-ahead and barcode/SKU lookups all run through one small set of functions. This guide shows how a search request flows end to end, how a facet selection becomes a filter, and how to add new search behavior without duplicating the pipeline.

  • Audience: Implementation partners and developers
  • Stack: Next.js 15 · React 19 · TypeScript · Nx
  • Example: An "In Stock Only" facet toggle. The example name is a placeholder. Replace it with your own.

The diagram shows where each search component runs: in the browser, on the storefront server or in the back-end search service.


Search architecture: in the browser, the Shopper opens the Results page (/search/...) on the storefront server. The Results page (Server Component) renders the Type-ahead box. When the shopper types a key, the Type-ahead box calls the API route (type-ahead only), which goes to the Search agent, then the Search client, which makes one HTTPS call to Znode search in the back end.


The results page is a Server Component, so it calls the search agent directly. The type-ahead box runs in the browser, so it goes through an API route first.


ComponentRuns onJob
Search agentStorefront serverBuilds filters, facets and sort from the URL, calls the client.
Search clientStorefront serverOne call returns products, facet counts and pagination together.
Facet & sort UIBrowserWrites the choice into the URL; no client-side state needed.
Results pageStorefront serverRe-runs the search on every request with the new URL.
Type-ahead boxBrowserCalls a small API route on every keystroke.


A Search Request, End to End

A keyword, the selected facets and the sort choice are all plain URL query parameters. The results page re-reads them and calls the search agent again on every request. There is no client-side search state to keep in sync.

The diagram shows how a search request flows end to end.


Search request sequence: 1, the Browser opens the results page with searchTerm and facetGroup; 2, the Results page awaits getSearchResult(searchParams); 3, getSearchResult has getFacetFilter parse facetGroup into RefineBy; 4, RefineBy is returned; 5, keyword, filters, RefineBy and sort go to Znode search; 6, products, facet counts and pagination come back; 7, the mapped product list and facet list return to the Results page; 8, the rendered grid and facet rail return to the Browser.


Solid arrows are requests; dashed arrows are responses. Steps 3–4 happen inside the same agent call, with no extra round trip to compute RefineBy.

Facets: Filters and Counts, in One Response

A facet is a query-string convention, not a separate API. Znode's full-text search endpoint returns the product list and the remaining facet counts together, as long as the request asked for the facet expand.

The diagram shows how a facet selection becomes a filter.


Facet flow: the URL (facetGroup=Brand|Acme) goes to getFacetFilter(), which parses it into a dictionary, then to RefineBy, then to Znode search, which filters and recounts facets. Znode search returns FullTextSearchResponse with products and facets in the same call, and bindCategoryFacet() passes facets straight through to the UI.


A facet selection never triggers a second request for counts. If a new facet attribute doesn't appear, check that it is marked as a facet in Znode Admin and that ExpandKeys.Facet is still requested.


PieceWhereJob
Facet UIpackages/base-components/.../product/facet/Renders facet groups by controlType; writes selections into the URL
getFacetFilterpackages/agents/src/product/product.tsParses facetGroup (and properties.Brand) into a filter dictionary
RefineBybindSearchModelCarries that dictionary into the search request as a JSON string
Facet countsFullTextSearchResponse.facetsRecomputed by Znode for the filtered result, returned in the same call


Add a Facet in 4 Steps: "In Stock Only"

Most new facets need no code at all. They only need the attribute marked as a facet in Znode Admin. This example covers the other case: a toggle with no catalog attribute behind it, added as a one-off filter next to the facet pipeline.

STEP 1 - Check whether it's already a facet

If the attribute is marked as a facet in Znode Admin, it already comes back in the search response's facet list. Nothing to build: the facet UI renders it automatically.

  • Do prefer a real facet whenever the catalog can express the rule. It gets counts, multi-select and chip removal for free.
  • Don't build a parallel filter mechanism for something the back end can already express as a facet.

STEP 2 - Add the toggle to the filter dictionary

For a toggle with no catalog facet behind it, extend getFacetFilter so it also reads a dedicated query flag, and add that flag to ISearchParams as optional.

packages/agents/src/product/product.ts
packages/types/src/search-params.ts
packages/agents/src/product/product.ts (inside getFacetFilter)
// CUSTOM: "In Stock Only" toggle, not a Znode-configured facet
if (filterParam?.inStockOnly === "true") {
  dictionary["InStockOnly"] = ["true"];
}

STEP 3 - Render the toggle

Write inStockOnly=true into the URL the same way the existing facet checkboxes do. The results page re-reads searchParams on every request, so no client-side state is needed beyond the URL itself.

  • Do reuse the existing URL-driven pattern so FacetChipList and back/forward navigation keep working.
  • Don't call an API route directly from the toggle. Let the Server Component re-run the search.

STEP 4 - Test the dictionary, not the UI

packages/agents/src/product/product.spec.ts
product.spec.ts
it("adds InStockOnly to RefineBy when requested", async () => {
  const result = await getFacetFilter({ inStockOnly: "true" } as ISearchParams);
  expect(result.InStockOnly).toEqual(["true"]);
});

Sorting Is a Fixed, Mapped List

Sort options are a small enum, not a free-text field. getSortByProductList maps a numeric sort value to a field Znode's search index actually supports: name, price, rating, reviews, stock status and popularity today.


StepWhere
Add the enum value and its mappinggetSortByProductList, packages/agents/src/product/product.ts
Confirm the back end can sort on that fieldThe search index configuration. Adding a case in the storefront does not create the capability.
Add it to the sort dropdown and translationsThe dropdown reads productData.sortList, filtered by getFilteredSortList


True ranking changes (boosting specific SKUs, relevance tuning) are configured on the search index, not in storefront code. The storefront only picks one of the sort keys the back end already exposes.

The dropdown that appears while typing runs in the browser, so it goes through a small API route on every keystroke, instead of calling the agent directly like the results page does.


BehaviorAPI routeNotes
Suggestions while typing/api/search/search-hydrated-typeaheadOnly when the store's type-ahead feature is on; otherwise falls back to a plain keyword search
Pre-search panel (recent/popular, "My Searches")/api/search/search-hydratedNeeds a catalog code and a user profile ID
Lightweight keyword suggestions/api/search/search-suggestionsNo facets or pricing, just matching keywords
Live type-ahead pricing/api/search/search-typeahead-pricelistNever cached; prices must stay current
Keyword redirects (vanity search terms)/api/search/search-redirectMatches configured keywords case-insensitively


Barcode scanning and SKU lookups reuse pieces of this pipeline rather than duplicating it. Pick the right one before extending any of them:


LookupTypeHow it works
Barcode scanFree-text relevanceTreats the scanned text as a search keyword and calls the exact same keyword search function as the results page.
Add-by-SKUExact lookupA direct product lookup by SKU, not full-text search, with different caching and error handling.
Quick Order SKU searchGrid-specificIts own row-by-row SKU resolution, separate from both of the above.


Search results are not cached by default, on purpose. The product search call has no cache-tag branch at all, and the pre-search panel and type-ahead pricing calls force a fresh fetch explicitly.


RuleDetails
Never tag the product search callSearch results depend on facets, catalog state and pricing visibility that change too often to cache safely.
Never tag pricing or inventory callsType-ahead pricing is deliberately always fresh, the same rule real-time pricing follows everywhere else in the storefront.
Tag only genuinely shared dataA search-adjacent banner or message that's identical for every shopper can use the normal CacheTags pattern.


The No-Results State

A keyword search with zero results shows a dedicated message with spelling and phrasing tips, not the generic "no records" state used elsewhere. "Did you mean" data is already on the response. Reuse it instead of inventing a new suggestion feature.

  • Do edit the existing translation keys, or add new tips to the list, for a copy change. No agent change needed.
  • Do render the existing "did you mean" alternatives when you want to suggest other terms.
  • Don't build a new suggestion pipeline. The suggested term and alternatives are already computed by the search back end.

Golden Rules


RuleWhat it means
Facets are a URL conventionParse and build facetGroup the same way the existing code does, so chips and navigation keep working.
Filters are built on the serverRefineBy is assembled in the agent, never sent as a raw filter from the browser.
One call returns products and facet countsDon't add a second round trip just to get updated counts.
Search results stay uncachedDon't add CacheTags to the product search, facet or pricing calls.
Know which lookup you're extendingKeyword search, SKU lookup and Quick Order's SKU search are three different functions.
Custom code stays markedAny non-attribute-backed facet or filter is marked // CUSTOM: <reason>.


Hand-Over Checklist

Before the pull request, confirm:

  • New facet logic lives in getFacetFilter or a clearly marked function beside it, not duplicated in a Client Component
  • Non-attribute-backed facets or filters are marked // CUSTOM: <reason>
  • New fields were added as optional fields on existing types, not new parallel types
  • No CacheTags filter was added to the product search, facet, or pricing calls
  • New translation keys were added to every language file
  • Agent changes are covered by a unit test on the mapped output
  • Barcode or SKU changes were made to the correct one of the three lookup paths

Troubleshooting


You seeWhat it usually means
A facet never appearsThe attribute isn't marked as a facet in Znode Admin, or the facet expand was dropped from the request
Selected facets don't filter the gridThe facetGroup encoding doesn't match the existing convention; check RefineBy on the request
Sorting has no effectThe sort case maps to a field the search index doesn't actually sort on
Type-ahead shows stale pricesThe pricing call was made with caching left on; it should always force a fresh fetch
"Did you mean" never appearsThe request explicitly turned off suggestions, or the keyword is already an exact match
Search looks a step behind after a catalog changeUnlikely to be a storefront cache. Search isn't tagged by default, so check the back-end search index refresh.


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.