Commerce fields and mapping

This is for:

System Administrator Developer

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:

Image of a canoe with associated metadata | Coveo for Commerce

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:

    Tip

    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:

Field management flow in Coveo for Commerce | Coveo for Commerce

  1. Create your Catalog source and index your commerce items.

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

  3. Define your catalog configuration. You’ll be required to:

    1. 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 the product_code metadata key as the product identifier, not the ec_product_id field.

      product-code metadata in catalog configuration| Coveo for Commerce

    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.

      metadata mapping in catalog configuration| Coveo for Commerce

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

    Important
    Important

    It’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 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. For example, if your metadata key for the unique identifier of a product is product_code, you must map the product_code metadata key to the ec_product_id standard commerce field, as well as to the permanentId field.