Search with Marqo

This guide shows you how to search your product catalog using Marqo's powerful ecommerce search API. Learn how to perform text searches, filter results, implement faceted search, and browse collections.

Prerequisites

A Marqo Cloud account
Your Marqo API key (find your API key guide)
An existing ecommerce index with products (add products guide)

Search Requests

Search requests are made via a POST /search request with a search body containing your query and search parameters.

Example

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "wireless headphones",
  "limit": 25
}'

Note: Replace {index_name} with your actual index name and {api_key} with your API key.

Response

{
  "hits": [
    {
      "productTitle": "Premium Wireless Bluetooth Headphones",
      "variantTitle": "Premium Wireless Bluetooth Headphones - Black", 
      "price": 199.99,
      "variantImageUrl": "https://cdn.example.com/headphones-black.jpg",
      "color": "Black",
      "collections": ["electronics", "audio"],
      "_id": "headphones-black-001",
      "_score": 1.23456
    },
    {
      "productTitle": "Wireless Earbuds Pro",
      "variantTitle": "Wireless Earbuds Pro - White",
      "price": 149.99,
      "variantImageUrl": "https://cdn.example.com/earbuds-white.jpg",
      "color": "White",
      "collections": ["electronics", "audio"],
      "_id": "earbuds-white-002", 
      "_score": 1.15432
    }
  ],
  "limit": 10,
  "offset": 0,
  "query": "wireless headphones"
}

Search Parameters

Here is a full list of parameters available for /search:

Parameter	Type	Default	Description
`q`	String	`null`	Query string for product search
`limit`	Integer	`10`	Maximum number of products to return
`offset`	Integer	`0`	Number of products to skip (for pagination)
`filter`	String	`null`	Filter string using Marqo's query DSL to narrow search results
`attributesToRetrieve`	Array of strings	`["productTitle", "variantTitle", "price", "variantImageUrl", "collections", "_id", "_score"]`	Specific product fields to return. If not specified, returns the default core product fields
`facets`	Object	`null`	Facet configuration for aggregated results
`sortBy`	Object	`null`	Sort configuration for results ordering
`userId`	String	`null`	User ID for personalization
`sessionId`	String	`null`	Session ID for personalization

Filtering

You can use Marqo's filter string DSL to refine search results. Filter strings can be used with all search methods and use a syntax based on Lucene with some differences. For complete filter syntax and examples, see our Filter DSL Guide.

Key Filter Features

Fielded searches - All term filters must be connected to a field, e.g., brand:Nike
Range filters - Efficient range filters for numeric types, e.g., price:[50 TO 300]
Boolean operators - Support for AND, OR, NOT with proper grouping
Array filtering - Filter over array fields like collections or tags

Examples

# Price range and availability filters
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "headphones",
  "filter": "price:[50 TO 300] AND is_available:true"
}'

# Logical operators with grouping
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "shoes",
  "filter": "(brand:Nike AND collections:athletic) OR (brand:Adidas AND price:[* TO 150])"
}'

# Array field filtering
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "electronics",
  "filter": "collections:audio OR collections:wireless"
}'

# Boolean and exact match
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "*",
  "filter": "is_featured:true AND brand:(Apple OR Samsung)"
}'

Common Filter Patterns

Filter Type	Example	Description
Price Range	`price:[50 TO 300]`	Products between $50-$300
Open Range	`price:[100 TO *]`	Products $100 and above
Exact Match	`brand:Nike`	Products with exact brand match
Boolean	`is_available:true`	Products that are available
Array Contains	`collections:electronics`	Products in electronics collection
Logical AND	`brand:Nike AND price:[* TO 200]`	Nike products under $200
Logical OR	`brand:(Nike OR Adidas)`	Products from either brand
Complex Expression	`(brand:Nike AND collections:athletic) OR (price:[* TO 50] AND is_sale:true)`	Nike athletic items OR sale items under $50
NOT Operator	`collections:electronics AND NOT brand:Apple`	Electronics excluding Apple products

Faceted Search

Facets allow you to aggregate data from your documents based on specific fields. This can be useful for creating filters, showing data distributions, or implementing drill-down search functionality.

Parameters

Parameter	Type	Default	Description
`fields`	Object	`null`	Fields to facet on and their configuration
`maxResults`	Integer	`100`	Maximum facet results per field (max: 10000)
`maxDepth`	Integer	`null`	Max documents to consider for aggregation
`order`	String	`"desc"`	Order of facet results: `asc` or `desc`

