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 theProduct
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 theProduct.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
andinventories.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
orKEY_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 forFulfillmentInfo
andtitle
. 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
valueIN_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 theProduct
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:
CatalogAttribute.indexableOption
: Sets the indexable option for an attribute.CatalogAttribute.dynamicFacetableOption
: Sets the dynamic faceting option for an attribute.CatalogAttribute.searchableOption
: Sets the searchable option for an attribute.CatalogAttribute.recommendationsFilteringOption
(Public Preview): Sets the recommendations filtering option for an attribute.
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 specifiedCatalogAttribute
in theAttributesConfig
by updating the catalog attribute with the sameCatalogAttribute.key
.See the API reference documentation for
ReplaceCatalogAttribute
.RemoveCatalogAttribute
: Removes an individual attribute configuration fromAttributesConfig
.Only
CatalogAttributes
that are not in use by products can be deleted. If aCatalogAttribute
is in use,RemoveCatalogAttribute
does not delete it, but resets its configuration properties to default values.CatalogAttribute.inUse
is set toTrue
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:
Product.attributes.indexable
.Product.attributes.searchable
. Only available for custom attributes.