Commerce fields and mapping

This is for:

In this article

Configure commerce fields
Important default Coveo fields
Map metadata keys to Coveo fields
Implementation flow

When you create a source, the Coveo Platform automatically generates a set of fields in your Coveo organization (if they don’t already exist).

The type of source you create determines which fields are generated in your organization. For example, if you create a Catalog source, the Coveo Platform generates a set of default fields that are common to all sources, such as language, permanentid, and uri. It also generates a set of commerce-specific standard fields. If you use a different source, you’ll need to configure these commerce-specific fields yourself.

To generate facets and power essential features, such as Coveo Machine Learning (Coveo ML) models, the Coveo Platform needs your catalog object information to be held in Coveo fields. You make this information available to the Coveo Platform by mapping it to specific fields. You also have to map certain product metadata to important default Coveo fields.

Configure commerce fields

In your catalog data, catalog object information is represented as metadata keys and values, as shown in the following image:

Image of a canoe with associated metadata | Coveo for Commerce

Before you can index your catalog data, make sure that the following types of commerce-specific fields are in your Coveo organization:

Standard commerce fields: These fields are used in all products. They hold important information, such as the product name, price, and description. These fields standardize your catalog data so that Coveo ML models can learn from expected field data.

Note

If you use a Catalog source, the Coveo Platform automatically generates the standard commerce fields. However, you still have to map your catalog object metadata keys to these fields.
Catalog structure fields: These fields represent the structure of your catalog entity. They’re mainly used to categorize commerce items and define their availability.
Custom fields: These fields are used to hold additional product information that’s not covered by the standard fields. For example, if you’re selling clothing, you might want to create custom fields and map the metadata keys that represent product size and color to these fields.

Important default Coveo fields

Besides the commerce-specific fields, the following default fields are important for your Coveo for Commerce implementation:

permanentid: Your catalog data must contain a metadata key that uniquely identifies each product. It’s crucial that you map your unique product identifier metadata to this field.
language: indexed items in Coveo for Commerce organizations are too short for automatic language detection. Even though commerce sources should only contain items in a single language, you must map your language metadata key to this field.

Map metadata keys to Coveo fields

Mapping is the process of associating metadata keys from your catalog data to populate Coveo fields. To populate your fields correctly, you’ll need to complete two stages of metadata mapping:

Catalog configuration mapping: You define these mappings when you configure your catalog entity. They only apply to standard commerce fields.

If you use a Catalog source to index your catalog data, the standard field mappings defined in the catalog configuration will overwrite any source mappings for the standard commerce fields.

If you use any other source, you’ll still have to define source mappings for the standard commerce fields as well as for any catalog structure or custom fields.

The standard fields mapped in the catalog configuration ensure that:

Coveo has the necessary data to drive its machine learning models.
Coveo Analytics events logged using the Event Protocol are enriched with the proper catalog data.

Source mapping: You define source mappings to associate the metadata keys from your source with Coveo fields. These mappings are necessary to provide visitors with a rich search experience, such as relevant result templates and facets.

If you use a Catalog source to index your catalog data, don’t define source mappings for the standard commerce fields:

Any source mappings for the standard fields will be overwritten by the catalog configuration mappings.
source mappings for these fields can’t be used to drive Coveo Machine Learning (Coveo ML) data models.

You’ll still need to define source mappings for any catalog structure or custom fields.

For detailed information on how to map your metadata keys to Coveo fields, see Map commerce fields.

Implementation flow

The typical implementation flow for mapping metadata keys to Coveo fields is as follows:

Field management flow in Coveo for Commerce | Coveo for Commerce

Create your Catalog source.
Create the commerce fields that you’ll map your metadata to. When using a Catalog source, the Coveo Platform automatically creates the standard commerce fields for you. You’ll need to manually create any structure and custom fields that you require. Fields are also used as attributes to build rules in the Coveo Merchandising Hub (CMH). If you want to use a given field as an attribute in rules, you must enable the Facet or Multi-value facet option for that field.
Define your catalog configuration. You’ll be required to:
1. Choose the metadata keys that uniquely identify your products, variants, and availabilities. It’s important to choose the metadata keys that hold the unique identifiers of items as opposed to the Coveo fields. For example, if your metadata key for the unique identifier of a product is product_code, you must choose the product_code metadata key as the product identifier, not the ec_product_id field.
2. Map your metadata keys to Coveo fields in the catalog. For example, Coveo’s standard field dedicated to a product’s price is ec_price. If your metadata key for the price of a product is price, you must map the price metadata key to the ec_price Coveo standard field.

Map your metadata keys to standard commerce fields in the index. While the standard field mappings defined in the catalog configuration is replicated in the index when using a Catalog source, you’ll still need to map your metadata keys for any custom fields you’ve created.

It’s crucial that you map the metadata key that uniquely identifies your products to the permanentid field.
You must also map the language metadata key in your catalog data to the language field.

Index your commerce items.