Skip to content

Commit 7660854

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: 641043920
1 parent f660ba5 commit 7660854

14 files changed

Lines changed: 509 additions & 126 deletions

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

Lines changed: 129 additions & 4 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/v2/common.proto";
2222
import "google/cloud/retail/v2/import_config.proto";
23+
import "google/protobuf/timestamp.proto";
2324

2425
option csharp_namespace = "Google.Cloud.Retail.V2";
2526
option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb";
@@ -87,6 +88,123 @@ 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.v2.SearchResponse.Facet.values] to
95+
// ignore on [facets][google.cloud.retail.v2.SearchResponse.Facet] during
96+
// the specified time range for the given
97+
// [SearchResponse.Facet.key][google.cloud.retail.v2.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 [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute].
123+
// This feature is available only for textual custom attributes.
124+
message MergedFacetValue {
125+
// All the facet values that are replaces by the same
126+
// [merged_value][google.cloud.retail.v2.CatalogAttribute.FacetConfig.MergedFacetValue.merged_value]
127+
// that follows. The maximum number of values per MergedFacetValue is 25.
128+
// Each value can have up to 128 characters.
129+
repeated string values = 1;
130+
131+
// All the previous values are replaced by this merged facet value.
132+
// This merged_value must be non-empty and can have up to 128 characters.
133+
string merged_value = 2;
134+
}
135+
136+
// The current facet key (i.e. attribute config) maps into the
137+
// [merged_facet_key][google.cloud.retail.v2.CatalogAttribute.FacetConfig.MergedFacet.merged_facet_key].
138+
// A facet key can have at most one child. The current facet key and the
139+
// merged facet key need both to be textual custom attributes or both
140+
// numerical custom attributes (same type).
141+
message MergedFacet {
142+
// The merged facet key should be a valid facet key that is different than
143+
// the facet key of the current catalog attribute. We refer this is
144+
// merged facet key as the child of the current catalog attribute. This
145+
// merged facet key can't be a parent of another facet key (i.e. no
146+
// directed path of length 2). This merged facet key needs to be either a
147+
// textual custom attribute or a numerical custom attribute.
148+
string merged_facet_key = 1;
149+
}
150+
151+
// Options to rerank based on facet values engaged by the user for the
152+
// current key. That key needs to be a custom textual key and facetable.
153+
// To use this control, you also need to pass all the facet keys engaged by
154+
// the user in the request using the field [SearchRequest.FacetSpec]. In
155+
// particular, if you don't pass the facet keys engaged that you want to
156+
// rerank on, this control won't be effective. Moreover, to obtain better
157+
// results, the facet values that you want to rerank on should be close to
158+
// English (ideally made of words, underscores, and spaces).
159+
message RerankConfig {
160+
// If set to true, then we also rerank the dynamic facets based on the
161+
// facet values engaged by the user for the current attribute key during
162+
// serving.
163+
bool rerank_facet = 1;
164+
165+
// If empty, rerank on all facet values for the current key. Otherwise,
166+
// will rerank on the facet values from this list only.
167+
repeated string facet_values = 2;
168+
}
169+
170+
// If you don't set the facet
171+
// [SearchRequest.FacetSpec.FacetKey.intervals][google.cloud.retail.v2.SearchRequest.FacetSpec.FacetKey.intervals]
172+
// in the request to a numerical attribute, then we use the computed
173+
// intervals with rounded bounds obtained from all its product numerical
174+
// attribute values. The computed intervals might not be ideal for some
175+
// attributes. Therefore, we give you the option to overwrite them with the
176+
// facet_intervals field. The maximum of facet intervals per
177+
// [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute] is 40. Each
178+
// interval must have a lower bound or an upper bound. If both bounds are
179+
// provided, then the lower bound must be smaller or equal than the upper
180+
// bound.
181+
repeated Interval facet_intervals = 1;
182+
183+
// Each instance represents a list of attribute values to ignore as facet
184+
// values for a specific time range. The maximum number of instances per
185+
// [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute] is 25.
186+
repeated IgnoredFacetValues ignored_facet_values = 2;
187+
188+
// Each instance replaces a list of facet values by a merged facet
189+
// value. If a facet value is not in any list, then it will stay the same.
190+
// To avoid conflicts, only paths of length 1 are accepted. In other words,
191+
// if "dark_blue" merged into "BLUE", then the latter can't merge into
192+
// "blues" because this would create a path of length 2. The maximum number
193+
// of instances of MergedFacetValue per
194+
// [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute] is 100. This
195+
// feature is available only for textual custom attributes.
196+
repeated MergedFacetValue merged_facet_values = 3;
197+
198+
// Use this field only if you want to merge a facet key into another facet
199+
// key.
200+
MergedFacet merged_facet = 4;
201+
202+
// Set this field only if you want to rerank based on facet values engaged
203+
// by the user for the current key. This option is only possible for custom
204+
// facetable textual keys.
205+
RerankConfig rerank_config = 5;
206+
}
207+
90208
// The type of an attribute.
91209
enum AttributeType {
92210
// The type of the attribute is unknown.
@@ -210,7 +328,9 @@ message CatalogAttribute {
210328
// are indexed so that it can be filtered, faceted, or boosted in
211329
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
212330
//
213-
// Must be specified, otherwise throws INVALID_FORMAT error.
331+
// Must be specified when
332+
// [AttributesConfig.attribute_config_level][google.cloud.retail.v2.AttributesConfig.attribute_config_level]
333+
// is CATALOG_LEVEL_ATTRIBUTE_CONFIG, otherwise throws INVALID_FORMAT error.
214334
IndexableOption indexable_option = 5;
215335

216336
// If DYNAMIC_FACETABLE_ENABLED, attribute values are available for dynamic
@@ -232,7 +352,9 @@ message CatalogAttribute {
232352
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search], as
233353
// there are no text values associated to numerical attributes.
234354
//
235-
// Must be specified, otherwise throws INVALID_FORMAT error.
355+
// Must be specified, when
356+
// [AttributesConfig.attribute_config_level][google.cloud.retail.v2.AttributesConfig.attribute_config_level]
357+
// is CATALOG_LEVEL_ATTRIBUTE_CONFIG, otherwise throws INVALID_FORMAT error.
236358
SearchableOption searchable_option = 7;
237359

238360
// If EXACT_SEARCHABLE_ENABLED, attribute values will be exact searchable.
@@ -246,6 +368,9 @@ message CatalogAttribute {
246368
// results. If unset, the server behavior defaults to
247369
// [RETRIEVABLE_DISABLED][google.cloud.retail.v2.CatalogAttribute.RetrievableOption.RETRIEVABLE_DISABLED].
248370
RetrievableOption retrievable_option = 12;
371+
372+
// Contains facet options.
373+
FacetConfig facet_config = 13;
249374
}
250375

251376
// Catalog level attribute config.
@@ -335,8 +460,8 @@ message CompletionConfig {
335460
// Output only. Name of the LRO corresponding to the latest suggestion terms
336461
// list import.
337462
//
338-
// Can use [GetOperation][google.longrunning.Operations.GetOperation] API to
339-
// retrieve the latest state of the Long Running Operation.
463+
// Can use [GetOperation][google.longrunning.Operations.GetOperation] API
464+
// method to retrieve the latest state of the Long Running Operation.
340465
string last_suggestions_import_operation = 6
341466
[(google.api.field_behavior) = OUTPUT_ONLY];
342467

‎google/cloud/retail/v2/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.v2.UserEvent.page_categories];
132+
repeated string page_categories = 4;
127133
}
128134

129135
// A rule is a condition-action pair
@@ -172,28 +178,29 @@ message Rule {
172178
}
173179

174180
// * Rule Condition:
175-
// - No
176-
// [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms]
177-
// provided is a global match.
178-
// - 1 or more
179-
// [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms]
180-
// provided are combined with OR operator.
181+
// - No
182+
// [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms]
183+
// provided is a global match.
184+
// - 1 or more
185+
// [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms]
186+
// provided are combined with OR operator.
187+
//
181188
// * Action Input: The request query and filter that are applied to the
182189
// retrieved products, in addition to any filters already provided with the
183190
// SearchRequest. The AND operator is used to combine the query's existing
184191
// filters with the filter rule(s). NOTE: May result in 0 results when
185192
// filters conflict.
193+
//
186194
// * Action Result: Filters the returned objects to be ONLY those that passed
187195
// the filter.
188196
message FilterAction {
189197
// A filter to apply on the matching condition results. Supported features:
190198
//
191199
// * [filter][google.cloud.retail.v2.Rule.FilterAction.filter] must be set.
192200
// * Filter syntax is identical to
193-
// [SearchRequest.filter][google.cloud.retail.v2.SearchRequest.filter]. See
201+
// [SearchRequest.filter][google.cloud.retail.v2.SearchRequest.filter]. For
194202
// more
195-
// details at the Retail Search
196-
// [user guide](/retail/search/docs/filter-and-order#filter).
203+
// information, see [Filter](/retail/docs/filter-and-order#filter).
197204
// * To filter products with product ID "product_1" or "product_2", and
198205
// color
199206
// "Red" or "Blue":<br>
@@ -206,7 +213,7 @@ message Rule {
206213
// Redirects a shopper to a specific page.
207214
//
208215
// * Rule Condition:
209-
// - Must specify
216+
// Must specify
210217
// [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms].
211218
// * Action Input: Request Query
212219
// * Action Result: Redirects shopper to provided uri.
@@ -288,6 +295,78 @@ message Rule {
288295
repeated string ignore_terms = 1;
289296
}
290297

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

315394
// Treats a set of terms as synonyms of one another.
316395
TwowaySynonymsAction twoway_synonyms_action = 11;
396+
397+
// Force returns an attribute as a facet in the request.
398+
ForceReturnFacetAction force_return_facet_action = 12;
399+
400+
// Remove an attribute as a facet in the request (if present).
401+
RemoveFacetAction remove_facet_action = 13;
317402
}
318403

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

‎google/cloud/retail/v2/completion_service.proto‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -151,10 +151,15 @@ message CompleteQueryRequest {
151151
// capped by 20.
152152
int32 max_suggestions = 5;
153153

154-
// The entity for customers that may run multiple different entities, domains,
155-
// sites or regions, for example, `Google US`, `Google Ads`, `Waymo`,
154+
// If true, attribute suggestions are enabled and provided in response.
155+
//
156+
// This field is only available for "cloud-retail" dataset.
157+
bool enable_attribute_suggestions = 9;
158+
159+
// The entity for customers who run multiple entities, domains, sites, or
160+
// regions, for example, `Google US`, `Google Ads`, `Waymo`,
156161
// `google.com`, `youtube.com`, etc.
157-
// If this is set, it should be exactly matched with
162+
// If this is set, it must be an exact match with
158163
// [UserEvent.entity][google.cloud.retail.v2.UserEvent.entity] to get
159164
// per-entity autocomplete results.
160165
string entity = 10;
@@ -179,8 +184,10 @@ message CompleteQueryResponse {
179184
map<string, CustomAttribute> attributes = 2;
180185
}
181186

182-
// Recent search of this user.
187+
// Deprecated: Recent search of this user.
183188
message RecentSearchResult {
189+
option deprecated = true;
190+
184191
// The recent search query.
185192
string recent_search = 1;
186193
}
@@ -195,9 +202,9 @@ message CompleteQueryResponse {
195202
// attribution of complete model performance.
196203
string attribution_token = 2;
197204

198-
// Matched recent searches of this user. The maximum number of recent searches
199-
// is 10. This field is a restricted feature. Contact Retail Search support
200-
// team if you are interested in enabling it.
205+
// Deprecated. Matched recent searches of this user. The maximum number of
206+
// recent searches is 10. This field is a restricted feature. If you want to
207+
// enable it, contact Retail Search support.
201208
//
202209
// This feature is only available when
203210
// [CompleteQueryRequest.visitor_id][google.cloud.retail.v2.CompleteQueryRequest.visitor_id]
@@ -216,5 +223,5 @@ message CompleteQueryResponse {
216223
//
217224
// Recent searches are deduplicated. More recent searches will be reserved
218225
// when duplication happens.
219-
repeated RecentSearchResult recent_search_results = 3;
226+
repeated RecentSearchResult recent_search_results = 3 [deprecated = true];
220227
}

0 commit comments

Comments
 (0)