About product attributes

Vertex AI Search for retail can leverage product attributes for indexing, dynamic faceting, searchability, filtering, and model quality. This page discusses setting product attribute configurations and how they are treated 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 for products that have store-specific promotions.

    inventories.price and inventories.originalPrice are numeric system attributes predefined by Vertex AI Search for retail. 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

Attribute configuration settings impact search and recommendations behavior across your site.

Search uses the following attribute settings:

  • Indexable: Search can filter and facet using this attribute.
  • Dynamic faceting: 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 search queries, which increases recall for that attribute. This control is applicable only for text attributes.
  • Retrievable: If set to true, search returns this attribute in responses to search queries. If all attributes have Retrievable set to false, the search results contain only the product name or (for variants) the product name and color information. The REST field RetrievableFields is deprecated for products. Use the retrievable site-wide control instead.

Recommendations uses the following attribute settings:

  • Filterable (Public Preview): This attribute can be used in recommendations filter expressions. This control is applicable only for text attributes.

Indexable

If an attribute is set to indexable, 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

Your index configuration changes go into effect immediately after you import catalog data. Otherwise it can take up to 12 hours or more for your changes to take effect. You can test if your changes have been applied on the Evaluate page.

Dynamic faceting

When dynamic faceting is enabled for an attribute, 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 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 have their searchability settings configured by Vertex AI Search for retail. These 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

Although products with a searchable attribute are more likely to appear in search results for that attribute, they are not guaranteed to appear.

Recommendations filtering

If an attribute has recommendations filtering turned on, it can be used in recommendations 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 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 Support. Search does not support returning to product-level configuration mode after you have switched.

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

Configuration methods

You can set attribute configurations in the following ways:

  • The Search for Retail console: Set attribute configurations on the catalog level using the Search for Retail console. This configures attributes globally across all products. Which of these settings are available in the console depends on the configuration mode.

  • The AttributeConfig API method: Set attribute configurations on the catalog level using the API. This configures attributes across all products.

  • 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 users and is not recommended.

Configure attributes in the console

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

To use this feature the configuration mode must be catalog level.

Changes to attribute configuration settings for indexable and searchable take effect immediately upon catalog ingestion. Otherwise, it can take up to 12 hours or more for changes to take effect. 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 users and is not recommended.

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