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 |
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://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
}
}'
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
}'