Menu
Search Connector
Load documents into a search index from a workflow and search them by meaning and words, with filters, sorting, choices, segment prices, access control and feedback tracking.
Browse 18 Search actions databaseOn this page
What this connector is for
Loads your own data into a search index and searches it. Search understands what things mean as well as the words they contain, so "waterproof walking boots" finds a product called "Merrell Moab GTX" even though they share no words. On top of that you get filters, sorting, choice lists with counts (facets), prices per segment, access control per document, and ranking you can tune and measure.
No connection is needed. Search indexes belong to your store.
An index is created and tuned in the designer's Search page: its fields, segments, synonyms, pinned results and ranking. See Search in the designer. This connector is how workflows load data into it and search it.
Every action returns a plain object under the standard envelope. Read it as {{<stepReference>.response.data.<field>}}. Every action, with its fields, is listed in the action reference.
How documents are shaped
An index holds documents, described by the fields you chose when creating it, for example a product with a title, a brand and a list of variants. Each document has a key field, usually id. Sending a document whose key already exists updates it, so loading is always safe to repeat.
Variants are objects inside a document, like sizes and colours of one shoe. They matter for filtering, explained under Filtering variants.
Add Or Update Documents
Point Documents at a JSON array, or at one object. Pointing it at a webhook body with {{trigger.body}} works as it is. Up to 500 documents per step; use a loop for more.
[{"id":"p1","title":"Trail running shoe","brand":"Acme",
"variants":[{"sku":"p1-a","color":"black","size":"M"},
{"sku":"p1-b","color":"white","size":"L"}]}]
- Invalid documents don't block the rest.
errorslists each problem with its exact place, likevariants[1].sku: This field is required. - Unchanged text isn't reprocessed. Only changes to text used for searching by meaning are re-analysed. Price and stock changes never are, so re-sending a whole catalogue is cheap.
- New text is searchable by words at once, and by meaning shortly after.
embeddingPendingtells you how many documents are still being analysed. - Who can see a document. Add
"_acl":{"allow":["gold"],"deny":["blocked"]}to a document to restrict it. Without it, everyone can see it. - Response:
upserted,failed,errors,warnings,embeddingPending.
Update Prices
Prices are loaded separately from product content, so a price change never reprocesses a product.
[{"key":"p1","unitKey":"p1-a","segment":"uk","amount":1999},
{"key":"p1","unitKey":"p1-a","segment":"uk","priceType":"sale",
"amount":1499,"validFrom":"2026-11-20","validTo":"2026-12-01"}]
- key is the document's key. unitKey is the variant price ID, the variant field chosen under Prices in the index settings, like its sku. segment is a segment you defined on the index, like
uk. - Products without variants are priced as a whole, even on an index where other products have variants. Leave unitKey out and the price applies to the product by its key. If the index's product price ID is a different field, send that field's value as unitKey instead.
- The amount is a whole number in the smallest unit of that segment's currency: pence for GBP, cents for USD and EUR.
1999is £19.99; for a currency without decimals, like JPY,1999is ¥1,999. An amount with a decimal point is rejected, so a price sent as19.99is never stored as 20p. Nothing is ever converted between currencies. - A sale price is used only between
validFromandvalidTo, then the list price returns by itself. While it is active, search results also return the list price aslistPriceso you can show a was/now price. - asOf orders prices from systems that can deliver out of order: a price older than the one stored is ignored and counted in
stale. - Up to 1,000 prices per step. Prices normally appear in search within a few seconds, and within about half a minute in the worst case. A price for a document that doesn't exist yet is held and applied when the document arrives.
- Response:
accepted,stale,rejectedanderrors.
Update Segment Values
Some product data differs per segment, like delivery time, stock or an exclusive flag. Define these as per-product fields in the designer's segment settings, then load their values here. Like prices, they are applied separately from product content, so updating them never reprocesses a product.
[{"key":"p1","unitKey":"p1-a","segment":"uk","values":{"deliveryDays":2,"exclusive":true}},
{"key":"p1","unitKey":"p1-a","segment":"eu","values":{"deliveryDays":5}}]
- A row replaces every value the variant had in that segment, so send all of them each time. Send
nullto clear one. - Each value must match its field's type: text, a whole number, a number, true or false, or an ISO 8601 date.
validFrom/validToapply the values only between those dates; asOf ignores older updates that arrive late.- Up to 1,000 rows per step. Values for a document that doesn't exist yet are held and applied when it arrives.
- Response:
accepted,stale,rejectedanderrors.
Search
Finds documents by meaning and by words together. Leave the search text empty to browse everything that matches the filter, with exact counts.
Filters are a JSON condition on the fields you made filterable:
{"and":[{"field":"brand","op":"eq","value":"Nike"},
{"field":"price","op":"lte","value":10000}]}
Operators: eq, neq, in, not_in, gt, gte, lt, lte, range (with any of gt, gte, lt, lte), exists, and near for locations (lat, lon, distance like "10km"). Combine with and, or and not. A field that isn't filterable is rejected with a clear message rather than ignored.
- Sorting works on fields you made sortable. With search text it reorders the best matches; without it, it sorts everything.
- Pick the segment with Segment (its key) or Segment Attributes (JSON like
{"country":"GB","channel":"retail"}), not both. Attributes must match exactly one segment; otherwise the search explains which ones did. - Ranking Profile picks one of the index's tuned profiles, including how strongly a weak meaning-only match is dropped; empty uses the index default. Visitor Id keeps a visitor in the same experiment variant.
- Access Groups are the groups the visitor belongs to. Documents restricted to other groups are hidden.
- How Many defaults to 10, up to 50. Text searches page up to 200 results deep; refine the search rather than paging deeper.
Filtering variants
Conditions on variant fields inside one and must be true of the same variant. "Black" and "size M" finds products that have a black variant in size M, not products that have some black variant and some M variant. To allow different variants, use separate scopes:
{"and":[{"nested":"variants","where":{"field":"variants.color","op":"eq","value":"black"}},
{"nested":"variants","where":{"field":"variants.size","op":"eq","value":"M"}}]}
Outside a scope, neq excludes products that have any variant with that value. Inside one, it means "has a variant that isn't".
Reading the results
{{<stepReference>.response.data.items}} holds the results, best first. Each has:
idanddocument: the fields you marked as shown in results.relevance(0 to 1): how well the meaning matched. Use this to show or threshold, not the internalscore.- For products with variants, every variant in
document.variantswithmatched(it satisfied your filter) andselected(the best one to display).selectedVariantis its position. pinned: truewhen a pinning rule placed it.- On priced indexes,
priceRangeover the matching variants and apriceon each variant. While a sale is the active price and is below the list price, that variant also has alistPrice: the "was" price to show besideprice(for example,listPrice12900 andprice10300: was £129, now £103). Products without variants carrypriceandlistPriceon the result itself. - On indexes with per-product fields, each sellable variant has
segmentValueswith the chosen segment's values, like{"deliveryDays":2,"exclusive":true}. Products without variants carry it on the result itself. The response'spricingalso returns the chosen segment's attributes.
Also returned: total, hasMore, facets, queryId (use it with Record Search Feedback), profile, and degraded: true if the search fell back to words only. warning explains an empty result caused by setup, such as an index with no documents.
Choices (facets)
Ask for fields in Choices To Return (like brand,color,price) and get back, for each, the values available with product counts:
[{"field":"brand","type":"terms","buckets":[{"value":"Acme","count":12,"selected":false}]},
{"field":"price","type":"stats","min":9.5,"max":180,"currency":"GBP"}]
- Counts are products, not variants: a product with three size M variants counts once. On priced indexes only variants sold in the chosen segment are counted.
- Choices for a variant field only count variants that match your other variant filters, so the numbers match what a click will produce.
- Each choice ignores its own filter, so a shopper who picked "Acme" still sees the other brands.
selectedmarks what is currently chosen. - Fields with text use
terms. Numbers and dates usestats(min and max), ranges or intervals. Pass an object for these:{"field":"price","ranges":[{"to":20,"label":"Under 20"},{"from":20}]}or{"field":"price","interval":10}. facetScopesays what was counted:all_matcheswhen browsing (exact), ortop_matchesfor text searches (the best results found).
Segments and prices
If the index has segments, pass a segment. Then:
- Only products with a variant sold in that segment are returned, and only their sellable variants are shown.
- Each variant carries only that segment's price, in that segment's currency.
priceworks as a filter and sort field, using that segment's price, and as a choice for price ranges.- Prices everywhere in search are in the currency's smallest unit, like the amounts you load: filter "under £100" as
10000, and show a returned1999as £19.99. Describe Search Index gives each segment'sdecimals(2 for GBP, 0 for JPY) to convert with. - Ascending price sorts by each product's cheapest variant, descending by its dearest.
- A price filter, colour and size all apply to the same variant.
Segment attributes and per-segment fields
Segments can carry attributes that describe them, like country, region or sales channel. Use them when you know the shopper's country but not the segment key, and to find segments in the designer.
Per-product fields hold values that differ per segment (see Update Segment Values). In a search they behave like price: filter, sort, count as choices or match search words using the chosen segment's value, for example {"field":"deliveryDays","op":"lte","value":3}. A condition on one also applies to the same variant as price, colour and size. They match search words only, not by meaning.
Each per-product field you can filter, sort, facet or search is stored once per segment, so the number of such fields is limited by how many segments you have: 20,000 divided by the number of segments (10 fields with 2,000 segments). Fields that are only shown in results have no limit beyond the 20 per index.
Search Multiple Indexes
Searches several indexes with one step, for example your products and your help content, so a shopper typing "waterproof boots care" gets matching products and care guides together.
Indexes is a JSON list of up to 5, by slug:
[{"index":"products"},
{"index":"content","weight":0.6,"limit":5}]
- Search Text is the same for every index. Each index is searched with its own ranking profile, synonyms, pinned results and rules.
- Filters, sorting, choices and fields differ between indexes, so they go on each entry in the list (
filter,sort,facets,fields,profile,limit,offset), not on the step. Use the same JSON as in Search. - Segment and Segment Attributes apply to every index that has segments and are ignored by the rest. Access Groups apply to all of them.
- How Many is the default per index, up to 50. An entry's own
limitwins. To page, set an entry'soffset.
Results come back grouped: groups has one entry per index, in the order you listed them, each with index, name and response. The response is exactly what Search returns, including items, total, facets and queryId. Read the products as {{search.response.data.groups[0].response.items}}.
Turn on Blend Into One List to also get blended: one ranked list mixing every index, each entry as { index, item, score }. Scores from different indexes can't be compared directly, so the blend goes by each result's position in its own index. Give an index a lower weight (default 1) to rank it below the others, such as 0.6 for content under products. The blended list has no paging; it is capped by How Many.
If one index can't be searched, for example a wrong slug or a missing segment, its group has an error with a message and code instead of a response, and the other groups still return. The step only fails when every index fails.
Each index records its own search, so a combined search shows as one search per index in Insights. Use each group's own queryId with Record Search Feedback.
Agentic Search
Answers an open-ended question, such as "what are your best-reviewed waterproof jackets under $200?", by letting an AI assistant turn it into a search. It only works on an index with Agentic search turned on in the designer (see Search in the designer); use Search for everything else. Give Search Index, Question and optionally How Many. The result has the same shape as Search: items, total and hasMore. Every question is independent; there is no follow-up conversation yet.
Describe Search Index and Find Field Values
These two steps are for assistants and any workflow that turns a customer's sentence into a search.
Describe Search Index returns what an index contains: the description you wrote, a short summary of what is in it, every field with what you can do with it (filter, sort, choices), the valid values for fields such as category, brand and colour, the lowest and highest values of number and date fields, the segments with their currencies, and a short guide. An assistant calls it first, so that "warm jacket under $50" becomes the words "warm jacket" plus a price filter, and so that it knows a request for something you don't sell is not worth searching. Write what the index contains, and what it does not, in the index description.
Find Field Values lists the values that exist for a field, optionally only those containing some text. Use it for fields with many values, such as brands.
When a search finds nothing, the result includes hints: a filter value that does not exist and what is valid instead, or a reminder of what the index is about.
Get Documents and Delete Documents
Get Documents reads what is stored, by key, with each document's analysis status (ready, pending or failed). Delete Documents removes documents and their prices; deleting a key that isn't there is not an error. Both take up to 500 keys.
Get Product Questions
When Product questions is turned on for an index (the index's Product questions tab), questions shoppers are likely to ask are written for every product, and kept up to date as products change. Get Product Questions returns them for one product, ready to show on a product page. Leave Lookup Field empty when Product is the document key; otherwise name the field, for example variants.sku. The result is { product, key, found, questions: [{ id, text, topic }], widget }; found is false when the product has no questions yet, and widget (present once the storefront widget is saved) says how the widget looks and what a click does. Return the result as-is from an API route and point the storefront widget at that route: the page only knows the workflow's address, never the index.
Record Search Feedback
Tell the index when a result was clicked or bought, using the queryId from the search that produced it (for a search step with reference search: {{search.response.data.queryId}}). This feeds the click-through and conversion figures in the designer's Insights, and lets experiments compare ranking profiles by real behaviour.
Keeping an index in sync
For an incremental sync from another system: Get Sync Progress at the start, fetch what changed since, Add Or Update Documents (and Update Prices), then Save Sync Progress at the very end. Saving it early would make a failed run skip records permanently.
Who the step searches as
A workflow acts for your store, so a step states the Access Groups and Segment it searches as. That is fine because the workflow author already has full access. It is also why anything a shopper can reach directly should not let the shopper choose these: take them from who is signed in.
Also applies here
Step Name
What it's for
Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.
Rules
- Must be at least 2 characters, and 50 characters or fewer.
- Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g.
"Get Order Details 2"). - Can't be empty.
Tips
- Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
- Renaming a step updates every reference to it elsewhere in the workflow automatically.
Step Reference
Syntax
Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.
Referencing a step's output
Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:
{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}
The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.
You can also reference steps by position instead of by reference:
{{steps[0].response.data.id}}
Referencing trigger data
{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}
Referencing workflow variables
{{variables.myVariable}}
See Variables for the full list of variable types and more examples, including connection-type variables.
Referencing runtime variables
A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:
{{runtimeVariables.myVariable}}
Notes
- If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
- Object values are automatically JSON-stringified when interpolated into a string field.
Execution Settings
Fire-and-forget
When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.
Continue on error
When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.
Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.
Caching
What it does
When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.
Configuring it
- Enabled — turn caching on or off for this step.
- TTL — how long (in seconds) a cached result stays valid.
- Cache key template — an expression (supporting the same
{{...}}step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.
When to use it
Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).
Locking
What it does
When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.
Configuring it
- Enabled — turn locking on or off for this step.
- Lock key — an expression (supporting the same
{{...}}step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access. - Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.
When to use it
Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.
Last updated 12 October 2026