@google-cloud/discoveryengine 2.3.0 → 2.4.0

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

@@ -0,0 +1,201 @@
+// 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.v1alpha;
+
+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/v1alpha/conversational_search_service.proto";
+import "google/cloud/discoveryengine/v1alpha/session.proto";
+import "google/protobuf/empty.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Alpha";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1alpha/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "SessionServiceProto";
+option java_package = "com.google.cloud.discoveryengine.v1alpha";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1alpha";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1alpha";
+
+// 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.v1alpha.Session] to create
+  // already exists, an ALREADY_EXISTS error is returned.
+  rpc CreateSession(CreateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      post: "/v1alpha/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      body: "session"
+      additional_bindings {
+        post: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+        body: "session"
+      }
+      additional_bindings {
+        post: "/v1alpha/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+        body: "session"
+      }
+    };
+    option (google.api.method_signature) = "parent,session";
+  }
+
+  // Deletes a Session.
+  //
+  // If the [Session][google.cloud.discoveryengine.v1alpha.Session] to delete
+  // does not exist, a NOT_FOUND error is returned.
+  rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1alpha/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        delete: "/v1alpha/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        delete: "/v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Updates a Session.
+  //
+  // [Session][google.cloud.discoveryengine.v1alpha.Session] action type cannot
+  // be changed. If the [Session][google.cloud.discoveryengine.v1alpha.Session]
+  // to update does not exist, a NOT_FOUND error is returned.
+  rpc UpdateSession(UpdateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      patch: "/v1alpha/{session.name=projects/*/locations/*/dataStores/*/sessions/*}"
+      body: "session"
+      additional_bindings {
+        patch: "/v1alpha/{session.name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+        body: "session"
+      }
+      additional_bindings {
+        patch: "/v1alpha/{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: "/v1alpha/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        get: "/v1alpha/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        get: "/v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all Sessions by their parent
+  // [DataStore][google.cloud.discoveryengine.v1alpha.DataStore].
+  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) {
+    option (google.api.http) = {
+      get: "/v1alpha/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      additional_bindings {
+        get: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+      }
+      additional_bindings {
+        get: "/v1alpha/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Lists metadata for all files in the current session.
+  rpc ListFiles(ListFilesRequest) returns (ListFilesResponse) {
+    option (google.api.http) = {
+      get: "/v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/files"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}
+
+// Request message for
+// [SessionService.ListFiles][google.cloud.discoveryengine.v1alpha.SessionService.ListFiles]
+// method.
+message ListFilesRequest {
+  // Required. The resource name of the Session.
+  // Format:
+  // `projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}`
+  // Name of the session resource to which the file belong.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Session"
+    }
+  ];
+
+  // Optional. The filter syntax consists of an expression language for
+  // constructing a predicate from one or more fields of the files being
+  // filtered. Filter expression is case-sensitive. Currently supported field
+  // names are:
+  // * upload_time
+  // * last_add_time
+  // * last_use_time
+  // * file_name
+  // * mime_type
+  //
+  // Some examples of filters would be:
+  // * "file_name = 'file_1'"
+  // * "file_name = 'file_1' AND mime_type = 'text/plain'"
+  // * "last_use_time > '2025-06-14T12:00:00Z'"
+  //
+  // For a full description of the filter format, please
+  // see https://google.aip.dev/160.
+  string filter = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The maximum number of files to return. The service may return
+  // fewer than this value. If unspecified, at most 100 files will be returned.
+  // The maximum value is 1000; values above 1000 will be coerced to 1000.
+  // If user specifies a value less than or equal to 0 - the request will be
+  // rejected with an INVALID_ARGUMENT error.
+  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A page token received from a previous `ListFiles` call.
+  // Provide this to retrieve the subsequent page.
+  //
+  // When paginating, all other parameters provided to `ListFiles`
+  // must match the call that provided the page token (except `page_size`, which
+  // may differ).
+  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for
+// [SessionService.ListFiles][google.cloud.discoveryengine.v1alpha.SessionService.ListFiles]
+// method.
+message ListFilesResponse {
+  // The [FileMetadata][google.cloud.discoveryengine.v1alpha.FileMetadata]s.
+  repeated FileMetadata files = 1;
+
+  // A token to retrieve next page of results.
+  // Pass this value in the
+  // [ListFilesRequest.page_token][google.cloud.discoveryengine.v1main.ListFilesRequest.page_token]
+  // field in the subsequent call to `ListFiles` method to
+  // retrieve the next page of results.
+  string next_page_token = 3;
+}

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

@@ -980,6 +980,10 @@ message GetSessionRequest {
       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.
@@ -1001,23 +1005,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;
 }
 

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

@@ -1102,22 +1102,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

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

@@ -18,6 +18,7 @@ package google.cloud.discoveryengine.v1beta;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1beta/answer.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
@@ -36,21 +37,42 @@ 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.v1beta.ConversationalSearchService.GetSession]
+    // API, if
+    // [GetSessionRequest.include_answer_details][google.cloud.discoveryengine.v1beta.GetSessionRequest.include_answer_details]
+    // 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.
@@ -66,6 +88,12 @@ message Session {
   // `projects/{project}/locations/global/collections/{collection}/engines/{engine}/sessions/*`
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
+  // Optional. The display name of the session.
+  //
+  // This field is used to identify the session in the UI.
+  // By default, the display name is the first turn query text in the session.
+  string display_name = 7 [(google.api.field_behavior) = OPTIONAL];
+
   // The state of the session.
   State state = 2;
 
@@ -82,6 +110,10 @@ message Session {
   // Output only. The time the session finished.
   google.protobuf.Timestamp end_time = 6
       [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. Whether the session is pinned, pinned session will be displayed
+  // on the top of the session list.
+  bool is_pinned = 8 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Defines a user inputed query.
@@ -92,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/v1beta/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.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/conversational_search_service.proto";
+import "google/cloud/discoveryengine/v1beta/session.proto";
+import "google/protobuf/empty.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 = "SessionServiceProto";
+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 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.v1beta.Session] to create
+  // already exists, an ALREADY_EXISTS error is returned.
+  rpc CreateSession(CreateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      post: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      body: "session"
+      additional_bindings {
+        post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+        body: "session"
+      }
+      additional_bindings {
+        post: "/v1beta/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+        body: "session"
+      }
+    };
+    option (google.api.method_signature) = "parent,session";
+  }
+
+  // Deletes a Session.
+  //
+  // If the [Session][google.cloud.discoveryengine.v1beta.Session] to delete
+  // does not exist, a NOT_FOUND error is returned.
+  rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1beta/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        delete: "/v1beta/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        delete: "/v1beta/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Updates a Session.
+  //
+  // [Session][google.cloud.discoveryengine.v1beta.Session] action type cannot
+  // be changed. If the [Session][google.cloud.discoveryengine.v1beta.Session]
+  // to update does not exist, a NOT_FOUND error is returned.
+  rpc UpdateSession(UpdateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      patch: "/v1beta/{session.name=projects/*/locations/*/dataStores/*/sessions/*}"
+      body: "session"
+      additional_bindings {
+        patch: "/v1beta/{session.name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+        body: "session"
+      }
+      additional_bindings {
+        patch: "/v1beta/{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: "/v1beta/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        get: "/v1beta/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        get: "/v1beta/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all Sessions by their parent
+  // [DataStore][google.cloud.discoveryengine.v1beta.DataStore].
+  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) {
+    option (google.api.http) = {
+      get: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      additional_bindings {
+        get: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+      }
+      additional_bindings {
+        get: "/v1beta/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}