Skip to content

Commit 8ef531e

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
docs: Keep the API doc up-to-date
feat: add search mode to search request. If not specified, a single search request triggers both product search and faceted search. feat: update grpc service config settings to reflect correct API deadlines PiperOrigin-RevId: 404039072
1 parent 451e783 commit 8ef531e

18 files changed

Lines changed: 231 additions & 86 deletions

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ message ColorInfo {
8484
// it is expected to have only 1 color. May consider using single "Mixed"
8585
// instead of multiple values.
8686
//
87-
// A maximum of 5 colors are allowed. Each value must be a UTF-8 encoded
87+
// A maximum of 25 colors are allowed. Each value must be a UTF-8 encoded
8888
// string with a length limit of 128 characters. Otherwise, an
8989
// INVALID_ARGUMENT error is returned.
9090
//
@@ -172,8 +172,8 @@ message FulfillmentInfo {
172172
// or the region IDs for
173173
// [FulfillmentInfo.type.same-day-delivery][google.cloud.retail.v2.FulfillmentInfo.type].
174174
//
175-
// A maximum of 2000 values are allowed. Each value must be a string with a
176-
// length limit of 10 characters, matching the pattern [a-zA-Z0-9_-]+, such as
175+
// A maximum of 3000 values are allowed. Each value must be a string with a
176+
// length limit of 30 characters, matching the pattern [a-zA-Z0-9_-]+, such as
177177
// "store1" or "REGION-2". Otherwise, an INVALID_ARGUMENT error is returned.
178178
repeated string place_ids = 2;
179179
}

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

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -115,18 +115,23 @@ message Product {
115115
// and
116116
// [ProductService.ListProducts][google.cloud.retail.v2.ProductService.ListProducts].
117117
//
118+
// [expire_time][google.cloud.retail.v2.Product.expire_time] must be later
119+
// than [available_time][google.cloud.retail.v2.Product.available_time] and
120+
// [publish_time][google.cloud.retail.v2.Product.publish_time], otherwise an
121+
// INVALID_ARGUMENT error is thrown.
122+
//
118123
// Google Merchant Center property
119124
// [expiration_date](https://support.google.com/merchants/answer/6324499).
120125
google.protobuf.Timestamp expire_time = 16;
121126

122127
// Input only. The TTL (time to live) of the product.
123128
//
124-
// If it is set, [expire_time][google.cloud.retail.v2.Product.expire_time]
125-
// is set as current timestamp plus
126-
// [ttl][google.cloud.retail.v2.Product.ttl]. The derived
127-
// [expire_time][google.cloud.retail.v2.Product.expire_time] is returned in
128-
// the output and [ttl][google.cloud.retail.v2.Product.ttl] is left blank
129-
// when retrieving the [Product][google.cloud.retail.v2.Product].
129+
// If it is set, it must be a non-negative value, and
130+
// [expire_time][google.cloud.retail.v2.Product.expire_time] is set as
131+
// current timestamp plus [ttl][google.cloud.retail.v2.Product.ttl]. The
132+
// derived [expire_time][google.cloud.retail.v2.Product.expire_time] is
133+
// returned in the output and [ttl][google.cloud.retail.v2.Product.ttl] is
134+
// left blank when retrieving the [Product][google.cloud.retail.v2.Product].
130135
//
131136
// If it is set, the product is not available for
132137
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search] after
@@ -141,8 +146,6 @@ message Product {
141146

142147
// Immutable. Full resource name of the product, such as
143148
// `projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id`.
144-
//
145-
// The branch ID must be "default_branch".
146149
string name = 1 [(google.api.field_behavior) = IMMUTABLE];
147150

148151
// Immutable. [Product][google.cloud.retail.v2.Product] identifier, which is

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

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import "google/api/annotations.proto";
2020
import "google/api/client.proto";
2121
import "google/api/field_behavior.proto";
2222
import "google/api/resource.proto";
23+
import "google/cloud/retail/v2/common.proto";
2324
import "google/cloud/retail/v2/import_config.proto";
2425
import "google/cloud/retail/v2/product.proto";
2526
import "google/cloud/retail/v2/purge_config.proto";
@@ -476,7 +477,7 @@ message SetInventoryRequest {
476477
// [Product.name][google.cloud.retail.v2.Product.name] is not found, the
477478
// inventory update will still be processed and retained for at most 1 day
478479
// until the [Product][google.cloud.retail.v2.Product] is created. If set to
479-
// false, an INVALID_ARGUMENT error is returned if the
480+
// false, a NOT_FOUND error is returned if the
480481
// [Product][google.cloud.retail.v2.Product] is not found.
481482
bool allow_missing = 4;
482483
}
@@ -551,8 +552,8 @@ message AddFulfillmentPlacesRequest {
551552
// If set to true, and the [Product][google.cloud.retail.v2.Product] is not
552553
// found, the fulfillment information will still be processed and retained for
553554
// at most 1 day and processed once the
554-
// [Product][google.cloud.retail.v2.Product] is created. If set to false, an
555-
// INVALID_ARGUMENT error is returned if the
555+
// [Product][google.cloud.retail.v2.Product] is created. If set to false, a
556+
// NOT_FOUND error is returned if the
556557
// [Product][google.cloud.retail.v2.Product] is not found.
557558
bool allow_missing = 5;
558559
}
@@ -562,7 +563,7 @@ message AddFulfillmentPlacesRequest {
562563
// [AddFulfillmentPlaces][] method.
563564
message AddFulfillmentPlacesMetadata {}
564565

565-
// Response of the RemoveFulfillmentPlacesRequest. Currently empty because
566+
// Response of the AddFulfillmentPlacesRequest. Currently empty because
566567
// there is no meaningful response populated from the [AddFulfillmentPlaces][]
567568
// method.
568569
message AddFulfillmentPlacesResponse {}
@@ -622,8 +623,8 @@ message RemoveFulfillmentPlacesRequest {
622623
// If set to true, and the [Product][google.cloud.retail.v2.Product] is not
623624
// found, the fulfillment information will still be processed and retained for
624625
// at most 1 day and processed once the
625-
// [Product][google.cloud.retail.v2.Product] is created. If set to false, an
626-
// INVALID_ARGUMENT error is returned if the
626+
// [Product][google.cloud.retail.v2.Product] is created. If set to false, a
627+
// NOT_FOUND error is returned if the
627628
// [Product][google.cloud.retail.v2.Product] is not found.
628629
bool allow_missing = 5;
629630
}

‎google/cloud/retail/v2/retail_v2.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ backend:
4848
- selector: google.cloud.retail.v2.ProductService.ImportProducts
4949
deadline: 300.0
5050
- selector: google.cloud.retail.v2.UserEventService.ImportUserEvents
51-
deadline: 300.0
51+
deadline: 600.0
5252
- selector: google.cloud.retail.v2.UserEventService.PurgeUserEvents
5353
deadline: 30.0
5454
- selector: google.longrunning.Operations.ListOperations

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

Lines changed: 54 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ message SearchRequest {
103103
// * "rating"
104104
// * "ratingCount"
105105
// * "attributes.key"
106+
// * "inventory(place_id,price)"
106107
string key = 1 [(google.api.field_behavior) = REQUIRED];
107108

108109
// Set only if values should be bucketized into intervals. Must be set
@@ -349,14 +350,39 @@ message SearchRequest {
349350
bool pin_unexpanded_results = 2;
350351
}
351352

353+
// The search mode of each search request.
354+
enum SearchMode {
355+
// Default value. In this case both product search and faceted search will
356+
// be performed. Both [SearchResponse.SearchResult] and
357+
// [SearchResponse.Facet] will be returned.
358+
SEARCH_MODE_UNSPECIFIED = 0;
359+
360+
// Only product search will be performed. The faceted search will be
361+
// disabled.
362+
//
363+
// Only [SearchResponse.SearchResult] will be returned.
364+
// [SearchResponse.Facet] will not be returned, even if
365+
// [SearchRequest.facet_specs][google.cloud.retail.v2.SearchRequest.facet_specs]
366+
// or
367+
// [SearchRequest.dynamic_facet_spec][google.cloud.retail.v2.SearchRequest.dynamic_facet_spec]
368+
// is set.
369+
PRODUCT_SEARCH_ONLY = 1;
370+
371+
// Only faceted search will be performed. The product search will be
372+
// disabled.
373+
//
374+
// When in this mode, one or both of [SearchRequest.facet_spec][] and
375+
// [SearchRequest.dynamic_facet_spec][google.cloud.retail.v2.SearchRequest.dynamic_facet_spec]
376+
// should be set. Otherwise, an INVALID_ARGUMENT error is returned. Only
377+
// [SearchResponse.Facet] will be returned. [SearchResponse.SearchResult]
378+
// will not be returned.
379+
FACETED_SEARCH_ONLY = 2;
380+
}
381+
352382
// Required. The resource name of the search engine placement, such as
353383
// `projects/*/locations/global/catalogs/default_catalog/placements/default_search`.
354-
// This field is used to identify the set of models that will be used to make
355-
// the search.
356-
//
357-
// We currently support one placement with the following ID:
358-
//
359-
// * `default_search`.
384+
// This field is used to identify the serving configuration name and the set
385+
// of models that will be used to make the search.
360386
string placement = 1 [(google.api.field_behavior) = REQUIRED];
361387

362388
// The branch resource name, such as
@@ -413,7 +439,8 @@ message SearchRequest {
413439

414440
// The filter syntax consists of an expression language for constructing a
415441
// predicate from one or more fields of the products being filtered. Filter
416-
// expression is case-sensitive.
442+
// expression is case-sensitive. See more details at this [user
443+
// guide](https://cloud.google.com/retail/docs/filter-and-order#filter).
417444
//
418445
// If this field is unrecognizable, an INVALID_ARGUMENT is returned.
419446
string filter = 10;
@@ -431,7 +458,9 @@ message SearchRequest {
431458

432459
// The order in which products are returned. Products can be ordered by
433460
// a field in an [Product][google.cloud.retail.v2.Product] object. Leave it
434-
// unset if ordered by relevance. OrderBy expression is case-sensitive.
461+
// unset if ordered by relevance. OrderBy expression is case-sensitive. See
462+
// more details at this [user
463+
// guide](https://cloud.google.com/retail/docs/filter-and-order#order).
435464
//
436465
// If this field is unrecognizable, an INVALID_ARGUMENT is returned.
437466
string order_by = 11;
@@ -449,11 +478,19 @@ message SearchRequest {
449478
// support team if you are interested in using dynamic facet feature.
450479
DynamicFacetSpec dynamic_facet_spec = 21;
451480

452-
// Boost specification to boost certain products.
481+
// Boost specification to boost certain products. See more details at this
482+
// [user guide](https://cloud.google.com/retail/docs/boosting).
483+
//
484+
// Notice that if both [ServingConfig.boost_control_ids][] and
485+
// [SearchRequest.boost_spec] are set, the boost conditions from both places
486+
// are evaluated. If a search request matches multiple boost conditions,
487+
// the final boost score is equal to the sum of the boost scores from all
488+
// matched boost conditions.
453489
BoostSpec boost_spec = 13;
454490

455491
// The query expansion specification that specifies the conditions under which
456-
// query expansion will occur.
492+
// query expansion will occur. See more details at this [user
493+
// guide](https://cloud.google.com/retail/docs/result-size#query_expansion).
457494
QueryExpansionSpec query_expansion_spec = 14;
458495

459496
// The keys to fetch and rollup the matching
@@ -476,6 +513,7 @@ message SearchRequest {
476513
// * price
477514
// * originalPrice
478515
// * discount
516+
// * inventory(place_id,price)
479517
// * attributes.key, where key is any key in the
480518
// [Product.attributes][google.cloud.retail.v2.Product.attributes] map.
481519
// * pickupInStore.id, where id is any
@@ -532,6 +570,10 @@ message SearchRequest {
532570
// instance, a special sale page may have the category hierarchy:
533571
// "pageCategories" : ["Sales > 2017 Black Friday Deals"].
534572
repeated string page_categories = 23;
573+
574+
// The search mode of the search request. If not specified, a single search
575+
// request triggers both product search and faceted search.
576+
SearchMode search_mode = 31;
535577
}
536578

537579
// Response message for
@@ -646,7 +688,8 @@ message SearchResponse {
646688
bool expanded_query = 1;
647689

648690
// Number of pinned results. This field will only be set when expansion
649-
// happens and [SearchRequest.query_expansion_spec.pin_unexpanded_results][]
691+
// happens and
692+
// [SearchRequest.QueryExpansionSpec.pin_unexpanded_results][google.cloud.retail.v2.SearchRequest.QueryExpansionSpec.pin_unexpanded_results]
650693
// is set to true.
651694
int64 pinned_result_count = 2;
652695
}

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,12 +120,12 @@ message UserEvent {
120120
// * `purchase-complete`
121121
//
122122
// In a `search` event, this field represents the products returned to the end
123-
// user on the current page (the end user may have not finished broswing the
123+
// user on the current page (the end user may have not finished browsing the
124124
// whole page yet). When a new page is returned to the end user, after
125125
// pagination/filtering/ordering even for the same query, a new `search` event
126126
// with different
127127
// [product_details][google.cloud.retail.v2.UserEvent.product_details] is
128-
// desired. The end user may have not finished broswing the whole page yet.
128+
// desired. The end user may have not finished browsing the whole page yet.
129129
repeated ProductDetail product_details = 6;
130130

131131
// The main completion details related to the event.
@@ -146,7 +146,7 @@ message UserEvent {
146146
// search, and etc.
147147
map<string, CustomAttribute> attributes = 7;
148148

149-
// The id or name of the associated shopping cart. This id is used
149+
// The ID or name of the associated shopping cart. This ID is used
150150
// to associate multiple items added or present in the cart before purchase.
151151
//
152152
// This can only be set for `add-to-cart`, `purchase-complete`, or
@@ -241,7 +241,7 @@ message UserEvent {
241241
// Tag Manager, this value is filled in automatically.
242242
string referrer_uri = 14;
243243

244-
// A unique id of a web page view.
244+
// A unique ID of a web page view.
245245
//
246246
// This should be kept the same for all user events triggered from the same
247247
// pageview. For example, an item detail page view could trigger multiple

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ message ColorInfo {
8484
// it is expected to have only 1 color. May consider using single "Mixed"
8585
// instead of multiple values.
8686
//
87-
// A maximum of 5 colors are allowed. Each value must be a UTF-8 encoded
87+
// A maximum of 25 colors are allowed. Each value must be a UTF-8 encoded
8888
// string with a length limit of 128 characters. Otherwise, an
8989
// INVALID_ARGUMENT error is returned.
9090
//
@@ -175,8 +175,8 @@ message FulfillmentInfo {
175175
// or the region IDs for
176176
// [FulfillmentInfo.type.same-day-delivery][google.cloud.retail.v2alpha.FulfillmentInfo.type].
177177
//
178-
// A maximum of 2000 values are allowed. Each value must be a string with a
179-
// length limit of 10 characters, matching the pattern [a-zA-Z0-9_-]+, such as
178+
// A maximum of 3000 values are allowed. Each value must be a string with a
179+
// length limit of 30 characters, matching the pattern [a-zA-Z0-9_-]+, such as
180180
// "store1" or "REGION-2". Otherwise, an INVALID_ARGUMENT error is returned.
181181
repeated string place_ids = 2;
182182
}

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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -115,13 +115,19 @@ message Product {
115115
// and
116116
// [ProductService.ListProducts][google.cloud.retail.v2alpha.ProductService.ListProducts].
117117
//
118+
// [expire_time][google.cloud.retail.v2alpha.Product.expire_time] must be
119+
// later than
120+
// [available_time][google.cloud.retail.v2alpha.Product.available_time] and
121+
// [publish_time][google.cloud.retail.v2alpha.Product.publish_time],
122+
// otherwise an INVALID_ARGUMENT error is thrown.
123+
//
118124
// Google Merchant Center property
119125
// [expiration_date](https://support.google.com/merchants/answer/6324499).
120126
google.protobuf.Timestamp expire_time = 16;
121127

122128
// Input only. The TTL (time to live) of the product.
123129
//
124-
// If it is set,
130+
// If it is set, it must be a non-negative value, and
125131
// [expire_time][google.cloud.retail.v2alpha.Product.expire_time] is set as
126132
// current timestamp plus [ttl][google.cloud.retail.v2alpha.Product.ttl].
127133
// The derived
@@ -144,8 +150,6 @@ message Product {
144150

145151
// Immutable. Full resource name of the product, such as
146152
// `projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id`.
147-
//
148-
// The branch ID must be "default_branch".
149153
string name = 1 [(google.api.field_behavior) = IMMUTABLE];
150154

151155
// Immutable. [Product][google.cloud.retail.v2alpha.Product] identifier, which

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import "google/api/annotations.proto";
2020
import "google/api/client.proto";
2121
import "google/api/field_behavior.proto";
2222
import "google/api/resource.proto";
23+
import "google/cloud/retail/v2alpha/common.proto";
2324
import "google/cloud/retail/v2alpha/export_config.proto";
2425
import "google/cloud/retail/v2alpha/import_config.proto";
2526
import "google/cloud/retail/v2alpha/product.proto";
@@ -505,7 +506,7 @@ message SetInventoryRequest {
505506
// name [Product.name][google.cloud.retail.v2alpha.Product.name] is not found,
506507
// the inventory update will still be processed and retained for at most 1 day
507508
// until the [Product][google.cloud.retail.v2alpha.Product] is created. If set
508-
// to false, an INVALID_ARGUMENT error is returned if the
509+
// to false, a NOT_FOUND error is returned if the
509510
// [Product][google.cloud.retail.v2alpha.Product] is not found.
510511
bool allow_missing = 4;
511512
}
@@ -581,7 +582,7 @@ message AddFulfillmentPlacesRequest {
581582
// not found, the fulfillment information will still be processed and retained
582583
// for at most 1 day and processed once the
583584
// [Product][google.cloud.retail.v2alpha.Product] is created. If set to false,
584-
// an INVALID_ARGUMENT error is returned if the
585+
// a NOT_FOUND error is returned if the
585586
// [Product][google.cloud.retail.v2alpha.Product] is not found.
586587
bool allow_missing = 5;
587588
}
@@ -591,7 +592,7 @@ message AddFulfillmentPlacesRequest {
591592
// [AddFulfillmentPlaces][] method.
592593
message AddFulfillmentPlacesMetadata {}
593594

594-
// Response of the RemoveFulfillmentPlacesRequest. Currently empty because
595+
// Response of the AddFulfillmentPlacesRequest. Currently empty because
595596
// there is no meaningful response populated from the [AddFulfillmentPlaces][]
596597
// method.
597598
message AddFulfillmentPlacesResponse {}
@@ -652,7 +653,7 @@ message RemoveFulfillmentPlacesRequest {
652653
// not found, the fulfillment information will still be processed and retained
653654
// for at most 1 day and processed once the
654655
// [Product][google.cloud.retail.v2alpha.Product] is created. If set to false,
655-
// an INVALID_ARGUMENT error is returned if the
656+
// a NOT_FOUND error is returned if the
656657
// [Product][google.cloud.retail.v2alpha.Product] is not found.
657658
bool allow_missing = 5;
658659
}

‎google/cloud/retail/v2alpha/retail_v2alpha.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ backend:
5252
- selector: google.cloud.retail.v2alpha.ProductService.ImportProducts
5353
deadline: 300.0
5454
- selector: google.cloud.retail.v2alpha.UserEventService.ImportUserEvents
55-
deadline: 300.0
55+
deadline: 600.0
5656
- selector: google.cloud.retail.v2alpha.UserEventService.PurgeUserEvents
5757
deadline: 30.0
5858
- selector: google.longrunning.Operations.ListOperations

0 commit comments

Comments
 (0)