feat: support case insensitive match on search facets

feat: allow disabling spell check in search requests
feat: allow adding labels in search requests
feat: allow returning min/max values on search numeric facets
feat: allow using serving configs as an alias of placements
feat: allow enabling recommendation filtering on custom attributes
feat: return output BigQuery table on product / event export response
docs: keep the API doc up-to-date with recent changes

PiperOrigin-RevId: 463980128

Author: Google APIs

google/cloud/retail/v2beta/catalog.proto

@@ -42,10 +42,10 @@ message ProductLevelConfig {
   //   default to
   //   [Product.Type.PRIMARY][google.cloud.retail.v2beta.Product.Type.PRIMARY]
   //   if unset.
-  // * `variant`: You can only ingest
-  // [Product.Type.VARIANT][google.cloud.retail.v2beta.Product.Type.VARIANT]
-  // [Product][google.cloud.retail.v2beta.Product]s.
-  //   This means
+  // * `variant` (incompatible with Retail Search): You can only
+  //   ingest
+  //   [Product.Type.VARIANT][google.cloud.retail.v2beta.Product.Type.VARIANT]
+  //   [Product][google.cloud.retail.v2beta.Product]s. This means
   //   [Product.primary_product_id][google.cloud.retail.v2beta.Product.primary_product_id]
   //   cannot be empty.
   //
@@ -56,8 +56,8 @@ message ProductLevelConfig {
   // [merchant_center_product_id_field][google.cloud.retail.v2beta.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;
 
@@ -78,8 +78,8 @@ message ProductLevelConfig {
   // [ingestion_product_type][google.cloud.retail.v2beta.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;
 }
@@ -144,6 +144,10 @@ message CatalogAttribute {
   // Required. Attribute name.
   // For example: `color`, `brands`, `attributes.custom_attribute`, such as
   // `attributes.xyz`.
+  // To be indexable, the attribute name can contain only alpha-numeric
+  // characters and underscores. For example, an attribute named
+  // `attributes.abc_xyz` can be indexed, but an attribute named
+  // `attributes.abc-xyz` cannot be indexed.
   string key = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Output only. Indicates whether this attribute has been used by any
@@ -153,15 +157,20 @@ message CatalogAttribute {
   // Otherwise, this field is `False`.
   //
   // [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute] can be
-  // pre-loaded by using [AddCatalogAttribute][], [ImportCatalogAttributes][],
-  // or [UpdateAttributesConfig][] APIs. This field is `False` for pre-loaded
+  // pre-loaded by using
+  // [CatalogService.AddCatalogAttribute][google.cloud.retail.v2beta.CatalogService.AddCatalogAttribute],
+  // [CatalogService.ImportCatalogAttributes][], or
+  // [CatalogService.UpdateAttributesConfig][google.cloud.retail.v2beta.CatalogService.UpdateAttributesConfig]
+  // APIs. This field is `False` for pre-loaded
   // [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s.
   //
-  // Only [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s that
-  // are not in use by products can be deleted.
+  // Only pre-loaded
   // [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s that are
-  // in use by products cannot be deleted; however, their configuration
-  // properties will reset to default values upon removal request.
+  // neither in use by products nor predefined can be deleted.
+  // [CatalogAttribute][google.cloud.retail.v2beta.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.
   //
   // After catalog changes, it takes about 10 minutes for this field to update.
   bool in_use = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -194,6 +203,14 @@ message CatalogAttribute {
   // [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search], as
   // there are no text values associated to numerical attributes.
   SearchableOption searchable_option = 7;
+
+  // When
+  // [AttributesConfig.attribute_config_level][google.cloud.retail.v2beta.AttributesConfig.attribute_config_level]
+  // is CATALOG_LEVEL_ATTRIBUTE_CONFIG, if RECOMMENDATIONS_FILTERING_ENABLED,
+  // attribute values are filterable for recommendations.
+  // This option works for categorical features only,
+  // does not work for numerical features, inventory filtering.
+  RecommendationsFilteringOption recommendations_filtering_option = 8;
 }
 
 // Catalog level attribute config.
@@ -254,14 +271,18 @@ message CompletionConfig {
   // Default value: 'exact-prefix'.
   string matching_order = 2;
 
-  // The maximum number of autocomplete suggestions returned per term. The
-  // maximum allowed max suggestions is 20. Default value is 20. If left unset
-  // or set to 0, then will fallback to default value.
+  // The maximum number of autocomplete suggestions returned per term. Default
+  // value is 20. If left unset or set to 0, then will fallback to default
+  // value.
+  //
+  // Value range is 1 to 20.
   int32 max_suggestions = 3;
 
   // The minimum number of characters needed to be typed in order to get
   // suggestions. Default value is 2. If left unset or set to 0, then will
   // fallback to default value.
+  //
+  // Value range is 1 to 20.
   int32 min_prefix_length = 4;
 
   // If set to true, the auto learning function is enabled. Auto learning uses
@@ -271,8 +292,8 @@ message CompletionConfig {
   // [CompleteQueryRequest][google.cloud.retail.v2beta.CompleteQueryRequest].
   bool auto_learning = 11;
 
-  // Output only. The input config for the import of the source data that
-  // contains the autocomplete phrases uploaded by the customer.
+  // Output only. The source data for the latest import of the autocomplete
+  // suggestion phrases.
   CompletionDataInputConfig suggestions_input_config = 5
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
@@ -284,24 +305,24 @@ message CompletionConfig {
   string last_suggestions_import_operation = 6
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The input config for the import of the source data that
-  // contains the / autocomplete denylist phrases uploaded by the customer.
+  // Output only. The source data for the latest import of the autocomplete
+  // denylist phrases.
   CompletionDataInputConfig denylist_input_config = 7
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. LRO corresponding to the latest denylist import.
+  // Output only. Name of the LRO corresponding to the latest denylist import.
   //
   // Can use [GetOperation][google.longrunning.Operations.GetOperation] API to
   // retrieve the latest state of the Long Running Operation.
   string last_denylist_import_operation = 8
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The input config for the import of the source data that
-  // contains the autocomplete allowlist phrases uploaded by the customer.
+  // Output only. The source data for the latest import of the autocomplete
+  // allowlist phrases.
   CompletionDataInputConfig allowlist_input_config = 9
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. LRO corresponding to the latest allowlist import.
+  // Output only. Name of the LRO corresponding to the latest allowlist import.
   //
   // Can use [GetOperation][google.longrunning.Operations.GetOperation] API to
   // retrieve the latest state of the Long Running Operation.

google/cloud/retail/v2beta/catalog_service.proto

@@ -384,7 +384,7 @@ message UpdateCompletionConfigRequest {
 // method.
 message GetAttributesConfigRequest {
   // Required. Full AttributesConfig resource name. Format:
-  // projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig
+  // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -417,7 +417,7 @@ message UpdateAttributesConfigRequest {
 // method.
 message AddCatalogAttributeRequest {
   // Required. Full AttributesConfig resource name. Format:
-  // projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig
+  // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig`
   string attributes_config = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -436,7 +436,7 @@ message AddCatalogAttributeRequest {
 // method.
 message RemoveCatalogAttributeRequest {
   // Required. Full AttributesConfig resource name. Format:
-  // projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig
+  // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig`
   string attributes_config = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -454,7 +454,7 @@ message RemoveCatalogAttributeRequest {
 // method.
 message ReplaceCatalogAttributeRequest {
   // Required. Full AttributesConfig resource name. Format:
-  // projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig
+  // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig`
   string attributes_config = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {

google/cloud/retail/v2beta/common.proto

@@ -30,7 +30,7 @@ option ruby_package = "Google::Cloud::Retail::V2beta";
 
 // At which level we offer configuration for attributes.
 enum AttributeConfigLevel {
-  // Value used when unset. Defaults to
+  // Value used when unset. In this case, server behavior defaults to
   // [CATALOG_LEVEL_ATTRIBUTE_CONFIG][google.cloud.retail.v2beta.AttributeConfigLevel.CATALOG_LEVEL_ATTRIBUTE_CONFIG].
   ATTRIBUTE_CONFIG_LEVEL_UNSPECIFIED = 0;
 
@@ -55,10 +55,24 @@ enum SolutionType {
   SOLUTION_TYPE_SEARCH = 2;
 }
 
+// If filtering for recommendations is enabled.
+enum RecommendationsFilteringOption {
+  // Value used when unset.
+  // In this case, server behavior defaults to
+  // [RECOMMENDATIONS_FILTERING_DISABLED][google.cloud.retail.v2beta.RecommendationsFilteringOption.RECOMMENDATIONS_FILTERING_DISABLED].
+  RECOMMENDATIONS_FILTERING_OPTION_UNSPECIFIED = 0;
+
+  // Recommendation filtering is disabled.
+  RECOMMENDATIONS_FILTERING_DISABLED = 1;
+
+  // Recommendation filtering is enabled.
+  RECOMMENDATIONS_FILTERING_ENABLED = 3;
+}
+
 // The use case of Cloud Retail Search.
 enum SearchSolutionUseCase {
-  // The value when it's unspecified. Defaults to
-  // [SEARCH][].
+  // The value when it's unspecified. In this case, server behavior defaults to
+  // [SEARCH_SOLUTION_USE_CASE_SEARCH][].
   SEARCH_SOLUTION_USE_CASE_UNSPECIFIED = 0;
 
   // Search use case. Expects the traffic has a non-empty
@@ -157,10 +171,13 @@ message Rule {
   }
 
   // * Rule Condition:
-  //   - No [Condition][query_terms] provided is a global match.
-  //   - 1 or more [Condition][query_terms] provided is combined with OR
-  //   operator.
-  // * Action Input: The request query and filter that will be applied to the
+  //   - No
+  //   [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
+  //   provided is a global match.
+  //   - 1 or more
+  //   [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
+  //   provided are combined with OR operator.
+  // * Action Input: The request query and filter that are applied to the
   // retrieved products, in addition to any filters already provided with the
   // SearchRequest. The AND operator is used to combine the query's existing
   // filters with the filter rule(s). NOTE: May result in 0 results when
@@ -187,8 +204,10 @@ message Rule {
   }
 
   // Redirects a shopper to a specific page.
+  //
   // * Rule Condition:
-  //   - Must specify [Condition][query_terms].
+  //   - Must specify
+  //   [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms].
   // * Action Input: Request Query
   // * Action Result: Redirects shopper to provided uri.
   message RedirectAction {
@@ -388,25 +407,30 @@ message CustomAttribute {
   // set. 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][google.cloud.retail.v2beta.AttributesConfig.attribute_config_level]
-  // of the [Catalog][google.cloud.retail.v2beta.Catalog] is
-  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
-  // searchable by text queries in
+  // of the [Catalog][google.cloud.retail.v2beta.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.v2beta.SearchService.Search].
   //
   // This field is ignored in a
   // [UserEvent][google.cloud.retail.v2beta.UserEvent].
   //
   // Only set if type [text][google.cloud.retail.v2beta.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][google.cloud.retail.v2beta.AttributesConfig.attribute_config_level]
-  // of the [Catalog][google.cloud.retail.v2beta.Catalog] is
-  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
-  // indexed, so that it can be filtered, faceted or boosted in
+  // of the [Catalog][google.cloud.retail.v2beta.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.v2beta.SearchService.Search].
   //
   // This field is ignored in a
@@ -418,7 +442,7 @@ message CustomAttribute {
   // and
   // [SearchRequest.boost_spec][google.cloud.retail.v2beta.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
@@ -490,9 +514,8 @@ message Interval {
   // The lower bound of the interval. If neither of the min fields are set, then
   // the lower bound is negative infinity.
   //
-  // This field must be not larger than
-  // [max][google.cloud.retail.v2beta.Interval.max]. Otherwise, an
-  // INVALID_ARGUMENT error is returned.
+  // This field must not be larger than max.
+  // Otherwise, an INVALID_ARGUMENT error is returned.
   oneof min {
     // Inclusive lower bound.
     double minimum = 1;
@@ -504,9 +527,8 @@ message Interval {
   // The upper bound of the interval. If neither of the max fields are set, then
   // the upper bound is positive infinity.
   //
-  // This field must be not smaller than
-  // [min][google.cloud.retail.v2beta.Interval.min]. Otherwise, an
-  // INVALID_ARGUMENT error is returned.
+  // This field must be not smaller than min.
+  // Otherwise, an INVALID_ARGUMENT error is returned.
   oneof max {
     // Inclusive upper bound.
     double maximum = 3;
@@ -562,7 +584,11 @@ message PriceInfo {
   float price = 2;
 
   // Price of the product without any discount. If zero, by default set to be
-  // the [price][google.cloud.retail.v2beta.PriceInfo.price].
+  // the [price][google.cloud.retail.v2beta.PriceInfo.price]. If set,
+  // [original_price][google.cloud.retail.v2beta.PriceInfo.original_price]
+  // should be greater than or equal to
+  // [price][google.cloud.retail.v2beta.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
@@ -649,10 +675,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;