Structure ecommerce product records

In ecommerce, you often deal with base products and their variants. A base product, such as a t-shirt, can have variants with different colors and sizes. You can store this data in Algolia in three ways:

Variant-level records: one Algolia record for each product variation.
Product-level records: one Algolia record for each base product. The record contains all variants.
Variation-group-level records: one Algolia record for each variation of a specific attribute, generally the color. Each record contains variations sharing this attribute value.

Record structure examples

The following example shows records for a t-shirt in two colors. Each color comes in two sizes. With the variant-level records model, each variant is a separate record:

JSON

[
  {
    "objectID": "v-neck-t-shirt-white-m",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "White",
    "size": "M",
    "image": "v-neck-t-shirt-white.jpg",
    "price": 19.99
  },
  {
    "objectID": "v-neck-t-shirt-white-l",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "White",
    "size": "L",
    "image": "v-neck-t-shirt-white.jpg",
    "price": 19.99
  },
  {
    "objectID": "v-neck-t-shirt-blue-m",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "Blue",
    "size": "M",
    "image": "v-neck-t-shirt-blue.jpg",
    "price": 22.99
  },
  {
    "objectID": "v-neck-t-shirt-blue-l",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "Blue",
    "size": "L",
    "image": "v-neck-t-shirt-blue.jpg",
    "price": 22.99
  }
]

With the product-level records model, all variants of a base product are in a single record. The common attributes sit at the top level. The varying attributes, such as color, size, images, and prices, sit in a variants array. Each array item corresponds to a unique variant:

JSON

{
  "objectID": "v-neck-t-shirt",
  "name": "V-neck t-shirt",
  "category": "Sport",
  "variants": [
    {
      "variantID": "v-neck-t-shirt-white-m",
      "color": "White",
      "size": "M",
      "image": "v-neck-t-shirt-white.jpg",
      "price": 19.99
    },
    {
      "variantID": "v-neck-t-shirt-white-l",
      "color": "White",
      "size": "L",
      "image": "v-neck-t-shirt-white.jpg",
      "price": 19.99
    },
    {
      "variantID": "v-neck-t-shirt-blue-m",
      "color": "Blue",
      "size": "M",
      "image": "v-neck-t-shirt-blue.jpg",
      "price": 22.99
    },
    {
      "variantID": "v-neck-t-shirt-blue-l",
      "color": "Blue",
      "size": "L",
      "image": "v-neck-t-shirt-blue.jpg",
      "price": 22.99
    }
  ]
}

With the variation-group-level records model, variants that share the same value of a given attribute, typically the color, sit in a single record. For the t-shirt example, there are two records, one for each color. The common attributes sit at the top level. The varying attributes, such as size and price, sit in a variants array. Each array item corresponds to a unique variant:

JSON

[
  {
    "objectID": "v-neck-t-shirt-white",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "White",
    "image": "v-neck-t-shirt-white.jpg",
    "variants": [
      {
        "variantID": "v-neck-t-shirt-white-m",
        "size": "M",
        "price": 19.99
      },
      {
        "variantID": "v-neck-t-shirt-white-l",
        "size": "L",
        "price": 19.99
      }
    ]
  },
  {
    "objectID": "v-neck-t-shirt-blue",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "Blue",
    "image": "v-neck-t-shirt-blue.jpg",
    "variants": [
      {
        "variantID": "v-neck-t-shirt-blue-m",
        "size": "M",
        "price": 22.99
      },
      {
        "variantID": "v-neck-t-shirt-blue-l",
        "size": "L",
        "price": 22.99
      }
    ]
  }
]

Choose your record model

When choosing between the three indexing models, consider whether you use Algolia AI or merchandising features. Use the variation-group-level or product-level record model if you use Algolia AI or merchandising features. These models can work better when your variants look alike:

Algolia groups click and conversion events from each variant by objectID, meaning by base product or by variation-group. This lets Algolia re-rank or personalize results at the product or variation-group level, not just for specific variants.
Merchandising at the product-level or variation-group-level is simpler when you have many variants. For example, you can promote or hide products or variations rather than individual variants.
Search analytics groups results by product or variation, which makes them simpler to analyze.

