@google-cloud/discoveryengine 2.3.0 → 2.5.0

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

@@ -1034,22 +1034,16 @@ message SearchRequest {
   // between /search API calls and /answer API calls.
   //
   // Example #1 (multi-turn /search API calls):
-  //   1. Call /search API with the auto-session mode (see below).
-  //   2. Call /search API with the session ID generated in the first call.
-  //      Here, the previous search query gets considered in query
-  //      standing. I.e., if the first query is "How did Alphabet do in 2022?"
-  //      and the current query is "How about 2023?", the current query will
-  //      be interpreted as "How did Alphabet do in 2023?".
+  //   Call /search API with the session ID generated in the first call.
+  //   Here, the previous search query gets considered in query
+  //   standing. I.e., if the first query is "How did Alphabet do in 2022?"
+  //   and the current query is "How about 2023?", the current query will
+  //   be interpreted as "How did Alphabet do in 2023?".
   //
   // Example #2 (coordination between /search API calls and /answer API calls):
-  //   1. Call /search API with the auto-session mode (see below).
-  //   2. Call /answer API with the session ID generated in the first call.
-  //      Here, the answer generation happens in the context of the search
-  //      results from the first search call.
-  //
-  // Auto-session mode: when `projects/.../sessions/-` is used, a new session
-  // gets automatically created. Otherwise, users can use the create-session API
-  // to create a session manually.
+  //   Call /answer API with the session ID generated in the first call.
+  //   Here, the answer generation happens in the context of the search
+  //   results from the first search call.
   //
   // Multi-turn Search feature is currently at private GA stage. Please use
   // v1alpha or v1beta version instead before we launch this feature to public
@@ -1075,6 +1069,115 @@ message SearchRequest {
   // Optional. The specification for returning the relevance score.
   RelevanceScoreSpec relevance_score_spec = 52
       [(google.api.field_behavior) = OPTIONAL];
+
+  // The ranking expression controls the customized ranking on retrieval
+  // documents. This overrides
+  // [ServingConfig.ranking_expression][google.cloud.discoveryengine.v1.ServingConfig.ranking_expression].
+  // The syntax and supported features depend on the
+  // `ranking_expression_backend` value. If `ranking_expression_backend` is not
+  // provided, it defaults to `RANK_BY_EMBEDDING`.
+  //
+  // If
+  // [ranking_expression_backend][google.cloud.discoveryengine.v1.SearchRequest.ranking_expression_backend]
+  // is not provided or set to `RANK_BY_EMBEDDING`, it should be a single
+  // function or multiple functions that are joined by "+".
+  //
+  //   * ranking_expression = function, { " + ", function };
+  //
+  // Supported functions:
+  //
+  //   * double * relevance_score
+  //   * double * dotProduct(embedding_field_path)
+  //
+  // Function variables:
+  //
+  //   * `relevance_score`: pre-defined keywords, used for measure relevance
+  //   between query and document.
+  //   * `embedding_field_path`: the document embedding field
+  //   used with query embedding vector.
+  //   * `dotProduct`: embedding function between `embedding_field_path` and
+  //   query embedding vector.
+  //
+  //  Example ranking expression:
+  //
+  //    If document has an embedding field doc_embedding, the ranking expression
+  //    could be `0.5 * relevance_score + 0.3 * dotProduct(doc_embedding)`.
+  //
+  // If
+  // [ranking_expression_backend][google.cloud.discoveryengine.v1.SearchRequest.ranking_expression_backend]
+  // is set to `RANK_BY_FORMULA`, the following expression types (and
+  // combinations of those chained using + or
+  // * operators) are supported:
+  //
+  //   * `double`
+  //   * `signal`
+  //   * `log(signal)`
+  //   * `exp(signal)`
+  //   * `rr(signal, double > 0)`  -- reciprocal rank transformation with second
+  //   argument being a denominator constant.
+  //   * `is_nan(signal)` -- returns 0 if signal is NaN, 1 otherwise.
+  //   * `fill_nan(signal1, signal2 | double)` -- if signal1 is NaN, returns
+  //   signal2 | double, else returns signal1.
+  //
+  //   Here are a few examples of ranking formulas that use the supported
+  //   ranking expression types:
+  //
+  //   - `0.2 * semantic_similarity_score + 0.8 * log(keyword_similarity_score)`
+  //   -- mostly rank by the logarithm of `keyword_similarity_score` with slight
+  //   `semantic_smilarity_score` adjustment.
+  //   - `0.2 * exp(fill_nan(semantic_similarity_score, 0)) + 0.3 *
+  //   is_nan(keyword_similarity_score)` -- rank by the exponent of
+  //   `semantic_similarity_score` filling the value with 0 if it's NaN, also
+  //   add constant 0.3 adjustment to the final score if
+  //   `semantic_similarity_score` is NaN.
+  //   - `0.2 * rr(semantic_similarity_score, 16) + 0.8 *
+  //   rr(keyword_similarity_score, 16)` -- mostly rank by the reciprocal rank
+  //   of `keyword_similarity_score` with slight adjustment of reciprocal rank
+  //   of `semantic_smilarity_score`.
+  //
+  // The following signals are supported:
+  //
+  //   * `semantic_similarity_score`: semantic similarity adjustment that is
+  //   calculated using the embeddings generated by a proprietary Google model.
+  //   This score determines how semantically similar a search query is to a
+  //   document.
+  //   * `keyword_similarity_score`: keyword match adjustment uses the Best
+  //   Match 25 (BM25) ranking function. This score is calculated using a
+  //   probabilistic model to estimate the probability that a document is
+  //   relevant to a given query.
+  //   * `relevance_score`: semantic relevance adjustment that uses a
+  //   proprietary Google model to determine the meaning and intent behind a
+  //   user's query in context with the content in the documents.
+  //   * `pctr_rank`: predicted conversion rate adjustment as a rank use
+  //   predicted Click-through rate (pCTR) to gauge the relevance and
+  //   attractiveness of a search result from a user's perspective. A higher
+  //   pCTR suggests that the result is more likely to satisfy the user's query
+  //   and intent, making it a valuable signal for ranking.
+  //   * `freshness_rank`: freshness adjustment as a rank
+  //   * `document_age`: The time in hours elapsed since the document was last
+  //   updated, a floating-point number (e.g., 0.25 means 15 minutes).
+  //   * `topicality_rank`: topicality adjustment as a rank. Uses proprietary
+  //   Google model to determine the keyword-based overlap between the query and
+  //   the document.
+  //   * `base_rank`: the default rank of the result
+  string ranking_expression = 26;
+
+  // The backend to use for the ranking expression evaluation.
+  enum RankingExpressionBackend {
+    reserved 1, 2;
+
+    // Default option for unspecified/unknown values.
+    RANKING_EXPRESSION_BACKEND_UNSPECIFIED = 0;
+    // Ranking by custom embedding model, the default way to evaluate the
+    // ranking expression.
+    RANK_BY_EMBEDDING = 3;
+    // Ranking by custom formula.
+    RANK_BY_FORMULA = 4;
+  }
+
+  // The backend to use for the ranking expression evaluation.
+  RankingExpressionBackend ranking_expression_backend = 53
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Response message for
@@ -1100,6 +1203,49 @@ message SearchResponse {
     // Output only. Google provided available scores.
     map<string, DoubleList> model_scores = 4
         [(google.api.field_behavior) = OUTPUT_ONLY];
+
+    // A set of ranking signals.
+    message RankSignals {
+      reserved 5;
+
+      // Keyword matching adjustment.
+      optional float keyword_similarity_score = 1
+          [(google.api.field_behavior) = OPTIONAL];
+      // Semantic relevance adjustment.
+      optional float relevance_score = 2
+          [(google.api.field_behavior) = OPTIONAL];
+      // Semantic similarity adjustment.
+      optional float semantic_similarity_score = 3
+          [(google.api.field_behavior) = OPTIONAL];
+      // Predicted conversion rate adjustment as a rank.
+      optional float pctr_rank = 4 [(google.api.field_behavior) = OPTIONAL];
+      // Topicality adjustment as a rank.
+      optional float topicality_rank = 6
+          [(google.api.field_behavior) = OPTIONAL];
+      // Age of the document in hours.
+      optional float document_age = 7 [(google.api.field_behavior) = OPTIONAL];
+      // Combined custom boosts for a doc.
+      optional float boosting_factor = 8
+          [(google.api.field_behavior) = OPTIONAL];
+
+      // The default rank of the result.
+      float default_rank = 32 [(google.api.field_behavior) = OPTIONAL];
+
+      // Custom clearbox signal represented by name and value pair.
+      message CustomSignal {
+        // Name of the signal.
+        string name = 1 [(google.api.field_behavior) = OPTIONAL];
+        // Float value representing the ranking signal (e.g. 1.25 for BM25).
+        float value = 2 [(google.api.field_behavior) = OPTIONAL];
+      }
+
+      // A list of custom clearbox signals.
+      repeated CustomSignal custom_signals = 33
+          [(google.api.field_behavior) = OPTIONAL];
+    }
+
+    // A set of ranking signals associated with the result.
+    RankSignals rank_signals = 7 [(google.api.field_behavior) = OPTIONAL];
   }
 
   // A facet result.

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

@@ -37,21 +37,27 @@ message Session {
     pattern: "projects/{project}/locations/{location}/dataStores/{data_store}/sessions/{session}"
     pattern: "projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/sessions/{session}"
     pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}"
+    plural: "sessions"
+    singular: "session"
   };
 
   // Represents a turn, including a query from the user and a
   // answer from service.
   message Turn {
-    // The user query.
-    Query query = 1;
+    // Optional. The user query. May not be set if this turn is merely
+    // regenerating an answer to a different turn
+    Query query = 1 [(google.api.field_behavior) = OPTIONAL];
 
-    // The resource name of the answer to the user query.
+    // Optional. The resource name of the answer to the user query.
     //
     // Only set if the answer generation (/answer API call) happened in this
     // turn.
-    string answer = 2 [(google.api.resource_reference) = {
-      type: "discoveryengine.googleapis.com/Answer"
-    }];
+    string answer = 2 [
+      (google.api.field_behavior) = OPTIONAL,
+      (google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/Answer"
+      }
+    ];
 
     // Output only. In
     // [ConversationalSearchService.GetSession][google.cloud.discoveryengine.v1.ConversationalSearchService.GetSession]
@@ -60,6 +66,13 @@ message Session {
     // is set to true, this field will be populated when getting answer query
     // session.
     Answer detailed_answer = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+    // Optional. Represents metadata related to the query config, for example
+    // LLM model and version used, model parameters (temperature, grounding
+    // parameters, etc.). The prefix "google." is reserved for Google-developed
+    // functionality.
+    map<string, string> query_config = 16
+        [(google.api.field_behavior) = OPTIONAL];
   }
 
   // Enumeration of the state of the session.
@@ -111,6 +124,6 @@ message Query {
     string text = 2;
   }
 
-  // Unique Id for the query.
-  string query_id = 1;
+  // Output only. Unique Id for the query.
+  string query_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 }

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

@@ -0,0 +1,128 @@
+// Copyright 2025 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/conversational_search_service.proto";
+import "google/cloud/discoveryengine/v1/session.proto";
+import "google/protobuf/empty.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 = "SessionServiceProto";
+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 managing Sessions and Session-related resources.
+service SessionService {
+  option (google.api.default_host) = "discoveryengine.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Creates a Session.
+  //
+  // If the [Session][google.cloud.discoveryengine.v1.Session] to create already
+  // exists, an ALREADY_EXISTS error is returned.
+  rpc CreateSession(CreateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      post: "/v1/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      body: "session"
+      additional_bindings {
+        post: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+        body: "session"
+      }
+      additional_bindings {
+        post: "/v1/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+        body: "session"
+      }
+    };
+    option (google.api.method_signature) = "parent,session";
+  }
+
+  // Deletes a Session.
+  //
+  // If the [Session][google.cloud.discoveryengine.v1.Session] to delete does
+  // not exist, a NOT_FOUND error is returned.
+  rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        delete: "/v1/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        delete: "/v1/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Updates a Session.
+  //
+  // [Session][google.cloud.discoveryengine.v1.Session] action type cannot be
+  // changed. If the [Session][google.cloud.discoveryengine.v1.Session] to
+  // update does not exist, a NOT_FOUND error is returned.
+  rpc UpdateSession(UpdateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      patch: "/v1/{session.name=projects/*/locations/*/dataStores/*/sessions/*}"
+      body: "session"
+      additional_bindings {
+        patch: "/v1/{session.name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+        body: "session"
+      }
+      additional_bindings {
+        patch: "/v1/{session.name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+        body: "session"
+      }
+    };
+    option (google.api.method_signature) = "session,update_mask";
+  }
+
+  // Gets a Session.
+  rpc GetSession(GetSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      get: "/v1/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        get: "/v1/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        get: "/v1/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all Sessions by their parent
+  // [DataStore][google.cloud.discoveryengine.v1.DataStore].
+  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      additional_bindings {
+        get: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+      }
+      additional_bindings {
+        get: "/v1/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}

package/build/protos/google/cloud/discoveryengine/v1alpha/common.proto

@@ -127,6 +127,21 @@ enum SearchAddOn {
   SEARCH_ADD_ON_LLM = 1;
 }
 
+// The origin of the file.
+enum FileOriginType {
+  // Default value.
+  FILE_ORIGIN_TYPE_UNSPECIFIED = 0;
+
+  // The file was provided by the user.
+  USER_PROVIDED = 1;
+
+  // The file was generated by an AI model.
+  AI_GENERATED = 2;
+
+  // The file was generated from other files by an internal process.
+  INTERNALLY_GENERATED = 3;
+}
+
 // A floating point interval.
 message Interval {
   // The lower bound of the interval. If neither of the min fields are

package/build/protos/google/cloud/discoveryengine/v1alpha/conversational_search_service.proto

@@ -859,7 +859,7 @@ message GetAnswerRequest {
 // Request for CreateSession method.
 message CreateSessionRequest {
   // Required. Full resource name of parent data store. Format:
-  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}`
+  // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store_id}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -889,7 +889,7 @@ message UpdateSessionRequest {
 // Request for DeleteSession method.
 message DeleteSessionRequest {
   // Required. The resource name of the Session to delete. Format:
-  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
+  // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -901,19 +901,23 @@ message DeleteSessionRequest {
 // Request for GetSession method.
 message GetSessionRequest {
   // Required. The resource name of the Session to get. Format:
-  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
+  // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
       type: "discoveryengine.googleapis.com/Session"
     }
   ];
+
+  // Optional. If set to true, the full session including all answer details
+  // will be returned.
+  bool include_answer_details = 2 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Request for ListSessions method.
 message ListSessionsRequest {
   // Required. The data store resource name. Format:
-  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}`
+  // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store_id}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -929,23 +933,40 @@ message ListSessionsRequest {
   // Provide this to retrieve the subsequent page.
   string page_token = 3;
 
-  // A filter to apply on the list results. The supported features are:
-  // user_pseudo_id, state.
+  // A comma-separated list of fields to filter by, in EBNF grammar.
+  // The supported fields are:
+  // * `user_pseudo_id`
+  // * `state`
+  // * `display_name`
+  // * `starred`
+  // * `is_pinned`
+  // * `labels`
+  // * `create_time`
+  // * `update_time`
   //
-  // Example:
+  // Examples:
   // "user_pseudo_id = some_id"
+  // "display_name = \"some_name\""
+  // "starred = true"
+  // "is_pinned=true AND (NOT labels:hidden)"
+  // "create_time > \"1970-01-01T12:00:00Z\""
   string filter = 4;
 
   // A comma-separated list of fields to order by, sorted in ascending order.
   // Use "desc" after a field name for descending.
   // Supported fields:
+  //
   //   * `update_time`
   //   * `create_time`
   //   * `session_name`
+  //   * `is_pinned`
   //
   // Example:
-  // "update_time desc"
-  // "create_time"
+  //
+  // * "update_time desc"
+  // * "create_time"
+  // * "is_pinned desc,update_time desc": list sessions by is_pinned first, then
+  //    by update_time.
   string order_by = 5;
 }