@google-cloud/discoveryengine 0.4.1 → 0.6.0

package/build/protos/google/cloud/discoveryengine/v1beta/search_service.proto

@@ -0,0 +1,546 @@
+// Copyright 2022 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.discoveryengine.v1beta;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1beta/common.proto";
+import "google/cloud/discoveryengine/v1beta/document.proto";
+import "google/protobuf/struct.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "SearchServiceProto";
+option java_package = "com.google.cloud.discoveryengine.v1beta";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";
+
+// Service for search.
+service SearchService {
+  option (google.api.default_host) = "discoveryengine.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Performs a search.
+  rpc Search(SearchRequest) returns (SearchResponse) {
+    option (google.api.http) = {
+      post: "/v1beta/{serving_config=projects/*/locations/*/dataStores/*/servingConfigs/*}:search"
+      body: "*"
+      additional_bindings {
+        post: "/v1beta/{serving_config=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:search"
+        body: "*"
+      }
+    };
+  }
+}
+
+// Request message for
+// [SearchService.Search][google.cloud.discoveryengine.v1beta.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
+      // [Document][google.cloud.discoveryengine.v1beta.Document] object, over
+      // which the facet values are computed. Facet key is case-sensitive.
+      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. Only supported on
+      // textual fields. For example, suppose "category" has three values
+      // "Action > 2022", "Action > 2021" and "Sci-Fi > 2022". If set
+      // "restricted_values" to "Action > 2022", the "category" facet will only
+      // contain "Action > 2022". Only supported on textual fields. Maximum
+      // is 10.
+      repeated string restricted_values = 3;
+
+      // Only get facet values that start with the given string prefix. For
+      // example, suppose "category" has three values "Action > 2022",
+      // "Action > 2021" and "Sci-Fi > 2022". If set "prefixes" to "Action", the
+      // "category" facet will only contain "Action > 2022" and "Action > 2021".
+      // Only supported on textual fields. Maximum is 10.
+      repeated string prefixes = 4;
+
+      // Only get facet values that contains the given strings. For example,
+      // suppose "category" has three values "Action > 2022",
+      // "Action > 2021" and "Sci-Fi > 2022". If set "contains" to "2022", the
+      // "category" facet will only contain "Action > 2022" and "Sci-Fi > 2022".
+      // Only supported on textual fields. Maximum is 10.
+      repeated string contains = 5;
+
+      // True to make facet keys case insensitive when getting faceting
+      // values with prefixes or contains; false otherwise.
+      bool case_insensitive = 6;
+
+      // The order in which documents are returned.
+      //
+      // Allowed values are:
+      //
+      // * "count desc", which means order by
+      // [SearchResponse.Facet.values.count][google.cloud.discoveryengine.v1beta.SearchResponse.Facet.FacetValue.count]
+      // descending.
+      //
+      // * "value desc", which means order by
+      // [SearchResponse.Facet.values.value][google.cloud.discoveryengine.v1beta.SearchResponse.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.discoveryengine.v1beta.SearchRequest.FacetSpec.FacetKey.intervals].
+      string order_by = 7;
+    }
+
+    // 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.discoveryengine.v1beta.SearchRequest.FacetSpec.FacetKey.key]
+    // is not excluded from the filter unless it is listed in this field.
+    //
+    // Listing a facet key in this field allows its values to appear as facet
+    // results, even when they are filtered out of search results. Using this
+    // field does not affect what search results are returned.
+    //
+    // For example, suppose there are 100 documents with the color facet "Red"
+    // and 200 documents with the color facet "Blue". A query containing the
+    // filter "color:ANY("Red")" and having "color" as
+    // [FacetKey.key][google.cloud.discoveryengine.v1beta.SearchRequest.FacetSpec.FacetKey.key]
+    // would by default return only "Red" documents in the search results, and
+    // also return "Red" with count 100 as the only color facet. Although there
+    // are also blue documents available, "Blue" would not be shown as an
+    // available facet value.
+    //
+    // If "color" is listed in "excludedFilterKeys", then the query returns the
+    // facet values "Red" with count 100 and "Blue" with count 200, because the
+    // "color" key is now excluded from the filter. Because this field doesn't
+    // affect search results, the search results are still correctly filtered to
+    // return only "Red" documents.
+    //
+    // 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 automatically.
+    // 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
+    // automatically.
+    //
+    // 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 API 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;
+  }
+
+  // Boost specification to boost certain documents.
+  message BoostSpec {
+    // Boost applies to documents 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.discoveryengine.v1beta.SearchRequest.filter]
+      // for detail syntax and limitations.
+      //
+      // Examples:
+      //
+      // * To boost documents with document ID "doc_1" or "doc_2", and
+      // color
+      //   "Red" or "Blue":
+      //     * (id: ANY("doc_1", "doc_2")) AND (color: 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 document a big promotion. However, it does not
+      // necessarily mean that the boosted document will be the top result at
+      // all times, nor that other documents 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 documents.
+      //
+      // Setting to -1.0 gives the document a big demotion. However, results
+      // that are deeply relevant might still be shown. The document 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 document 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 20.
+    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. In this case, server behavior
+      // defaults to
+      // [Condition.DISABLED][google.cloud.discoveryengine.v1beta.SearchRequest.QueryExpansionSpec.Condition.DISABLED].
+      CONDITION_UNSPECIFIED = 0;
+
+      // Disabled query expansion. Only the exact search query is used, even if
+      // [SearchResponse.total_size][google.cloud.discoveryengine.v1beta.SearchResponse.total_size]
+      // is zero.
+      DISABLED = 1;
+
+      // Automatic query expansion built by the Search API.
+      AUTO = 2;
+    }
+
+    // The condition under which query expansion should occur. Default to
+    // [Condition.DISABLED][google.cloud.discoveryengine.v1beta.SearchRequest.QueryExpansionSpec.Condition.DISABLED].
+    Condition condition = 1;
+  }
+
+  // The specification for query spell correction.
+  message SpellCorrectionSpec {
+    // Enum describing under which mode spell correction should occur.
+    enum Mode {
+      // Unspecified spell correction mode. In this case, server behavior
+      // defaults to
+      // [Mode.AUTO][google.cloud.discoveryengine.v1beta.SearchRequest.SpellCorrectionSpec.Mode.AUTO].
+      MODE_UNSPECIFIED = 0;
+
+      // Search API will try to find a spell suggestion if there
+      // is any and put in the
+      // [SearchResponse.corrected_query][google.cloud.discoveryengine.v1beta.SearchResponse.corrected_query].
+      // The spell suggestion will not be used as the search query.
+      SUGGESTION_ONLY = 1;
+
+      // Automatic spell correction built by the Search API. Search will
+      // be based on the corrected query if found.
+      AUTO = 2;
+    }
+
+    // The mode under which spell correction should take effect to
+    // replace the original search query. Default to
+    // [Mode.AUTO][google.cloud.discoveryengine.v1beta.SearchRequest.SpellCorrectionSpec.Mode.AUTO].
+    Mode mode = 1;
+  }
+
+  // The specification that configs the desired behavior of the UCS content
+  // search.
+  message ContentSearchSpec {
+    // The specification that configs the snippet in the search results.
+    message SnippetSpec {
+      // Max number of snippets returned in each search result.
+      // If the matching snippets is less than the max_snippet_count, return all
+      // of the snippets; otherwise, return the max_snippet_count.
+      //
+      // At most 5 snippets will be returned for each SearchResult.
+      int32 max_snippet_count = 1;
+
+      // if true, only snippet reference is returned.
+      bool reference_only = 2;
+    }
+
+    // The specification that configs the summary in the search response.
+    message SummarySpec {
+      // The number of top results the summary should be generated from.
+      // If the number of returned results is less than summary_result_count,
+      // then the summary would be derived from all the results; otherwise, the
+      // summary would be derived from the top results.
+      //
+      // At most 5 results can be used for generating summary.
+      int32 summary_result_count = 1;
+    }
+
+    // If there is no snippet spec provided, there will be no snippet in the
+    // search result.
+    SnippetSpec snippet_spec = 1;
+
+    // If there is no summary spec provided, there will be no summary in the
+    // search response.
+    SummarySpec summary_spec = 2;
+  }
+
+  // Required. The resource name of the Search serving config, such as
+  // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config`.
+  // This field is used to identify the serving configuration name, set
+  // of models used to make the search.
+  string serving_config = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/ServingConfig"
+    }
+  ];
+
+  // The branch resource name, such as
+  // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0`.
+  //
+  // Use `default_branch` as the branch ID or leave this field empty, to search
+  // documents under the default branch.
+  string branch = 2 [(google.api.resource_reference) = {
+    type: "discoveryengine.googleapis.com/Branch"
+  }];
+
+  // Raw search query.
+  string query = 3;
+
+  // Maximum number of [Document][google.cloud.discoveryengine.v1beta.Document]s
+  // to return. If unspecified, defaults to a reasonable value. The maximum
+  // allowed value is 100. Values above 100 will be coerced to 100.
+  //
+  // If this field is negative, an  `INVALID_ARGUMENT`  is returned.
+  int32 page_size = 4;
+
+  // A page token received from a previous
+  // [SearchService.Search][google.cloud.discoveryengine.v1beta.SearchService.Search]
+  // call. Provide this to retrieve the subsequent page.
+  //
+  // When paginating, all other parameters provided to
+  // [SearchService.Search][google.cloud.discoveryengine.v1beta.SearchService.Search]
+  // must match the call that provided the page token. Otherwise, an
+  //  `INVALID_ARGUMENT`  error is returned.
+  string page_token = 5;
+
+  // A 0-indexed integer that specifies the current offset (that is, starting
+  // result location, amongst the
+  // [Document][google.cloud.discoveryengine.v1beta.Document]s deemed by the API
+  // as relevant) in search results. This field is only considered if
+  // [page_token][google.cloud.discoveryengine.v1beta.SearchRequest.page_token]
+  // is unset.
+  //
+  // If this field is negative, an  `INVALID_ARGUMENT`  is returned.
+  int32 offset = 6;
+
+  // The filter syntax consists of an expression language for constructing a
+  // predicate from one or more fields of the documents being filtered. Filter
+  // expression is case-sensitive.
+  //
+  // If this field is unrecognizable, an  `INVALID_ARGUMENT`  is returned.
+  string filter = 7;
+
+  // The order in which documents are returned. Document can be ordered by
+  // a field in an [Document][google.cloud.discoveryengine.v1beta.Document]
+  // 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 = 8;
+
+  // 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 = 9;
+
+  // Boost specification to boost certain documents.
+  BoostSpec boost_spec = 10;
+
+  // Additional search parameters.
+  //
+  // For
+  // [IndustryVertical.SITE_SEARCH][google.cloud.discoveryengine.v1beta.IndustryVertical.SITE_SEARCH]
+  // vertical, supported values are:
+  //
+  // * `user_country_code`: string. Default empty. If set to non-empty, results
+  //    are restricted or boosted based on the location provided.
+  // * `search_type`: double. Default empty. Enables non-webpage searching
+  //   depending on the value. The only valid non-default value is 1,
+  //   which enables image searching.
+  // This field is ignored for other verticals.
+  map<string, google.protobuf.Value> params = 11;
+
+  // The query expansion specification that specifies the conditions under which
+  // query expansion will occur.
+  QueryExpansionSpec query_expansion_spec = 13;
+
+  // The spell correction specification that specifies the mode under
+  // which spell correction will take effect.
+  SpellCorrectionSpec spell_correction_spec = 14;
+
+  // 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.
+  //
+  // This field should NOT have a fixed value such as `unknown_visitor`.
+  //
+  // This should be the same identifier as
+  // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id]
+  // and
+  // [CompleteQueryRequest.user_pseudo_id][google.cloud.discoveryengine.v1beta.CompleteQueryRequest.user_pseudo_id]
+  //
+  // 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_pseudo_id = 15;
+
+  // The content search spec that configs the desired behavior of content
+  // search.
+  ContentSearchSpec content_search_spec = 24;
+}
+
+// Response message for
+// [SearchService.Search][google.cloud.discoveryengine.v1beta.SearchService.Search]
+// method.
+message SearchResponse {
+  // Represents the search results.
+  message SearchResult {
+    // [Document.id][google.cloud.discoveryengine.v1beta.Document.id] of the
+    // searched [Document][google.cloud.discoveryengine.v1beta.Document].
+    string id = 1;
+
+    // The document data snippet in the search response. Only fields that are
+    // marked as retrievable are populated.
+    Document document = 2;
+  }
+
+  // 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 "colors".
+        string value = 1;
+
+        // Interval value for a facet, such as [10, 20) for facet "price". It
+        // matches
+        // [SearchRequest.FacetSpec.FacetKey.intervals][google.cloud.discoveryengine.v1beta.SearchRequest.FacetSpec.FacetKey.intervals].
+        Interval interval = 2;
+      }
+
+      // Number of items that have this facet value.
+      int64 count = 3;
+    }
+
+    // The key for this facet. E.g., "colors" or "price". It matches
+    // [SearchRequest.FacetSpec.FacetKey.key][google.cloud.discoveryengine.v1beta.SearchRequest.FacetSpec.FacetKey.key].
+    string key = 1;
+
+    // The facet values for this field.
+    repeated FacetValue values = 2;
+
+    // Whether the facet is dynamically generated.
+    bool dynamic_facet = 3;
+  }
+
+  // Guided search result. The guided search helps user to refine the search
+  // results and narrow down to the real needs from a broaded search results.
+  message GuidedSearchResult {
+    // Useful attribute for search result refinements.
+    message RefinementAttribute {
+      // Attribute key used to refine the results e.g. 'movie_type'.
+      string attribute_key = 1;
+
+      // Attribute value used to refine the results e.g. 'drama'.
+      string attribute_value = 2;
+    }
+
+    // A list of ranked refinement attributes.
+    repeated RefinementAttribute refinement_attributes = 1;
+  }
+
+  // Summary of the top N search result specified by the summary spec.
+  message Summary {
+    // The summary content.
+    string summary_text = 1;
+  }
+
+  // A list of matched documents. The order represents the ranking.
+  repeated SearchResult results = 1;
+
+  // Results of facets requested by user.
+  repeated Facet facets = 2;
+
+  // Guided search result.
+  GuidedSearchResult guided_search_result = 8;
+
+  // The estimated total count of matched items irrespective of pagination. The
+  // count of
+  // [results][google.cloud.discoveryengine.v1beta.SearchResponse.results]
+  // returned by pagination may be less than the
+  // [total_size][google.cloud.discoveryengine.v1beta.SearchResponse.total_size]
+  // that matches.
+  int32 total_size = 3;
+
+  // A unique search token. This should be included in the
+  // [UserEvent][google.cloud.discoveryengine.v1beta.UserEvent] logs resulting
+  // from this search, which enables accurate attribution of search model
+  // performance.
+  string attribution_token = 4;
+
+  // A token that can be sent as
+  // [SearchRequest.page_token][google.cloud.discoveryengine.v1beta.SearchRequest.page_token]
+  // to retrieve the next page. If this field is omitted, there are no
+  // subsequent pages.
+  string next_page_token = 5;
+
+  // Contains the spell corrected query, if found. If the spell correction type
+  // is AUTOMATIC, then the search results are based on corrected_query.
+  // Otherwise the original query is used for search.
+  string corrected_query = 7;
+
+  // A summary as part of the search results.
+  // This field is only returned if
+  // [SearchRequest.ContentSearchSpec.summary_spec][google.cloud.discoveryengine.v1beta.SearchRequest.ContentSearchSpec.summary_spec]
+  // is set.
+  Summary summary = 9;
+
+  // Controls applied as part of the Control service.
+  repeated string applied_controls = 10;
+}

