Skip to content

Getting Started with Marqo for Ecommerce Search

Before You Start: Check Our Integrations

Is your site hosted on an ecommerce platform? You might be able to get started faster with one of Marqo's one-click integrations. Check out the available integrations to see if your platform (Shopify, Magento, etc. ) has a pre-built connector.

If no integration exists for your platform, or you'd prefer to integrate directly, please continue with this guide to integrate directly with our dev-friendly API.

Guide Prerequisites

  • Marqo Cloud Account: Sign up at cloud.marqo.ai. (if you don't have an account, please reach out!)
  • Python 3.7+ installed on your machine
  • Your product data in JSON format (data can be in any format — guide assumes JSON)

Step 1: Get Your API Key

  1. Sign into Marqo Cloud
  2. Navigate to the API Keys section in your dashboard
  3. Create a new API key and copy it - you'll need this for the code

Step 2: Create Your Index (In the Console)

Marqo indexes can be created via the REST API, the python client, or the Marqo Cloud console. This guide walks through setting up an index via the console.

In the Marqo Cloud console:

  1. Click "Indexes" in the left navigation
  2. Click "Create Index"
  3. Configure your index:
    • Index Name: my-ecommerce-store
    • Indexing mode: Image-compatible
    • Model: Select marqo-ecommerce-embeddings-L (optimized for ecommerce)
    • Shard Type: marqo.balanced (perfect for getting started)
    • Number of Shards: 1
    • Inference Pod Type: marqo.GPU
    • Number of Inference Pods: 1
  4. Click "Create Index"

Your index will take a few minutes to initialize. You'll see the status change from "Creating" to "Ready".

Why use ecommerce models? Marqo's specialized ecommerce models outperform existing solutions like Amazon Titan's Multimodal Embedding by up to 88% and the best open source model by up to 31% for product search tasks.

Step 3: Prepare Your Product Data

Create a JSON file with your product data. For this guide, here's the required format:

products.json: 

[
  {
    "_id": 1,
    "name": "Red Summer Dress",
    "image_url" : summer_dress.png,
    "description": "Beautiful red dress perfect for summer events",
    "price": 89.99,
    "category": "Clothing"
  },
  {
    "_id": 2,
    "name": "Blue Sneakers",
    "image_url" : blue_sneakers.png,
    "description": "Comfortable blue running sneakers",
    "price": 129.99,
    "category": "Shoes"
  },
  {
    "_id": 3,
    "name": "Coffee Maker",
    "image_url" : coffee_maker.png,
    "description": "Automatic drip coffee maker",
    "price": 79.99,
    "category": "Appliances"
  }
]

Step 4: Install and Set Up Python Client

pip install marqo

Create a new Python file called ecommerce_search.py:

import marqo
import json

# Replace with your actual API key from Step 1
API_KEY = "your_api_key_here"
INDEX_NAME = "my-ecommerce-store"  # Same name as Step 2

# Initialize Marqo client
mq = marqo.Client("https://api.marqo.ai", api_key=API_KEY)

Step 5: Read in Documents

with open("products.json", "r") as file:
    documents = json.load(file)

Step 6: Index Documents

Add your products to the search index:

mq.index(INDEX_NAME).add_documents(
    documents,
    # create document embeddings that use both the image and the title
    mappings={
        "multimodal": {
            "type": "multimodal_combination",
            "weights": {
                "image_url": 0.9,
                "name": 0.1
            }
        }
    },
    # set the tensor field
    tensor_fields=["multimodal"]
)
print("Products added successfully!")

Step 7: Search Your Products

Basic Search Configuration

results = mq.index(INDEX_NAME).search(
    q="red jacket",
    search_method="HYBRID",
    hybrid_parameters={
        "rrfK": 60,
        "alpha": 0.7,
        "searchableAttributesLexical": [
            "title",
            "description"
        ]
    }
)

Complete Example Script

import marqo
import json

# Configuration
API_KEY = "your_api_key_here"
INDEX_NAME = "my-ecommerce-store"

# Initialize client
client = marqo.Client("https://api.marqo.ai", api_key=API_KEY)

# Sample products (you can also load from products.json file)
sample_products = [
    {
        "_id": "1",
        "name": "Red Summer Dress",
        "description": "Beautiful red dress perfect for summer events",
        "price": 89.99,
        "category": "Clothing"
    },
    {
        "_id": "2", 
        "name": "Blue Running Sneakers",
        "description": "Comfortable blue sneakers for running",
        "price": 129.99,
        "category": "Shoes"
    }
]

# Alternative: Load from JSON file
# with open("products.json", "r") as file:
#     products_data = json.load(file)
#     sample_products = []
#     for product in products_data:
#         sample_products.append({
#             "_id": str(product['product_id']),
#             "name": product['name'],
#             "description": product.get('description', ''),
#             "price": product.get('price', 0),
#             "category": product.get('category', '')
#         })

# Add products
client.index(INDEX_NAME).add_documents(sample_products)

# Search
results = client.index(INDEX_NAME).search(
    "red dress for special occasion",
    search_method="HYBRID",
    limit=5
)

# Display results
for hit in results['hits']:
    print(f"✨ {hit['name']} - ${hit['price']}")