Skip to content

Search Proxy (Cloudflare Worker)

  • Config: components/search_proxy/wrangler.toml
  • Source: components/search_proxy/src/

The main search API. Routes search queries to Marqo via service bindings, with authentication, caching, settings management, and metrics.

Worker Names

Env Worker Name Domain
Staging staging-ecom-api staging-ecom.dev-marqo.org
Preprod preprod-ecom-api ecom.preprod-marqo.org
Prod prod-ecom-api ecom.marqo-ep.ai

Bindings

Binding Type Purpose
KV KV Namespace Index settings (populated by Settings Exporter Lambda)
KV_QCFG KV Namespace Query config overrides (populated by Admin Lambda)
MARQO_WORKER Service Binding Marqo search backend (global-worker)
PIXEL_WORKER Service Binding Analytics pixel tracking
AGENTIC_SEARCH_WORKER Service Binding AI-powered conversational search

Request Flow

  1. Extract API key from X-API-Key or Shopify proxy auth
  2. Validate API key with control plane gateway
  3. Load index settings from KV
  4. Apply query overrides from KV_QCFG
  5. Check for redirects (parallel with search)
  6. Call Marqo via MARQO_WORKER service binding
  7. Transform and return results
  8. Enqueue metrics to SQS (async via waitUntil)

Key Endpoints

Path Method Purpose
/search POST Main search
/search/composite POST Multi-query search
/recommendations/similar POST Similar product recs
/recommendations/complementary POST Complementary recs
/recommendations/for-you POST Personalized recs
/search/suggestions POST Autocomplete
/collections POST Collection-filtered search
/agentic/search POST AI conversational search
/agentic/chat POST Multi-turn AI chat

External Dependencies

Service How Credentials
Marqo Service binding to global-worker N/A (internal)
SQS (metrics) AWS SDK via IAM user AWS_ACCESS_KEY_ID/SECRET from Secrets Manager
DDB (redirects) AWS SDK via IAM user Same IAM user as SQS
KV (settings) Cloudflare KV binding N/A (built-in)
Control plane API HTTP to API Gateway IAM or API key

Typical Investigation Paths

Search returning errors:

  1. Tail worker logs: npx wrangler tail {env}-ecom-api
  2. Check if settings exist in KV for the account
  3. Check Marqo worker health via service binding

Stale search results / settings not applying:

  1. Read KV key for the account: npx wrangler kv key get --namespace-id {id} "{system_account_id}"
  2. Compare with DDB source: query EcomIndexSettingsTable for the account pk
  3. Check settings exporter Lambda logs (DDB stream consumer)

High latency:

  1. Check Marqo backend health
  2. Check CloudWatch dashboard for p99 latency widgets
  3. Look for slow queries in worker logs