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 Source-Link: googleapis/googleapis@8ef531e Source-Link: https://github.com/googleapis/googleapis-gen/commit/86e91097a445a4b0972a20e4b0e3e87f9aadd2c0 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiODZlOTEwOTdhNDQ1YTRiMDk3MmEyMGU0YjBlM2U4N2Y5YWFkZDJjMCJ9
googleapis · Oct 19, 2021 · 49b9b8e · 49b9b8e
1 parent b64baa4
commit 49b9b8e
Show file tree

Hide file tree

Showing 93 changed files with 6,711 additions and 205 deletions.
diff --git a/protos/google/cloud/retail/v2/common.proto b/protos/google/cloud/retail/v2/common.proto
@@ -84,7 +84,7 @@ message ColorInfo {
   // it is expected to have only 1 color. May consider using single "Mixed"
   // instead of multiple values.
   //
-  // A maximum of 5 colors are allowed. Each value must be a UTF-8 encoded
+  // A maximum of 25 colors are allowed. Each value must be a UTF-8 encoded
   // string with a length limit of 128 characters. Otherwise, an
   // INVALID_ARGUMENT error is returned.
   //
@@ -172,8 +172,8 @@ message FulfillmentInfo {
   // or the region IDs for
   // [FulfillmentInfo.type.same-day-delivery][google.cloud.retail.v2.FulfillmentInfo.type].
   //
-  // A maximum of 2000 values are allowed. Each value must be a string with a
-  // length limit of 10 characters, matching the pattern [a-zA-Z0-9_-]+, such as
+  // A maximum of 3000 values are allowed. Each value must be a string with a
+  // length limit of 30 characters, matching the pattern [a-zA-Z0-9_-]+, such as
   // "store1" or "REGION-2". Otherwise, an INVALID_ARGUMENT error is returned.
   repeated string place_ids = 2;
 }

diff --git a/protos/google/cloud/retail/v2/product.proto b/protos/google/cloud/retail/v2/product.proto
@@ -115,18 +115,23 @@ message Product {
     // and
     // [ProductService.ListProducts][google.cloud.retail.v2.ProductService.ListProducts].
     //
+    // [expire_time][google.cloud.retail.v2.Product.expire_time] must be later
+    // than [available_time][google.cloud.retail.v2.Product.available_time] and
+    // [publish_time][google.cloud.retail.v2.Product.publish_time], otherwise an
+    // INVALID_ARGUMENT error is thrown.
+    //
     // Google Merchant Center property
     // [expiration_date](https://support.google.com/merchants/answer/6324499).
     google.protobuf.Timestamp expire_time = 16;
 
     // Input only. The TTL (time to live) of the product.
     //
-    // If it is set, [expire_time][google.cloud.retail.v2.Product.expire_time]
-    // is set as current timestamp plus
-    // [ttl][google.cloud.retail.v2.Product.ttl]. The derived
-    // [expire_time][google.cloud.retail.v2.Product.expire_time] is returned in
-    // the output and [ttl][google.cloud.retail.v2.Product.ttl] is left blank
-    // when retrieving the [Product][google.cloud.retail.v2.Product].
+    // If it is set, it must be a non-negative value, and
+    // [expire_time][google.cloud.retail.v2.Product.expire_time] is set as
+    // current timestamp plus [ttl][google.cloud.retail.v2.Product.ttl]. The
+    // derived [expire_time][google.cloud.retail.v2.Product.expire_time] is
+    // returned in the output and [ttl][google.cloud.retail.v2.Product.ttl] is
+    // left blank when retrieving the [Product][google.cloud.retail.v2.Product].
     //
     // If it is set, the product is not available for
     // [SearchService.Search][google.cloud.retail.v2.SearchService.Search] after
@@ -141,8 +146,6 @@ message Product {
 
   // Immutable. Full resource name of the product, such as
   // `projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id`.
-  //
-  // The branch ID must be "default_branch".
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // Immutable. [Product][google.cloud.retail.v2.Product] identifier, which is

diff --git a/protos/google/cloud/retail/v2/product_service.proto b/protos/google/cloud/retail/v2/product_service.proto
@@ -20,6 +20,7 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/cloud/retail/v2/common.proto";
 import "google/cloud/retail/v2/import_config.proto";
 import "google/cloud/retail/v2/product.proto";
 import "google/cloud/retail/v2/purge_config.proto";
@@ -476,7 +477,7 @@ message SetInventoryRequest {
   // [Product.name][google.cloud.retail.v2.Product.name] is not found, the
   // inventory update will still be processed and retained for at most 1 day
   // until the [Product][google.cloud.retail.v2.Product] is created. If set to
-  // false, an INVALID_ARGUMENT error is returned if the
+  // false, a NOT_FOUND error is returned if the
   // [Product][google.cloud.retail.v2.Product] is not found.
   bool allow_missing = 4;
 }
@@ -551,8 +552,8 @@ message AddFulfillmentPlacesRequest {
   // If set to true, and the [Product][google.cloud.retail.v2.Product] is not
   // found, the fulfillment information will still be processed and retained for
   // at most 1 day and processed once the
-  // [Product][google.cloud.retail.v2.Product] is created. If set to false, an
-  // INVALID_ARGUMENT error is returned if the
+  // [Product][google.cloud.retail.v2.Product] is created. If set to false, a
+  // NOT_FOUND error is returned if the
   // [Product][google.cloud.retail.v2.Product] is not found.
   bool allow_missing = 5;
 }
@@ -562,7 +563,7 @@ message AddFulfillmentPlacesRequest {
 // [AddFulfillmentPlaces][] method.
 message AddFulfillmentPlacesMetadata {}
 
-// Response of the RemoveFulfillmentPlacesRequest.  Currently empty because
+// Response of the AddFulfillmentPlacesRequest.  Currently empty because
 // there is no meaningful response populated from the [AddFulfillmentPlaces][]
 // method.
 message AddFulfillmentPlacesResponse {}
@@ -622,8 +623,8 @@ message RemoveFulfillmentPlacesRequest {
   // If set to true, and the [Product][google.cloud.retail.v2.Product] is not
   // found, the fulfillment information will still be processed and retained for
   // at most 1 day and processed once the
-  // [Product][google.cloud.retail.v2.Product] is created. If set to false, an
-  // INVALID_ARGUMENT error is returned if the
+  // [Product][google.cloud.retail.v2.Product] is created. If set to false, a
+  // NOT_FOUND error is returned if the
   // [Product][google.cloud.retail.v2.Product] is not found.
   bool allow_missing = 5;
 }

diff --git a/protos/google/cloud/retail/v2/search_service.proto b/protos/google/cloud/retail/v2/search_service.proto
@@ -103,6 +103,7 @@ message SearchRequest {
       //     * "rating"
       //     * "ratingCount"
       //     * "attributes.key"
+      //     * "inventory(place_id,price)"
       string key = 1 [(google.api.field_behavior) = REQUIRED];
 
       // Set only if values should be bucketized into intervals. Must be set
@@ -349,14 +350,39 @@ message SearchRequest {
     bool pin_unexpanded_results = 2;
   }
 
+  // The search mode of each search request.
+  enum SearchMode {
+    // Default value. In this case both product search and faceted search will
+    // be performed. Both [SearchResponse.SearchResult] and
+    // [SearchResponse.Facet] will be returned.
+    SEARCH_MODE_UNSPECIFIED = 0;
+
+    // Only product search will be performed. The faceted search will be
+    // disabled.
+    //
+    // Only [SearchResponse.SearchResult] will be returned.
+    // [SearchResponse.Facet] will not be returned, even if
+    // [SearchRequest.facet_specs][google.cloud.retail.v2.SearchRequest.facet_specs]
+    // or
+    // [SearchRequest.dynamic_facet_spec][google.cloud.retail.v2.SearchRequest.dynamic_facet_spec]
+    // is set.
+    PRODUCT_SEARCH_ONLY = 1;
+
+    // Only faceted search will be performed. The product search will be
+    // disabled.
+    //
+    // When in this mode, one or both of [SearchRequest.facet_spec][] and
+    // [SearchRequest.dynamic_facet_spec][google.cloud.retail.v2.SearchRequest.dynamic_facet_spec]
+    // should be set. Otherwise, an INVALID_ARGUMENT error is returned. Only
+    // [SearchResponse.Facet] will be returned. [SearchResponse.SearchResult]
+    // will not be returned.
+    FACETED_SEARCH_ONLY = 2;
+  }
+
   // Required. The resource name of the search engine placement, such as
   // `projects/*/locations/global/catalogs/default_catalog/placements/default_search`.
-  // This field is used to identify the set of models that will be used to make
-  // the search.
-  //
-  // We currently support one placement with the following ID:
-  //
-  // * `default_search`.
+  // This field is used to identify the serving configuration name and the set
+  // of models that will be used to make the search.
   string placement = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The branch resource name, such as
@@ -413,7 +439,8 @@ message SearchRequest {
 
   // The filter syntax consists of an expression language for constructing a
   // predicate from one or more fields of the products being filtered. Filter
-  // expression is case-sensitive.
+  // expression is case-sensitive. See more details at this [user
+  // guide](https://cloud.google.com/retail/docs/filter-and-order#filter).
   //
   // If this field is unrecognizable, an INVALID_ARGUMENT is returned.
   string filter = 10;
@@ -431,7 +458,9 @@ message SearchRequest {
 
   // The order in which products are returned. Products can be ordered by
   // a field in an [Product][google.cloud.retail.v2.Product] object. Leave it
-  // unset if ordered by relevance. OrderBy expression is case-sensitive.
+  // unset if ordered by relevance. OrderBy expression is case-sensitive. See
+  // more details at this [user
+  // guide](https://cloud.google.com/retail/docs/filter-and-order#order).
   //
   // If this field is unrecognizable, an INVALID_ARGUMENT is returned.
   string order_by = 11;
@@ -449,11 +478,19 @@ message SearchRequest {
   // support team if you are interested in using dynamic facet feature.
   DynamicFacetSpec dynamic_facet_spec = 21;
 
-  // Boost specification to boost certain products.
+  // Boost specification to boost certain products. See more details at this
+  // [user guide](https://cloud.google.com/retail/docs/boosting).
+  //
+  // Notice that if both [ServingConfig.boost_control_ids][] and
+  // [SearchRequest.boost_spec] are set, the boost conditions from both places
+  // are evaluated. If a search request matches multiple boost conditions,
+  // the final boost score is equal to the sum of the boost scores from all
+  // matched boost conditions.
   BoostSpec boost_spec = 13;
 
   // The query expansion specification that specifies the conditions under which
-  // query expansion will occur.
+  // query expansion will occur. See more details at this [user
+  // guide](https://cloud.google.com/retail/docs/result-size#query_expansion).
   QueryExpansionSpec query_expansion_spec = 14;
 
   // The keys to fetch and rollup the matching
@@ -476,6 +513,7 @@ message SearchRequest {
   // * price
   // * originalPrice
   // * discount
+  // * inventory(place_id,price)
   // * attributes.key, where key is any key in the
   //   [Product.attributes][google.cloud.retail.v2.Product.attributes] map.
   // * pickupInStore.id, where id is any
@@ -532,6 +570,10 @@ message SearchRequest {
   // instance, a special sale page may have the category hierarchy:
   // "pageCategories" : ["Sales > 2017 Black Friday Deals"].
   repeated string page_categories = 23;
+
+  // The search mode of the search request. If not specified, a single search
+  // request triggers both product search and faceted search.
+  SearchMode search_mode = 31;
 }
 
 // Response message for
@@ -646,7 +688,8 @@ message SearchResponse {
     bool expanded_query = 1;
 
     // Number of pinned results. This field will only be set when expansion
-    // happens and [SearchRequest.query_expansion_spec.pin_unexpanded_results][]
+    // happens and
+    // [SearchRequest.QueryExpansionSpec.pin_unexpanded_results][google.cloud.retail.v2.SearchRequest.QueryExpansionSpec.pin_unexpanded_results]
     // is set to true.
     int64 pinned_result_count = 2;
   }

diff --git a/protos/google/cloud/retail/v2/user_event.proto b/protos/google/cloud/retail/v2/user_event.proto
@@ -120,12 +120,12 @@ message UserEvent {
   // * `purchase-complete`
   //
   // In a `search` event, this field represents the products returned to the end
-  // user on the current page (the end user may have not finished broswing the
+  // user on the current page (the end user may have not finished browsing the
   // whole page yet). When a new page is returned to the end user, after
   // pagination/filtering/ordering even for the same query, a new `search` event
   // with different
   // [product_details][google.cloud.retail.v2.UserEvent.product_details] is
-  // desired. The end user may have not finished broswing the whole page yet.
+  // desired. The end user may have not finished browsing the whole page yet.
   repeated ProductDetail product_details = 6;
 
   // The main completion details related to the event.
@@ -146,7 +146,7 @@ message UserEvent {
   // search, and etc.
   map<string, CustomAttribute> attributes = 7;
 
-  // The id or name of the associated shopping cart. This id is used
+  // The ID or name of the associated shopping cart. This ID is used
   // to associate multiple items added or present in the cart before purchase.
   //
   // This can only be set for `add-to-cart`, `purchase-complete`, or
@@ -241,7 +241,7 @@ message UserEvent {
   // Tag Manager, this value is filled in automatically.
   string referrer_uri = 14;
 
-  // A unique id of a web page view.
+  // A unique ID of a web page view.
   //
   // This should be kept the same for all user events triggered from the same
   // pageview. For example, an item detail page view could trigger multiple

diff --git a/protos/google/cloud/retail/v2alpha/common.proto b/protos/google/cloud/retail/v2alpha/common.proto
@@ -84,7 +84,7 @@ message ColorInfo {
   // it is expected to have only 1 color. May consider using single "Mixed"
   // instead of multiple values.
   //
-  // A maximum of 5 colors are allowed. Each value must be a UTF-8 encoded
+  // A maximum of 25 colors are allowed. Each value must be a UTF-8 encoded
   // string with a length limit of 128 characters. Otherwise, an
   // INVALID_ARGUMENT error is returned.
   //
@@ -175,8 +175,8 @@ message FulfillmentInfo {
   // or the region IDs for
   // [FulfillmentInfo.type.same-day-delivery][google.cloud.retail.v2alpha.FulfillmentInfo.type].
   //
-  // A maximum of 2000 values are allowed. Each value must be a string with a
-  // length limit of 10 characters, matching the pattern [a-zA-Z0-9_-]+, such as
+  // A maximum of 3000 values are allowed. Each value must be a string with a
+  // length limit of 30 characters, matching the pattern [a-zA-Z0-9_-]+, such as
   // "store1" or "REGION-2". Otherwise, an INVALID_ARGUMENT error is returned.
   repeated string place_ids = 2;
 }

diff --git a/protos/google/cloud/retail/v2alpha/product.proto b/protos/google/cloud/retail/v2alpha/product.proto
@@ -115,13 +115,19 @@ message Product {
     // and
     // [ProductService.ListProducts][google.cloud.retail.v2alpha.ProductService.ListProducts].
     //
+    // [expire_time][google.cloud.retail.v2alpha.Product.expire_time] must be
+    // later than
+    // [available_time][google.cloud.retail.v2alpha.Product.available_time] and
+    // [publish_time][google.cloud.retail.v2alpha.Product.publish_time],
+    // otherwise an INVALID_ARGUMENT error is thrown.
+    //
     // Google Merchant Center property
     // [expiration_date](https://support.google.com/merchants/answer/6324499).
     google.protobuf.Timestamp expire_time = 16;
 
     // Input only. The TTL (time to live) of the product.
     //
-    // If it is set,
+    // If it is set, it must be a non-negative value, and
     // [expire_time][google.cloud.retail.v2alpha.Product.expire_time] is set as
     // current timestamp plus [ttl][google.cloud.retail.v2alpha.Product.ttl].
     // The derived
@@ -144,8 +150,6 @@ message Product {
 
   // Immutable. Full resource name of the product, such as
   // `projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id`.
-  //
-  // The branch ID must be "default_branch".
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // Immutable. [Product][google.cloud.retail.v2alpha.Product] identifier, which

diff --git a/protos/google/cloud/retail/v2alpha/product_service.proto b/protos/google/cloud/retail/v2alpha/product_service.proto
@@ -20,6 +20,7 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/cloud/retail/v2alpha/common.proto";
 import "google/cloud/retail/v2alpha/export_config.proto";
 import "google/cloud/retail/v2alpha/import_config.proto";
 import "google/cloud/retail/v2alpha/product.proto";
@@ -505,7 +506,7 @@ message SetInventoryRequest {
   // name [Product.name][google.cloud.retail.v2alpha.Product.name] is not found,
   // the inventory update will still be processed and retained for at most 1 day
   // until the [Product][google.cloud.retail.v2alpha.Product] is created. If set
-  // to false, an INVALID_ARGUMENT error is returned if the
+  // to false, a NOT_FOUND error is returned if the
   // [Product][google.cloud.retail.v2alpha.Product] is not found.
   bool allow_missing = 4;
 }
@@ -581,7 +582,7 @@ message AddFulfillmentPlacesRequest {
   // not found, the fulfillment information will still be processed and retained
   // for at most 1 day and processed once the
   // [Product][google.cloud.retail.v2alpha.Product] is created. If set to false,
-  // an INVALID_ARGUMENT error is returned if the
+  // a NOT_FOUND error is returned if the
   // [Product][google.cloud.retail.v2alpha.Product] is not found.
   bool allow_missing = 5;
 }
@@ -591,7 +592,7 @@ message AddFulfillmentPlacesRequest {
 // [AddFulfillmentPlaces][] method.
 message AddFulfillmentPlacesMetadata {}
 
-// Response of the RemoveFulfillmentPlacesRequest.  Currently empty because
+// Response of the AddFulfillmentPlacesRequest.  Currently empty because
 // there is no meaningful response populated from the [AddFulfillmentPlaces][]
 // method.
 message AddFulfillmentPlacesResponse {}
@@ -652,7 +653,7 @@ message RemoveFulfillmentPlacesRequest {
   // not found, the fulfillment information will still be processed and retained
   // for at most 1 day and processed once the
   // [Product][google.cloud.retail.v2alpha.Product] is created. If set to false,
-  // an INVALID_ARGUMENT error is returned if the
+  // a NOT_FOUND error is returned if the
   // [Product][google.cloud.retail.v2alpha.Product] is not found.
   bool allow_missing = 5;
 }