Skip to main content

Prepare/execute flow

const search = client.search()

// Prepare caches expensive operations
await search.prepare({ query: 'ring' })

// Execute retrieves results using cached data
await search.execute({ query: 'ring' })
You can perform any operations between prepare and execute:
// Immediate execution
await search.prepare({ query: 'ring' })
await search.execute({ query: 'ring' })

// User interaction in between
await search.prepare({ query: 'ring' })
// User adjusts filters, changes sort order, etc.
await search.execute({ query: 'ring', filters: { color: 'Gold' } })

// Navigation in between
await search.prepare({ query: 'ring' })
// User navigates to different page, browser action, etc.
await search.execute({ query: 'ring', page: 2 })

// Multiple executions from one prepare
await search.prepare({ query: 'ring' })
await search.execute({ query: 'ring', page: 1 })
await search.execute({ query: 'ring', page: 2 })

Passing search IDs between pages

The search_id returned from prepare is valid for 15 minutes and can be reused across page navigations.
// On search page - prepare search
const search = client.search()
const prepareResult = await search.prepare({ 
  query: 'ring',
})

// Store search_id for navigation
const searchId = prepareResult.data?.searchId
sessionStorage.setItem('current_search_id', searchId)

// Navigate to results page
window.location.href = `/search?q=ring&sid=${searchId}`

// On results page - retrieve and use search_id
const urlParams = new URLSearchParams(window.location.search)
const storedSearchId = urlParams.get('sid')

// Create new search controller and execute with search_id
const search = client.search()
await search.execute({ 
  query: 'ring',
  searchId: storedSearchId,
})
Passing search IDs ensures consistent ranking, preserved merchandising rules, accurate analytics, and reduced server load.

Concurrent API calls

Call prepare and autocomplete concurrently for search-as-you-type:
const search = client.search()
const suggest = client.suggest()

const [prepareResult, suggestResult] = await Promise.all([
  search.prepare({ query: 'ring' }),
  suggest.execute('ring'),
])

if (suggestResult.data) {
  renderSuggestions(suggestResult.data.matchedQueries)
}

const searchResult = await search.execute({ query: 'ring' })

Next steps

Caching

Learn how the SDK caches requests and results.

Performance

Optimize your implementation for speed.