Skip to content

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

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