About dictionary fields

This is for:

Developer System Administrator

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.

Notes

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.