This is the documentation for Recommendations AI, Retail Search, and the new Retail console.

Configure attributes

Stay organized with collections Save and categorize content based on your preferences.

Retail Search can leverage product attributes for indexing, dynamic faceting, and searchability. This page discusses setting those configurations and how they are treated by Retail Search depending on the method and configuration you use.

Attribute types

Product attributes can have different default settings and allowed options depending on their type.

  • System attributes: Predefined system attributes are existing Product fields that provide more information about the product. These include product attributes like brand, availability, color, and size. For all available system attributes for products, see the Product reference documentation.

  • Custom attributes: Custom attributes are extra attributes that you define using the Product.attributes field. For example, this could include store names, vendors, or style. For examples and limits for custom attributes, see the Product.attributes reference documentation.

  • Inventory-level attributes: System or custom attributes that provide store-level information about the product. You might use inventory-level attributes for products whose properties vary significantly between stores and regions, such as grocery items, or products that have store-specific promotions.

    inventories.price and inventories.originalPrice are numeric system attributes predefined by the Retail API. You can create custom inventory-level attributes, which can be textual or numeric. Inventory-level attributes are indexable by default. Setting searchable and dynamic faceting is not supported for inventory-level attributes.

Available configuration settings

You can enable and disable the following types of attribute configurations:

  • Indexable: Retail Search can filter and facet using this attribute.
  • Dynamic faceting: Retail Search can automatically use this attribute as a dynamic facet based on past user behavior such as facet clicks and views. To enable dynamic faceting for an attribute, Indexable must be set to true for that attribute.
  • Searchable: This attribute is searchable by Retail Search queries, which increases recall for that attribute. This control is applicable only for text attributes.
  • Filterable (Public Preview): This attribute can be used in Recommendations AI filter expressions. This control is applicable only for text attributes.

Indexable

If an attribute is set to indexable, Retail Search can filter and facet using the attribute.

  • System attributes: Indexability is always enabled for predefined system attributes. This setting can't be disabled for system attributes.
  • Custom attributes: Enabled by default. You can disable indexability for any custom attribute. If you plan to make a custom attributes indexable, it must follow the regex pattern [a-zA-Z0-9][a-zA-Z0-9_]*. For example, key0LikeThis or KEY_1_LIKE_THIS.
  • Inventory-level attributes: Always enabled for system inventory-level attributes; this setting can't be changed. Enabled by default for custom inventory-level attributes; this setting can be turned off.
  • Dependencies: N/A

Changes to attribute configuration settings for indexable take effect within 12 hours, or immediately on your next catalog ingestion. You can test if your changes have been applied on the Evaluate page.

Dynamic faceting

When dynamic faceting is enabled for an attribute, Retail Search can use the attribute as a dynamic facet. Dynamic facets can be automatically added to a search based on past user behavior such as facet clicks and views.

  • System attributes: Enabled by default if indexability is set to true. You can disable dynamic faceting for any system attribute.
  • Custom attributes: Enabled by default if indexability is set to true. You can disable dynamic faceting for any custom attribute.
  • Inventory-level attributes: Not supported.
  • Dependencies: To enable dynamic faceting for an attribute, you must first enable indexability for that attribute.

Setting dynamic faceting for an attribute is always global. The dynamic faceting configuration you apply to that attribute is used by products across the catalog that use that attribute.

Dynamic faceting configuration changes take up to two days. You can test if your changes have been applied on the Evaluate page.

For numerical custom attributes, buckets need to be specified in the request. Numerical values are not bucketed automatically.

Searchable

If an attribute is set to searchable, recall for that attribute in Retail Search queries is improved.

Only textual attributes values can have searchability enabled. It is not applicable to numerical attributes.

  • System attributes: Predefined textual system attributes for Product are always searchable. This setting cannot be changed.
  • Custom attributes: Disabled by default. You can enable this configuration for any textual custom attribute.
  • Inventory-level attributes: Not supported.
  • Dependencies: N/A

