Item Variations

Overview

Anytime you have products that come in variations - for example, in different colors - knowing how to structure your data to best represent your inventory without duplicates can become tricky. Good examples are t-shirts of different colors or smartphones with different storage capacity (and consequently different prices).

Let’s take the example of an e-commerce website selling t-shirts and sweatshirts in a variety of models and colors. The simplest solution would be to have one record per model and only have a list of possible color variants. The issue with this approach is that whenever someone searches for “red t-shirt”, the engine returns all the t-shirt models that have at least one variant in red. However, the thumbnail would not necessarily be red, which would be confusing.

Instead, we want to make sure that whenever someone types “red t-shirt”, the page only displays products with a red thumbnail. Also, we want to make sure we only get single item per model, and find a clever way to display all variants.

Dataset Example

In our inventory, we have two t-shirt models (A and B) and two models of sweatshirts (C and D). Each model comes in several colors.

In our dataset, we can represent them by creating one record for each color variant of each item. Each record specifies the type, the model, the color and the associated thumbnail. Here’s what our records look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
  {
    "type": "t-shirt",
    "model": "B",
    "color": "blue",
    "thumbnail_url": "tshirt-B-blue.png"
  },
  {
    "type": "sweatshirt",
    "model": "C",
    "color": "red",
    "thumbnail_url": "sweatshirt-C-red.png"
  },
  ...
]

Going a step further, we could also add all the possible color variations for each record. This way, we could display all the variants for a single product in our front end (e.g., color swatches under the thumbnail), allowing the end user to discover them.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
    "type": "t-shirt",
    "model": "B",
    "color": "blue",
    "thumbnail_url": "tshirt-B-blue.png",
    "color_variants": ["orange", "teal", "yellow", "red", "green"]
  },
  {
    "type": "t-shirt",
    "model": "B",
    "color": "orange",
    "thumbnail_url": "tshirt-B-orange.png",
    "color_variants": ["blue", "teal", "yellow", "red", "green"]
  },
  ...
]

With this approach, every record represents a single variation, which ensures we always display consistent data. Having one record per variation also lets you add granular custom ranking attributes, like number_of_sales. Besides, you can leverage Algolia’s distinct feature to de-duplicate models. This way, when someone searches for “t-shirt”, they only get one of each model.

Using the API

At indexing time

Before de-duplicating items, we want to restrict what attributes are searchable. We don’t want to search into thumbnail_url, which may be irrelevant and add noise, nor into color_variants, because it could lead to false positives. Therefore, we can set model, type and color as searchableAttributes.

1
2
3
4
5
6
7
$index->setSettings([
  'searchableAttributes' => [
    "model",
    "type",
    "color"
  ]
]);

1
2
3
4
5
6
7
index.set_settings({
  searchableAttributes: [
    'model',
    'type',
    'color'
  ]
})

1
2
3
4
5
6
7
index.setSettings({
  searchableAttributes: [
    'model',
    'type',
    'color'
  ]
});

1
2
3
4
5
6
7
index.set_settings({
    'searchableAttributes': [
        'model',
        'type',
        'color'
    ]
})

1
2
3
4
5
6
7
index.setSettings([
  "searchableAttributes": [
    "model",
    "type",
    "color"
  ]
])

1
2
3
4
5
6
7
8
9
index.setSettings(
  new JSONObject().put(
    "searchableAttributes",
    new JSONArray()
      .put("model")
      .put("type")
      .put("color")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string>
    {
      "model",
      "type",
      "color"
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
index.setSettings(
  new IndexSettings().setSearchableAttributes(Arrays.asList(
    "model",
    "type",
    "color"
  ))
);

1
2
3
4
5
6
7
res, err := index.SetSettings(search.Settings{
  SearchableAttributes: opt.SearchableAttributes(
    "model",
    "type",
    "color",
  ),
})

1
2
3
4
5
6
7
8
9
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    searchableAttributes = Some(Seq(
      SearchableAttributes.attributes("model")
      SearchableAttributes.attribute("type")
      SearchableAttributes.attributes("color")
    ))
  )
}

1
2
3
4
5
6
7
8
9
val settings = settings {
    searchableAttributes {
        +"model"
        +"type"
        +"color"
    }
}

index.setSettings(settings)

To use distinct you first need to set model as attributeForDistinct during indexing time. Only then can you set distinct to true to de-duplicate your results. Note that setting distinct at indexing time is optional. If you want to, you can set it at query time instead.

1
2
3
4
$index->setSettings([
  'attributeForDistinct' => 'model',
  'distinct' => true
]);

1
2
3
4
index.set_settings({
  attributeForDistinct: 'model',
  distinct: true
})

1
2
3
4
index.setSettings({
  attributeForDistinct: 'model',
  distinct: true
});

1
2
3
4
index.set_settings({
    'attributeForDistinct': 'model',
    'distinct': True
})

1
2
3
4
index.setSettings([
  "attributeForDistinct": "model",
  "distinct": true
])

1
2
3
4
5
index.setSettings(
  new JSONObject()
    .put("attributeForDistinct", "model")
    .put("distinct", true)
);

1
2
3
4
5
6
7
8
9
10
IndexSettings settings = new IndexSettings
{
    AttributeForDistinct = "model",
    Distinct = true
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
index.setSettings(
  new IndexSettings()
    .setAttributeForDistinct("model")
    .setDistinct(Distinct.of(true))
);

1
2
3
4
res, err := index.SetSettings(search.Settings{
  AttributeForDistinct: opt.AttributeForDistinct("model"),
  Distinct:             opt.Distinct(true),
})

1
2
3
4
5
6
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributeForDistinct = Some("model"),
    distinct = Some(true)
  )
}

1
2
3
4
5
6
val settings = settings {
    attributeForDistinct = Attribute("model")
    distinct = Distinct(1)
}

index.setSettings(settings)

At query time

Once attributeForDistinct is set, you can enable distinct by setting it to true. Note that you can set distinct to true or 1 interchangeably.

1
2
3
$results = $index->search('query', [
  'distinct' => true
]);

1
2
3
results = index.search('query', {
  distinct: true
})

1
2
3
4
5
6
7
index.search({
  query: 'query',
  distinct: true
}).then(res => {
  // console.log(res);
});

1
2
3
results = index.search('query', {
    'distinct': True
})

1
2
3
4
5
6
7
let query = Query(query: "query")
query.distinct = true

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
index.search(
  new Query("query").setDistinct(true)
);

1
2
3
index.Search(new Query<JObject>("query") {
    Distinct = true
});

1
2
3
index.search(
  new Query("query").setDistinct(Distinct.of(true))
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Distinct(true),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    distinct = Some(true)
  )
}

1
2
3
4
5
val query = query("query") {
    distinct = Distinct(1)
}

index.search(query)

Using the Dashboard

You can also set your attribute for distinct and enable distinct in your Algolia dashboard.

1. Go to your dashboard and select your index.
2. Click on the Configuration tab.
3. In the Searchable Attributes section, click the “Add a searchable attribute” button.
4. Select the model, type and color attributes in the dropdown one after another.
5. Click the Deduplication and Grouping tab, which you can find under Search behavior.
6. Set the Distinct dropdown to true.
7. Set the Attribute for Distinct dropdown to model.
8. Don’t forget to save your changes!

When distinct is set to true, we get one color for each model. To control which one, you can set a new attribute with business metrics (e.g., number_of_sales) and set it up for custom ranking.

Additionally, we can display all available colors for each item thanks to the color_variants attribute. This way, the end user can access all possible variants from the search results without the page being crowded with too many items.