About fields

This is for:

Developer System Administrator

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. 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.

    One example of this is when authors create a document from a template and don’t change the template’s preset metadata values.

    Another example is when an indexed item doesn’t have a title associated with it. The @title field is automatically populated with the item’s URL because 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 the Coveo Platform.

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 the Coveo Platform.

  • Search interfaces often contain facets which let users filter their search results by selecting the desired values. Each facet represents a field in your index and is populated with values found in your content metadata. facet placement and presentation can also be dynamically improved thanks to the Coveo ML Dynamic Navigation Experience model and its Facet Generator complement.

  • You can configure your search 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 the Coveo Platform 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 origin of the items.

  • 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 the Coveo Platform to search for engine parts and maintenance manuals. When configuring your search interface, you choose to offer the following sorting options to your users:

    • Sorting results by the 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 interface to implement result folding. This displays some search results as child items of other search results (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.

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, as well as by the Coveo ML Dynamic Navigation Experience model and its Facet Generator complement. For details on facets that support multi-value fields, 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 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 copies to Mary Davis and Lisa Brown. The @to field isn’t a multi-value field in this case, but it could be. However, the @cc field is a multi-value field which contains Mary Davis and Lisa Brown as values.

Notes

  • When creating a field, click the Multi-value facet box to indicate that this field can contain multiple values and ensure that all of these values are considered to be separate facet options. If you don’t select this option, the many field values appear as a single large value (for example, 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) page of the Coveo Administration Console, because they only exist within the operations in which a query consists.

Example

Geolocalized search results and discounted prices are typical examples of operations that require dynamic fields.

Dictionary fields

You can assign different values to a dictionary field, depending on the context that’s sent when a 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 natively supported by the Push API and Stream API. You can use indexing pipeline extensions (IPEs) to leverage dictionary fields with other sources.

  • 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 do not 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.