Adding Products to Marqo
This guide shows you how to add product documents to your Marqo ecommerce search index. Learn about the core product data structure, different value types, and comprehensive examples for building a robust product catalog.
Prerequisites
- A Marqo Cloud account (sign up here)
- Your Marqo API key (find your API key guide)
- An existing ecommerce index (create an index guide)
Add (or Replace) Documents
Documents (products) can be added or replaced by a POST /documents
request with the following body:
{
"documents": [
{
"_id": "PROD-001",
"product_name": "Premium Wireless Headphones",
"main_image_url": "https://cdn.example.com/headphones.jpg",
"product_description": "High-quality over-ear headphones with noise cancellation",
"price": 199.99,
"collections": ["electronics", "audio", "wireless"],
"parent_product_id": "HP-SERIES",
"variant_name": "Premium Wireless Headphones - Black"
}
]
}
Add Documents Parameters
Add documents parameters | Value Type | Description |
---|---|---|
documents |
Array of objects | An array of documents. Each document is represented as a JSON object. |
Document Parameters
Each document has the following fields:
Parameter | Type | Required | Description |
---|---|---|---|
_id |
string | Required | A unique string identifying this document. If catalogue contains variants, set this to the variant id |
product_name |
string | Required | The product's name e.g.: "Swim Cap" |
variant_name |
string | Optional | The variant's name: e.g. "Swim Cap - Red" |
main_image_url |
url | Required | The image URL that Marqo must use for vision search. Note that the URL must be publicly accessible. This must also be the image of the variant, if using variants. |
price |
number | Required | The price of the product. |
collections |
array of strings | Optional | An array of collections that this product belongs to. |
parent_product_id |
string | Optional | If specified then the parent_product_id represents the parent product of this variant. When present, only one of each parent product id will be shown in search results. |
product_description |
string | Optional | Description of the product. |
Additional Custom Fields
You can add any other custom fields to your product documents beyond the core parameters listed above. Here are the accepted field types and their properties:
Field Type | Description |
---|---|
Strings | Text fields |
Floats | Numeric fields that can be used to filter search results |
Bools | Boolean fields that can be used to filter search results |
Ints | Integer fields that can be used to filter search results |
Array | Currently only arrays of strings are supported. Can be used for filtering and lexical search |
Example with Custom Fields
{
"_id": "PROD-001",
"product_name": "Premium Wireless Headphones",
"main_image_url": "https://cdn.example.com/headphones.jpg",
"price": 199.99,
"collections": ["electronics", "audio"],
"product_description": "High-quality headphones",
// Custom fields
"brand": "AudioTech", // String
"weight_grams": 250.5, // Float
"is_wireless": true, // Bool
"stock_quantity": 45, // Int
"features": ["bluetooth", "noise-cancel"] // Array of strings
}
Adding Products to Your Index
curl -X POST 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '{
"documents": [
{
"_id": "PROD-001",
"product_name": "Premium Wireless Headphones",
"variant_name": "Premium Wireless Headphones - Black",
"main_image_url": "https://cdn.example.com/headphones.jpg",
"price": 199.99,
"collections": ["electronics", "audio", "wireless"],
"parent_product_id": "HP-SERIES",
"product_description": "High-quality over-ear headphones with noise cancellation"
}
]
}'
Response
The response of the add_documents
endpoint operates on two levels. A status code of 200
indicates that the batch request has been successfully received and processed by Marqo. The response has the following fields:
Field Name | Type | Description |
---|---|---|
errors |
Boolean | Indicates whether any errors occurred during the processing of the batch request. |
items |
Array | An array of objects, each representing the processing status of an individual document in the batch. |
processingTimeMs |
Integer | The time taken to process the batch request, in milliseconds. |
index_name |
String | The name of the index to which the documents were added. |
Each item in the items
array has the following fields:
Field Name | Type | Description |
---|---|---|
_id |
String | The ID of the document that was processed. |
status |
Integer | The status code of the document processing. |
message |
String | A message that provides additional information about the processing status of the document. This field only exists when the status is not 200 . |
Here is the HTTP status code of the individual document responses:
Status Code | Description |
---|---|
200 |
The document is successfully added to the index. |
400 |
Bad request. Returned for invalid input (e.g., invalid field types). Inspect message for details. |
429 |
Marqo vector store receives too many requests. Please try again later. |
500 |
Internal error. |
Best Practices
Data Quality
- Consistent IDs: Use meaningful, consistent product IDs (e.g.,
ELEC-001
,CLOTH-002
) - Complete Descriptions: Provide detailed, searchable product descriptions
- High-Quality Images: Use clear, high-resolution product images with publicly accessible URLs
- Accurate Pricing: Keep prices up-to-date and in consistent format