About dictionary fields
About 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.