search_service.proto

// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.retail.v2alpha;

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/product.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

option csharp_namespace = "Google.Cloud.Retail.V2Alpha";
option go_package = "google.golang.org/genproto/googleapis/cloud/retail/v2alpha;retail";
option java_multiple_files = true;
option java_outer_classname = "SearchServiceProto";
option java_package = "com.google.cloud.retail.v2alpha";
option objc_class_prefix = "RETAIL";
option php_namespace = "Google\\Cloud\\Retail\\V2alpha";
option ruby_package = "Google::Cloud::Retail::V2alpha";

// Service for search.
//
// This feature is only available for users who have Retail Search enabled.
// Contact Retail Support (retail-search-support@google.com) if you are
// interested in using Retail Search.
service SearchService {
  option (google.api.default_host) = "retail.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Performs a search.
  //
  // This feature is only available for users who have Retail Search enabled.
  // Contact Retail Support (retail-search-support@google.com) if you are
  // interested in using Retail Search.
  rpc Search(SearchRequest) returns (SearchResponse) {
    option (google.api.http) = {
      post: "/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:search"
      body: "*"
    };
  }
}

// Request message for
// [SearchService.Search][google.cloud.retail.v2alpha.SearchService.Search]
// method.
message SearchRequest {
  // A facet specification to perform faceted search.
  message FacetSpec {
    // Specifies how a facet is computed.
    message FacetKey {
      // Required. Supported textual and numerical facet keys in
      // [Product][google.cloud.retail.v2alpha.Product] object, over which the
      // facet values are computed. Facet key is case-sensitive.
      //
      // Allowed facet keys when
      // [FacetKey.query][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.query]
      // is not specified:
      //
      // Textual facet keys:
      // * brands
      // * categories
      // * genders
      // * ageGroups
      // * availability
      // * colorFamilies
      // * colors
      // * sizes
      // * materials
      // * patterns
      // * conditions
      // * attributes.key
      // * pickupInStore
      // * shipToStore
      // * sameDayDelivery
      // * nextDayDelivery
      // * customFulfillment1
      // * customFulfillment2
      // * customFulfillment3
      // * customFulfillment4
      // * customFulfillment5
      //
      // Numeric facet keys:
      // * price
      // * discount
      // * rating
      // * ratingCount
      // * attributes.key
      string key = 1 [(google.api.field_behavior) = REQUIRED];

      // Set only if values should be bucketized into intervals. Must be set
      // for facets with numerical values. Must not be set for facet with text
      // values. Maximum number of intervals is 30.
      repeated Interval intervals = 2;

      // Only get facet for the given restricted values. For example, when using
      // "pickupInStore" as key and set restricted values to
      // ["store123", "store456"], only facets for "store123" and "store456" are
      // returned. Only supported on textual fields and fulfillments.
      // Maximum is 20.
      //
      // Must be set for the fulfillment facet keys:
      //
      // * pickupInStore
      //
      // * shipToStore
      //
      // * sameDayDelivery
      //
      // * nextDayDelivery
      //
      // * customFulfillment1
      //
      // * customFulfillment2
      //
      // * customFulfillment3
      //
      // * customFulfillment4
      //
      // * customFulfillment5
      repeated string restricted_values = 3;

      // Only get facet values that start with the given string prefix. For
      // example, suppose "categories" has three values "Women > Shoe",
      // "Women > Dress" and "Men > Shoe". If set "prefixes" to "Women", the
      // "categories" facet will give only "Women > Shoe" and "Women > Dress".
      // Only supported on textual fields. Maximum is 10.
      repeated string prefixes = 8;

      // Only get facet values that contains the given strings. For example,
      // suppose "categories" has three values "Women > Shoe",
      // "Women > Dress" and "Men > Shoe". If set "contains" to "Shoe", the
      // "categories" facet will give only "Women > Shoe" and "Men > Shoe".
      // Only supported on textual fields. Maximum is 10.
      repeated string contains = 9;

      // The order in which [Facet.values][] are returned.
      //
      // Allowed values are:
      //
      // * "count desc", which means order by [Facet.FacetValue.count][]
      // descending.
      //
      // * "value desc", which means order by [Facet.FacetValue.value][]
      // descending.
      //   Only applies to textual facets.
      //
      // If not set, textual values are sorted in [natural
      // order](https://en.wikipedia.org/wiki/Natural_sort_order); numerical
      // intervals are sorted in the order given by
      // [FacetSpec.FacetKey.intervals][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.intervals];
      // [FulfillmentInfo.ids][] are sorted in the order given by
      // [FacetSpec.FacetKey.restricted_values][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.restricted_values].
      string order_by = 4;

      // The query that is used to compute facet for the given facet key.
      // When provided, it will override the default behavior of facet
      // computation. The query syntax is the same as a filter expression. See
      // [SearchRequest.filter][google.cloud.retail.v2alpha.SearchRequest.filter]
      // for detail syntax and limitations. Notice that there is no limitation
      // on
      // [FacetKey.key][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.key]
      // when query is specified.
      //
      // In the response, [FacetValue.value][] will be always "1" and
      // [FacetValue.count][] will be the number of results that matches the
      // query.
      //
      // For example, you can set a customized facet for "shipToStore",
      // where
      // [FacetKey.key][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.key]
      // is "customizedShipToStore", and
      // [FacetKey.query][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.query]
      // is "availability: ANY(\"IN_STOCK\") AND shipToStore: ANY(\"123\")".
      // Then the facet will count the products that are both in stock and ship
      // to store "123".
      string query = 5;
    }

    // Required. The facet key specification.
    FacetKey facet_key = 1 [(google.api.field_behavior) = REQUIRED];

    // Maximum of facet values that should be returned for this facet. If
    // unspecified, defaults to 20. The maximum allowed value is 300. Values
    // above 300 will be coerced to 300.
    //
    // If this field is negative, an INVALID_ARGUMENT is returned.
    int32 limit = 2;

    // List of keys to exclude when faceting.
    //
    // By default,
    // [FacetKey.key][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.key]
    // is not excluded from the filter unless it is listed in this field.
    //
    // For example, suppose there are 100 products with color facet "Red" and
    // 200 products with color facet "Blue". A query containing the filter
    // "colorFamilies:ANY("Red")" and have "colorFamilies" as
    // [FacetKey.key][google.cloud.retail.v2alpha.SearchRequest.FacetSpec.FacetKey.key]
    // will by default return the "Red" with count 100.
    //
    // If this field contains "colorFamilies", then the query returns both the
    // "Red" with count 100 and "Blue" with count 200, because the
    // "colorFamilies" key is now excluded from the filter.
    //
    // A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error
    // is returned.
    repeated string excluded_filter_keys = 3;

    // Enables dynamic position for this facet. If set to true, the position of
    // this facet among all facets in the response is determined by Google
    // Retail Search. It will be ordered together with dynamic facets if dynamic
    // facets is enabled. If set to false, the position of this facet in the
    // response will be the same as in the request, and it will be ranked before
    // the facets with dynamic position enable and all dynamic facets.
    //
    // For example, you may always want to have rating facet returned in
    // the response, but it's not necessarily to always display the rating facet
    // at the top. In that case, you can set enable_dynamic_position to true so
    // that the position of rating facet in response will be determined by
    // Google Retail Search.
    //
    // Another example, assuming you have the following facets in the request:
    //
    // * "rating", enable_dynamic_position = true
    //
    // * "price", enable_dynamic_position = false
    //
    // * "brands", enable_dynamic_position = false
    //
    // And also you have a dynamic facets enable, which will generate a facet
    // 'gender'. Then the final order of the facets in the response can be
    // ("price", "brands", "rating", "gender") or ("price", "brands", "gender",
    // "rating") depends on how Google Retail Search orders "gender" and
    // "rating" facets. However, notice that "price" and "brands" will always be
    // ranked at 1st and 2nd position since their enable_dynamic_position are
    // false.
    bool enable_dynamic_position = 4;
  }

  // The specifications of dynamically generated facets.
  message DynamicFacetSpec {
    // Enum to control DynamicFacet mode
    enum Mode {
      // Default value.
      MODE_UNSPECIFIED = 0;

      // Disable Dynamic Facet.
      DISABLED = 1;

      // Automatic mode built by Google Retail Search.
      ENABLED = 2;
    }

    // Mode of the DynamicFacet feature.
    // Defaults to
    // [Mode.DISABLED][google.cloud.retail.v2alpha.SearchRequest.DynamicFacetSpec.Mode.DISABLED]
    // if it's unset.
    Mode mode = 1;
  }

  // Boost specification to boost certain items.
  message BoostSpec {
    // Boost applies to products which match a condition.
    message ConditionBoostSpec {
      // An expression which specifies a boost condition. The syntax and
      // supported fields are the same as a filter expression. See
      // [SearchRequest.filter][google.cloud.retail.v2alpha.SearchRequest.filter]
      // for detail syntax and limitations.
      //
      // Examples:
      //
      // * To boost products with product ID "product_1" or "product_2", and
      // color "Red" or "Blue":
      //   ```
      //   (id: ANY("product_1", "product_2"))
      //   AND
      //   (colorFamilies: ANY("Red", "Blue"))
      //   ```
      string condition = 1;

      // Strength of the condition boost, which should be in [-1, 1]. Negative
      // boost means demotion. Default is 0.0.
      //
      // Setting to 1.0 gives the item a big promotion. However, it does not
      // necessarily mean that the boosted item will be the top result at all
      // times, nor that other items will be excluded. Results could still be
      // shown even when none of them matches the condition. And results that
      // are significantly more relevant to the search query can still trump
      // your heavily favored but irrelevant items.
      //
      // Setting to -1.0 gives the item a big demotion. However, results that
      // are deeply relevant might still be shown. The item will have an
      // upstream battle to get a fairly high ranking, but it is not blocked out
      // completely.
      //
      // Setting to 0.0 means no boost applied. The boosting condition is
      // ignored.
      float boost = 2;
    }

    // Condition boost specifications. If a product matches multiple conditions
    // in the specifictions, boost scores from these specifications are all
    // applied and combined in a non-linear way. Maximum number of
    // specifications is 10.
    repeated ConditionBoostSpec condition_boost_specs = 1;
  }

  // Specification to determine under which conditions query expansion should
  // occur.
  message QueryExpansionSpec {
    // Enum describing under which condition query expansion should occur.
    enum Condition {
      // Unspecified query expansion condition. This defaults to
      // [Condition.DISABLED][google.cloud.retail.v2alpha.SearchRequest.QueryExpansionSpec.Condition.DISABLED].
      CONDITION_UNSPECIFIED = 0;

      // Disabled query expansion. Only the exact search query is used, even if
      // [SearchResponse.total_size][google.cloud.retail.v2alpha.SearchResponse.total_size]
      // is zero.
      DISABLED = 1;

      // Automatic query expansion built by Google Retail Search.
      AUTO = 3;
    }

    // The condition under which query expansion should occur. Default to
    // [Condition.DISABLED][google.cloud.retail.v2alpha.SearchRequest.QueryExpansionSpec.Condition.DISABLED].
    Condition condition = 1;
  }

  // The relevance threshold of the search results. The higher relevance
  // threshold is, the higher relevant results are shown and the less number of
  // results are returned.
  enum RelevanceThreshold {
    // Default value. Defaults to
    // [RelevanceThreshold.HIGH][google.cloud.retail.v2alpha.SearchRequest.RelevanceThreshold.HIGH].
    RELEVANCE_THRESHOLD_UNSPECIFIED = 0;

    // High relevance threshold.
    HIGH = 1;

    // Medium relevance threshold.
    MEDIUM = 2;

    // Low relevance threshold.
    LOW = 3;

    // Lowest relevance threshold.
    LOWEST = 4;
  }

  // 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`.
  string placement = 1 [(google.api.field_behavior) = REQUIRED];

  // The branch resource name, such as
  // `projects/*/locations/global/catalogs/default_catalog/branches/0`.
  //
  // Use "default_branch" as the branch ID or leave this field empty, to search
  // products under the default branch.
  string branch = 2 [
    (google.api.resource_reference) = { type: "retail.googleapis.com/Branch" }
  ];

  // Raw search query.
  string query = 3;

  // Required. A unique identifier for tracking visitors. For example, this
  // could be implemented with an HTTP cookie, which should be able to uniquely
  // identify a visitor on a single device. This unique identifier should not
  // change if the visitor logs in or out of the website.
  //
  // The field must be a UTF-8 encoded string with a length limit of 128
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  string visitor_id = 4 [(google.api.field_behavior) = REQUIRED];

  // User information.
  UserInfo user_info = 5;

  // Maximum number of [Product][google.cloud.retail.v2alpha.Product]s to
  // return. If unspecified, defaults to a reasonable value. The maximum allowed
  // value is 120. Values above 120 will be coerced to 120.
  //
  // If this field is negative, an INVALID_ARGUMENT is returned.
  int32 page_size = 7;

  // A page token
  // [SearchResponse.next_page_token][google.cloud.retail.v2alpha.SearchResponse.next_page_token],
  // received from a previous
  // [SearchService.Search][google.cloud.retail.v2alpha.SearchService.Search]
  // call. Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to
  // [SearchService.Search][google.cloud.retail.v2alpha.SearchService.Search]
  // must match the call that provided the page token. Otherwise, an
  // INVALID_ARGUMENT error is returned.
  string page_token = 8;

  // A 0-indexed integer that specifies the current offset (that is, starting
  // result location, amongst the
  // [Product][google.cloud.retail.v2alpha.Product]s deemed by the API as
  // relevant) in search results. This field is only considered if
  // [page_token][google.cloud.retail.v2alpha.SearchRequest.page_token] is
  // unset.
  //
  // If this field is negative, an INVALID_ARGUMENT is returned.
  int32 offset = 9;

  // 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.
  //
  // If this field is unrecognizable, an INVALID_ARGUMENT is returned.
  string filter = 10;

  // The filter applied to every search request when quality improvement such as
  // query expansion is needed. For example, if a query does not have enough
  // results, an expanded query with
  // [SearchRequest.canonical_filter][google.cloud.retail.v2alpha.SearchRequest.canonical_filter]
  // will be returned as a supplement of the original query. This field is
  // strongly recommended to achieve high search quality.
  //
  // See
  // [SearchRequest.filter][google.cloud.retail.v2alpha.SearchRequest.filter]
  // for more details about filter syntax.
  string canonical_filter = 28;

  // The order in which products are returned. Products can be ordered by
  // a field in an [Product][google.cloud.retail.v2alpha.Product] object. Leave
  // it unset if ordered by relevance. OrderBy expression is case-sensitive.
  //
  // If this field is unrecognizable, an INVALID_ARGUMENT is returned.
  string order_by = 11;

  // Facet specifications for faceted search. If empty, no facets are returned.
  //
  // A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error
  // is returned.
  repeated FacetSpec facet_specs = 12;

  // The specification for dynamically generated facets. Notice that only
  // textual facets can be dynamically generated.
  //
  // This feature requires additional allowlisting. Contact Retail Support
  // (retail-search-support@google.com) if you are interested in using dynamic
  // facet feature.
  DynamicFacetSpec dynamic_facet_spec = 21;

  // Boost specification to boost certain products.
  BoostSpec boost_spec = 13;

  // The query expansion specification that specifies the conditions under which
  // query expansion will occur.
  QueryExpansionSpec query_expansion_spec = 14;

  // The relevance threshold of the search results.
  //
  // Defaults to
  // [RelevanceThreshold.HIGH][google.cloud.retail.v2alpha.SearchRequest.RelevanceThreshold.HIGH],
  // which means only the most relevant results are shown, and the least number
  // of results are returned.
  RelevanceThreshold relevance_threshold = 15;

  // The keys to fetch and rollup the matching
  // [variant][google.cloud.retail.v2alpha.Product.Type.VARIANT]
  // [Product][google.cloud.retail.v2alpha.Product]s attributes. The attributes
  // from all the matching
  // [variant][google.cloud.retail.v2alpha.Product.Type.VARIANT]
  // [Product][google.cloud.retail.v2alpha.Product]s are merged and
  // de-duplicated. Notice that rollup
  // [variant][google.cloud.retail.v2alpha.Product.Type.VARIANT]
  // [Product][google.cloud.retail.v2alpha.Product]s attributes will lead to
  // extra query latency. Maximum number of keys is 10.
  //
  // For
  // [Product.fulfillment_info][google.cloud.retail.v2alpha.Product.fulfillment_info],
  // a fulfillment type and a fulfillment ID must be provided in the format of
  // "fulfillmentType.filfillmentId". E.g., in "pickupInStore.store123",
  // "pickupInStore" is fulfillment type and "store123" is the store ID.
  //
  // Supported keys are:
  //
  // * colorFamilies
  // * price
  // * originalPrice
  // * discount
  // * attributes.key, where key is any key in the
  //   [Product.attributes][google.cloud.retail.v2alpha.Product.attributes] map.
  // * pickupInStore.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.PICKUP_IN_STORE][].
  // * shipToStore.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.SHIP_TO_STORE][].
  // * sameDayDelivery.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.SAME_DAY_DELIVERY][].
  // * nextDayDelivery.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.NEXT_DAY_DELIVERY][].
  // * customFulfillment1.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.CUSTOM_TYPE_1][].
  // * customFulfillment2.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.CUSTOM_TYPE_2][].
  // * customFulfillment3.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.CUSTOM_TYPE_3][].
  // * customFulfillment4.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.CUSTOM_TYPE_4][].
  // * customFulfillment5.id, where id is any [FulfillmentInfo.ids][] for type
  //   [FulfillmentInfo.Type.CUSTOM_TYPE_5][].
  //
  // If this field is set to an invalid value other than these, an
  // INVALID_ARGUMENT error is returned.
  repeated string variant_rollup_keys = 17;

  // The categories associated with a category page. Required for category
  // navigation queries to achieve good search quality. The format should be
  // the same as
  // [UserEvent.page_categories][google.cloud.retail.v2alpha.UserEvent.page_categories];
  //
  // To represent full path of category, use '>' sign to separate different
  // hierarchies. If '>' is part of the category name, please replace it with
  // other character(s).
  //
  // Category pages include special pages such as sales or promotions. For
  // instance, a special sale page may have the category hierarchy:
  // "pageCategories" : ["Sales > 2017 Black Friday Deals"].
  repeated string page_categories = 23;
}