package/build/protos/google/cloud/discoveryengine/v1beta/user_event.proto

@@ -114,17 +114,19 @@ message UserEvent {
   // Token to attribute an API response to user action(s) to trigger the event.
   //
   // Highly recommended for user events that are the result of
-  // [PredictionService.Predict][]. This field enables accurate attribution of
-  // recommendation model performance.
+  // [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend].
+  // This field enables accurate attribution of recommendation model
+  // performance.
   //
   // The value must be one of:
   //
   // * [PredictResponse.attribution_token][] for events that are the result of
-  // [PredictionService.Predict][].
+  // [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend].
   // * [SearchResponse.attribution_token][google.cloud.discoveryengine.v1beta.SearchResponse.attribution_token] for events that are the result of
-  // [SearchService.Search][].
+  // [SearchService.Search][google.cloud.discoveryengine.v1beta.SearchService.Search].
   // * [CompleteQueryResponse.attribution_token][] for events that are the
-  // result of [SearchService.CompleteQuery][].
+  // result of
+  // [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1beta.CompletionService.CompleteQuery].
   //
   // This token enables us to accurately attribute page view or conversion
   // completion back to the event and the particular predict response containing
@@ -138,14 +140,15 @@ message UserEvent {
   // predicate from one or more fields of the documents being filtered.
   //
   // One example is for `search` events, the associated
-  // [SearchService.SearchRequest][] may contain a filter expression in
-  // [SearchService.SearchRequest.filter][] conforming to
-  // https://google.aip.dev/160#filtering.
+  // [SearchRequest][google.cloud.discoveryengine.v1beta.SearchRequest] may
+  // contain a filter expression in
+  // [SearchRequest.filter][google.cloud.discoveryengine.v1beta.SearchRequest.filter]
+  // conforming to https://google.aip.dev/160#filtering.
   //
   // Similarly, for `view-item-list` events that are generated from a
-  // [PredictionService.PredictRequest][], this field may be populated directly
-  // from [PredictionService.PredictRequest.filter][] conforming to
-  // https://google.aip.dev/160#filtering.
+  // [RecommendationService.RecommendRequest][], this field may be populated
+  // directly from [RecommendationService.RecommendRequest.filter][] conforming
+  // to https://google.aip.dev/160#filtering.
   //
   // The value must be a UTF-8 encoded string with a length limit of 1,000
   // characters. Otherwise, an INVALID_ARGUMENT error is returned.
@@ -207,8 +210,8 @@ message UserEvent {
   // those custom attributes when training models and serving predictions, which
   // helps improve recommendation quality.
   //
-  // This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT
-  // error is returned:
+  // This field needs to pass all below criteria, otherwise an
+  // `INVALID_ARGUMENT` error is returned:
   //
   // * The key must be a UTF-8 encoded string with a length limit of 5,000
   //   characters.
@@ -218,7 +221,8 @@ message UserEvent {
   // * For number attributes, at most 400 values are allowed.
   //
   // For product recommendations, an example of extra user information is
-  // traffic_channel, which is how a user arrives at the site. Users can arrive
+  // ` traffic_channel`, which is how a user arrives at the site. Users can
+  // arrive
   // at the site by coming to the site directly, coming through Google
   // search, or in other ways.
   map<string, CustomAttribute> attributes = 17;
@@ -283,9 +287,10 @@ message SearchInfo {
   //
   // At least one of
   // [search_query][google.cloud.discoveryengine.v1beta.SearchInfo.search_query]
-  // or [page_categories][] is required for `search` events. Other event types
-  // should not set this field. Otherwise, an INVALID_ARGUMENT error is
-  // returned.
+  // or
+  // [PageInfo.page_category][google.cloud.discoveryengine.v1beta.PageInfo.page_category]
+  // is required for `search` events. Other event types should not set this
+  // field. Otherwise, an INVALID_ARGUMENT error is returned.
   string search_query = 1;
 
   // The order in which products are returned, if applicable.
@@ -378,23 +383,24 @@ message TransactionInfo {
 
 // Detailed document information associated with a user event.
 message DocumentInfo {
-  // A required descriptor of the associated Document.
+  // A required descriptor of the associated
+  // [Document][google.cloud.discoveryengine.v1beta.Document].
   //
   // * If [id][google.cloud.discoveryengine.v1beta.DocumentInfo.id] is
-  // specified, then the default values for {location}, {collection_id},
-  // {data_store_id}, and {branch_id} are used when annotating with the stored
-  // Document.
+  // specified, then the default values for
+  // `{location}`, `{collection_id}`, `{data_store_id}`, and `{branch_id}` are
+  // used when annotating with the stored Document.
   //
   // * If [name][google.cloud.discoveryengine.v1beta.DocumentInfo.name] is
   // specified, then the provided values (default values allowed) for
-  // {location}, {collection_id}, {data_store_id}, and {branch_id} are used when
-  // annotating with the stored Document.
+  // `{location}`, `{collection_id}`, `{data_store_id}`, and
+  // `{branch_id}` are used when annotating with the stored Document.
   oneof document_descriptor {
     // Required. The Document resource ID.
     string id = 1 [(google.api.field_behavior) = REQUIRED];
 
     // Required. The Document resource full name, of the form:
-    // projects/{project\_id}/locations/{location}/collections/{collection\_id}/dataStores/{data\_store\_id}/branches/{branch\_id}/documents/{document\_id}
+    // `projects/{project_id}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}/branches/{branch_id}/documents/{document_id}`
     string name = 2 [
       (google.api.field_behavior) = REQUIRED,
       (google.api.resource_reference) = {
@@ -451,7 +457,7 @@ message MediaInfo {
   // Media progress should be computed using only the media_progress_duration
   // relative to the media total length.
   //
-  // This value must be between [0, 1.0] inclusive.
+  // This value must be between `[0, 1.0]` inclusive.
   //
   // If this is not a playback or the progress cannot be computed (e.g. ongoing
   // livestream), this field should be unset.