Commerce fields and mapping

This is for:

System Administrator Developer

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 and catalog structure fields. If you use a different source, you have 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.

  • Catalog structure fields: These fields represent the structure of your catalog entity. They’re mainly used to categorize commerce items and define their availability.

    Note

    If you use a Catalog source, the Coveo Platform automatically generates the standard commerce fields and catalog structure fields. However, you still have to map your catalog object metadata keys to these fields.

  • 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:

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.

    Tip

    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:

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

    Important

    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

  1. Create your Catalog source.

  2. 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 and catalog structure fields for you. You’ll need to manually create any 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.

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

      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

  5. Index your commerce items.