This Recommendations AI documentation references the Recommendations console. We recommend switching to the Retail console and using the Retail documentation, which documents Recommendations AI, the Retail console, and Retail Search.

If you are using the v1beta version of Recommendations AI, migrate to the Retail API version.

Catalogs and catalog information

This page provides best practices for creating your catalog information and populating your catalog data.

Overview

The catalog data you import into Recommendations AI has a direct effect on the quality of the resulting model, and therefore on the quality of the predictions Recommendations AI provides. In general, the more accurate and specific catalog information you can provide, the higher quality your model.

Your catalog should be kept up to date. You can upload catalog changes as often as needed; ideally, every day for catalogs with a high rate of change. You can upload (patch) existing product items; only the changed fields will be updated. There is no charge for uploading catalog information. For more information, see Keeping your catalog up to date.

Products

The catalog is a collection of product objects.

Required product information

The following fields are required; you must provide values for them when you create product items in your catalog. They should also correspond with the values used in your internal product database, and should accurately reflect the product represented, because they are included in training your models.

In some cases, other fields are also required. Refer to the complete list of all product fields on the Product reference page.

All product information you provide can be used to improve the quality of recommendations. Be sure to provide as many fields as possible.

Field Notes
name The full, unique resource name of the product. Required for all `Product` methods except for import. During import, the name is automatically generated and does not need to be manually provided.
id The product ID used by your product database. The ID field must be unique across your entire catalog. The same value is used when you record a user event, and is also returned by the predict method.
title Product title from your product database. A UTF-8 encoded string. Limited to 1250 characters.

Using product levels

When you import your catalog for the first time, you must specify whether you are providing only primary items, or primary items as well as their variants.

  • Primary items are what the Retail API returns in prediction results. These can be individual (SKU-level) items, or groups of similar items (SKU groups). By default, the Retail API is configured for importing only primary items.
  • Variant items are versions of a primary product. Variants can only be individual (SKU-level) items. For example, if the primary product is "V-neck shirt", variants could be "Brown v-neck shirt, size XL" and "White v-neck shirt, size S". Primaries and variants are sometimes described as "parent" and "child" items. Importing variants is optional.

During catalog import, set your product levels by using the Catalog.patch method. For example:

curl -X PATCH 

-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" 

-H "Content-Type: application/json; charset=utf-8" 

--data '{
    "productLevelConfig": {
      "ingestionProductType": "PRODUCT-TYPE",
      "merchantCenterProductIdField": "PRODUCT-ID-FIELD"
    }
 }' 

"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

To determine the best product level choices for your implementation, you will need to review your catalog data and your website logic. What item IDs are available to you when you capture user event data? What item IDs would be most effective to be returned with predictions? How do those IDs compare and relate to each other?

Use the appropriate steps, depending on whether you are importing from Merchant Center or not:

Determining your product levels for importing from Merchant Center

When you import catalog data from Merchant Center, the Retail API uses ingestionProductType to help identify whether to upload them as primaries or variants, and the merchantCenterProductIdField field to specify whether to use the Merchant Center offer_id or item_group_id as the product ID.

Review your catalog data and your website logic to answer the following questions:

  • Do I have both primaries and variants in my catalog?
  • If so, what level of item will I have available when I capture user event data?
  • What type of items do I need returned with my predictions?

Determine if:

  1. Your catalog has only one level of items. This can mean that either:

    • All of your products and events are at the SKU level, and you want SKU-level predictions.
    • All of your products and events are at the group level, and you want group-level predictions.

    If so, import with only primary items. This is the default import setting.

  2. You want group-level (primary) predictions, but your Merchant Center products are SKU-level. In this case, your import decision depends on how your events are captured.

    1. Your events are captured at the group level. If so, use the following settings during import:

      Where multiple Merchant Center products have the same Merchant Center item_group_id, Recommendations AI imports only one of them as a primary product and uses the item_group_id as its product ID. Products that don't have an item_group_id can't be imported in this case. Recorded events must refer to the primary (group-level) product ID.

    2. Your events are captured at the SKU level. If so, use the following settings during import:

      Recommendations AI imports your products as variants and uses the Merchant Center offer_id as its product ID. Recorded events must refer to the variant (SKU-level) product ID.

Determining your product levels for importing without Merchant Center

Either all of your products must have a value for primaryProductId or none of them can. You cannot import catalog data with primaryProductId set for some items but not for others.

  1. If your catalog has only one level of items, this can mean that either:

    • All of your products and events are at the SKU level, and you want SKU-level predictions.
    • All of your products and events are at the group level, and you want group-level predictions.

    If so, import with only primary items. This is the default, recommended import setting.

  2. If your events and products are SKU-level, you can get group-level predictions. Set ingestionProductType to variant during import.

SKU-level prediction is not supported if you have only group-level events and products.

If you plan to import catalog data from Merchant Center in the future, review your data as described for Merchant Center imports to ensure you are making the correct choice. Changing this configuration can be done only by deleting the catalog and uploading it again (see Changing product-level configuration).

Recommendations AI schema

When importing a catalog from BigQuery, use the Recommendations AI schema below to create a BigQuery table with the correct format and load it with your catalog data. Then, import the catalog.