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:
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.
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.
Your events are captured at the group level. If so, use the following settings during import:
ingestionProductType
set toprimary
(default)merchantCenterProductIdField
set toitemGroupId
.
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 theitem_group_id
as its product ID. Products that don't have anitem_group_id
can't be imported in this case. Recorded events must refer to the primary (group-level) product ID.Your events are captured at the SKU level. If so, use the following settings during import:
ingestionProductType
set tovariant
.merchantCenterProductIdField
set toofferId
(default).
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.
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.
If your events and products are SKU-level, you can get group-level predictions. Set
ingestionProductType
tovariant
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.