- Resource: Control
- FacetSpec
- FacetKey
- Rule
- BoostAction
- RedirectAction
- OnewaySynonymsAction
- DoNotAssociateAction
- ReplacementAction
- IgnoreAction
- FilterAction
- TwowaySynonymsAction
- ForceReturnFacetAction
- FacetPositionAdjustment
- RemoveFacetAction
- Condition
- QueryTerm
- TimeRange
- SearchSolutionUseCase
- Methods
Resource: Control
Configures dynamic metadata that can be linked to a ServingConfig
and affect search or recommendation results at serving time.
JSON representation |
---|
{ "name": string, "displayName": string, "associatedServingConfigIds": [ string ], "solutionTypes": [ enum ( |
Fields | |
---|---|
name |
Immutable. Fully qualified name |
displayName |
Required. The human readable control display name. Used in Retail UI. This field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error is thrown. |
associatedServingConfigIds[] |
Output only. List of Note the association is managed via the |
solutionTypes[] |
Required. Immutable. The solution types that the control is used for. Currently we support setting only one type of solution at creation time. Only |
searchSolutionUseCase[] |
Specifies the use case for the control. Affects what condition fields can be set. Only settable by search controls. Will default to |
Union field A behavior/type must be specified on creation. Type cannot be changed once specified (e.g. A Rule control will always be a Rule control.). An INVALID_ARGUMENT will be returned if either condition is violated. |
|
facetSpec |
A facet specification to perform faceted search. Note that this field is deprecated and will throw NOT_IMPLEMENTED if used for creating a control. |
rule |
A rule control - a condition-action pair. Enacts a set action when the condition is triggered. For example: Boost "gShoe" when query full matches "Running Shoes". |
FacetSpec
A facet specification to perform faceted search.
JSON representation |
---|
{
"facetKey": {
object ( |
Fields | |
---|---|
facetKey |
Required. The facet key specification. |
limit |
Maximum of facet values that should be returned for this facet. If unspecified, defaults to 50. The maximum allowed value is 300. Values above 300 will be coerced to 300. If this field is negative, an INVALID_ARGUMENT is returned. |
excludedFilterKeys[] |
List of keys to exclude when faceting. By default, Listing a facet key in this field allows its values to appear as facet results, even when they are filtered out of search results. Using this field does not affect what search results are returned. For example, suppose there are 100 products with the color facet "Red" and 200 products with the color facet "Blue". A query containing the filter "colorFamilies:ANY("Red")" and having "colorFamilies" as If "colorFamilies" is listed in "excludedFilterKeys", then the query returns the facet values "Red" with count 100 and "Blue" with count 200, because the "colorFamilies" key is now excluded from the filter. Because this field doesn't affect search results, the search results are still correctly filtered to return only "Red" products. A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error is returned. |
enableDynamicPosition |
Enables dynamic position for this facet. If set to true, the position of this facet among all facets in the response is determined by Google Retail Search. It is ordered together with dynamic facets if dynamic facets is enabled. If set to false, the position of this facet in the response is the same as in the request, and it is ranked before the facets with dynamic position enable and all dynamic facets. For example, you may always want to have rating facet returned in the response, but it's not necessarily to always display the rating facet at the top. In that case, you can set enableDynamicPosition to true so that the position of rating facet in response is determined by Google Retail Search. Another example, assuming you have the following facets in the request:
And also you have a dynamic facets enable, which generates a facet "gender". Then, the final order of the facets in the response can be ("price", "brands", "rating", "gender") or ("price", "brands", "gender", "rating") depends on how Google Retail Search orders "gender" and "rating" facets. However, notice that "price" and "brands" are always ranked at first and second position because their enableDynamicPosition values are false. |
FacetKey
Specifies how a facet is computed.
JSON representation |
---|
{
"key": string,
"intervals": [
{
object ( |
Fields | |
---|---|
key |
Required. Supported textual and numerical facet keys in Allowed facet keys when
|
intervals[] |
Set only if values should be bucketized into intervals. Must be set for facets with numerical values. Must not be set for facet with text values. Maximum number of intervals is 40. For all numerical facet keys that appear in the list of products from the catalog, the percentiles 0, 10, 30, 50, 70, 90, and 100 are computed from their distribution weekly. If the model assigns a high score to a numerical facet key and its intervals are not specified in the search request, these percentiles become the bounds for its intervals and are returned in the response. If the facet key intervals are specified in the request, then the specified intervals are returned instead. |
restrictedValues[] |
Only get facet for the given restricted values. For example, when using "pickupInStore" as key and set restricted values to ["store123", "store456"], only facets for "store123" and "store456" are returned. Only supported on predefined textual fields, custom textual attributes and fulfillments. Maximum is 20. Must be set for the fulfillment facet keys:
|
prefixes[] |
Only get facet values that start with the given string prefix. For example, suppose "categories" has three values "Women > Shoe", "Women > Dress" and "Men > Shoe". If set "prefixes" to "Women", the "categories" facet gives only "Women > Shoe" and "Women > Dress". Only supported on textual fields. Maximum is 10. |
contains[] |
Only get facet values that contains the given strings. For example, suppose "categories" has three values "Women > Shoe", "Women > Dress" and "Men > Shoe". If set "contains" to "Shoe", the "categories" facet gives only "Women > Shoe" and "Men > Shoe". Only supported on textual fields. Maximum is 10. |
caseInsensitive |
True to make facet keys case insensitive when getting faceting values with prefixes or contains; false otherwise. |
orderBy |
The order in which Allowed values are:
If not set, textual values are sorted in natural order; numerical intervals are sorted in the order given by |
query |
The query that is used to compute facet for the given facet key. When provided, it overrides the default behavior of facet computation. The query syntax is the same as a filter expression. See In the response, For example, you can set a customized facet for "shipToStore", where |
returnMinMax |
Returns the min and max value for each numerical facet intervals. Ignored for textual facets. |
Rule
A rule is a condition-action pair
- A condition defines when a rule is to be triggered.
- An action specifies what occurs on that trigger. Currently rules only work for
controls
withSOLUTION_TYPE_SEARCH
.
JSON representation |
---|
{ "condition": { object ( |
Fields | |
---|---|
condition |
Required. The condition that triggers the rule. If the condition is empty, the rule will always apply. |
Union field action . An action must be provided. action can be only one of the following: |
|
boostAction |
A boost action. |
redirectAction |
Redirects a shopper to a specific page. |
onewaySynonymsAction |
Treats specific term as a synonym with a group of terms. Group of terms will not be treated as synonyms with the specific term. |
doNotAssociateAction |
Prevents term from being associated with other terms. |
replacementAction |
Replaces specific terms in the query. |
ignoreAction |
Ignores specific terms from query during search. |
filterAction |
Filters results. |
twowaySynonymsAction |
Treats a set of terms as synonyms of one another. |
forceReturnFacetAction |
Force returns an attribute as a facet in the request. |
removeFacetAction |
Remove an attribute as a facet in the request (if present). |
BoostAction
A boost action to apply to results matching condition specified above.
JSON representation |
---|
{ "boost": number, "productsFilter": string } |
Fields | |
---|---|
boost |
Strength of the condition boost, which must be in [-1, 1]. Negative boost means demotion. Default is 0.0. Setting to 1.0 gives the item a big promotion. However, it does not necessarily mean that the boosted item will be the top result at all times, nor that other items will be excluded. Results could still be shown even when none of them matches the condition. And results that are significantly more relevant to the search query can still trump your heavily favored but irrelevant items. Setting to -1.0 gives the item a big demotion. However, results that are deeply relevant might still be shown. The item will have an upstream battle to get a fairly high ranking, but it is not blocked out completely. Setting to 0.0 means no boost applied. The boosting condition is ignored. |
productsFilter |
The filter can have a max size of 5000 characters. An expression which specifies which products to apply an action to. The syntax and supported fields are the same as a filter expression. See Examples:
|
RedirectAction
Redirects a shopper to a specific page.
- Rule Condition: Must specify
Condition.query_terms
. - Action Input: Request Query
- Action Result: Redirects shopper to provided uri.
JSON representation |
---|
{ "redirectUri": string } |
Fields | |
---|---|
redirectUri |
URL must have length equal or less than 2000 characters. |
OnewaySynonymsAction
Maps a set of terms to a set of synonyms. Set of synonyms will be treated as synonyms of each query term only. queryTerms
will not be treated as synonyms of each other. Example: "sneakers" will use a synonym of "shoes". "shoes" will not use a synonym of "sneakers".
JSON representation |
---|
{ "queryTerms": [ string ], "synonyms": [ string ], "onewayTerms": [ string ] } |
Fields | |
---|---|
queryTerms[] |
Terms from the search query. Will treat synonyms as their synonyms. Not themselves synonyms of the synonyms. Can specify up to 100 terms. |
synonyms[] |
Defines a set of synonyms. Cannot contain duplicates. Can specify up to 100 synonyms. |
onewayTerms[] |
Will be [deprecated = true] post migration; |
DoNotAssociateAction
Prevents query_term
from being associated with specified terms during search. Example: Don't associate "gShoe" and "cheap".
JSON representation |
---|
{ "queryTerms": [ string ], "doNotAssociateTerms": [ string ], "terms": [ string ] } |
Fields | |
---|---|
queryTerms[] |
Terms from the search query. Will not consider doNotAssociateTerms for search if in search query. Can specify up to 100 terms. |
doNotAssociateTerms[] |
Cannot contain duplicates or the query term. Can specify up to 100 terms. |
terms[] |
Will be [deprecated = true] post migration; |
ReplacementAction
Replaces a term in the query. Multiple replacement candidates can be specified. All queryTerms
will be replaced with the replacement term. Example: Replace "gShoe" with "google shoe".
JSON representation |
---|
{ "queryTerms": [ string ], "replacementTerm": string, "term": string } |
Fields | |
---|---|
queryTerms[] |
Terms from the search query. Will be replaced by replacement term. Can specify up to 100 terms. |
replacementTerm |
Term that will be used for replacement. |
term |
Will be [deprecated = true] post migration; |
IgnoreAction
Prevents a term in the query from being used in search. Example: Don't search for "shoddy".
JSON representation |
---|
{ "ignoreTerms": [ string ] } |
Fields | |
---|---|
ignoreTerms[] |
Terms to ignore in the search query. |
FilterAction
Rule Condition:
- No
Condition.query_terms
provided is a global match. - 1 or more
Condition.query_terms
provided are combined with OR operator.
- No
Action Input: The request query and filter that are applied to the retrieved products, in addition to any filters already provided with the SearchRequest. The AND operator is used to combine the query's existing filters with the filter rule(s). NOTE: May result in 0 results when filters conflict.
Action Result: Filters the returned objects to be ONLY those that passed the filter.
JSON representation |
---|
{ "filter": string } |
Fields | |
---|---|
filter |
A filter to apply on the matching condition results. Supported features:
|
TwowaySynonymsAction
Creates a set of terms that will be treated as synonyms of each other. Example: synonyms of "sneakers" and "shoes":
- "sneakers" will use a synonym of "shoes".
- "shoes" will use a synonym of "sneakers".
JSON representation |
---|
{ "synonyms": [ string ] } |
Fields | |
---|---|
synonyms[] |
Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. |
ForceReturnFacetAction
Force returns an attribute/facet in the request around a certain position or above.
Rule Condition: Must specify non-empty
Condition.query_terms
(for search only) orCondition.page_categories
(for browse only), but can't specify both.Action Inputs: attribute name, position
Action Result: Will force return a facet key around a certain position or above if the condition is satisfied.
Example: Suppose the query is "shoes", the Condition.query_terms
is "shoes", the ForceReturnFacetAction.FacetPositionAdjustment.attribute_name
is "size" and the ForceReturnFacetAction.FacetPositionAdjustment.position
is 8.
Two cases: a) The facet key "size" is not already in the top 8 slots, then the facet "size" will appear at a position close to 8. b) The facet key "size" in among the top 8 positions in the request, then it will stay at its current rank.
JSON representation |
---|
{
"facetPositionAdjustments": [
{
object ( |
Fields | |
---|---|
facetPositionAdjustments[] |
Each instance corresponds to a force return attribute for the given condition. There can't be more 15 instances here. |
FacetPositionAdjustment
Each facet position adjustment consists of a single attribute name (i.e. facet key) along with a specified position.
JSON representation |
---|
{ "attributeName": string, "position": integer } |
Fields | |
---|---|
attributeName |
The attribute name to force return as a facet. Each attribute name should be a valid attribute name, be non-empty and contain at most 80 characters long. |
position |
This is the position in the request as explained above. It should be strictly positive be at most 100. |
RemoveFacetAction
Removes an attribute/facet in the request if is present.
Rule Condition: Must specify non-empty
Condition.query_terms
(for search only) orCondition.page_categories
(for browse only), but can't specify both.Action Input: attribute name
Action Result: Will remove the attribute (as a facet) from the request if it is present.
Example: Suppose the query is "shoes", the Condition.query_terms
is "shoes" and the attribute name "size", then facet key "size" will be removed from the request (if it is present).
JSON representation |
---|
{ "attributeNames": [ string ] } |
Fields | |
---|---|
attributeNames[] |
The attribute names (i.e. facet keys) to remove from the dynamic facets (if present in the request). There can't be more 3 attribute names. Each attribute name should be a valid attribute name, be non-empty and contain at most 80 characters. |
Condition
Metadata that is used to define a condition that triggers an action. A valid condition must specify at least one of 'queryTerms' or 'productsFilter'. If multiple fields are specified, the condition is met if all the fields are satisfied e.g. if a set of query terms and productFilter are set, then only items matching the productFilter for requests with a query matching the query terms wil get boosted.
JSON representation |
---|
{ "queryTerms": [ { object ( |
Fields | |
---|---|
queryTerms[] |
A list (up to 10 entries) of terms to match the query on. If not specified, match all queries. If many query terms are specified, the condition is matched if any of the terms is a match (i.e. using the OR operator). |
activeTimeRange[] |
Range of time(s) specifying when Condition is active. Condition true if any time range matches. |
pageCategories[] |
Used to support browse uses cases. A list (up to 10 entries) of categories or departments. The format should be the same as |
QueryTerm
Query terms that we want to match on.
JSON representation |
---|
{ "value": string, "fullMatch": boolean } |
Fields | |
---|---|
value |
The value of the term to match on. Value cannot be empty. Value can have at most 3 terms if specified as a partial match. Each space separated string is considered as one term. For example, "a b c" is 3 terms and allowed, but " a b c d" is 4 terms and not allowed for a partial match. |
fullMatch |
Whether this is supposed to be a full or partial match. |
TimeRange
Used for time-dependent conditions. Example: Want to have rule applied for week long sale.
JSON representation |
---|
{ "startTime": string, "endTime": string } |
Fields | |
---|---|
startTime |
Start of time range. Range is inclusive. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
endTime |
End of time range. Range is inclusive. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
SearchSolutionUseCase
The use case of Cloud Retail Search.
Enums | |
---|---|
SEARCH_SOLUTION_USE_CASE_UNSPECIFIED |
The value when it's unspecified. In this case, server behavior defaults to SEARCH_SOLUTION_USE_CASE_SEARCH . |
SEARCH_SOLUTION_USE_CASE_SEARCH |
Search use case. Expects the traffic has a non-empty query . |
SEARCH_SOLUTION_USE_CASE_BROWSE |
Browse use case. Expects the traffic has an empty query . |
Methods |
|
---|---|
|
Creates a Control. |
|
Deletes a Control. |
|
Gets a Control. |
|
Lists all Controls by their parent Catalog . |
|
Updates a Control. |