Products with a searchable attribute are not guaranteed to appear in search results for that attribute.

Recommendations filtering

If an attribute has recommendations filtering turned on, it can be used in Recommendations AI filter expressions to filter products in predictions.

  • System attributes: Off by default. You can turn on this setting for any predefined system textual attributes for Product, except for FulfillmentInfo and title. Not supported for numeric attributes.
  • Custom attributes: Off by default. You can turn on this setting for any custom textual attributes for Product. Not supported for numeric attributes.
  • Inventory-level attributes: Supported only for the availability value IN_STOCK.
  • Dependencies: N/A

Configuration modes

The configuration mode that the Retail API is set to determines how attribute configurations are treated and which attribute configurations you can set.

  • Catalog level configuration mode (default): In this mode, attribute configurations on the catalog level on the catalog level are used as the source of truth.
  • Product level configuration mode (deprecated): In this mode, attribute configurations on the product level are used as the source of truth.

Previously, product level configuration was the default mode. If you are still on product level configuration mode and need to switch to catalog level configuration mode, contact Retail support. Retail Search does not support returning to product level configuration mode after you have switched.

To check the configuration mode, go to the Retail console Controls page. If the Indexable option is available as a column on the Site-wide controls tab, the Retail API is in catalog level configuration mode. If the Indexable column is not available on the Site-wide controls tab, the Retail API is in product level configuration mode.

Configuration methods

You can set attribute configurations in the following ways:

  • The Retail Google Cloud console: Configure attribute configurations on the catalog level using the Google Cloud console. This configures attributes globally across all products. Which of these settings are available in the console depends on the configuration mode the Retail API is set to.

  • The Product API method (deprecated): Set custom attributes on the product level using the Product API method. Setting attributes with this method is not available to new Retail API users and is not recommended.

Configure attributes in the console

You can globally set attribute options across all products from the Retail console Controls page, on the Site-wide controls tab. For more details on how to set this in the console, see Set site-wide attribute controls.

The Retail API must be in catalog level configuration mode to use this feature.

Changes to attribute configuration settings for indexable and searchable take effect within 12 hours, or immediately on your next catalog ingestion. Dynamic faceting configuration changes take up to two days. You can test if your changes have been applied on the Evaluate page.

Configure attributes with AttributesConfig

The AttributesConfig API resource lets you manage attribute configurations on the catalog level.

The following fields set attribute options at the catalog level:

To retrieve all attribute configurations, use the GetAttributesConfig method.

Update multiple attributes

Use the updateAttributesConfig method to update multiple attributes at the catalog level.

The catalog attributes you include in the request are updated in the catalog, or inserted if they do not exist. If there is no value for a catalog attribute field, it is assigned a default value.

The maximum number of catalog attributes allowed in a request is 1000.

Update an individual attribute

The following methods are used to update individual catalog attributes:

  • AddCatalogAttribute: Adds an individual attribute configuration to a catalog attribute.

    See the API reference documentation for AddCatalogAttribute.

  • ReplaceCatalogAttribute: Modifies an individual attribute configuration. This replaces the specified CatalogAttribute in the AttributesConfig by updating the catalog attribute with the same CatalogAttribute.key.

    See the API reference documentation for ReplaceCatalogAttribute.

  • RemoveCatalogAttribute: Removes an individual attribute configuration from AttributesConfig.

    Only CatalogAttributes that are not in use by products can be deleted. If a CatalogAttribute is in use, RemoveCatalogAttribute does not delete it, but resets its configuration properties to default values. CatalogAttribute.inUse is set to True if the attribute is in use by any products.

    See the API reference documentation for RemoveCatalogAttribute.

Configure attributes with the Product method (deprecated)

Setting attributes with this method is not available to new Retail API users and is not recommended.

The following fields set indexable and searchable settings for a specific product via the Product API method: