Commerce fields and mapping
Commerce fields and mapping
In Coveo for Commerce, a field is a data container that holds information about a catalog object. When defining your payload to index your catalog data, this information is represented as metadata keys and values, as shown in the following image:
To work with Coveo, this information must be made available to Coveo fields. This allows Coveo to generate facets and power essential features, such as Coveo Machine Learning (Coveo ML) models.
The following types of fields must be configured:
-
Standard commerce fields: These fields are used in all products and hold important information, such as the product name, price, and description. These fields provide a layer of standardization to catalog data to ensure ML models can learn from expected field data.
-
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 information about a product that’s not covered by standard fields. For example, if you’re selling clothing, you might want to create custom fields which contain the metadata keys representing the size and color of a product.
For detailed instructions on managing Coveo for Commerce fields, see Commerce fields.
About product unique identifiers
Your catalog data must contain a metadata key that uniquely identifies each product.
It’s crucial that this metadata is mapped to the permanentId
field in Coveo.
When using a Catalog source to index your catalog data, Coveo automatically creates a standard field called ec_product_id
to hold the unique identifier of a product.
If you use ec_product_id
as the metadata key that uniquely identifies your products, the mapping to the permanentId
field is done automatically.
If you use a different metadata key to uniquely identify your products, or if you’re not using a Catalog source, you must manually map the metadata key to the permanentId
field.
Additionally, you must create a custom field in Coveo that matches the name of your chosen metadata key exactly.
For example, if the metadata key that uniquely identifies a product is product_code
, you must create a field named product_code
in Coveo and map it to the permanentId
field.
Mapping metadata keys to Coveo fields
Mapping is the process of associating metadata keys from your catalog data to populate Coveo fields. To ensure your fields are populated correctly, you’ll need to complete two stages of metadata mapping:
-
Catalog configuration mapping: This step occurs when defining the configuration of your catalog entity and applies to standard commerce fields only. It ensures that Coveo has the necessary data to drive its ML models.
When you use a Catalog source to index your catalog data, the standard field mappings defined in the catalog configuration are automatically replicated at the source level.
-
Source mapping: This step maps your metadata keys from your source to Coveo fields. This mapping is necessary to provide visitors with a rich search experience, such as relevant result templates and facets.
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:
-
Create the commerce fields that will map to your metadata. When using a Catalog source, the standard commerce fields are automatically created for you, but you’ll need to create the required structure fields and any custom fields.
-
Define your catalog configuration. You’ll be required to:
-
Choose the metadata keys that uniquely identifies 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 theproduct_code
metadata key as the product identifier, not theec_product_id
field. -
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 isprice
, you must map theprice
metadata key to theec_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.
ImportantIt’s crucial to map the metadata keys that hold the unique identifiers of your products to the
permanentId
field.When using a Catalog source to index your catalog data, Coveo automatically creates a standard field called
ec_product_id
to hold the unique identifier of a product. If you useec_product_id
as the metadata key that uniquely identifies your products, the mapping to thepermanentId
field is done automatically.If you use a different metadata key to uniquely identify your products, or if you’re not using a Catalog source, you must manually map the metadata key to the
permanentId
field. For example, if your metadata key for the unique identifier of a product isproduct_code
, you must map theproduct_code
metadata key to theec_product_id
standard commerce field, as well as to thepermanentId
field.