feat: allow users to disable spell check in search requests (#183)

* docs: fix docstring formatting

Committer: parthea
PiperOrigin-RevId: 449545643

Source-Link: googleapis/googleapis@1bed8a0

Source-Link: googleapis/googleapis-gen@d4ccc5f
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZDRjY2M1ZmM2MTJjMjYwNTQ2YmNlY2VmMjg3MzU3NTY4OGEwMmQ4YiJ9

* 🦉 Updates from OwlBot post-processor

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

* feat: allow users to disable spell check in search requests
feat: allow users to add labels in search requests
docs: deprecate indexable/searchable on the product level custom attributes
docs: keep the API doc up-to-date with recent changes

PiperOrigin-RevId: 452193046

Source-Link: googleapis/googleapis@4e0282f

Source-Link: googleapis/googleapis-gen@3fa3c84
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiM2ZhM2M4NGUzZGE4YzhlNjA0ZTEyOWMxNDEzNjdkZDA5MjY4NzhmMyJ9

* 🦉 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>

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

@@ -40,10 +40,10 @@ message ProductLevelConfig {
   //   default to
   //   [Product.Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY] if
   //   unset.
-  // * `variant`: You can only ingest
-  // [Product.Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
-  // [Product][google.cloud.retail.v2.Product]s.
-  //   This means
+  // * `variant` (incompatible with Retail Search): You can only
+  //   ingest
+  //   [Product.Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
+  //   [Product][google.cloud.retail.v2.Product]s. This means
   //   [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id]
   //   cannot be empty.
   //
@@ -54,8 +54,8 @@ message ProductLevelConfig {
   // [merchant_center_product_id_field][google.cloud.retail.v2.ProductLevelConfig.merchant_center_product_id_field]
   // is `itemGroupId`, an INVALID_ARGUMENT error is returned.
   //
-  // See [Using product
-  // levels](https://cloud.google.com/retail/recommendations-ai/docs/catalog#product-levels)
+  // See [Product
+  // levels](https://cloud.google.com/retail/docs/catalog#product-levels)
   // for more details.
   string ingestion_product_type = 1;
 
@@ -76,8 +76,8 @@ message ProductLevelConfig {
   // [ingestion_product_type][google.cloud.retail.v2.ProductLevelConfig.ingestion_product_type]
   // is `variant`, an INVALID_ARGUMENT error is returned.
   //
-  // See [Using product
-  // levels](https://cloud.google.com/retail/recommendations-ai/docs/catalog#product-levels)
+  // See [Product
+  // levels](https://cloud.google.com/retail/docs/catalog#product-levels)
   // for more details.
   string merchant_center_product_id_field = 2;
 }

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

@@ -115,24 +115,29 @@ message CustomAttribute {
   // Otherwise, an INVALID_ARGUMENT error is returned.
   repeated double numbers = 2;
 
-  // This field will only be used when
+  // This field is normally ignored unless
   // [AttributesConfig.attribute_config_level][] of the
-  // [Catalog][google.cloud.retail.v2.Catalog] is
-  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
-  // searchable by text queries in
+  // [Catalog][google.cloud.retail.v2.Catalog] is set to the deprecated
+  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG' mode. For information about product-level
+  // attribute configuration, see [Configuration
+  // modes](https://cloud.google.com/retail/docs/attribute-config#config-modes).
+  // If true, custom attribute values are searchable by text queries in
   // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
   //
   // This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
   //
   // Only set if type [text][google.cloud.retail.v2.CustomAttribute.text] is
   // set. Otherwise, a INVALID_ARGUMENT error is returned.
-  optional bool searchable = 3;
+  optional bool searchable = 3 [deprecated = true];
 
-  // This field will only be used when
+  // This field is normally ignored unless
   // [AttributesConfig.attribute_config_level][] of the
-  // [Catalog][google.cloud.retail.v2.Catalog] is
-  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
-  // indexed, so that it can be filtered, faceted or boosted in
+  // [Catalog][google.cloud.retail.v2.Catalog] is set to the deprecated
+  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG' mode. For information about product-level
+  // attribute configuration, see [Configuration
+  // modes](https://cloud.google.com/retail/docs/attribute-config#config-modes).
+  // If true, custom attribute values are indexed, so that they can be filtered,
+  // faceted or boosted in
   // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
   //
   // This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
@@ -142,7 +147,7 @@ message CustomAttribute {
   // and
   // [SearchRequest.boost_spec][google.cloud.retail.v2.SearchRequest.boost_spec]
   // for more details.
-  optional bool indexable = 4;
+  optional bool indexable = 4 [deprecated = true];
 }
 
 // Fulfillment information, such as the store IDs for in-store pickup or region
@@ -284,7 +289,10 @@ message PriceInfo {
   float price = 2;
 
   // Price of the product without any discount. If zero, by default set to be
-  // the [price][google.cloud.retail.v2.PriceInfo.price].
+  // the [price][google.cloud.retail.v2.PriceInfo.price]. If set,
+  // [original_price][google.cloud.retail.v2.PriceInfo.original_price] should be
+  // greater than or equal to [price][google.cloud.retail.v2.PriceInfo.price],
+  // otherwise an INVALID_ARGUMENT error is thrown.
   float original_price = 3;
 
   // The costs associated with the sale of a particular product. Used for gross
@@ -368,10 +376,14 @@ message Rating {
 // Information of an end user.
 message UserInfo {
   // Highly recommended for logged-in users. Unique identifier for logged-in
-  // user, such as a user name.
+  // user, such as a user name. Don't set for anonymous users.
   //
   // Always use a hashed value for this ID.
   //
+  // Don't set the field to the same fixed ID for different users. This mixes
+  // the event history of those users together, which results in degraded
+  // model quality.
+  //
   // The field must be a UTF-8 encoded string with a length limit of 128
   // characters. Otherwise, an INVALID_ARGUMENT error is returned.
   string user_id = 1;

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

@@ -133,9 +133,9 @@ message CompleteQueryRequest {
   //
   // * user-data
   //
-  // * cloud-retail
-  //   This option requires additional allowlisting. Before using cloud-retail,
-  //   contact Cloud Retail support team first.
+  // * cloud-retail:
+  //   This option requires enabling auto-learning function first. See
+  //   [guidelines](https://cloud.google.com/retail/docs/completion-overview#generated-completion-dataset).
   string dataset = 6;
 
   // Completion max suggestions. If left unset or set to 0, then will fallback
@@ -154,10 +154,13 @@ message CompleteQueryResponse {
     string suggestion = 1;
 
     // Custom attributes for the suggestion term.
+    //
     // * For "user-data", the attributes are additional custom attributes
     // ingested through BigQuery.
+    //
     // * For "cloud-retail", the attributes are product attributes generated
-    // by Cloud Retail.
+    // by Cloud Retail. This is an experimental feature. Contact Retail Search
+    // support team if you are interested in enabling it.
     map<string, CustomAttribute> attributes = 2;
   }
 
@@ -185,11 +188,15 @@ message CompleteQueryResponse {
   // [CompleteQueryRequest.visitor_id][google.cloud.retail.v2.CompleteQueryRequest.visitor_id]
   // field is set and [UserEvent][google.cloud.retail.v2.UserEvent] is imported.
   // The recent searches satisfy the follow rules:
+  //
   //  * They are ordered from latest to oldest.
+  //
   //  * They are matched with
   //  [CompleteQueryRequest.query][google.cloud.retail.v2.CompleteQueryRequest.query]
   //  case insensitively.
+  //
   //  * They are transformed to lower cases.
+  //
   //  * They are UTF-8 safe.
   //
   // Recent searches are deduplicated. More recent searches will be reserved

protos/google/cloud/retail/v2/import_config.proto

@@ -214,11 +214,18 @@ message ImportProductsRequest {
   // [ReconciliationMode.INCREMENTAL][google.cloud.retail.v2.ImportProductsRequest.ReconciliationMode.INCREMENTAL].
   ReconciliationMode reconciliation_mode = 5;
 
-  // Pub/Sub topic for receiving notification. If this field is set,
+  // Full Pub/Sub topic name for receiving notification. If this field is set,
   // when the import is finished, a notification will be sent to
   // specified Pub/Sub topic. The message data will be JSON string of a
   // [Operation][google.longrunning.Operation].
-  // Format of the Pub/Sub topic is `projects/{project}/topics/{topic}`.
+  //
+  // Format of the Pub/Sub topic is `projects/{project}/topics/{topic}`. It has
+  // to be within the same project as
+  // [ImportProductsRequest.parent][google.cloud.retail.v2.ImportProductsRequest.parent].
+  // Make sure that both
+  // `cloud-retail-customer-data-access@system.gserviceaccount.com` and
+  // `service-<project number>@gcp-sa-retail.iam.gserviceaccount.com`
+  // have the `pubsub.topics.publish` IAM permission on the topic.
   //
   // Only supported when
   // [ImportProductsRequest.reconciliation_mode][google.cloud.retail.v2.ImportProductsRequest.reconciliation_mode]

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

@@ -63,6 +63,16 @@ message PredictRequest {
   // they took to trigger the predict request. Note that this user event detail
   // won't be ingested to userEvent logs. Thus, a separate userEvent write
   // request is required for event logging.
+  //
+  // Don't set
+  // [UserEvent.visitor_id][google.cloud.retail.v2.UserEvent.visitor_id] or
+  // [UserInfo.user_id][google.cloud.retail.v2.UserInfo.user_id] to the same
+  // fixed ID for different users. If you are trying to receive non-personalized
+  // recommendations (not recommended; this can negatively impact model
+  // performance), instead set
+  // [UserEvent.visitor_id][google.cloud.retail.v2.UserEvent.visitor_id] to a
+  // random unique ID and leave
+  // [UserInfo.user_id][google.cloud.retail.v2.UserInfo.user_id] unset.
   UserEvent user_event = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Maximum number of results to return per page. Set this property
@@ -143,7 +153,7 @@ message PredictRequest {
   // * Each resource can have multiple labels, up to a maximum of 64.
   // * Each label must be a key-value pair.
   // * Keys have a minimum length of 1 character and a maximum length of 63
-  //   characters, and cannot be empty. Values can be empty, and have a maximum
+  //   characters and cannot be empty. Values can be empty and have a maximum
   //   length of 63 characters.
   // * Keys and values can contain only lowercase letters, numeric characters,
   //   underscores, and dashes. All characters must use UTF-8 encoding, and
@@ -169,9 +179,9 @@ message PredictResponse {
     //
     // Possible values:
     //
-    // * `product`: JSON representation of the product. Will be set if
+    // * `product`: JSON representation of the product. Is set if
     //   `returnProduct` is set to true in `PredictRequest.params`.
-    // * `score`: Prediction score in double value. Will be set if
+    // * `score`: Prediction score in double value. Is set if
     //   `returnScore` is set to true in `PredictRequest.params`.
     map<string, google.protobuf.Value> metadata = 2;
   }

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

@@ -536,11 +536,11 @@ message Product {
   // * [name][google.cloud.retail.v2.Product.name]
   // * [color_info][google.cloud.retail.v2.Product.color_info]
   //
-  // Maximum number of paths is 30. Otherwise, an INVALID_ARGUMENT error is
+  // The maximum number of paths is 30. Otherwise, an INVALID_ARGUMENT error is
   // returned.
   //
   // Note: Returning more fields in
-  // [SearchResponse][google.cloud.retail.v2.SearchResponse] may increase
+  // [SearchResponse][google.cloud.retail.v2.SearchResponse] can increase
   // response payload size and serving latency.
   google.protobuf.FieldMask retrievable_fields = 30;
 

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

@@ -88,7 +88,7 @@ service ProductService {
 
   // Bulk import of multiple [Product][google.cloud.retail.v2.Product]s.
   //
-  // Request processing may be synchronous. No partial updating is supported.
+  // Request processing may be synchronous.
   // Non-existing items are created.
   //
   // Note that it is possible for a subset of the
@@ -139,7 +139,7 @@ service ProductService {
   //
   // Pre-existing inventory information can only be updated with
   // [SetInventory][google.cloud.retail.v2.ProductService.SetInventory],
-  // [AddFulfillmentPlaces][google.cloud.retail.v2.ProductService.AddFulfillmentPlaces],
+  // [ProductService.AddFulfillmentPlaces][google.cloud.retail.v2.ProductService.AddFulfillmentPlaces],
   // and
   // [RemoveFulfillmentPlaces][google.cloud.retail.v2.ProductService.RemoveFulfillmentPlaces].
   //
@@ -345,6 +345,11 @@ message UpdateProductRequest {
   //
   // If an unsupported or unknown field is provided, an INVALID_ARGUMENT error
   // is returned.
+  //
+  // The attribute key can be updated by setting the mask path as
+  // "attributes.${key_name}". If a key name is present in the mask but not in
+  // the patching product from the request, this key will be deleted after the
+  // update.
   google.protobuf.FieldMask update_mask = 2;
 
   // If set to true, and the [Product][google.cloud.retail.v2.Product] is not
@@ -572,7 +577,9 @@ message SetInventoryMetadata {}
 // method.
 message SetInventoryResponse {}
 
-// Request message for [AddFulfillmentPlaces][] method.
+// Request message for
+// [ProductService.AddFulfillmentPlaces][google.cloud.retail.v2.ProductService.AddFulfillmentPlaces]
+// method.
 message AddFulfillmentPlacesRequest {
   // Required. Full resource name of [Product][google.cloud.retail.v2.Product],
   // such as
@@ -640,15 +647,19 @@ message AddFulfillmentPlacesRequest {
 
 // Metadata related to the progress of the AddFulfillmentPlaces operation.
 // Currently empty because there is no meaningful metadata populated from the
-// [AddFulfillmentPlaces][] method.
+// [ProductService.AddFulfillmentPlaces][google.cloud.retail.v2.ProductService.AddFulfillmentPlaces]
+// method.
 message AddFulfillmentPlacesMetadata {}
 
 // Response of the AddFulfillmentPlacesRequest.  Currently empty because
-// there is no meaningful response populated from the [AddFulfillmentPlaces][]
+// there is no meaningful response populated from the
+// [ProductService.AddFulfillmentPlaces][google.cloud.retail.v2.ProductService.AddFulfillmentPlaces]
 // method.
 message AddFulfillmentPlacesResponse {}
 
-// Request message for [AddLocalInventories][] method.
+// Request message for
+// [ProductService.AddLocalInventories][google.cloud.retail.v2.ProductService.AddLocalInventories]
+// method.
 message AddLocalInventoriesRequest {
   // Required. Full resource name of [Product][google.cloud.retail.v2.Product],
   // such as
@@ -700,11 +711,15 @@ message AddLocalInventoriesRequest {
 
 // Metadata related to the progress of the AddLocalInventories operation.
 // Currently empty because there is no meaningful metadata populated from the
-// [AddLocalInventories][] method.
+// [ProductService.AddLocalInventories][google.cloud.retail.v2.ProductService.AddLocalInventories]
+// method.
 message AddLocalInventoriesMetadata {}
 
-// Response of the [AddLocalInventories][] API.  Currently empty because
-// there is no meaningful response populated from the [AddLocalInventories][]
+// Response of the
+// [ProductService.AddLocalInventories][google.cloud.retail.v2.ProductService.AddLocalInventories]
+// API.  Currently empty because there is no meaningful response populated from
+// the
+// [ProductService.AddLocalInventories][google.cloud.retail.v2.ProductService.AddLocalInventories]
 // method.
 message AddLocalInventoriesResponse {}
 
@@ -782,7 +797,8 @@ message RemoveFulfillmentPlacesRequest {
   // If this field is set to an invalid value other than these, an
   // INVALID_ARGUMENT error is returned.
   //
-  // This field directly corresponds to [Product.fulfillment_info.type][].
+  // This field directly corresponds to
+  // [Product.fulfillment_info.type][google.cloud.retail.v2.FulfillmentInfo.type].
   string type = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Required. The IDs for this

protos/google/cloud/retail/v2/purge_config.proto

@@ -37,7 +37,10 @@ message PurgeUserEventsRequest {
   // Required. The resource name of the catalog under which the events are
   // created. The format is
   // `projects/${projectId}/locations/global/catalogs/${catalogId}`
-  string parent = 1 [(google.api.field_behavior) = REQUIRED];
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" }
+  ];
 
   // Required. The filter string to specify the events to be deleted with a
   // length limit of 5,000 characters. Empty string filter is not allowed. The