About dictionary fields

This is for:

In this article

Limitations
Index dictionary fields
Query dictionary fields

Dictionary fields let you store multiple key-value pairs under a single field. This is useful when you want to store different values for an item, and display one of them depending on the context of the search. The most common use case is in commerce environments, when a single item can have multiple price values, depending on the store location.

Dictionary is not a type of field, but rather a capability option for string and numeric fields. To enable the dictionary capability, set the keyValue property to true when creating or updating a field through the Field API.

Limitations

If you make a dictionary field free-text searchable, all its values are indexed as free-text searchable. You should therefore avoid making dictionary fields free-text searchable if you want the values to remain secret.

Currently, dictionary fields are natively supported by the Push API and Stream API. To have sources other than Catalog and Push populate dictionary fields, you must create an indexing pipeline extension with the API, and specify you want to use version 2 of the API.
Dictionary fields are limited to 100,000 key-value pairs.

Index dictionary fields

When indexing an item, to set a value for a dictionary field, pass an object with key-value pairs as metadata.

{
   "data": "item data",
   ...
   "myfield": {
       "": "default",
       "key1": "value1",
       "key2": "value2"
   },
   ...
}

This will index all the different values under myfield on the item. This field needs to already exist in your list of fields. You can have multiple dictionary fields per item.

You can specify the default value for a dictionary field by using the empty string "" as a key. If you don’t specify a default value, and the context isn’t provided, the field won’t exist on the item.

Note

While dictionary fields allow you to abstract multiple key-value pairs under a single field, these keys don’t create separate fields visible in your Coveo organization.

You can retrieve dictionary field values using the dictionaryFieldContext query parameter.

Query dictionary fields

The Search API exposes the dictionaryFieldContext query parameter that lets you send the desired key to be selected per field.

{
   "dictionaryFieldContext": {
       "myfield": "key1",
       "myotherfield": "key2",
       ...
   },
}

This lets you select a different key for every field. If no context is selected for a dictionary field, the default value will be returned, if one exists. If there’s no default value, the field will be undefined. You can’t select more than one key per field. Facets, ranking rules, and filters are all able to use this value as a regular field type.