This page introduces some of the facet features and how to use them.
Definitions related to facets
This section provides some basic definitions and explanations for some terms related to facets:
Facets: The facet specifications to perform faceted search. They help users find what they want by filtering the results. For example, if a user searches for
shoes
, some facets that could be returned are:price
,attributes.department
,attributes.colors
, andattributes.size
.System attributes: Predefined system attributes are existing product fields that provide more information about the product. These include a few predefined product attributes like
brand
,availability
,color
, andsize
.Custom attributes: Custom attributes are extra attributes that you define using the Product.attributes field. For example, this could include
style
,color
ordepartment
.Facet key: This is the name of a facet. For example, it could be
attributes.department
orsizes
. The facet keys correspond to the attribute names. For example, the (product) system attribute namesizes
corresponds to the facet keysizes
. Similarly, the (product) custom attribute namedepartment
corresponds to the facet keyattributes.department
(for custom attributes, the prefixattributes.
is added to the custom attribute name to obtain the facet key). The terms attribute name, facet key, and facet name are interchangeable.Facet value: For textual keys, this is one of the textual values of a facet. By example, the textual facet key
brands
could have such textual values asAsics
andNike
. For numerical keys, a facet value is an interval. By example, the numerical facet key price could have an interval of the form [20, 30).Type of an attribute or facet: They can be either textual or numerical.
Pinned facets: This is a facet that you pass in the request using the FacetSpec with the option enableDynamicPosition
=false
. The facets should appear in their original order before all the dynamic facets in the response.Dynamic facets: These are facets that search ranks on its side. They are either passed in the request with the option
enableDynamicPosition
=true
or fetched according to the search models. They are then ranked by the same trained models with the most relevant ones at the top.Facetable or dynamic faceting: When an attribute is enabled for 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, you must also enable indexing for that attribute.
Filter: The filter syntax consists of an expression language for constructing a predicate from one or more fields of the products being filtered. For example, if a user engages the facet values
Asics
of the facet keyattributes.brands
, then part of the filter could be(attributes.brands:ANY(\"Asics",\"Nike\"))
. Filter expression is case-sensitive. See more details about the filter in this user guide.
About dynamic facets
When dynamic faceting is enabled for a
serving config, search
can automatically use attributes as dynamic facets in search results for this
configuration, based on past user behavior such as facet clicks and views.
Dynamic facets won't be effective for serving config without dynamic faceting
enabled. Dynamic facets are either passed in the request with the option
enableDynamicPosition
=true
or fetched according to the search models. They are then ranked
by the same models with the most relevant ones at the top.
By default, most facet keys are facetable. Dynamic faceting settings in the API
can be overwritten for some specific facet keys of your choice by site-wide
attribute controls in the Search for Retail console. In other words, if
you want some facet keys to be non-facetable, you need to disable dynamic
faceting for each of these keys in the Attribute
controls
tab. For more information, see Managing site-wide attribute
controls. Note that dynamic facets can be created
based just on accurate product catalog data. However, for the feature to work
optimally for your site, the facet models need to learn from activity on your
site. For this, you need to set query, category, and filter fields in your
search event uploads accurately.
If none of your serving configs has dynamic facets enabled and you just enabled dynamic facets in a serving config, you expect to wait 3-4 days before dynamic facets work.
Facet controls
This section provides instructions for creating different types of facet controls:
- Ignore facet values controls
- Replace facet values controls
- Merge facets controls
- Set numerical intervals controls
- Remove facets controls
- Force return facets controls
- Rerank dynamic facets controls
Vertex AI Search for retail performs case-sensitive matching for all these facet controls unless stated otherwise.
Create an ignore facet values control
Create an ignore facet values control when you want to remove some unwanted facet values for some specific facet keys.
This control is useful to erase unwanted facet values like NA
and
Not_applicable
. But, it can also be used to erase seasonal trends like
Easter
if you are in October.
To create a control that ignores facet values:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Ignore facet values.
Specify the attribute name.
For example,
brands
for a system attribute. For a custom attribute, the name starts withattributes.
—for example,attributes.department
andattributes.colors
.Optional: Specify Start Time and/or End Time.
Specify one or more attribute values as Ignore values.
For example,
NA
,Not_applicable
andEaster
.Click Submit.
Create a replace facet values control
Create a replace facet values control when you want to consolidate a number of similar facet values into one single term.
Replacing facet values is sometimes referred to as merging facet values.
To avoid conflicts and useless mappings, if an attribute value facet_value_1
is replaced by another attribute value facet_value_2
, then the latter can't be
replaced by another attribute value. For example, if you replace ruby
with
dark red
, you can't subsequently replace dark red
with red
.
For each attribute name, an attribute value shouldn't appear more than once in the Replace values field.
To create a control that replaces facet values:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Replace facet values.
Specify the attribute name.
This feature works only for custom attributes, which start with the prefix with
attributes.
—for example,attributes.department
andattributes.colors
.Specify one or more attribute values as Replace values.
For example,
RED
,Red
,dark red
,bright red
,ruby
, andcrimson
.An attribute value can only appear once in the Replace values field.
Specify a single attribute value as Replacement term, for example,
red
.Click Submit.
Although the replaced values might disappear quickly, the replacement terms can take up to 4 days to appear.
When the replace facet values control takes effect, if the facet key (in this
example attributes.colors
) is returned in the response, the replaced facet
values (such as dark red
and crimson
) won't be present as facet values. They
are replaced by their replacement terms (for example, red
).
Create a merge facets control
It is better to set correctly the product custom attribute names and values on
your side before the products are ingested into search's
database. However, if you can't change custom attribute names, you can create
merge facets controls. You create a merge facets control if you want to
merge (replace) a facet with another facet. For example, you might have
several custom facet keys for colors like attributes.colors_jeans
,
attributes.colors_clothes
and attributes.colors_hue
and you want to replace
them with an existing custom facet key called attributes.colors
.
To create a control that merged a facet into another:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Merge facets.
Specify a valid custom facet key that merges into another one.
This feature works only for custom attributes, which start with the prefix with
attributes.
—for example,attributes.colors_clothes
andattributes.colors_jeans
.Specify a valid custom facet key as the merged key.
Click Submit.
This control typically takes effect in 2-4 days.
Create a set numerical intervals control
The set numerical intervals control lets you determine the intervals for a numeric facet instead of having to accept calculated intervals.
For example, search might calculate the intervals [10,15),
[15,20) [20,25), [25,30), [30,40) and [40,50) and [50,infinity) for the custom
numerical facet key attributes.monitor_size
. But, you might prefer the
intervals [0,14), [14,17), [17,21), [21,24), [24,27), [27,32) and [32,infinity)
instead.
About calculated intervals and set intervals
For all numerical custom attributes and the numerical system attributes price
,
rating
and ratingCount
, search calculates some intervals
with round bounds based on the distribution of all the (numerical) attribute
values for each of these attributes. You can also specify some intervals in the
request. As a last option, you can set your own intervals for each numerical
facet key using the following
set numerical intervals controls.
Here is the priority order that determines which intervals are used:
First, if some intervals are specified in the request for a numerical facet key, these intervals are kept.
Otherwise, if a numerical facet key is dynamic or passed in the request without intervals, then the intervals that you include using the set numerical intervals controls are added to that numerical facet key if these intervals are non-empty.
Otherwise, the previously mentioned calculated intervals with round bounds are be added.
Create the control
If you want to specify your own intervals for numeric facet keys instead of using the ones that Vertex AI Search for retail calculates for you, then create a set numerical intervals controls.
To create a control for adding intervals:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Set numerical intervals.
Specify the name of a numerical attribute.
For example,
price
for a system attribute. For a custom attribute, the name starts withattributes.
—for example,attributes.number_of_pieces
.Specify at least one of Minimum or Maximum. If both are specified, the minimum can't be greater than the maximum. You can choose each bound to be Inclusive or Exclusive.
To add more intervals, click + Add intervals. The maximum number of intervals is 40.
Click Submit.
Create a remove facets control
The remove facets control lets you to remove a specific facet key from the dynamic facets. Facet keys are removed based on some given query terms or page categories.
This control is useful if you want to remove some facet keys for some query
terms or browse. For example, you can use this control to remove the facet key
attributes.shoe_size
for the query 'shoes'.
To create a control for remove facet:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Remove facets.
Each control is for search or browse, but it can't apply to both. Do one of the following:
For search queries, click Search and specify some partial query terms or some exact query terms to match. See detailed information in query terms and conditions. The query terms need to be lowercase for both cases. For example, you can specify the partial query terms
shirts
,polo
,jackets
,t-shirt
andfall coats
and the facet keys specified next won't appear as a dynamic facet if the lowercase query is one of these query terms or contains any of these query terms as a unigram.For browse, click Browse categories and specify some page categories. You can specify a list (up to 10 entries) of categories or departments. The format should be the same as the user event page categories. For example, it could be
page_categories
:Sales > 2023 Black Friday Deals
. If there is an exact match (case sensitive) between the latter and one of the page categories passed in the event (for browse), then the facet keys specified next won't appear as a dynamic facet.
Specify at least one valid facet key in Attributes to ignore.
Click Submit.
Create a force return facets control
The force return facets control can affect the list position of a dynamic facet key for a specific query or browse event.
This control is useful if you want to force a specific facet key among the
dynamic facets for some query terms or browse. For example, you can use this
control to force the facet key brands
to appear to position 10 or a smaller
position for the query handbags
. If the facet brands
is already in the top
10 for the dynamic facets for this query, then it shouldn't move much. If it is
not in the top 10 or not in the list of dynamic facets, then it should move to
position 10 approximately.
To create a control for force return facet:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Force return facets.
Each control is for search or browse, but it can't apply to both. Do one of the following:
For search queries, click Search and specify some partial query terms or some exact query terms to match. See detailed information in query terms and conditions. The query terms need to be lowercase for both cases. For example, you can specify the partial query terms
shirts
,polo
,jackets
,t-shirt
andfall coats
and the facet keys specified next should appear around their respective position or above among the dynamic facets if the lowercase query is one of these query terms or contains any of these query terms as a unigram.For browse, click Browse categories and specify some page categories. You can specify a list (up to 10 entries) of categories or departments. The format should be the same as the user event page categories. For example, it could be
page_categories
:Sales > 2023 Black Friday Deals
. If there is an exact match (case sensitive) between the latter and one of the page categories passed in the event (for browse), then the facet keys specified next should appear around their respective position or above among the dynamic facets.
Specify a valid facet key and an integer position between 1 and 100 (inclusive).
If you want to specify more than one facet key, click +Add Adjustment and redo the previous step.
Click Submit.
Create a rerank dynamic facets control
The dynamic facet ranking depends on the query (search) or page categories (browse). The rerank dynamic facets control also allows the ranking to depend on some facet values engaged by the user.
For example, using this control, if the
user engages the facet value watches
of the facet key attributes.department
following a search or browse, then the ranking will also depend on the facet
value watches
. You can specify the facet values that you want to rerank on by
facet key, or specify only the facet key and rerank on all its facet values.
To create a control for rerank dynamic facets:
Go to the Controls page in the Search for Retail console.
On the Facet controls tab, click add_boxCreate control.
The Create control pane opens.
Select Rerank dynamic facets.
Specify a valid custom textual facet key (all custom keys have the prefix
attributes.
).You can either specify some specific facet values or apply to all.
If you want to rerank on all its facet values, click add_boxAny value changes.
If you want to rerank on specific facet values, click add_boxSelected values changes. Then insert all the facet values that you would like to rerank on (case sensitive). For example, it could be
watches
,luggages
,bed
.
Click Submit.
You need to pass all the facet keys engaged by the user in the request
for the following reason. Suppose that a user browses for sales. The user gets a
first list of facet keys presented. Then, the user engages first the facet key
attributes.age_group
. Next, they engage the facet key attributes.department
with the facet values watches
, for which you set up a control to rerank on. At
that point, search reranks the keys. So, it is possible that the
previously engaged facet key attributes.age_group
won't be returned in the
response. If you pass this key in the request (using a
Facetspec with
enableDynamicPosition
set to true
),
it will automatically be returned in the response. However,
search could return that key at position 27 and you might show
only the first 20 keys to the user. Because of this, on your side, you need to
make sure that these keys previously engaged by the user will be
shown to the user (you might have to filter out some intermediate non-engaged
keys in the response if you don't want to show too many keys to the user).