A search profile is a saved recipe for one search box: which fields a query looks in and how much each counts, how forgiving it is about typos, which facets and sort orders it offers, which filters always apply and what each hit returns. An index can hold up to 50 profiles, for example one for the storefront search page and one for a B2B catalog.
The profile editor with a live preview of the saved and the draft settings
Each profile has a profileKey, 16 URL-safe characters that never change. The storefront calls POST /v1/search/<profileKey> and sends only the query, filters, sort and page; everything else comes from the profile. A saved change applies to the very next search.
In the cabinet, open an index and then Search profiles. The editor is split into the blocks below and shows a live preview of the draft next to the saved profile. The same profile is plain JSON in the API and in the editor's JSON view.
GET/v1/projects/:projectId/indices/:indexId/profilesProject member or any secret keyPOST/v1/projects/:projectId/indices/:indexId/profilesProject admin or a full-access secret keyPUT/v1/projects/:projectId/indices/:indexId/profiles/:profileIdProject admin or a full-access secret keyDELETE/v1/projects/:projectId/indices/:indexId/profiles/:profileIdProject admin or a full-access secret keyPUT replaces the whole profile, so send every setting you want to keep. A save checks the profile against the index mapping: a field must exist and carry the flag its use needs (searchable, facetable, filterable, sortable or returnable), or the API answers 400 PROFILE_INVALID with one issue per field.
stringValues 1 to 100 charactersThe name you and your team know the profile by. It shows in the cabinet; shoppers never see it.
409 PROFILE_NAME_TAKEN.field → weightValues weights above 0, up to 100; at least one fieldThe fields a query looks in, each with a weight. A match in a field with weight 3 counts three times as much as a match in a field with weight 1. Only searchable fields can be listed.
all | anyDefault allall returns a product only when every word of the query matches; any is happy with one word. all gives precise results for short queries; any returns more products and ranks those that match more words higher.
all, every word has to be found in the same field. "samsung oled" matches a title that holds both words, but not a product whose brand is Samsung and whose title only says OLED. Put the brand into the title field, or use any if your catalog splits words across fields.all. Long natural-language queries are the first to stop matching.numberDefault 2Values 0 to 100; 0 turns it offAn extra boost for products where the query's words appear next to each other, in order. It only lifts products that already match; it never adds new ones.
AUTO | 0 | 1 | 2Default AUTOHow many letters may differ between a query word and a word in a product. AUTO allows none for words of one or two letters, one typo for words of three to five letters and two for longer words. 0 turns typo tolerance off.
AUTO for most catalogs. A fixed 2 lets short words match far too much: two changed letters turn a three-letter word into almost any other.0 for catalogs searched mostly by codes, where a single changed character is a different product.numberDefault 1Values 0 to 10How many letters at the start of a word must be typed exactly before typos are allowed. With 1, "lamp" can match "lump" but not "damp".
booleanDefault trueWhen a search finds nothing, the engine looks for a corrected spelling of the query among the words in your products. The response returns it as correctedQuery, so the storefront can show "Did you mean …?".
booleanDefault trueWith this on, a search that finds nothing is run once more with the corrected query, and the response returns those results with correctedQuery set. Off, the response stays empty and only carries the suggestion.
list of facetsDefault the index facetsValues up to 50The filter panels next to the results, in order. Leave the setting out and the profile shows the index facets, which you manage once on the index's Facets page. Set it, even to an empty list, and this profile shows its own facets instead.
A facet has a type and a facetable field, and an optional label:
terms: the field's values with product counts; limit 1 to 500 (default 20), order count or key.range: buckets you define with from and to; from is included and to is not. Up to 50 buckets, numeric fields only.stats: the lowest and highest value in the results, for a price slider. Numeric fields only.hierarchy: a category tree that shows the children of the deepest selected category; limit 1 to 500 (default 50). Hierarchy fields only.booleanDefault trueLeaves out facets with nothing to pick for the current search. A facet the request already filters on stays even when it is empty, so the shopper can still see and clear the selection.
list of sortsDefault ["_relevance"]Values 1 to 50 optionsThe sort orders a shopper can pick. Each option is up to 10 clauses joined by commas and applied in order: _relevance (best match first) or field:asc / field:desc on a sortable field, for example price:asc or inStock:desc,_relevance. A field may appear once per option. A request asking for a sort that is not in this list answers 400 SORT_NOT_ALLOWED.
_relevance in the list. Without it, a shopper who picked "price, low to high" cannot get back to best matches._relevance at the end yourself.sortDefault _relevanceThe sort used when a request does not ask for one. It must be one of the sort options, or the save fails.
_relevance. A category page with an empty query is a good place for a field sort such as newest first.list of sort clausesDefault []Values up to 10 clausesSort clauses that lead every search, before the default or the requested sort, such as inStock:desc to show products in stock first. A clause of the chosen sort on the same field is dropped, since it would change nothing after the pinned one.
field → filterDefault {}Filters every search gets. A product shows up only when it matches all of them, and the storefront cannot lift them. A filter is a value, a list of values (any of them), a range {"gte": 10, "lt": 50}, {"exists": true} or category nodes {"terms": ["TV>OLED"]}, on a filterable or facetable field.
{"inStock": true} for a shop that never shows sold-out products.field → filterDefault {}Products that match any of these never show up, whatever the request asks for. They take the same filter forms as always-on filters.
list of fieldsDefault []Values up to 100Fields a request may filter on besides the facet fields. A request filtering on any other field answers 400 FILTER_NOT_ALLOWED, which keeps storefront requests from filtering on fields you did not mean to expose.
currency or a visibility flag.list of fieldsDefault every returnable fieldValues up to 200The fields each hit returns. Leave it out and a hit carries every returnable field of the mapping.
numberDefault 24Values 1 to 1000How many hits a page holds when the request does not say. It cannot be higher than the most a request may ask for.
numberDefault 100Values 1 to 1000The largest perPage a request may send; above it the API answers 400 PER_PAGE_TOO_LARGE. Independently, page × perPage cannot go past 10,000 results.