Skip to content

Commit 81b0808

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: support per-entity search and autocomplete
feat: add model get API feat: support new filter syntax for recommendation feat: expose A/B experiment info in search response docs: keep the API doc up-to-date with recent changes PiperOrigin-RevId: 522675546
1 parent 13e4201 commit 81b0808

13 files changed

Lines changed: 142 additions & 38 deletions

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,7 @@ message CatalogAttribute {
140140

141141
// The status of the exact-searchable option of a catalog attribute.
142142
enum ExactSearchableOption {
143-
// Value used when unset. Defaults to
144-
// [EXACT_SEARCHABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.ExactSearchableOption.EXACT_SEARCHABLE_DISABLED].
143+
// Value used when unset.
145144
EXACT_SEARCHABLE_OPTION_UNSPECIFIED = 0;
146145

147146
// Exact searchable option enabled for an attribute.
@@ -153,8 +152,7 @@ message CatalogAttribute {
153152

154153
// The status of the retrievable option of a catalog attribute.
155154
enum RetrievableOption {
156-
// Value used when unset. Defaults to
157-
// [RETRIEVABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.RetrievableOption.RETRIEVABLE_DISABLED].
155+
// Value used when unset.
158156
RETRIEVABLE_OPTION_UNSPECIFIED = 0;
159157

160158
// Retrievable option enabled for an attribute.
@@ -171,6 +169,10 @@ message CatalogAttribute {
171169
// characters and underscores. For example, an attribute named
172170
// `attributes.abc_xyz` can be indexed, but an attribute named
173171
// `attributes.abc-xyz` cannot be indexed.
172+
//
173+
// If the attribute key starts with `attributes.`, then the attribute is a
174+
// custom attribute. Attributes such as `brands`, `patterns`, and `title` are
175+
// built-in and called system attributes.
174176
string key = 1 [(google.api.field_behavior) = REQUIRED];
175177

176178
// Output only. Indicates whether this attribute has been used by any
@@ -243,11 +245,14 @@ message CatalogAttribute {
243245

244246
// If EXACT_SEARCHABLE_ENABLED, attribute values will be exact searchable.
245247
// This property only applies to textual custom attributes and requires
246-
// indexable set to enabled to enable exact-searchable.
248+
// indexable set to enabled to enable exact-searchable. If unset, the server
249+
// behavior defaults to
250+
// [EXACT_SEARCHABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.ExactSearchableOption.EXACT_SEARCHABLE_DISABLED].
247251
ExactSearchableOption exact_searchable_option = 11;
248252

249253
// If RETRIEVABLE_ENABLED, attribute values are retrievable in the search
250-
// results.
254+
// results. If unset, the server behavior defaults to
255+
// [RETRIEVABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.RetrievableOption.RETRIEVABLE_DISABLED].
251256
RetrievableOption retrievable_option = 12;
252257
}
253258

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -378,7 +378,7 @@ message ColorInfo {
378378
// it is expected to have only 1 color. May consider using single "Mixed"
379379
// instead of multiple values.
380380
//
381-
// A maximum of 25 colors are allowed. Each value must be a UTF-8 encoded
381+
// A maximum of 75 colors are allowed. Each value must be a UTF-8 encoded
382382
// string with a length limit of 128 characters. Otherwise, an
383383
// INVALID_ARGUMENT error is returned.
384384
//

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

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ option objc_class_prefix = "RETAIL";
3333
option php_namespace = "Google\\Cloud\\Retail\\V2beta";
3434
option ruby_package = "Google::Cloud::Retail::V2beta";
3535

36-
// Auto-completion service for retail.
36+
// Autocomplete service for retail.
3737
//
3838
// This feature is only available for users who have Retail Search enabled.
3939
// Enable Retail Search on Cloud Console before using this feature.
@@ -74,7 +74,7 @@ service CompletionService {
7474
}
7575
}
7676

77-
// Auto-complete parameters.
77+
// Autocomplete parameters.
7878
message CompleteQueryRequest {
7979
// Required. Catalog for which the completion is performed.
8080
//
@@ -150,9 +150,17 @@ message CompleteQueryRequest {
150150
// The maximum allowed max suggestions is 20. If it is set higher, it will be
151151
// capped by 20.
152152
int32 max_suggestions = 5;
153+
154+
// The entity for customers that may run multiple different entities, domains,
155+
// sites or regions, for example, `Google US`, `Google Ads`, `Waymo`,
156+
// `google.com`, `youtube.com`, etc.
157+
// If this is set, it should be exactly matched with
158+
// [UserEvent.entity][google.cloud.retail.v2beta.UserEvent.entity] to get
159+
// per-entity autocomplete results.
160+
string entity = 10;
153161
}
154162

155-
// Response of the auto-complete query.
163+
// Response of the autocomplete query.
156164
message CompleteQueryResponse {
157165
// Resource that represents completion results.
158166
message CompletionResult {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ message BigQuerySource {
126126
// The schema is available here:
127127
// https://support.google.com/analytics/answer/7029846.
128128
//
129-
// Supported values for auto-completion imports:
129+
// Supported values for autocomplete imports:
130130
//
131131
// * `suggestions` (default): One JSON completion suggestion per line.
132132
// * `denylist`: One JSON deny suggestion per line.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2021 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

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

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2021 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -64,6 +64,14 @@ service ModelService {
6464
};
6565
}
6666

67+
// Gets a model.
68+
rpc GetModel(GetModelRequest) returns (Model) {
69+
option (google.api.http) = {
70+
get: "/v2beta/{name=projects/*/locations/*/catalogs/*/models/*}"
71+
};
72+
option (google.api.method_signature) = "name";
73+
}
74+
6775
// Pauses the training of an existing model.
6876
rpc PauseModel(PauseModelRequest) returns (Model) {
6977
option (google.api.http) = {
@@ -154,6 +162,17 @@ message UpdateModelRequest {
154162
[(google.api.field_behavior) = OPTIONAL];
155163
}
156164

165+
// Request for getting a model.
166+
message GetModelRequest {
167+
// Required. The resource name of the
168+
// [Model][google.cloud.retail.v2beta.Model] to get. Format:
169+
// `projects/{project_number}/locations/{location_id}/catalogs/{catalog}/models/{model_id}`
170+
string name = 1 [
171+
(google.api.field_behavior) = REQUIRED,
172+
(google.api.resource_reference) = { type: "retail.googleapis.com/Model" }
173+
];
174+
}
175+
157176
// Request for pausing training of a model.
158177
message PauseModelRequest {
159178
// Required. The name of the model to pause.

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,9 @@ message PredictRequest {
130130
// * (colors: ANY("Red", "Blue")) AND NOT (categories: ANY("Phones"))
131131
// * (availability: ANY("IN_STOCK")) AND
132132
// (colors: ANY("Red") OR categories: ANY("Phones"))
133+
//
134+
// For more information, see
135+
// [Filter recommendations](https://cloud.google.com/retail/docs/filter-recs).
133136
string filter = 5;
134137

135138
// Use validate only mode for this prediction query. If set to true, a

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -587,12 +587,11 @@ message Product {
587587

588588
// Output only. A list of local inventories specific to different places.
589589
//
590-
// This is only available for users who have Retail Search enabled, and it can
591-
// be managed by
590+
// This field can be managed by
592591
// [ProductService.AddLocalInventories][google.cloud.retail.v2beta.ProductService.AddLocalInventories]
593592
// and
594593
// [ProductService.RemoveLocalInventories][google.cloud.retail.v2beta.ProductService.RemoveLocalInventories]
595-
// APIs.
594+
// APIs if fine-grained, high-volume updates are necessary.
596595
repeated LocalInventory local_inventories = 35
597596
[(google.api.field_behavior) = OUTPUT_ONLY];
598597
}

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

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -154,9 +154,6 @@ service ProductService {
154154
// [Operation][google.longrunning.Operation]s associated with the stale
155155
// updates are not marked as [done][google.longrunning.Operation.done] until
156156
// they are obsolete.
157-
//
158-
// This feature is only available for users who have Retail Search enabled.
159-
// Enable Retail Search on Cloud Console before using this feature.
160157
rpc SetInventory(SetInventoryRequest) returns (google.longrunning.Operation) {
161158
option (google.api.http) = {
162159
post: "/v2beta/{inventory.name=projects/*/locations/*/catalogs/*/branches/*/products/**}:setInventory"
@@ -169,6 +166,14 @@ service ProductService {
169166
};
170167
}
171168

169+
// It is recommended to use the
170+
// [ProductService.AddLocalInventories][google.cloud.retail.v2beta.ProductService.AddLocalInventories]
171+
// method instead of
172+
// [ProductService.AddFulfillmentPlaces][google.cloud.retail.v2beta.ProductService.AddFulfillmentPlaces].
173+
// [ProductService.AddLocalInventories][google.cloud.retail.v2beta.ProductService.AddLocalInventories]
174+
// achieves the same results but provides more fine-grained control over
175+
// ingesting local inventory data.
176+
//
172177
// Incrementally adds place IDs to
173178
// [Product.fulfillment_info.place_ids][google.cloud.retail.v2beta.FulfillmentInfo.place_ids].
174179
//
@@ -190,9 +195,6 @@ service ProductService {
190195
// [Operation][google.longrunning.Operation]s associated with the stale
191196
// updates will not be marked as [done][google.longrunning.Operation.done]
192197
// until being obsolete.
193-
//
194-
// This feature is only available for users who have Retail Search enabled.
195-
// Enable Retail Search on Cloud Console before using this feature.
196198
rpc AddFulfillmentPlaces(AddFulfillmentPlacesRequest)
197199
returns (google.longrunning.Operation) {
198200
option (google.api.http) = {
@@ -206,6 +208,14 @@ service ProductService {
206208
};
207209
}
208210

211+
// It is recommended to use the
212+
// [ProductService.RemoveLocalInventories][google.cloud.retail.v2beta.ProductService.RemoveLocalInventories]
213+
// method instead of
214+
// [ProductService.RemoveFulfillmentPlaces][google.cloud.retail.v2beta.ProductService.RemoveFulfillmentPlaces].
215+
// [ProductService.RemoveLocalInventories][google.cloud.retail.v2beta.ProductService.RemoveLocalInventories]
216+
// achieves the same results but provides more fine-grained control over
217+
// ingesting local inventory data.
218+
//
209219
// Incrementally removes place IDs from a
210220
// [Product.fulfillment_info.place_ids][google.cloud.retail.v2beta.FulfillmentInfo.place_ids].
211221
//
@@ -227,9 +237,6 @@ service ProductService {
227237
// [Operation][google.longrunning.Operation]s associated with the stale
228238
// updates will not be marked as [done][google.longrunning.Operation.done]
229239
// until being obsolete.
230-
//
231-
// This feature is only available for users who have Retail Search enabled.
232-
// Enable Retail Search on Cloud Console before using this feature.
233240
rpc RemoveFulfillmentPlaces(RemoveFulfillmentPlacesRequest)
234241
returns (google.longrunning.Operation) {
235242
option (google.api.http) = {
@@ -271,9 +278,6 @@ service ProductService {
271278
// [Operation][google.longrunning.Operation]s associated with the stale
272279
// updates will not be marked as [done][google.longrunning.Operation.done]
273280
// until being obsolete.
274-
//
275-
// This feature is only available for users who have Retail Search enabled.
276-
// Enable Retail Search on Cloud Console before using this feature.
277281
rpc AddLocalInventories(AddLocalInventoriesRequest)
278282
returns (google.longrunning.Operation) {
279283
option (google.api.http) = {
@@ -313,9 +317,6 @@ service ProductService {
313317
// [Operation][google.longrunning.Operation]s associated with the stale
314318
// updates will not be marked as [done][google.longrunning.Operation.done]
315319
// until being obsolete.
316-
//
317-
// This feature is only available for users who have Retail Search enabled.
318-
// Enable Retail Search on Cloud Console before using this feature.
319320
rpc RemoveLocalInventories(RemoveLocalInventoriesRequest)
320321
returns (google.longrunning.Operation) {
321322
option (google.api.http) = {

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

Lines changed: 64 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ option java_package = "com.google.cloud.retail.v2beta";
3333
option objc_class_prefix = "RETAIL";
3434
option php_namespace = "Google\\Cloud\\Retail\\V2beta";
3535
option ruby_package = "Google::Cloud::Retail::V2beta";
36+
option (google.api.resource_definition) = {
37+
type: "retail.googleapis.com/Experiment"
38+
pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/experiments/{experiment}"
39+
};
3640

3741
// Service for search.
3842
//
@@ -112,7 +116,16 @@ message SearchRequest {
112116

113117
// Set only if values should be bucketized into intervals. Must be set
114118
// for facets with numerical values. Must not be set for facet with text
115-
// values. Maximum number of intervals is 30.
119+
// values. Maximum number of intervals is 40.
120+
//
121+
// For all numerical facet keys that appear in the list of products from
122+
// the catalog, the percentiles 0, 10, 30, 50, 70, 90 and 100 are
123+
// computed from their distribution weekly. If the model assigns a high
124+
// score to a numerical facet key and its intervals are not specified in
125+
// the search request, these percentiles will become the bounds
126+
// for its intervals and will be returned in the response. If the
127+
// facet key intervals are specified in the request, then the specified
128+
// intervals will be returned instead.
116129
repeated Interval intervals = 2;
117130

118131
// Only get facet for the given restricted values. For example, when using
@@ -575,7 +588,7 @@ message SearchRequest {
575588

576589
// Facet specifications for faceted search. If empty, no facets are returned.
577590
//
578-
// A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error
591+
// A maximum of 200 values are allowed. Otherwise, an INVALID_ARGUMENT error
579592
// is returned.
580593
repeated FacetSpec facet_specs = 12;
581594

@@ -675,7 +688,7 @@ message SearchRequest {
675688
// INVALID_ARGUMENT error is returned.
676689
repeated string variant_rollup_keys = 17;
677690

678-
// The categories associated with a category page. Required for category
691+
// The categories associated with a category page. Must be set for category
679692
// navigation queries to achieve good search quality. The format should be
680693
// the same as
681694
// [UserEvent.page_categories][google.cloud.retail.v2beta.UserEvent.page_categories];
@@ -727,6 +740,14 @@ message SearchRequest {
727740
// The spell correction specification that specifies the mode under
728741
// which spell correction will take effect.
729742
optional SpellCorrectionSpec spell_correction_spec = 35;
743+
744+
// The entity for customers that may run multiple different entities, domains,
745+
// sites or regions, for example, `Google US`, `Google Ads`, `Waymo`,
746+
// `google.com`, `youtube.com`, etc.
747+
// If this is set, it should be exactly matched with
748+
// [UserEvent.entity][google.cloud.retail.v2beta.UserEvent.entity] to get
749+
// search results boosted by entity.
750+
string entity = 38;
730751
}
731752

732753
// Response message for
@@ -926,4 +947,44 @@ message SearchResponse {
926947
// that are not applied during serving.
927948
repeated SearchRequest.BoostSpec.ConditionBoostSpec
928949
invalid_condition_boost_specs = 14;
950+
951+
// Metadata related to A/B testing [Experiment][] associated with this
952+
// response. Only exists when an experiment is triggered.
953+
repeated ExperimentInfo experiment_info = 17;
954+
}
955+
956+
// Metadata for active A/B testing [Experiments][].
957+
message ExperimentInfo {
958+
// Metadata for active serving config A/B tests.
959+
message ServingConfigExperiment {
960+
// The fully qualified resource name of the original
961+
// [SearchRequest.placement][google.cloud.retail.v2beta.SearchRequest.placement]
962+
// in the search request prior to reassignment by experiment API. For
963+
// example: `projects/*/locations/*/catalogs/*/servingConfigs/*`.
964+
string original_serving_config = 1 [(google.api.resource_reference) = {
965+
type: "retail.googleapis.com/ServingConfig"
966+
}];
967+
968+
// The fully qualified resource name of the serving config
969+
// [VariantArm.serving_config_id][] responsible for generating the search
970+
// response. For example:
971+
// `projects/*/locations/*/catalogs/*/servingConfigs/*`.
972+
string experiment_serving_config = 2 [(google.api.resource_reference) = {
973+
type: "retail.googleapis.com/ServingConfig"
974+
}];
975+
}
976+
977+
// Information associated with the specific experiment entity being recorded.
978+
oneof experiment_metadata {
979+
// A/B test between existing Cloud Retail Search
980+
// [ServingConfig][google.cloud.retail.v2beta.ServingConfig]s.
981+
ServingConfigExperiment serving_config_experiment = 2;
982+
}
983+
984+
// The fully qualified resource name of the experiment that provides the
985+
// serving config under test, should an active experiment exist. For example:
986+
// `projects/*/locations/global/catalogs/default_catalog/experiments/experiment_id`
987+
string experiment = 1 [(google.api.resource_reference) = {
988+
type: "retail.googleapis.com/Experiment"
989+
}];
929990
}

0 commit comments

Comments
 (0)