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

Understanding 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 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 need to 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.

SourceSitecoreAndCoveoSystemFields

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.

Understanding when modified Sitecore fields are updated in the Coveo index

A Coveo field defines how a Sitecore field is indexed in a Coveo source. Given that Sitecore fields are defined in templates, and that templates can be modified over time (e.g. a field is added or removed, or its type is changed), you may wonder exactly when a Coveo field is updated to reflect its modifications. This happens as soon as you re-index any Sitecore item of the database containing the modified template. The result is that Coveo now has your newly modified field. If it happens that the item that you re-indexed inherits from the template that you modified, it will be indexed along with your newly modified field. However, as a general rule, it’s best to perform a rebuild of your search indexes. This way, you ensure that all items inheriting from the modified template now have your newly modified field.

Controlling which fields to index

Coveo indexes have a technical limit of fields (see Content licensing limits). Hence, we recommend that you control the fields to be indexed (see Specify which fields to index).

Changing the setting of a Coveo field

When a Sitecore field or computed field is indexed by Coveo, it can be used for field queries or to display its value in an interface. To be able to use the field in more complex controls, such as facets, you must explicitly change the setting of the field (see Change the settings of Sitecore fields).