feat: support async write mode for WriteUserEvent API (#3770)

* feat: support async write mode for WriteUserEvent API
feat: support collect GA4 event format with prebuilt whistle rule
feat: support exact searchable and retrievable in catalog attribute config
feat: deprecate retrievable_fields in product attribute
feat: support diversity type in serving config
docs: keep the API doc up-to-date with recent changes

PiperOrigin-RevId: 495660792

Source-Link: googleapis/googleapis@0dbe50f

Source-Link: googleapis/googleapis-gen@59b8ced
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXJldGFpbC8uT3dsQm90LnlhbWwiLCJoIjoiNTliOGNlZDA2NmJhMTk2NTdlMDZkNzhjMjAxZTYyMGNhNmFiNzljMiJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

packages/google-cloud-retail/protos/google/cloud/retail/v2/catalog.proto

@@ -104,8 +104,7 @@ message CatalogAttribute {
 
   // The status of the indexable option of a catalog attribute.
   enum IndexableOption {
-    // Value used when unset. Defaults to
-    // [INDEXABLE_ENABLED][google.cloud.retail.v2.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED].
+    // Value used when unset.
     INDEXABLE_OPTION_UNSPECIFIED = 0;
 
     // Indexable option enabled for an attribute.
@@ -117,8 +116,7 @@ message CatalogAttribute {
 
   // The status of the dynamic facetable option of a catalog attribute.
   enum DynamicFacetableOption {
-    // Value used when unset. Defaults to
-    // [DYNAMIC_FACETABLE_ENABLED][google.cloud.retail.v2.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED].
+    // Value used when unset.
     DYNAMIC_FACETABLE_OPTION_UNSPECIFIED = 0;
 
     // Dynamic facetable option enabled for an attribute.
@@ -130,8 +128,7 @@ message CatalogAttribute {
 
   // The status of the searchable option of a catalog attribute.
   enum SearchableOption {
-    // Value used when unset. Defaults to
-    // [SEARCHABLE_DISABLED][google.cloud.retail.v2.CatalogAttribute.SearchableOption.SEARCHABLE_DISABLED].
+    // Value used when unset.
     SEARCHABLE_OPTION_UNSPECIFIED = 0;
 
     // Searchable option enabled for an attribute.
@@ -141,6 +138,32 @@ message CatalogAttribute {
     SEARCHABLE_DISABLED = 2;
   }
 
+  // The status of the exact-searchable option of a catalog attribute.
+  enum ExactSearchableOption {
+    // Value used when unset. Defaults to
+    // [EXACT_SEARCHABLE_DISABLED][google.cloud.retail.v2.CatalogAttribute.ExactSearchableOption.EXACT_SEARCHABLE_DISABLED].
+    EXACT_SEARCHABLE_OPTION_UNSPECIFIED = 0;
+
+    // Exact searchable option enabled for an attribute.
+    EXACT_SEARCHABLE_ENABLED = 1;
+
+    // Exact searchable option disabled for an attribute.
+    EXACT_SEARCHABLE_DISABLED = 2;
+  }
+
+  // The status of the retrievable option of a catalog attribute.
+  enum RetrievableOption {
+    // Value used when unset. Defaults to
+    // [RETRIEVABLE_DISABLED][google.cloud.retail.v2.CatalogAttribute.RetrievableOption.RETRIEVABLE_DISABLED].
+    RETRIEVABLE_OPTION_UNSPECIFIED = 0;
+
+    // Retrievable option enabled for an attribute.
+    RETRIEVABLE_ENABLED = 1;
+
+    // Retrievable option disabled for an attribute.
+    RETRIEVABLE_DISABLED = 2;
+  }
+
   // Required. Attribute name.
   // For example: `color`, `brands`, `attributes.custom_attribute`, such as
   // `attributes.xyz`.
@@ -164,13 +187,13 @@ message CatalogAttribute {
   // APIs. This field is `False` for pre-loaded
   // [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute]s.
   //
-  // Only pre-loaded
-  // [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute]s that are
-  // neither in use by products nor predefined can be deleted.
-  // [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute]s that are
-  // either in use by products or are predefined cannot be deleted; however,
-  // their configuration properties will reset to default values upon removal
-  // request.
+  // Only pre-loaded [catalog
+  // attributes][google.cloud.retail.v2.CatalogAttribute] that are neither in
+  // use by products nor predefined can be deleted. [Catalog
+  // attributes][google.cloud.retail.v2.CatalogAttribute] that are
+  // either in use by products or are predefined attributes cannot be deleted;
+  // however, their configuration properties will reset to default values upon
+  // removal request.
   //
   // After catalog changes, it takes about 10 minutes for this field to update.
   bool in_use = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -184,12 +207,16 @@ message CatalogAttribute {
   // is CATALOG_LEVEL_ATTRIBUTE_CONFIG, if INDEXABLE_ENABLED attribute values
   // are indexed so that it can be filtered, faceted, or boosted in
   // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
+  //
+  // Must be specified, otherwise throws INVALID_FORMAT error.
   IndexableOption indexable_option = 5;
 
   // If DYNAMIC_FACETABLE_ENABLED, attribute values are available for dynamic
   // facet. Could only be DYNAMIC_FACETABLE_DISABLED if
   // [CatalogAttribute.indexable_option][google.cloud.retail.v2.CatalogAttribute.indexable_option]
   // is INDEXABLE_DISABLED. Otherwise, an INVALID_ARGUMENT error is returned.
+  //
+  // Must be specified, otherwise throws INVALID_FORMAT error.
   DynamicFacetableOption dynamic_facetable_option = 6;
 
   // When
@@ -202,7 +229,18 @@ message CatalogAttribute {
   // will not be searchable by text queries in
   // [SearchService.Search][google.cloud.retail.v2.SearchService.Search], as
   // there are no text values associated to numerical attributes.
+  //
+  // Must be specified, otherwise throws INVALID_FORMAT error.
   SearchableOption searchable_option = 7;
+
+  // If EXACT_SEARCHABLE_ENABLED, attribute values will be exact searchable.
+  // This property only applies to textual custom attributes and requires
+  // indexable set to enabled to enable exact-searchable.
+  ExactSearchableOption exact_searchable_option = 11;
+
+  // If RETRIEVABLE_ENABLED, attribute values are retrievable in the search
+  // results.
+  RetrievableOption retrievable_option = 12;
 }
 
 // Catalog level attribute config.

packages/google-cloud-retail/protos/google/cloud/retail/v2/catalog_service.proto

@@ -339,7 +339,7 @@ message GetDefaultBranchResponse {
 // method.
 message GetCompletionConfigRequest {
   // Required. Full CompletionConfig resource name. Format:
-  // projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/completionConfig
+  // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/completionConfig`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {

packages/google-cloud-retail/protos/google/cloud/retail/v2/common.proto

@@ -83,8 +83,8 @@ message Condition {
     // Value cannot be empty.
     // Value can have at most 3 terms if specified as a partial match. Each
     // space separated string is considered as one term.
-    // Example) "a b c" is 3 terms and allowed, " a b c d" is 4 terms and not
-    // allowed for partial match.
+    // For example, "a b c" is 3 terms and allowed, but " a b c d" is 4 terms
+    // and not allowed for a partial match.
     string value = 1;
 
     // Whether this is supposed to be a full or partial match.
@@ -113,6 +113,7 @@ message Condition {
 }
 
 // A rule is a condition-action pair
+//
 // * A condition defines when a rule is to be triggered.
 // * An action specifies what occurs on that trigger.
 // Currently rules only work for [controls][google.cloud.retail.v2.Control] with
@@ -201,7 +202,8 @@ message Rule {
   }
 
   // Creates a set of terms that will be treated as synonyms of each other.
-  // Example: synonyms of "sneakers" and "shoes".
+  // Example: synonyms of "sneakers" and "shoes":
+  //
   //  * "sneakers" will use a synonym of "shoes".
   //  * "shoes" will use a synonym of "sneakers".
   message TwowaySynonymsAction {

packages/google-cloud-retail/protos/google/cloud/retail/v2/completion_service.proto

@@ -36,7 +36,7 @@ option ruby_package = "Google::Cloud::Retail::V2";
 // Auto-completion service for retail.
 //
 // This feature is only available for users who have Retail Search enabled.
-// Please enable Retail Search on Cloud Console before using this feature.
+// Enable Retail Search on Cloud Console before using this feature.
 service CompletionService {
   option (google.api.default_host) = "retail.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -45,7 +45,7 @@ service CompletionService {
   // Completes the specified prefix with keyword suggestions.
   //
   // This feature is only available for users who have Retail Search enabled.
-  // Please enable Retail Search on Cloud Console before using this feature.
+  // Enable Retail Search on Cloud Console before using this feature.
   rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
     option (google.api.http) = {
       get: "/v2/{catalog=projects/*/locations/*/catalogs/*}:completeQuery"
@@ -60,7 +60,7 @@ service CompletionService {
   // are indexed successfully and ready for serving. The process takes hours.
   //
   // This feature is only available for users who have Retail Search enabled.
-  // Please enable Retail Search on Cloud Console before using this feature.
+  // Enable Retail Search on Cloud Console before using this feature.
   rpc ImportCompletionData(ImportCompletionDataRequest)
       returns (google.longrunning.Operation) {
     option (google.api.http) = {
@@ -110,8 +110,10 @@ message CompleteQueryRequest {
   // number of language codes is 3.
   repeated string language_codes = 3;
 
-  // The device type context for completion suggestions.
-  // It is useful to apply different suggestions on different device types, e.g.
+  // The device type context for completion suggestions. We recommend that you
+  // leave this field empty.
+  //
+  // It can apply different suggestions on different device types, e.g.
   // `DESKTOP`, `MOBILE`. If it is empty, the suggestions are across all device
   // types.
   //

packages/google-cloud-retail/protos/google/cloud/retail/v2/control.proto

@@ -60,9 +60,8 @@ message Control {
   // characters. Otherwise, an INVALID_ARGUMENT error is thrown.
   string display_name = 2 [(google.api.field_behavior) = REQUIRED];
 
-  // Output only. List of [serving
-  // configuration][google.cloud.retail.v2.ServingConfig] ids that are
-  // associated with this control in the same
+  // Output only. List of [serving config][google.cloud.retail.v2.ServingConfig]
+  // ids that are associated with this control in the same
   // [Catalog][google.cloud.retail.v2.Catalog].
   //
   // Note the association is managed via the

packages/google-cloud-retail/protos/google/cloud/retail/v2/prediction_service.proto

@@ -19,6 +19,7 @@ package google.cloud.retail.v2;
 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/user_event.proto";
 import "google/protobuf/struct.proto";
 
@@ -61,7 +62,7 @@ message PredictRequest {
   // The ID of the Recommendations AI serving config or placement.
   // Before you can request predictions from your model, you must create at
   // least one serving config or placement for it. For more information, see
-  // [Managing serving configurations]
+  // [Manage serving configs]
   // (https://cloud.google.com/retail/docs/manage-configs).
   //
   // The full list of available serving configs can be seen at
@@ -116,12 +117,11 @@ message PredictRequest {
   //  * filterOutOfStockItems  tag=(-"promotional")
   //  * filterOutOfStockItems
   //
-  // If your filter blocks all prediction results, the API will return generic
-  // (unfiltered) popular products. If you only want results strictly matching
-  // the filters, set `strictFiltering` to True in `PredictRequest.params` to
-  // receive empty results instead.
-  // Note that the API will never return items with storageStatus of "EXPIRED"
-  // or "DELETED" regardless of filter choices.
+  // If your filter blocks all prediction results, the API will return *no*
+  // results. If instead you want empty result sets to return generic
+  // (unfiltered) popular products, set `strictFiltering` to False in
+  // `PredictRequest.params`. Note that the API will never return items with
+  // storageStatus of "EXPIRED" or "DELETED" regardless of filter choices.
   //
   // If `filterSyntaxV2` is set to true under the `params` field, then
   // attribute-based expressions are expected instead of the above described
@@ -148,7 +148,7 @@ message PredictRequest {
   // * `returnScore`: Boolean. If set to true, the prediction 'score'
   //    corresponding to each returned product will be set in the
   //    `results.metadata` field in the prediction response. The given
-  //    'score' indicates the probability of an product being clicked/purchased
+  //    'score' indicates the probability of a product being clicked/purchased
   //    given the user's context and history.
   // * `strictFiltering`: Boolean. True by default. If set to false, the service
   //    will return generic (unfiltered) popular products instead of empty if

packages/google-cloud-retail/protos/google/cloud/retail/v2/product.proto

@@ -104,7 +104,13 @@ message Product {
 
   oneof expiration {
     // The timestamp when this product becomes unavailable for
-    // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
+    // [SearchService.Search][google.cloud.retail.v2.SearchService.Search]. Note
+    // that this is only applicable to
+    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY] and
+    // [Type.COLLECTION][google.cloud.retail.v2.Product.Type.COLLECTION], and
+    // ignored for [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT].
+    // In general, we suggest the users to delete the stale products explicitly,
+    // instead of using this field to determine staleness.
     //
     // If it is set, the [Product][google.cloud.retail.v2.Product] is not
     // available for
@@ -124,7 +130,13 @@ message Product {
     // [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.
+    // Input only. The TTL (time to live) of the product. Note that this is only
+    // applicable to [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+    // and [Type.COLLECTION][google.cloud.retail.v2.Product.Type.COLLECTION],
+    // and ignored for
+    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]. In general,
+    // we suggest the users to delete the stale products explicitly, instead of
+    // using this field to determine staleness.
     //
     // If it is set, it must be a non-negative value, and
     // [expire_time][google.cloud.retail.v2.Product.expire_time] is set as
@@ -226,7 +238,7 @@ message Product {
   //
   //
   // To represent full path of category, use '>' sign to separate different
-  // hierarchies. If '>' is part of the category name, please replace it with
+  // hierarchies. If '>' is part of the category name, replace it with
   // other character(s).
   //
   // For example, if a shoes product belongs to both
@@ -356,7 +368,11 @@ message Product {
 
   // The timestamp when this [Product][google.cloud.retail.v2.Product] becomes
   // available for
-  // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
+  // [SearchService.Search][google.cloud.retail.v2.SearchService.Search]. Note
+  // that this is only applicable to
+  // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY] and
+  // [Type.COLLECTION][google.cloud.retail.v2.Product.Type.COLLECTION], and
+  // ignored for [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT].
   google.protobuf.Timestamp available_time = 18;
 
   // The online availability of the [Product][google.cloud.retail.v2.Product].
@@ -542,7 +558,9 @@ message Product {
   // Note: Returning more fields in
   // [SearchResponse][google.cloud.retail.v2.SearchResponse] can increase
   // response payload size and serving latency.
-  google.protobuf.FieldMask retrievable_fields = 30;
+  //
+  // This field is deprecated. Use the retrievable site-wide control instead.
+  google.protobuf.FieldMask retrievable_fields = 30 [deprecated = true];
 
   // Output only. Product variants grouped together on primary product which
   // share similar product attributes. It's automatically grouped by
@@ -559,7 +577,11 @@ message Product {
   // Output only. A list of local inventories specific to different places.
   //
   // This is only available for users who have Retail Search enabled, and it can
-  // be managed by [AddLocalInventories][] and [RemoveLocalInventories][] APIs.
+  // be managed by
+  // [ProductService.AddLocalInventories][google.cloud.retail.v2.ProductService.AddLocalInventories]
+  // and
+  // [ProductService.RemoveLocalInventories][google.cloud.retail.v2.ProductService.RemoveLocalInventories]
+  // APIs.
   repeated LocalInventory local_inventories = 35
       [(google.api.field_behavior) = OUTPUT_ONLY];
 }