Field Parameters

Parameter	Type	Description
`type`	String	Facet type: `string`, `number`, or `array`
`ranges`	Array	For numeric fields: define value ranges
`excludeTerms`	Array	Exclude specific terms from this facet

Range Parameters (Numeric Fields)

Parameter	Type	Default	Description
`from`	Number	`null`	Lower bound (inclusive), `-Inf` if not specified
`to`	Number	`null`	Upper bound (exclusive), `Inf` if not specified
`name`	String	`null`	Custom range name (defaults to "from:to")

Examples

# Price ranges and category facets
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "electronics",
  "facets": {
    "fields": {
      "price": {
        "type": "number",
        "ranges": [
          {"to": 50},
          {"from": 50, "to": 100},
          {"from": 100, "to": 200},
          {"from": 200, "name": "$200+"}
        ]
      },
      "brand": {"type": "string"},
      "collections": {"type": "array"}
    }
  }
}'

# Simple string facet
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "shoes",
  "facets": {
    "fields": {
      "brand": {"type": "string", "maxResults": 10}
    }
  }
}'

Response

{
  "hits": [...],
  "facets": {
    "price": {
      "0.0:50.0": {
        "count": 15,
        "min": 19.99,
        "max": 49.99,
        "avg": 34.50,
        "sum": 517.50
      },
      "$200+": {
        "count": 8,
        "min": 200.00,
        "max": 599.99,
        "avg": 325.00
      }
    },
    "brand": {
      "Nike": {"count": 25},
      "Adidas": {"count": 18},
      "Apple": {"count": 12}
    },
    "collections": {
      "electronics": {"count": 120},
      "audio": {"count": 45}
    }
  }
}

Sorting

sortBy allows you to sort the search results based on specific numerical fields. This can be useful for ordering results by price, rating, or any other numerical attribute.

Parameters

Parameter	Type	Default	Description
`fields`	List[Dict]	No default	A list of fields to be sorted on, with sort order and missing policy
`sortDepth`	Integer	`null`	The number of documents to be sorted in the global phase
`minSortCandidates`	Integer	`null`	The minimum number of documents to be sorted on

Field Parameters

Parameter	Type	Default	Description
`fieldName`	String	No default	The field to be sorted on
`order`	String	`"desc"`	The sort order: `"desc"` or `"asc"`
`missing`	String	`"last"`	Missing value policy: `"first"` or `"last"`

Examples

# Sort by price descending
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
    "q": "shoes",
    "sortBy": {
        "fields": [{"fieldName": "price"}]
    }
}'

# Multi-field sort with missing value handling
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
    "q": "electronics",
    "sortBy": {
        "fields": [
            {"fieldName": "rating", "order": "desc", "missing": "last"},
            {"fieldName": "price", "order": "asc", "missing": "first"}
        ]
    }
}'

# Performance optimization with minSortCandidates
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
    "q": "laptops",
    "sortBy": {
        "fields": [{"fieldName": "price", "order": "desc"}],
        "minSortCandidates": 1000,
        "sortDepth": 60
    }
}'

Pagination

Handle large result sets with pagination using limit and offset parameters.

Parameters

Parameter	Type	Default	Description
`limit`	Integer	`10`	Maximum number of documents to return
`offset`	Integer	`0`	Number of documents to skip

Examples

# Page 1 (first 20 results)
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "laptops",
  "limit": 20,
  "offset": 0
}'

# Page 2 (results 21-40)
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "laptops",
  "limit": 20,
  "offset": 20
}'

Search as You Type

Search as you type provides real-time search results as users input queries, creating an instant and responsive search experience. This feature leverages the same search endpoint with optimized parameters for real-time performance.

Implementation

Use the standard search endpoint with these considerations for optimal real-time performance:

Lower limits: Use smaller limit values (5-10) for faster response times
Minimal attributes: Only retrieve essential fields using attributesToRetrieve
Client-side debouncing: Implement 200-300ms delays between requests
Minimum query length: Consider requiring 2-3 characters before triggering search

Example

# Real-time search with optimized parameters
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "q": "iph",
  "limit": 5,
  "attributesToRetrieve": ["productTitle", "variantTitle", "price", "variantImageUrl"]
}'

Best Practices

Debouncing: Implement client-side delays to prevent excessive API calls
Progressive loading: Start with minimal results and allow expansion
Caching: Cache recent results to improve perceived performance
Error handling: Gracefully handle timeouts and network issues
Accessibility: Ensure screen readers can navigate real-time results