@google-cloud/discoveryengine 0.6.0 → 0.7.0

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

@@ -0,0 +1,289 @@
+// 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.v1;
+
+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/v1/common.proto";
+import "google/cloud/discoveryengine/v1/document.proto";
+import "google/protobuf/struct.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "SearchServiceProto";
+option java_package = "com.google.cloud.discoveryengine.v1";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1";
+
+// 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: "/v1/{serving_config=projects/*/locations/*/dataStores/*/servingConfigs/*}:search"
+      body: "*"
+      additional_bindings {
+        post: "/v1/{serving_config=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:search"
+        body: "*"
+      }
+    };
+  }
+}
+
+// Request message for
+// [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search]
+// method.
+message SearchRequest {
+  // 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.v1.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.v1.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.v1.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.v1.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.v1.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.v1.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;
+    }
+
+    // If there is no snippet spec provided, there will be no snippet in the
+    // search result.
+    SnippetSpec snippet_spec = 1;
+  }
+
+  // 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.v1.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.v1.SearchService.Search]
+  // call. Provide this to retrieve the subsequent page.
+  //
+  // When paginating, all other parameters provided to
+  // [SearchService.Search][google.cloud.discoveryengine.v1.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.v1.Document]s deemed by the API as
+  // relevant) in search results. This field is only considered if
+  // [page_token][google.cloud.discoveryengine.v1.SearchRequest.page_token] is
+  // unset.
+  //
+  // If this field is negative, an  `INVALID_ARGUMENT`  is returned.
+  int32 offset = 6;
+
+  // Information about the end user.
+  // Highly recommended for analytics. The user_agent string in UserInfo will
+  // be used to deduce device_type for analytics.
+  UserInfo user_info = 21;
+
+  // Additional search parameters.
+  //
+  // For public website search only, 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.
+  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.v1.UserEvent.user_pseudo_id]
+  // and
+  // [CompleteQueryRequest.user_pseudo_id][google.cloud.discoveryengine.v1.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;
+
+  // Whether to turn on safe search. This is only supported for
+  // [ContentConfig.PUBLIC_WEBSITE][].
+  bool safe_search = 20;
+
+  // The user labels applied to a resource must meet the following requirements:
+  //
+  // * 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
+  //   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
+  //   international characters are allowed.
+  // * The key portion of a label must be unique. However, you can use the same
+  //   key with multiple resources.
+  // * Keys must start with a lowercase letter or international character.
+  //
+  // See [Google Cloud
+  // Document](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
+  // for more details.
+  map<string, string> user_labels = 22;
+}
+
+// Response message for
+// [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search]
+// method.
+message SearchResponse {
+  // Represents the search results.
+  message SearchResult {
+    // [Document.id][google.cloud.discoveryengine.v1.Document.id] of the
+    // searched [Document][google.cloud.discoveryengine.v1.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 list of matched documents. The order represents the ranking.
+  repeated SearchResult results = 1;
+
+  // The estimated total count of matched items irrespective of pagination. The
+  // count of [results][google.cloud.discoveryengine.v1.SearchResponse.results]
+  // returned by pagination may be less than the
+  // [total_size][google.cloud.discoveryengine.v1.SearchResponse.total_size]
+  // that matches.
+  int32 total_size = 3;
+
+  // A unique search token. This should be included in the
+  // [UserEvent][google.cloud.discoveryengine.v1.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.v1.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;
+}