// Response message for
// [SearchService.Search][google.cloud.retail.v2alpha.SearchService.Search]
// method.
message SearchResponse {
  // Represents the search results.
  message SearchResult {
    // [Product.id][google.cloud.retail.v2alpha.Product.id] of the searched
    // [Product][google.cloud.retail.v2alpha.Product].
    string id = 1;

    // The product data snippet in the search response. Only
    // [Product.name][google.cloud.retail.v2alpha.Product.name] is guaranteed to
    // be populated.
    //
    // [Product.variants][google.cloud.retail.v2alpha.Product.variants] contains
    // the product variants that match the search query. If there are multiple
    // product variants matching the query, top 5 most relevant product variants
    // are returned and ordered by relevancy.
    //
    // If relevancy can be deternmined, use
    // [matching_variant_fields][google.cloud.retail.v2alpha.SearchResponse.SearchResult.matching_variant_fields]
    // to look up matched product variants fields. If relevancy cannot be
    // determined, e.g. when searching "shoe" all products in a shoe product can
    // be a match, 5 product variants are returned but order is meaningless.
    Product product = 2;

    // The count of matched
    // [variant][google.cloud.retail.v2alpha.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2alpha.Product]s.
    int32 matching_variant_count = 3;

    // If a [variant][google.cloud.retail.v2alpha.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2alpha.Product] matches the search query,
    // this map indicates which [Product][google.cloud.retail.v2alpha.Product]
    // fields are matched. The key is the
    // [Product.name][google.cloud.retail.v2alpha.Product.name], the value is a
    // field mask of the matched [Product][google.cloud.retail.v2alpha.Product]
    // fields. If matched attributes cannot be determined, this map will be
    // empty.
    //
    // For example, a key "sku1" with field mask
    // "products.color_info" indicates there is a match between
    // "sku1" [ColorInfo][google.cloud.retail.v2alpha.ColorInfo] and the query.
    map<string, google.protobuf.FieldMask> matching_variant_fields = 4;

    // The rollup matching
    // [variant][google.cloud.retail.v2alpha.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2alpha.Product] attributes. The key is one
    // of the
    // [SearchRequest.variant_rollup_keys][google.cloud.retail.v2alpha.SearchRequest.variant_rollup_keys].
    // The values are the merged and de-duplicated
    // [Product][google.cloud.retail.v2alpha.Product] attributes. Notice that
    // the rollup values are respect filter. For example, when filtering by
    // "colorFamilies:ANY(\"red\")" and rollup "colorFamilies", only "red" is
    // returned.
    //
    // For textual and numerical attributes, the rollup values is a list of
    // string or double values with type
    // [google.protobuf.ListValue][google.protobuf.ListValue]. For example, if
    // there are two variants with colors "red" and "blue", the rollup values
    // are
    //
    //     { key: "colorFamilies"
    //       value {
    //         list_value {
    //           values { string_value: "red" }
    //           values { string_value: "blue" }
    //          }
    //       }
    //     }
    //
    // For
    // [Product.fulfillment_info][google.cloud.retail.v2alpha.Product.fulfillment_info],
    // the rollup values is a double value with type
    // [google.protobuf.Value][google.protobuf.Value]. For example,
    // `{key: "pickupInStore.store1" value { number_value: 10 }}` means a there
    // are 10 variants in this product are available in the store "store1".
    map<string, google.protobuf.Value> variant_rollup_values = 5;
  }

  // A facet result.
  message Facet {
    // A facet value which contains value names and their count.
    message FacetValue {
      // A facet value which contains values.
      oneof facet_value {
        // Text value of a facet, such as "Black" for facet "colorFamilies".
        string value = 1;

        // Interval value for a facet, such as [10, 20) for facet "price".
        Interval interval = 2;
      }

      // Number of items that have this facet value.
      int64 count = 3;
    }

    // The key for this facet. E.g., "colorFamilies" or "price" or
    // "attributes.attr1".
    string key = 1;

    // The facet values for this field.
    repeated FacetValue values = 2;

    // Whether the facet is dynamically generated.
    bool dynamic_facet = 3;
  }

  // Information describing query expansion including whether expansion has
  // occurred.
  message QueryExpansionInfo {
    // Bool describing whether query expansion has occurred.
    bool expanded_query = 1;
  }

  // A list of matched items. The order represents the ranking.
  repeated SearchResult results = 1;

  // Results of facets requested by user.
  repeated Facet facets = 2;

  // The estimated total count of matched items irrespective of pagination. The
  // count of [results][google.cloud.retail.v2alpha.SearchResponse.results]
  // returned by pagination may be less than the
  // [total_size][google.cloud.retail.v2alpha.SearchResponse.total_size] that
  // matches.
  int32 total_size = 3;

  // If spell correction applies, the corrected query. Otherwise, empty.
  string corrected_query = 4;

  // A unique search token. This should be included in the
  // [UserEvent][google.cloud.retail.v2alpha.UserEvent] logs resulting from this
  // search, which enables accurate attribution of search model performance.
  string attribution_token = 5;

  // A token that can be sent as
  // [SearchRequest.page_token][google.cloud.retail.v2alpha.SearchRequest.page_token]
  // to retrieve the next page. If this field is omitted, there are no
  // subsequent pages.
  string next_page_token = 6;

  // Query expansion information for the returned results.
  QueryExpansionInfo query_expansion_info = 7;

  // The URI of a customer-defined redirect page. If redirect action is
  // triggered, no search will be performed, and only
  // [redirect_uri][google.cloud.retail.v2alpha.SearchResponse.redirect_uri] and
  // [attribution_token][google.cloud.retail.v2alpha.SearchResponse.attribution_token]
  // will be set in the response.
  string redirect_uri = 10;
}