Skip to content

Browse with Marqo

This guide shows you how to retrieve collections 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

Collections Requests

Collections requests are made via a POST /collections request.

Example

curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "womens-midi-dresses",
  "limit": 100,
  "offset": 200,
  "filter": "facet:isInstock:True",
  "sortBy": {
    "fields": [
      {"fieldName": "facet:ListPrice"}
    ]
  }
}'

Response

{
  "hits": [
    {
      "product_name": "Premium Wireless Bluetooth Headphones",
      "price": 199.99,
      "main_image_url": "https://cdn.example.com/headphones.jpg",
      "product_description": "High-quality over-ear headphones with noise cancellation",
      "_id": "PROD-001",
      "_score": 1.23456
    },
    {
      "product_name": "Wireless Earbuds Pro",
      "price": 149.99,
      "main_image_url": "https://cdn.example.com/earbuds.jpg",
      "product_description": "Compact wireless earbuds with premium sound",
      "_id": "PROD-002", 
      "_score": 1.15432
    }
  ],
  "limit": 10,
  "offset": 0,
  "query": "wireless headphones"
}

Collection Parameters

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

Parameter Type Default Description
collectionName String null (required) The name of the collection to browse
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 ["product_name", "price", "main_image_url", "product_description", "_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://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "audio-headphones",
  "filter": "price:[50 TO 300] AND is_available:true"
}'

# Logical operators with grouping
curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "athletic-shoes",
  "filter": "(brand:Nike AND collections:athletic) OR (brand:Adidas AND price:[* TO 150])"
}'

# Array field filtering
curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "electronics",
  "filter": "collections:audio OR collections:wireless"
}'

# Boolean and exact match
curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "featured-electronics",
  "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

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://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "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://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "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. This feature is only available for HYBRID search on unstructured indexes created with Marqo 2.22.0 or later.

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://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
    "collectionName": "shoes",
    "sortBy": {
        "fields": [{"fieldName": "price"}]
    }
}'

# Multi-field sort with missing value handling
curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
    "collectionName": "electronics",
    "sortBy": {
        "fields": [
            {"fieldName": "rating", "order": "desc", "missing": "last"},
            {"fieldName": "price", "order": "asc", "missing": "first"}
        ]
    }
}'

# Performance optimization with minSortCandidates
curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
    "collectionName": "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://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "laptops",
  "limit": 20,
  "offset": 0
}'

# Page 2 (results 21-40)
curl -X POST 'https://api.ecomm.marqo.ai/collections' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
  "collectionName": "laptops",
  "limit": 20,
  "offset": 20
}'