Skip to content

Deduping & Variants

Marqo's search API provides built-in support for searching over product variants, allowing you to group variants together and ensure diverse, relevant search results without duplicates.

Overview

Products often have multiple variants (different colors, sizes, or other attributes). Marqo's search API handles variants using collapse fields, which group related product variants together and return only the most relevant variant from each group. This ensures users see diverse results without duplicate products cluttering their search results.

How Variant Search Works

Using Collapse Fields

Marqo's search API includes a collapseFields parameter that groups search results by a specified field (typically a product ID or parent product identifier). This ensures that:

  • One variant per product: Only the highest-scoring variant from each product group is returned
  • Diverse results: Users see different products, not multiple variants of the same product
  • Maintains relevance: Results are still ranked by relevance, just grouped by product

Basic Variant Grouping

To search over variants and group them by product, use the collapseFields parameter in your search request:

curl -X POST "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search" \
  -H "x-marqo-index-id: {index_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "running shoes",
    "collapseFields": [{"name": "product_id"}],
    "limit": 10
  }'

This will return the top-ranked variant from each product, ensuring product diversity in search results.

Selecting Specific Variants

You can also control which variant is selected from each group using sortBy within the collapse field. For example, to return the cheapest variant from each product:

curl -X POST "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search" \
  -H "x-marqo-index-id: {index_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "running shoes",
    "collapseFields": [
      {
        "name": "product_id",
        "sortBy": {
          "fields": [{"fieldName": "price", "order": "asc"}]
        }
      }
    ],
    "limit": 10
  }'

This returns the cheapest variant from each product group while maintaining group ordering by relevance.

Combining with Filters and Facets

Collapse fields work seamlessly with other search features:

curl -X POST "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/search" \
  -H "x-marqo-index-id: {index_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "running shoes",
    "collapseFields": [{"name": "product_id"}],
    "filter": "price:[* TO 100]",
    "facets": {
      "fields": {
        "color": {"type": "string"},
        "size": {"type": "string"}
      }
    }
  }'

This example groups variants by product, filters by price, and provides facets for color and size.

Variant Types Supported

Color Variants

Products with different colors are automatically grouped when using collapseFields with a product identifier field. Each color variant is indexed separately, but only one variant per product appears in results.

Size Variants

Size variants are handled the same way—grouped by product ID so users see one product per result, not multiple sizes of the same product.

Multi-Dimensional Variants

Products with multiple variant dimensions (e.g., color + size combinations) are all grouped under the same product identifier, ensuring users see diverse products rather than multiple combinations of the same base product.

Requirements

For collapse fields to work:

  • Field must be defined: The collapse field (e.g., product_id) must be defined in your index settings during index creation
  • String values: Field values must be strings, present in all documents, and cannot be empty or whitespace
  • Single field: Currently supports grouping on one collapse field (multi-field support coming in future updates)

Best Practices

  1. Use product identifiers: Use a consistent product identifier field (e.g., product_id, parent_product_id) for grouping variants
  2. Index all variants: Make sure all product variants are indexed with the same product identifier
  3. Choose representative variants: Use sortBy within collapse fields to select the most appropriate variant (e.g., cheapest, highest-rated, most popular)
  4. Combine with filters: Use filters to narrow results while maintaining variant grouping
  5. Test variant selection: Verify that the variant selection strategy (relevance vs. sortBy) works well for your use case