Skip to content

Commit f660ba5

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: support merged facets
feat: add product purge API feat: add page_categories to control condition feat: support attribute suggestion in autocomplete feat: support frequent bought together model config feat: allow to skip denylist postfiltering in recommendations chore: deprecate recent search result in autocomplete docs: keep the API doc up-to-date with recent changes PiperOrigin-RevId: 641043279
1 parent a32cd99 commit f660ba5

14 files changed

Lines changed: 516 additions & 132 deletions

‎google/cloud/retail/v2beta/catalog.proto‎

Lines changed: 136 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import "google/api/field_behavior.proto";
2020
import "google/api/resource.proto";
2121
import "google/cloud/retail/v2beta/common.proto";
2222
import "google/cloud/retail/v2beta/import_config.proto";
23+
import "google/protobuf/timestamp.proto";
2324

2425
option csharp_namespace = "Google.Cloud.Retail.V2Beta";
2526
option go_package = "cloud.google.com/go/retail/apiv2beta/retailpb;retailpb";
@@ -87,6 +88,124 @@ message ProductLevelConfig {
8788
// Catalog level attribute config for an attribute. For example, if customers
8889
// want to enable/disable facet for a specific attribute.
8990
message CatalogAttribute {
91+
// Possible options for the facet that corresponds to the current attribute
92+
// config.
93+
message FacetConfig {
94+
// [Facet values][google.cloud.retail.v2beta.SearchResponse.Facet.values] to
95+
// ignore on [facets][google.cloud.retail.v2beta.SearchResponse.Facet]
96+
// during the specified time range for the given
97+
// [SearchResponse.Facet.key][google.cloud.retail.v2beta.SearchResponse.Facet.key]
98+
// attribute.
99+
message IgnoredFacetValues {
100+
// List of facet values to ignore for the following time range. The facet
101+
// values are the same as the attribute values. There is a limit of 10
102+
// values per instance of IgnoredFacetValues. Each value can have at most
103+
// 128 characters.
104+
repeated string values = 1;
105+
106+
// Time range for the current list of facet values to ignore.
107+
// If multiple time ranges are specified for an facet value for the
108+
// current attribute, consider all of them. If both are empty, ignore
109+
// always. If start time and end time are set, then start time
110+
// must be before end time.
111+
// If start time is not empty and end time is empty, then will ignore
112+
// these facet values after the start time.
113+
google.protobuf.Timestamp start_time = 2;
114+
115+
// If start time is empty and end time is not empty, then ignore these
116+
// facet values before end time.
117+
google.protobuf.Timestamp end_time = 3;
118+
}
119+
120+
// Replaces a set of textual facet values by the same (possibly different)
121+
// merged facet value. Each facet value should appear at most once as a
122+
// value per
123+
// [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]. This
124+
// feature is available only for textual custom attributes.
125+
message MergedFacetValue {
126+
// All the facet values that are replaces by the same
127+
// [merged_value][google.cloud.retail.v2beta.CatalogAttribute.FacetConfig.MergedFacetValue.merged_value]
128+
// that follows. The maximum number of values per MergedFacetValue is 25.
129+
// Each value can have up to 128 characters.
130+
repeated string values = 1;
131+
132+
// All the previous values are replaced by this merged facet value.
133+
// This merged_value must be non-empty and can have up to 128 characters.
134+
string merged_value = 2;
135+
}
136+
137+
// The current facet key (i.e. attribute config) maps into the
138+
// [merged_facet_key][google.cloud.retail.v2beta.CatalogAttribute.FacetConfig.MergedFacet.merged_facet_key].
139+
// A facet key can have at most one child. The current facet key and the
140+
// merged facet key need both to be textual custom attributes or both
141+
// numerical custom attributes (same type).
142+
message MergedFacet {
143+
// The merged facet key should be a valid facet key that is different than
144+
// the facet key of the current catalog attribute. We refer this is
145+
// merged facet key as the child of the current catalog attribute. This
146+
// merged facet key can't be a parent of another facet key (i.e. no
147+
// directed path of length 2). This merged facet key needs to be either a
148+
// textual custom attribute or a numerical custom attribute.
149+
string merged_facet_key = 1;
150+
}
151+
152+
// Options to rerank based on facet values engaged by the user for the
153+
// current key. That key needs to be a custom textual key and facetable.
154+
// To use this control, you also need to pass all the facet keys engaged by
155+
// the user in the request using the field [SearchRequest.FacetSpec]. In
156+
// particular, if you don't pass the facet keys engaged that you want to
157+
// rerank on, this control won't be effective. Moreover, to obtain better
158+
// results, the facet values that you want to rerank on should be close to
159+
// English (ideally made of words, underscores, and spaces).
160+
message RerankConfig {
161+
// If set to true, then we also rerank the dynamic facets based on the
162+
// facet values engaged by the user for the current attribute key during
163+
// serving.
164+
bool rerank_facet = 1;
165+
166+
// If empty, rerank on all facet values for the current key. Otherwise,
167+
// will rerank on the facet values from this list only.
168+
repeated string facet_values = 2;
169+
}
170+
171+
// If you don't set the facet
172+
// [SearchRequest.FacetSpec.FacetKey.intervals][google.cloud.retail.v2beta.SearchRequest.FacetSpec.FacetKey.intervals]
173+
// in the request to a numerical attribute, then we use the computed
174+
// intervals with rounded bounds obtained from all its product numerical
175+
// attribute values. The computed intervals might not be ideal for some
176+
// attributes. Therefore, we give you the option to overwrite them with the
177+
// facet_intervals field. The maximum of facet intervals per
178+
// [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute] is 40.
179+
// Each interval must have a lower bound or an upper bound. If both bounds
180+
// are provided, then the lower bound must be smaller or equal than the
181+
// upper bound.
182+
repeated Interval facet_intervals = 1;
183+
184+
// Each instance represents a list of attribute values to ignore as facet
185+
// values for a specific time range. The maximum number of instances per
186+
// [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute] is 25.
187+
repeated IgnoredFacetValues ignored_facet_values = 2;
188+
189+
// Each instance replaces a list of facet values by a merged facet
190+
// value. If a facet value is not in any list, then it will stay the same.
191+
// To avoid conflicts, only paths of length 1 are accepted. In other words,
192+
// if "dark_blue" merged into "BLUE", then the latter can't merge into
193+
// "blues" because this would create a path of length 2. The maximum number
194+
// of instances of MergedFacetValue per
195+
// [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute] is 100.
196+
// This feature is available only for textual custom attributes.
197+
repeated MergedFacetValue merged_facet_values = 3;
198+
199+
// Use this field only if you want to merge a facet key into another facet
200+
// key.
201+
MergedFacet merged_facet = 4;
202+
203+
// Set this field only if you want to rerank based on facet values engaged
204+
// by the user for the current key. This option is only possible for custom
205+
// facetable textual keys.
206+
RerankConfig rerank_config = 5;
207+
}
208+
90209
// The type of an attribute.
91210
enum AttributeType {
92211
// The type of the attribute is unknown.
@@ -210,7 +329,9 @@ message CatalogAttribute {
210329
// are indexed so that it can be filtered, faceted, or boosted in
211330
// [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search].
212331
//
213-
// Must be specified, otherwise throws INVALID_FORMAT error.
332+
// Must be specified when
333+
// [AttributesConfig.attribute_config_level][google.cloud.retail.v2beta.AttributesConfig.attribute_config_level]
334+
// is CATALOG_LEVEL_ATTRIBUTE_CONFIG, otherwise throws INVALID_FORMAT error.
214335
IndexableOption indexable_option = 5;
215336

216337
// If DYNAMIC_FACETABLE_ENABLED, attribute values are available for dynamic
@@ -232,7 +353,9 @@ message CatalogAttribute {
232353
// [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search], as
233354
// there are no text values associated to numerical attributes.
234355
//
235-
// Must be specified, otherwise throws INVALID_FORMAT error.
356+
// Must be specified, when
357+
// [AttributesConfig.attribute_config_level][google.cloud.retail.v2beta.AttributesConfig.attribute_config_level]
358+
// is CATALOG_LEVEL_ATTRIBUTE_CONFIG, otherwise throws INVALID_FORMAT error.
236359
SearchableOption searchable_option = 7;
237360

238361
// When
@@ -254,6 +377,9 @@ message CatalogAttribute {
254377
// results. If unset, the server behavior defaults to
255378
// [RETRIEVABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.RetrievableOption.RETRIEVABLE_DISABLED].
256379
RetrievableOption retrievable_option = 12;
380+
381+
// Contains facet options.
382+
FacetConfig facet_config = 13;
257383
}
258384

259385
// Catalog level attribute config.
@@ -343,8 +469,8 @@ message CompletionConfig {
343469
// Output only. Name of the LRO corresponding to the latest suggestion terms
344470
// list import.
345471
//
346-
// Can use [GetOperation][google.longrunning.Operations.GetOperation] API to
347-
// retrieve the latest state of the Long Running Operation.
472+
// Can use [GetOperation][google.longrunning.Operations.GetOperation] API
473+
// method to retrieve the latest state of the Long Running Operation.
348474
string last_suggestions_import_operation = 6
349475
[(google.api.field_behavior) = OUTPUT_ONLY];
350476

@@ -374,10 +500,10 @@ message CompletionConfig {
374500
}
375501

376502
// Represents a link between a Merchant Center account and a branch.
377-
// Once a link is established, products from the linked merchant center account
378-
// will be streamed to the linked branch.
503+
// After a link is established, products from the linked Merchant Center account
504+
// are streamed to the linked branch.
379505
message MerchantCenterLink {
380-
// Required. The linked [Merchant center account
506+
// Required. The linked [Merchant Center account
381507
// ID](https://developers.google.com/shopping-content/guides/accountstatuses).
382508
// The account must be a standalone account or a sub-account of a MCA.
383509
int64 merchant_center_account_id = 1 [(google.api.field_behavior) = REQUIRED];
@@ -387,7 +513,7 @@ message MerchantCenterLink {
387513
// empty value will use the currently configured default branch. However,
388514
// changing the default branch later on won't change the linked branch here.
389515
//
390-
// A single branch ID can only have one linked merchant center account ID.
516+
// A single branch ID can only have one linked Merchant Center account ID.
391517
string branch_id = 2;
392518

393519
// String representing the destination to import for, all if left empty.
@@ -469,8 +595,8 @@ message Catalog {
469595
[(google.api.field_behavior) = REQUIRED];
470596

471597
// The Merchant Center linking configuration.
472-
// Once a link is added, the data stream from Merchant Center to Cloud Retail
598+
// After a link is added, the data stream from Merchant Center to Cloud Retail
473599
// will be enabled automatically. The requester must have access to the
474-
// merchant center account in order to make changes to this field.
600+
// Merchant Center account in order to make changes to this field.
475601
MerchantCenterLinkingConfig merchant_center_linking_config = 6;
476602
}

‎google/cloud/retail/v2beta/common.proto‎

Lines changed: 95 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,12 @@ message Condition {
124124
// Range of time(s) specifying when Condition is active.
125125
// Condition true if any time range matches.
126126
repeated TimeRange active_time_range = 3;
127+
128+
// Used to support browse uses cases.
129+
// A list (up to 10 entries) of categories or departments.
130+
// The format should be the same as
131+
// [UserEvent.page_categories][google.cloud.retail.v2beta.UserEvent.page_categories];
132+
repeated string page_categories = 4;
127133
}
128134

129135
// A rule is a condition-action pair
@@ -173,17 +179,19 @@ message Rule {
173179
}
174180

175181
// * Rule Condition:
176-
// - No
177-
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
178-
// provided is a global match.
179-
// - 1 or more
180-
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
181-
// provided are combined with OR operator.
182+
// - No
183+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
184+
// provided is a global match.
185+
// - 1 or more
186+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
187+
// provided are combined with OR operator.
188+
//
182189
// * Action Input: The request query and filter that are applied to the
183190
// retrieved products, in addition to any filters already provided with the
184191
// SearchRequest. The AND operator is used to combine the query's existing
185192
// filters with the filter rule(s). NOTE: May result in 0 results when
186193
// filters conflict.
194+
//
187195
// * Action Result: Filters the returned objects to be ONLY those that passed
188196
// the filter.
189197
message FilterAction {
@@ -193,9 +201,8 @@ message Rule {
193201
// set.
194202
// * Filter syntax is identical to
195203
// [SearchRequest.filter][google.cloud.retail.v2beta.SearchRequest.filter].
196-
// See more
197-
// details at the Retail Search
198-
// [user guide](/retail/search/docs/filter-and-order#filter).
204+
// For more
205+
// information, see [Filter](/retail/docs/filter-and-order#filter).
199206
// * To filter products with product ID "product_1" or "product_2", and
200207
// color
201208
// "Red" or "Blue":<br>
@@ -208,7 +215,7 @@ message Rule {
208215
// Redirects a shopper to a specific page.
209216
//
210217
// * Rule Condition:
211-
// - Must specify
218+
// Must specify
212219
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms].
213220
// * Action Input: Request Query
214221
// * Action Result: Redirects shopper to provided uri.
@@ -290,6 +297,78 @@ message Rule {
290297
repeated string ignore_terms = 1;
291298
}
292299

300+
// Force returns an attribute/facet in the request around a certain position
301+
// or above.
302+
//
303+
// * Rule Condition:
304+
// Must specify non-empty
305+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
306+
// (for search only) or
307+
// [Condition.page_categories][google.cloud.retail.v2beta.Condition.page_categories]
308+
// (for browse only), but can't specify both.
309+
//
310+
// * Action Inputs: attribute name, position
311+
//
312+
// * Action Result: Will force return a facet key around a certain position
313+
// or above if the condition is satisfied.
314+
//
315+
// Example: Suppose the query is "shoes", the
316+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
317+
// is "shoes", the
318+
// [ForceReturnFacetAction.FacetPositionAdjustment.attribute_name][google.cloud.retail.v2beta.Rule.ForceReturnFacetAction.FacetPositionAdjustment.attribute_name]
319+
// is "size" and the
320+
// [ForceReturnFacetAction.FacetPositionAdjustment.position][google.cloud.retail.v2beta.Rule.ForceReturnFacetAction.FacetPositionAdjustment.position]
321+
// is 8.
322+
//
323+
// Two cases: a) The facet key "size" is not already in the top 8 slots, then
324+
// the facet "size" will appear at a position close to 8. b) The facet key
325+
// "size" in among the top 8 positions in the request, then it will stay at
326+
// its current rank.
327+
message ForceReturnFacetAction {
328+
// Each facet position adjustment consists of a single attribute name (i.e.
329+
// facet key) along with a specified position.
330+
message FacetPositionAdjustment {
331+
// The attribute name to force return as a facet. Each attribute name
332+
// should be a valid attribute name, be non-empty and contain at most 80
333+
// characters long.
334+
string attribute_name = 1;
335+
336+
// This is the position in the request as explained above. It should be
337+
// strictly positive be at most 100.
338+
int32 position = 2;
339+
}
340+
341+
// Each instance corresponds to a force return attribute for the given
342+
// condition. There can't be more 3 instances here.
343+
repeated FacetPositionAdjustment facet_position_adjustments = 1;
344+
}
345+
346+
// Removes an attribute/facet in the request if is present.
347+
//
348+
// * Rule Condition:
349+
// Must specify non-empty
350+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
351+
// (for search only) or
352+
// [Condition.page_categories][google.cloud.retail.v2beta.Condition.page_categories]
353+
// (for browse only), but can't specify both.
354+
//
355+
// * Action Input: attribute name
356+
//
357+
// * Action Result: Will remove the attribute (as a facet) from the request
358+
// if it is present.
359+
//
360+
// Example: Suppose the query is "shoes", the
361+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
362+
// is "shoes" and the attribute name "size", then facet key "size" will be
363+
// removed from the request (if it is present).
364+
message RemoveFacetAction {
365+
// The attribute names (i.e. facet keys) to remove from the dynamic facets
366+
// (if present in the request). There can't be more 3 attribute names.
367+
// Each attribute name should be a valid attribute name, be non-empty and
368+
// contain at most 80 characters.
369+
repeated string attribute_names = 1;
370+
}
371+
293372
// An action must be provided.
294373
oneof action {
295374
// A boost action.
@@ -316,6 +395,12 @@ message Rule {
316395

317396
// Treats a set of terms as synonyms of one another.
318397
TwowaySynonymsAction twoway_synonyms_action = 11;
398+
399+
// Force returns an attribute as a facet in the request.
400+
ForceReturnFacetAction force_return_facet_action = 12;
401+
402+
// Remove an attribute as a facet in the request (if present).
403+
RemoveFacetAction remove_facet_action = 13;
319404
}
320405

321406
// Required. The condition that triggers the rule.

0 commit comments

Comments
 (0)