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

REST Resource: projects.locations.catalogs.controls

Resource: Control

Configures dynamic serving time metadata that is used to pre and post process search/recommendation model results.

JSON representation
{
  "name": string,
  "displayName": string,
  "associatedServingConfigIds": [
    string
  ],
  "solutionTypes": [
    enum (SolutionType)
  ],

  // Union field control can be only one of the following:
  "facetSpec": {
    object (FacetSpec)
  },
  "rule": {
    object (Rule)
  }
  // End of list of possible types for union field control.
}
Fields
name

string

Immutable. Fully qualified name projects/*/locations/global/catalogs/*/controls/*

displayName

string

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[]

string

Output only. List of serving configuration ids that that are associated with this control. Note the association is managed via the ServingConfig, this is an output only denormalizeed view. Assumed to be in the same catalog.

solutionTypes[]

enum (SolutionType)

Required. Immutable. The solution types that the serving config is used for. Currently we support setting only one type of solution at creation time.

Only SOLUTION_TYPE_SEARCH value is supported at the moment. If no solution type is provided at creation time, will default to SOLUTION_TYPE_SEARCH.

Union field control. The behavior/type of the control

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. control can be only one of the following:

facetSpec

object (FacetSpec)

A facet specification to perform faceted search.

rule

object (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 (FacetKey)
  },
  "limit": integer,
  "excludedFilterKeys": [
    string
  ],
  "enableDynamicPosition": boolean
}
Fields
facetKey

object (FacetKey)

Required. The facet key specification.

limit

integer

Maximum of facet values that should be returned for this facet. If unspecified, defaults to 20. 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[]

string

List of keys to exclude when faceting.

By default, FacetKey.key is not excluded from the filter unless it is listed in this field.

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 FacetKey.key would by default return only "Red" products in the search results, and also return "Red" with count 100 as the only color facet. Although there are also blue products available, "Blue" would not be shown as an available facet value.

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

boolean

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 placements.search. It will be ordered together with dynamic facets if dynamic facets is enabled. If set to false, the position of this facet in the response will be the same as in the request, and it will be 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 will be determined by Google Retail placements.search.

Another example, assuming you have the following facets in the request:

  • "rating", enableDynamicPosition = true

  • "price", enableDynamicPosition = false

  • "brands", enableDynamicPosition = false

And also you have a dynamic facets enable, which will generate 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 placements.search orders "gender" and "rating" facets. However, notice that "price" and "brands" will always be ranked at 1st and 2nd position since their enableDynamicPosition are false.

FacetKey

Specifies how a facet is computed.

JSON representation
{
  "key": string,
  "intervals": [
    {
      object (Interval)
    }
  ],
  "restrictedValues": [
    string
  ],
  "prefixes": [
    string
  ],
  "contains": [
    string
  ],
  "caseInsensitive": boolean,
  "orderBy": string,
  "query": string
}
Fields
key

string

Required. Supported textual and numerical facet keys in Product object, over which the facet values are computed. Facet key is case-sensitive.

Allowed facet keys when FacetKey.query is not specified:

  • textual_field =

    • "brands"
    • "categories"
    • "genders"
    • "ageGroups"
    • "availability"
    • "colorFamilies"
    • "colors"
    • "sizes"
    • "materials"
    • "patterns"
    • "conditions"
    • "attributes.key"
    • "pickupInStore"
    • "shipToStore"
    • "sameDayDelivery"
    • "nextDayDelivery"
    • "customFulfillment1"
    • "customFulfillment2"
    • "customFulfillment3"
    • "customFulfillment4"
    • "customFulfillment5"
    • "inventory(placeId,attributes.key)"
  • numerical_field =

    • "price"
    • "discount"
    • "rating"
    • "ratingCount"
    • "attributes.key"
    • "inventory(placeId,price)"
    • "inventory(placeId,originalPrice)"
    • "inventory(placeId,attributes.key)"
intervals[]

object (Interval)

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 30.

restrictedValues[]

string

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:

  • pickupInStore

  • shipToStore

  • sameDayDelivery

  • nextDayDelivery

  • customFulfillment1

  • customFulfillment2

  • customFulfillment3

  • customFulfillment4

  • customFulfillment5

prefixes[]

string

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 will give only "Women > Shoe" and "Women > Dress". Only supported on textual fields. Maximum is 10.

contains[]

string

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 will give only "Women > Shoe" and "Men > Shoe". Only supported on textual fields. Maximum is 10.

caseInsensitive

boolean

True to make facet keys case insensitive when getting faceting values with prefixes or contains; false otherwise.

orderBy

string

The order in which SearchResponse.Facet.values are returned.

Allowed values are:

If not set, textual values are sorted in natural order; numerical intervals are sorted in the order given by FacetSpec.FacetKey.intervals; FulfillmentInfo.place_ids are sorted in the order given by FacetSpec.FacetKey.restricted_values.

query

string

The query that is used to compute facet for the given facet key. When provided, it will override the default behavior of facet computation. The query syntax is the same as a filter expression. See SearchRequest.filter for detail syntax and limitations. Notice that there is no limitation on FacetKey.key when query is specified.

In the response, SearchResponse.Facet.values.value will be always "1" and SearchResponse.Facet.values.count will be the number of results that match the query.

For example, you can set a customized facet for "shipToStore", where FacetKey.key is "customizedShipToStore", and FacetKey.query is "availability: ANY("IN_STOCK") AND shipToStore: ANY("123")". Then the facet will count the products that are both in stock and ship to store "123".

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 only boost rules are supported. Currently only supported by the search endpoint.

JSON representation
{
  "condition": {
    object (Condition)
  },

  // Union field action can be only one of the following:
  "boostAction": {
    object (BoostAction)
  },
  "redirectAction": {
    object (RedirectAction)
  },
  "onewaySynonymsAction": {
    object (OnewaySynonymsAction)
  },
  "doNotAssociateAction": {
    object (DoNotAssociateAction)
  },
  "replacementAction": {
    object (ReplacementAction)
  },
  "ignoreAction": {
    object (IgnoreAction)
  },
  "filterAction": {
    object (FilterAction)
  },
  "twowaySynonymsAction": {
    object (TwowaySynonymsAction)
  }
  // End of list of possible types for union field action.
}
Fields
condition

object (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

object (BoostAction)

A boost action.

redirectAction

object (RedirectAction)

Redirects a shopper to a specific page.

onewaySynonymsAction

object (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

object (DoNotAssociateAction)

Prevents term from being associated with other terms.

replacementAction

object (ReplacementAction)

Replaces specific terms in the query.

ignoreAction

object (IgnoreAction)

Ignores specific terms from query during search.

filterAction

object (FilterAction)

Filters results.

twowaySynonymsAction

object (TwowaySynonymsAction)

Treats a set of terms as synonyms of one another.

BoostAction

A boost action to apply to results matching condition specified above.

JSON representation
{
  "boost": number,
  "productsFilter": string
}
Fields
boost

number

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

string

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 SearchRequest.filter for detail syntax and limitations.

Examples:

  • To boost products with product ID "product_1" or "product_2", and color "Red" or "Blue":
    (id: ANY("product_1", "product_2"))
    AND
    (colorFamilies: ANY("Red", "Blue"))

RedirectAction

Redirects a shopper to a specific page.

  • Rule Condition:
  • Must specify [Condition][queryTerms].
  • Action Input: Request Query
  • Action Result: Redirects shopper to provided uri.
JSON representation
{
  "redirectUri": string
}
Fields
redirectUri

string

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[]

string

Terms from the search query. Will treat synonyms as their synonyms. Not themselves synonyms of the synonyms. Can specify up to 100 terms.

synonyms[]

string

Defines a set of synonyms. Cannot contain duplicates. Can specify up to 100 synonyms.

onewayTerms[]

string

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[]

string

Terms from the search query. Will not consider doNotAssociateTerms for search if in search query. Can specify up to 100 terms.

doNotAssociateTerms[]

string

Cannot contain duplicates or the query term. Can specify up to 100 terms.

terms[]

string

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[]

string

Terms from the search query. Will be replaced by replacement term. Can specify up to 100 terms.

replacementTerm

string

Term that will be used for replacement.

term

string

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[]

string

Terms to ignore in the search query.

FilterAction

  • Rule Condition:
  • No [Condition][queryTerms] provided is a global match.
  • 1 or more [Condition][queryTerms] provided is combined with OR operator.
  • Action Input: The request query and filter that will be 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

string

A filter to apply on the matching condition results. Supported features:

  • filter must be set.
  • Filter syntax is identical to SearchRequest.filter. See more details at the Retail placements.search user guide.
  • To filter products with product ID "product_1" or "product_2", and color "Red" or "Blue":
    (id: ANY("product_1", "product_2"))
    AND
    (colorFamilies: ANY("Red", "Blue"))

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[]

string

Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms.

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 (QueryTerm)
    }
  ],
  "activeTimeRange": [
    {
      object (TimeRange)
    }
  ]
}
Fields
queryTerms[]

object (QueryTerm)

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[]

object (TimeRange)

Range of time(s) specifying when Condition is active. Condition true if any time range matches.

QueryTerm

Query terms that we want to match on.

JSON representation
{
  "value": string,
  "fullMatch": boolean
}
Fields
value

string

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. Example) "a b c" is 3 terms and allowed, " a b c d" is 4 terms and not allowed for partial match.

fullMatch

boolean

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

string (Timestamp format)

Start of time range. Range is inclusive.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

End of time range. Range is inclusive.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Methods

create

Creates a Control.

delete

Deletes a Control.

get

Gets a Control.

list

Lists all Controls linked to this catalog.

patch

Updates a Control.