About Sitecore, Coveo for Sitecore, and Coveo fields

This is for:

Developer System Administrator

A Sitecore item generally inherits from a template. A template defines a set of fields, which can be of any one of these types: Single-Line Text, Multi-Line Text, Number, Date, Droplist, Droplink, etc. Therefore, in a sense, a Sitecore item is an aggregation of fields.

A Coveo item is also composed of several fields, which can be of any one of these types: String, Integer, Floating point, and Date/time. Therefore, a Coveo item is also an aggregation of fields.

The role of Coveo for Sitecore is to index Sitecore items along with their fields in a way that’s coherent with the Coveo index. It:

  1. Converts Sitecore field values to a format compatible with the Coveo index.

  2. Adds a field mapping to the Coveo source, which is used to map Sitecore fields with Coveo fields when indexing.

Coveo fields are most commonly divided into custom and system fields. Coveo already defines several system fields, which for the most part are filled automatically by Coveo: title, author, uri, etc. However, custom fields aren’t handled in the same way. As soon as you rebuild your search indexes, Coveo for Sitecore gets all the fields that you have added to the Included Fields list through the Command Center (at https://<SITECORE_INSTANCE_ROOT>/coveo/command-center/index.html#fields/template/). For each one of these fields, one custom field is created. Coveo for Sitecore names custom fields using a special convention (see Manage Sitecore content in the Coveo Administration Console).

How fields work behind the scenes

  • Sitecore fields are mapped to equivalent Coveo fields in the Coveo Platform. Coveo fields are the mechanism that control how Sitecore fields are indexed.

  • The Coveo Administration Console Sources (platform-ca | platform-eu | platform-au) page shows that one Coveo source is created for each Sitecore instance database that’s indexed.

  • By default, only one Coveo field is created in your Coveo organization when a Sitecore field with a given name and settings appears in many indexes. However, one Sitecore field can be mapped to multiple, index-specific Coveo field names (or Translated Names as they’re called in the Command Center) by configuring the field as isSourceSpecific.

    Command Center showing Coveo field names | Coveo for Sitecore

  • Coveo field names can only contain lowercase letters (a-z), numbers (0-9), and underscores. Coveo for Sitecore translates special characters in Sitecore field names, including underscores.

When a Sitecore field with given name and settings appears in many sources, the Coveo Administration Console indicates the number of sources that contain the related Coveo field in the Used in Sources column (see the Fields (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console).

Whenever you change the field settings in the fieldMap section of the Coveo.SearchProvider.Custom.config file, your field definitions in Coveo and the mapping assigned to your sources update.

Handling duplicate field names between indexes

Sitecore fields in two indexes will have the same name in Sitecore. By default, Coveo will index a single field for both, assuming that they have the same settings. However, if you must separate the fields between indexes, setting the field to isSourceSpecific=true in the fieldMap will add a f at the beginning of each field and a unique hash at the end. This process is called field translation (see About the Coveo Search Provider configuration file - fieldNames).

For example, the field productname will be added only once in Coveo for both the master and web index, and for any additional manually created indexes, with the isSourceSpecific setting set to true, the productname field will become fproductnameXXXXX where the XXXXX will be unique for each Sitecore index.

Important

Using the isSourceSpecific setting will create the same field for each index, which will increase the total amount of indexed fields. Keep in mind that Coveo has a field limit per organization (see Content licensing limits).

Handling duplicate field names in the same index

In Sitecore, nothing prevents you from creating many fields with the same name. If these fields are all of the same type (for example, Single-Line Text), then a single field is created in your search indexes. If an item includes several of these fields and they’re all of type String (for example, Single-Line Text), the item is indexed with a semicolon-separated list of all the values contained in those fields.

However, if you’re indexing two Sitecore fields with the same name but different types (for example, one being of type Single-Line Text, and the other being a Number), then items that include one of these fields might be indexed without the field. When this occurs, you typically see a message such as the following in the Sitecore logs:

WARN  Detected a type change for the field "<SITECORE_FIELD_NAME>", but other mappings have been detected. Its type won't be changed and the field won't be usable for this source "<SOURCE_NAME>".
Tip
Leading practice

In Sitecore, use a field naming convention which prevents collisions with Coveo system fields from occurring.

Preventing name collisions with Coveo system fields

Coveo defines several system fields which, for the most part, are filled automatically by Coveo (for example, title, source, author, uri).

To prevent name collisions between fields created in Sitecore and Coveo system fields, some Coveo system field names are set to isSourceSpecific="true" in Coveo.SearchProvider.config. Consequently, if a Sitecore item includes a field whose name is the same as a Coveo system field, your Coveo Platform master and web source items include your translated Sitecore field and the non-translated Coveo system field.

Note

Field names are case insensitive. If you create a field called Author in Sitecore, this name is considered identical to the Coveo author system field.
Example

You’ve created a parts template in Sitecore which includes a source field. With the source field set to isSourceSpecific="true" in Coveo.SearchProvider.config, an indexed item in your Coveo Platform web source shows both the Coveo source system field (containing the Coveo index name) and your Sitecore field, translated as fsource25249, with the value you set on your Sitecore item.

Screenshot showing system fields and permissions in Sitecore and Coveo

Despite Coveo for Sitecore efforts to allow you to create fields in Sitecore with names identical to Coveo system fields, you might notice instances where your Sitecore field value gets overwritten by the one in the corresponding Coveo system field. This can occur with the following fields:

  • body

  • clickableUri

  • date

  • documentId

  • fileName

  • fileType

  • id

  • indexedDate

  • modifiedDate

  • orderingId

  • originalSize

  • parentId

  • printableUri

  • retrievedDate

  • size

  • title

Tip
Leading practice

In Sitecore, use a field naming convention which prevents collisions with Coveo system fields from occurring.

Updating Coveo fields after Sitecore template modifications

A Coveo field represents how a Sitecore field is indexed in a Coveo source. Sitecore fields are defined in templates that may change over time (for example, fields added, removed, or modified). A Coveo field is updated to reflect the Sitecore template modification as soon as you re-index any Sitecore item of the database containing the modified Sitecore template.

Tip

To ensure all affected items are updated, it’s best to rebuild your search indexes.

Updating a Coveo field after a Sitecore field attribute modification

Coveo fields include settings that let you take advantage of features based on field values, such as faceting, free-text searching, and result sorting. Coveo for Sitecore lets you set Sitecore field attributes in your Sitecore instance configuration. You can then propagate those settings to the corresponding Coveo fields with an indexing action or an API synchronization call.

In some cases, an indexing action or API synchronization call may not change the Coveo field settings as expected. Coveo for Sitecore has a field setting conflict handling mechanism that may prevent the changes from being applied. See Reset a field setting for more details and how to work around this.

Controlling which fields to index

Coveo indexes have a technical limit of fields (see Content licensing limits). Control the fields to be indexed (see Specify which fields to index).