Synonym Placeholders

Placeholder synonyms are one of the four types of synonyms Algolia offers. They allow you to place not-yet-defined “tokens” and replace them 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 search, their query matches any of your token’s replacement terms. Placeholders let you have a single record for an item with multiple variants (instead of multiple records that leverage the distinct feature).

When to use placeholders

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

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

However, 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 related to the specific model they own. These queries won’t return the correct record because there’s no mention of which iPhone models the case is made for.

The multi-record workaround

You could consider including the model information by creating a separate record for every model the case supports. For example:

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 record. However, this approach has a couple of disadvantages:

• It requires many records. As you can see in the preceding snippet, you 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.

Try synonym placeholders instead

In the 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 span more than one attribute.

For example, it’s better to use distinct when indexing long documents. 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 only one result per document by using ‘distinct’ on the document’s title. Ideally, these records contain one or two paragraphs of text. Therefore, you end up with different records with only a few attributes in common. This is different from the preceding iPhone case example, where the data is almost always the same and only one tiny piece of information changes.