Use the variant-level record model if you don’t use Algolia AI or merchandising. This model is more granular and better suited for precise control:

Results match the most relevant variant directly. For example, a search for “red shoes” returns only variants with “red” in their data. In contrast, the product model requires more frontend work to display the correct variant.
Faceting is more accurate. A like color: green AND size: 40 returns only matching variants, not entire products with partial matches. In the product model the two conditions can match different variants, so the results can include products where no single variant satisfies both. See Filters and arrays of objects.
You can update individual variant attributes, such as price or stock. The product model requires resending the full list of variants, because it doesn’t support partial updates.

The variation-group-level model is a good compromise between the two other models.It offers better AI and merchandising features than the variant-level model, while staying more granular than the product-level model. For example, using color as the grouping attribute means a search for red shoes returns only records with “red” in their data. This lets you show the matching image without extra frontend work.

Capabilities by record model

	Variant-level	Product-level	Variation-group-level
AI features	PER VARIANT	PER PRODUCT	PER VARIATION GROUP
Rules and merchandising	PER VARIANT	PER PRODUCT	PER VARIATION GROUP
Search analytics	PER VARIANT	PER PRODUCT	PER VARIATION GROUP
Textual relevance	OPTIMIZED	SUPPORTED	OPTIMIZED FOR THE VARIATION
Faceting support	OPTIMIZED	Requires frontend work (see below)	OPTIMIZED FOR THE VARIATION
Variant-powered PLP	OPTIMIZED	Requires frontend work (see below)	OPTIMIZED FOR THE VARIATION
Granular variant update	SUPPORTED	Not supported	Not supported
Average record size	Depending on further choices (see Average record size)	OPTIMIZED	OPTIMIZED
Number of records	HIGH	OPTIMIZED	Depends on the number of variants of each variation

Average record size for the variant-level model

The average record size for the variant-level model depends on what you want to show on your results, for example, if you want to include color swatches or images carousels. To display those, each of your variant records needs to have information about their siblings, which increases the average record size.

Results display

Group records per product

Depending on your desired end-user experience and catalog size, showing one result per product, instead of listing each variant separately, can offer a cleaner, friendlier interface. With the product-level record model, you get one result per product by default. The variant-level model requires using the distinct feature to group variants under a single result. To do this, include a shared product ID in each variant record and set the distinct parameter on that attribute:

JSON

{
  "objectID": "v-neck-t-shirt-white-m"
  "name": "V-neck t-shirt",
  "baseProductID": "v-neck-t-shirt",
  // ...
}

The variation-group-level model gives you the choice:

By default, you get one result per variation (for example, one per color).
Or you can use the distinct feature the same way as for the variant-level model and display one result per product.

The variant-level record model lets users refine results. In this model, Algolia returns only the variants that match a selected , with no extra frontend logic required. This also works well for the variation-group-level model when it’s based on color. Images are often the same for all variants of a given color, so a record’s variants tend to share the same image. This means you don’t need extra frontend logic here either. In contrast, the product-level model always returns the entire product, including all variants. To display only the matching variants, you need to post-process the search results in your InstantSearch code:

JavaScript

hits({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => {
      const colorFacets = results._state.disjunctiveFacetsRefinements['variants.color'] || [];

      let selectedVariant;
      if (colorFacets.length > 0) {
        selectedVariant = item.variants.find(variant => {
            return colorFacets.includes(variant.color);
        });
      } else {
        selectedVariant = item.variants[0];
      }

      item.image = selectedVariant.image;
      item.price = selectedVariant.price;
      item.url = selectedVariant.url;

      return item;
    });
  },
});

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Structure ecommerce product records

Record structure examples

Choose your record model

Capabilities by record model

Average record size for the variant-level model

Results display

Group records per product

Facets

​Record structure examples

​Choose your record model

​Capabilities by record model

​Average record size for the variant-level model

​Results display

​Group records per product

​Facets

Record structure examples

Choose your record model

Capabilities by record model

Average record size for the variant-level model

Results display

Group records per product

Facets