Synonym Placeholders

Placeholders allow you to place not-yet-defined “tokens” (that can take any value from a list of defined words) as synonyms.

For example, “iPhone <version>” can mean “iPhone 7” or “iPhone 14” since “<version>” can be replaced by any of the following: “3G”, “3GS”, “4”, “4S”, “5”, “5C”, “5S”, “6”, “6S”, “7”, “8”, “X”, “11”, “12”, “13”, “14”.

Assume you sell phone cases. Since the same case will fit an iPhone 13 and an iPhone 14, you may want people who search for each of these models to find the same case. Your users probably won’t search for “Case for iPhone”; it’s more likely that they’ll search for “case iphone 13”, “iphone 14 case”, or something related to the specific model they own. However, if your record has a product_name field called “Case for iPhone”, these queries won’t return the correct record because there’s no mention of which models the case fits.

The multi-record workaround

You could create a record for every model the case supports. For example:

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

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 two records for one product. If you have many such multi-variant products, this can quickly deplete your record quota.
• It reduces performance. Since the distinct operation happens at query time, it affects search performance.

Use synonym placeholders instead

To define a placeholder, assign a token term and a list of replacement words. This token is inserted into your record’s attribute values when a user’s query matches one of the token’s replacement terms.

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

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

Define placeholders with angle brackets. Then, add the possible replacement terms as a list of strings.

1
2
3
4
5
{
   "type": "placeholder",
   "placeholder": "<model>",
   "replacements": ["13", "14"]
}

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

When to use distinct instead of placeholders

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 when 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 differs from the preceding iPhone case example, where the data is almost always the same and only one tiny piece of information changes.