Item Variations

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).

Take the example of an ecommerce 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, you want to make sure that whenever someone types “red t-shirt”, the page only displays products with a red thumbnail. Also, you want to make sure to only get a single item per model, and find a clever way to display all variants.

Dataset example

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

In your dataset, you 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 your 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, you could also add all the possible color variations for each record. This way, you could display all the variants for a single product in your front end (for example, 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 displaying always 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, restrict what attributes are searchable. You 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, you 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
8
9
index.setSettings({
  searchableAttributes: [
    'model',
    'type',
    'color'
  ]
}).then(() => {
  // done
});

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
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
5
6
index.setSettings({
  attributeForDistinct: 'model',
  distinct: true
}).then(() => {
  // done
});

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
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
index.search('query', {
  distinct: true
}).then(({ hits }) => {
  console.log(hits);
});

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

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

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

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, then go to the Search product 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, you get one color for each model. To control which one, you can set a new attribute with business metrics, for example, number_of_sales, and set it up for custom ranking.

Additionally, you 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.