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 a given field and display one depending on the query context, such as user type, subscription level, or store location. A common use case is in commerce environments, where a product may have different price values depending on customer eligibility.

Dictionary isn’t a type of field, but rather a capability option for string and numeric fields.

To enable dictionary support for a field, set the keyValue property to true when creating or updating the field through the Field API.

Field limit and cardinality considerations

Cardinality refers to the number of distinct values contained in a dictionary field.

When you index a dictionary field, Coveo creates an underlying field for each distinct value it contains. Since each distinct value in a dictionary contributes an underlying field, high-cardinality dictionaries can quickly consume your available field quota and affect query latency and indexing performance.

To optimize performance, Coveo uses a deduplication process, only creating an underlying field for each unique numerical value in a dictionary. This means that multiple keys sharing the same numerical value all contribute to the same underlying field.

For example, suppose you index a price_list dictionary with four keys but only two unique values:

"price_list": {
  "key_1": 10.99,
  "key_2": 10.99,
  "key_3": 12.99,
  "key_4": 10.99
}

In this case, the index creates only two underlying fields: one for 10.99 and another for 12.99.

However, if your dictionary contains hundreds of distinct numerical values, the index will create hundreds of fields.

Dictionary fields storing string values don’t benefit from deduplication. Every unique string value creates its own underlying field, even if identical strings appear in other dictionary entries.

Limitations

Important

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 the values must remain confidential or internal.

  • Currently, dictionary fields are natively supported by the Push API and Stream API. To have sources other than Catalog and Push populate dictionary fields, create an indexing pipeline extension with the API, and specify you want to use version 2 of the API.

  • Dictionary fields can technically contain up to 100,000 key-value pairs. However, each distinct value counts toward your organization’s field limit (5,000 by default). Large dictionaries with many unique values may exceed your field quota and significantly degrade performance. Contact your Coveo representative if you need to increase your field limit. You can monitor your field usage in the Limits (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

  • Dictionary fields storing string values don’t benefit from deduplication. Each unique string value creates a separate underlying field, increasing memory usage and query latency.

Leading practices

Dictionary fields let you store multiple values under a single field, but large dictionaries can impact performance. Keep the following recommendations in mind:

  • Item size: Each key/value pair increases the size of the indexed item. Larger items take longer to ingest and use more memory, potentially slowing down indexing and query response times. Removing unnecessary keys and excluding irrelevant fields from your results can improve loading time.

  • Cardinality: To stay within your field limit and maintain good performance, keep the number of distinct values in the low hundreds. Treat anything over 1,000 unique values per dictionary as high risk and consider a different modeling strategy.

  • Dictionary strings: Avoid using dictionary fields for high-cardinality string values. Dictionary fields storing string values don’t benefit from deduplication. Every unique string value creates a separate underlying field, even if identical strings appear in multiple items. This can quickly consume your field quota and increase index size.

Index dictionary fields

When indexing an item, you can set values for a dictionary field by passing an object with key-value pairs in the item metadata.

The field must already exist in your Coveo organization and be dictionary-enabled.

For example, the following JSON object defines different prices in the price_list field based on the user’s subscription level:

{
    "DocumentId": "product://001",
    "ec_name": "Mercury Alternator",
    "model": "Authentic",
    "ec_brand": "Barca",
    "ec_description": "Barca Mercury makes high-quality boat alternators that are perfect for powering all your boating needs.",
    "ec_item_group_id": "001",
    "ec_product_id": "Barca-Alt-001",
    "price_list": { 1
        "Default": 4000.00, 2
        "Vip": 3750.00, 3
        "Premium": 3900.00 4
    },
    "ec_in_stock": true,
    "ec_category": "Alternators",
    "departement": "Boat parts",
    "objecttype": "Product"
}
1 price_list is a dictionary field with key-value pairs.
2 The Default key defines the default price for all users.
3 The Vip key defines a special price for VIP users.
4 The Premium key defines a price for Premium users.

You can define multiple dictionary fields on the same item.

Retrieve values from dictionary fields

To retrieve a specific value from a dictionary field, you must indicate which key to use at query time.

There are two ways to do this:

  • Embedding the dictionaryFieldContext parameter in a search token.

  • Specifying the key using the dictionaryFieldContext parameter in the query. This is only available for queries targeting the Search API. If you’re using the Commerce API, you can only specify the key in the search token.

Note

If a key is specified in both the token and the query, the value from the token takes precedence.

In a search token

You can embed a dictionary key selection in the search token used to authenticate users.

This is particularly useful for ensuring a consistent experience in interfaces tailored to user-specific pricing or metadata.

For example, you might define the dictionary key in the token for authenticated VIP subscribers:

{
  "userIds": [
    {
      "name": "asmith@ibuystuff.com",
      "type": "User",
      "provider": "Email Security Provider"
    }
  ],
  "userDisplayName": "Alice Smith",
  "userGroups": "buyers",
  "dictionaryFieldContext": { "price_list": "Vip" } 1
}
1 This ensures that the price_list field returns the value associated with the Vip key.

In a query

The Search API supports a dictionaryFieldContext parameter that lets you define the dictionary key to use for each dictionary field in the query.

For example, the following query retrieves the value associated with the Vip key for the price_list field:

GET https://myOrgId.org.coveo.com/rest/search/v2?q=alternator&dictionaryFieldContext={ "price_list": "Vip" }

This query returns the VIP price for each item that has a Vip key in its price_list field.

How dictionary key selection works

The value returned for a dictionary field depends entirely on the dictionary key specified at query time (either in the token or the query).

Dictionary key selection is resolved as follows:

  • If a key is specified for a dictionary field, and that key exists in the field, the value associated with that key is returned.

  • If a key is specified but doesn’t exist in a returned item’s field, the field isn’t returned for that item.

  • If no key is specified for a dictionary field, the field isn’t returned in the results.

Notes

  • Dictionary fields don’t support selecting multiple keys at once.

  • Facets, ranking rules, and filters can all reference the resolved dictionary value as if it were a regular field.

Key selection examples

Suppose the following dictionary values are indexed for the price_list field:

"price_list": {
   "Default": 4000.00,
   "Vip": 3750.00,
   "Premium": 3900.00
}

Here’s how different query inputs affect the value returned:

Use case Returned value Explanation

Valid key selected

{
  "dictionaryFieldContext": { "price_list": "Vip" }
}

"price_list": 3750.00

Returns the value associated with the selected key.

Unknown key selected

{
  "dictionaryFieldContext": { "price_list": "Enterprise" }
}

price_list field isn’t returned.

No value exists for the selected key. The field isn’t returned in results.

dictionaryFieldContext parameter not specified in the query or token

price_list field isn’t returned.

No key is specified, so no value is returned.