Synonym Placeholders

Placeholder synonyms are one of the four types of synonyms Algolia offers. They allow you to place not-yet-defined “tokens” that can be replaced with any value from a list of defined terms.

To define a placeholder, you need to assign a token term and a list of replacement words to one of your objects. You can then insert this token in your object’s attribute values. When users make a search, their query matches any of your token’s replacement terms. Placeholders let you have a single record for an item with multiple variants, as opposed to multiple records that leverage the distinct feature.

Placeholders

For example, let’s assume you sell phone cases. Most phone cases work for different models: the same case can work for iPhone 6, iPhone 7, and iPhone 8. As a result, you may want for people who search for each of these respective models to find the same case. Let’s consider what a record for this product could look like:

1
2
3
{
  "product_name": "Case for iPhone"
}

Your users probably won’t search for “Case for iPhone”. It’s more likely that they’ll search for “case iphone 7”, “iphone 6 case”, or something that relates to the specific iPhone model that they own. The problem is, these queries won’t return our record, because there’s no mention of which iPhone models the case is made for.

One way you could include the model information is by creating a separate record for every model the case supports.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
    "product_name": "Case for iPhone",
    "sku": "123456",
    "model": "iPhone 6"
  },
  {
    "product_name": "Case for iPhone",
    "sku": "123456",
    "model": "iPhone 7"
  },
  {
    "product_name": "Case for iPhone",
    "sku": "123456",
    "model": "iPhone 8"
  }
]

Now, whenever a user searches, you can apply the distinct parameter on the sku attribute to show only the best matching version.

This approach has a couple of disadvantages:

• It requires many records. As you can see in the snippet above, we need three records for one product. If you have many multi-variant products, this can quickly deplete your record quota.
• Distinct is a costly operation. Since distinct happens at query time, it affects performance.

In our phone case example, it makes more sense to use synonym placeholders to achieve the same result, but with a single record.

1
2
3
4
5
6
[
  {
    "product_name": "Case for iPhone <model>",
    "sku": "123456"
  }
]

You can define placeholders with angle brackets. Then, you can add the possible replacement terms as a list of strings.

1
2
3
4
5
{
   "type": "placeholder",
   "placeholder": "<model>",
   "replacements": ["6", "7", "8"]
}

Now, searches for “case iphone 6”, “case iphone 7” or “case iphone 8” will match case for iPhone <model> in any of your records.

When to use distinct

Sometimes it makes sense to use distinct instead of placeholders.

As a rule of thumb:

• Use placeholders if you have tiny variations in a single record.
• Use distinct on large documents, or when the variations on a single record spans more than one attribute.

For example, it’s better to use distinct when you want to index long documents with Algolia. In this case, you have to split long chunks of text into smaller records to limit record size, and improve relevance. You can then ensure to only yield one result per document by using distinct on the title of the document. Ideally, these records contain one or two paragraphs of text. Therefore, you end up with different records that have only a few attributes in common. This is different from our iPhone case example, where the data is almost always the same, and only one tiny piece of information changes.