Leveraging Variant and Availability Fields to Filter on Products

The way you define your catalog data will determine which fields, of the catalog object types you create, can be associated to a filter when using facets.

When the structure of your queried catalog is simple (i.e., contains only products), then understanding which fields are available for facets is equally simple. You can create facets on all facet-enabled fields populated by items identified as products in the catalog.

However, if the structure of the queried catalog is more complex (i.e., contains products, variants, and/or availability channels), facets can affect multiple object types (see Facet Association).

Ensure that a given field on which you want to create a facet is only defined for one type of object in the catalog. This can be verified in the content browser. For example, to test the color field, in the content browser search bar, enter @color and ensure that there’s only one value in the Object Type facet (e.g., Variant)

Facet Association

The Facet Association tab gives users the ability to quickly view which facetable field names exist between object types. This enables them to view which object type a field comes from when we display the facets.

In advanced use cases, your data structure may require having the same facetable fields on multiple object types. For example, you may want to use the same language field across all your items. In this case, the value @language would need to appear on all object types (Product, Variant and Availability) to return matching results.

The catalog automatically detects the fields that you can use to generate facets and checks for updates every 15 minutes.

To determine when the next refresh will occur, view the last update time at the bottom of the Field Association tab in your catalog.

Retrieve the Available Variant and Availability Fields

Use the GET endpoint to retrieve the variant.fields and availability.fields. The variant and availability fields you’ll see in the response are fields you can create facets on, which are automatically selected by the catalog.

You’ll get a response like this one:

{
  "availability": {
    "availableSkusField": "availableskus",
    "fields": [
      "availabilityid",
    ],
    "idField": "productid",
    "objectType": "Availability"
  },
 
// ...
 
  },
  "variant": {
    "fields": [
      "productsize",
      "width"
    ],
    "idField": "sku",
    "objectType": "Variant"
  }
}

Query Your Commerce Catalog Content

In most cases, you will want queries originating from a given commerce search interface to target a specific catalog in your Coveo organization.

Prerequisites

Before proceeding on to step 1, you must have:

  1. Indexed commerce catalog content

  2. Created a Coveo commerce catalog

Step 1: Retrieve the Catalog Name

To be able to query a given catalog, you must know its unique name.

Access the Catalogs page, and then locate and copy the desired catalog name from the table.

Step 2: Configure Your Search Interface

Use one of the following methods to ensure that your commerce search interface targets the desired catalog.

The easiest way to query a catalog is to configure a query pipeline rule that transparently adds the catalog identifier to each query.

  1. Access the Query Pipelines page.

  2. Double click the query pipeline used by your search interface.

  3. Select the Query Parameters tab.

  4. In the upper-right corner, click Add a Query Parameters Rule.

  5. In the Add a Query Parameter Rule panel:

    1. In the Parameter name box, enter commerce.catalogId.

    2. In the Parameter value box, enter the catalog name retrieved in step 1.

    3. Click Add Rule.

Queries originating from your commerce search interface will now target the specified catalog.

Method 2: Use a buildingQuery Event Handler

In a JavaScript Search Framework interface, if you would rather modify queries before sending them to the Search API, you can code a buildingQuery event handler that sets the commerce property of the QueryBuilder object as desired (see JavaScript Search Framework Events).

document.addEventListener("DOMContentLoaded", () => {
 
  // ...
 
  const root = document.getElementById("search");
  Coveo.$$(root).on("buildingQuery", (e, args) => {
    args.queryBuilder.commerce = { catalogId: "<MY_CATALOG_NAME>" };
  });
 
  // ...
 
  Coveo.init(root);
});

Where you would replace <MY_CATALOG_NAME> with the name of your catalog.

Product Filters for a Specific Channel

When filtering on products, users may want to locate a specific store that carries a certain product. Using the method of your choice, your site will need to determine which stores are the closest to the user. You must then retrieve the identifier associated to this store that matches the value from your catalog availability identifier field.

You can leverage this store identifier (i.e: store-123), in your search interface to filter on products that are only available in this store. Ensure you have properly configured your availability channels. The identifier must match the value set in the catalog’s availability identifier field.

You’ve configured your catalog with the field availabilityid as the availability.idField in the following fashion:

{
   "name": "Multiple Channel Catalog",
   "product": ...,
   "variant": ...,
   "availability": {
       "idField": "availabilityid",
       "availableSkus": "availableskus"
   }
}

You then pushed availability items where the availabilityid field contains a unique identifier (i.e. store-123):

 {
    "availabilityid": "store-123",
    "lat": 45.4975,
    "long": 73.5687,
    "availableskus": ["001-red-8_wide","001-red-9_wide","001-red-10_wide","001-red-11_wide", "001-blue-8_wide"],
    "objecttype": "Availability"
 }

With both your items and catalog on the same availabilityid, you can therefore add the @availabilityid==store-123 query to filter on all products that are available in this store.

Availability Constraints

If you have any availability constraints defined in your availability channel and in your data format from the source, it means you may want to filter on that specific channel. For instance, in a business-to-business scenario (B2B), we commonly see this availability constraint as being a price list, group or entitlement. In a business-to-consumer scenario (B2C), this availability constraint could be a store.

For this filter to work properly, your search interface must use a catalog configured with multiple channels.

The following code will add a filter in the query to only retrieve products that are available in your channel:


 <script>
   document.addEventListener('DOMContentLoaded', function () {
     var root = document.body;
     Coveo.$$(root).on('buildingQuery', function(e, args) {
       args.queryBuilder.advancedExpression.addFieldExpression('@availabilityid', '=', [<AVAILABILITY_ID>]);
     });
   });
 </script>

Recommended Articles