About Fields

Index Content Coveo Relevance Cloud Developer System Administrator Product Documentation

A field is an index-wide data container that holds specific information about each individual item whose corresponding source mappings include rules to populate this field.

Each Coveo organization source automatically comes with a set of standard system fields populated from standard metadata. You can also create fields that are filled with the content or metadata of your choice when adding mappings for sources (see Add or Edit a Field). Fields can be leveraged in a search interface to optimize the global search experience.

Notes

  • In the Coveo documentation, field names are preceded by an @ character.

  • Some fields such as @author and @title may have inaccurate values when, for example, authors create a document from a template and omit to change the template metadata values.

    For example, an indexed item doesn’t have a title associated with it. Therefore, the @title field is automatically populated with the item’s URL since the author didn’t provide a title.

Field Origins

On the Fields (platform-ca | platform-eu | platform-au) page, the Origin column indicates the field provenance (Default or Other).

Default

Default fields are required by the Coveo index and apply to all sources. They’re automatically created on the Fields (platform-ca | platform-eu | platform-au) page and, for the most part, automatically filled by Coveo.

Example

@title, @author, and @uri.

See also About the SYS Field Name Prefix.

Other

Other fields are either custom fields or standard source fields.

Field Types

The possible field types are the following:

  • String

    Example

    The value of the @department field is Sales.

    Note

    The String type is also used for Boolean metadata.

    For example, the value of the @published field is true.

  • Integer 32

    Example

    The value of the @rgbcolor field is 54,117,136.

  • Integer 64

    Example

    The value of the @timesinceepoch field is 1517341713150.

  • Decimal

    Examples

    The value of the @weight field is 5.25. The value of the length field is 3.

  • Date

    Example

    The value of the @date field is 2018-01-30.

  • Vector

    Example

    The value of the @personalizationdata field is [0.235, 0.1234, 0.789, 0.765].

Field Uses

You can leverage fields in several parts of Coveo.

  • Facets in a search result page are based on field values (see Using Facets). Search page users can filter their search results by selecting only the desired values for a facet field.

  • You can configure your search page interface so that search results display certain field values. This provides additional information on the item to your search page users.

    Example

    Your company uses Coveo to search for text documents. When configuring your search result template, you choose to display the @source and @author field values. This makes it easier for your search page users to determine the item origin.

  • You can configure your search interface so that it offers the option to sort search results based on the value of a certain field.

    Example

    Your company uses Coveo to search for engine parts and maintenance manuals. When configuring your search page interface, you choose to offer the following sorting options to your users:

    • Sorting results by date the item was entered in your system (@date field)

    • Sorting results by part weight (@weight field)

    • Sorting results by file size (@size field)

  • You can configure your search page interface to implement result folding, i.e., so that some search results are displayed as child items of another search result (see About Result Folding and Folding Results).

  • When you know the name of a field, you can make advanced field queries to retrieve items for which this field value matches your entry (see Advanced Field Queries).

Multi-Value Fields

A multi-value field is a field to which many string values are associated. Multi-value fields are also supported in facets (see Multi-value facet).

Examples

  • An item contains English text and its Spanish translation. The @language field values for this item are therefore English and Spanish.

  • John Smith creates an item, and then his coworker Barbara Allen edits it. Both are therefore marked as authors of this document. The @author field values for this item are therefore John Smith and Barbara Allen.

  • John Smith sends an email to Barbara Allen, with a copy to Mary Davis and Lisa Brown. The @to field is therefore not a multi-value field in this case, but it could be. The @cc field, however, is and contains Mary Davis and Lisa Brown as values.

Notes

  • When creating a field, click the Multi-value facet box to indicate that this field is susceptible to contain many values and ensure that all values are considered as separate facet options. If you don’t select this option, the many field values appear as a single large value (e.g., value1;value2;value3) and are displayed as such in a facet.

  • Multi-value fields only support string values.

Dynamic Fields

A dynamic field is temporarily created by a query function. It contains a value resulting from the query function calculation. Dynamic fields aren’t listed on the Fields (platform-ca | platform-eu | platform-au) Administration Console page, since they only exist within the operations in which a query consists.

Example

Geolocalized search results and discounted prices are typical examples of operations requiring a dynamic field (see Leverage Geolocalization and Discounted Price).

Dictionary Fields

A dictionary field lets you assign different values to that field depending on the context that’s sent when an end user performs a query. The most common use case is in commerce environments, when you have multiple store locations with varying prices.

Notes

  • Dictionary fields support both string and numerical values.

  • There’s no additional configuration required to create a dictionary field. Passing a dictionary as the value for a given field will automatically turn it into a dictionary field.

  • Currently, dictionary fields are only supported by the Push API and the Stream API.

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 this abstracts multiple values under one field, in the index, it will actually be creating one field per key, meaning that indexing a dictionary with thousands of keys will create thousands of fields. Although there’s no limit, going above a few hundred keys will cause negative performance impacts.

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.