@google-cloud/discoveryengine 1.0.0 → 1.1.0

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

@@ -66,7 +66,7 @@ message UserEvent {
   // quality.
   //
   // The field must be a UTF-8 encoded string with a length limit of 128
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   //
   // The field should not contain PII or user-data. We recommend to use Google
   // Analytics [Client
@@ -119,20 +119,17 @@ message UserEvent {
   //
   // The value must be one of:
   //
-  // * [PredictResponse.attribution_token][] for events that are the result of
+  // * [RecommendResponse.attribution_token][] for events that are the result of
   // [RecommendationService.Recommend][].
   // * [SearchResponse.attribution_token][google.cloud.discoveryengine.v1.SearchResponse.attribution_token] for events that are the result of
   // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search].
-  // * [CompleteQueryResponse.attribution_token][] for events that are the
-  // result of
-  // [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1.CompletionService.CompleteQuery].
   //
   // This token enables us to accurately attribute page view or conversion
   // completion back to the event and the particular predict response containing
   // this clicked/purchased product. If user clicks on product K in the
-  // recommendation results, pass [PredictResponse.attribution_token][] as a URL
-  // parameter to product K's page. When recording events on product K's page,
-  // log the [PredictResponse.attribution_token][] to this field.
+  // recommendation results, pass [RecommendResponse.attribution_token][] as a
+  // URL parameter to product K's page. When recording events on product K's
+  // page, log the [RecommendResponse.attribution_token][] to this field.
   string attribution_token = 8;
 
   // The filter syntax consists of an expression language for constructing a
@@ -140,8 +137,9 @@ message UserEvent {
   //
   // One example is for `search` events, the associated
   // [SearchRequest][google.cloud.discoveryengine.v1.SearchRequest] may contain
-  // a filter expression in [SearchRequest.filter][] conforming to
-  // https://google.aip.dev/160#filtering.
+  // a filter expression in
+  // [SearchRequest.filter][google.cloud.discoveryengine.v1.SearchRequest.filter]
+  // conforming to https://google.aip.dev/160#filtering.
   //
   // Similarly, for `view-item-list` events that are generated from a
   // [RecommendationService.RecommendRequest][], this field may be populated
@@ -149,10 +147,11 @@ message UserEvent {
   // 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.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string filter = 9;
 
-  // List of Documents associated with this user event.
+  // List of [Document][google.cloud.discoveryengine.v1.Document]s associated
+  // with this user event.
   //
   // This field is optional except for the following event types:
   //
@@ -174,12 +173,14 @@ message UserEvent {
   // Panel metadata associated with this user event.
   PanelInfo panel = 11;
 
-  // Search API details related to the event.
+  // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search]
+  // details related to the event.
   //
   // This field should be set for `search` event.
   SearchInfo search_info = 12;
 
-  // CompleteQuery API details related to the event.
+  // [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1.CompletionService.CompleteQuery]
+  // details related to the event.
   //
   // This field should be set for `search` event when autocomplete function is
   // enabled and the user clicks a suggestion for search.
@@ -219,7 +220,7 @@ 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
+  // `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.
@@ -235,7 +236,7 @@ message PageInfo {
   //
   // This should be kept the same for all user events triggered from the same
   // pageview. For example, an item detail page view could trigger multiple
-  // events as the user is browsing the page. The `pageViewId` property should
+  // events as the user is browsing the page. The `pageview_id` property should
   // be kept the same for all these events so that they can be grouped together
   // properly.
   //
@@ -251,10 +252,10 @@ message PageInfo {
   //
   // Category pages include special pages such as sales or promotions. For
   // instance, a special sale page may have the category hierarchy:
-  // "pageCategory" : "Sales > 2017 Black Friday Deals".
+  // `"pageCategory" : "Sales > 2017 Black Friday Deals"`.
   //
   // Required for `view-category-page` events. Other event types should not set
-  // this field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string page_category = 2;
 
   // Complete URL (window.location.href) of the user's current page.
@@ -281,24 +282,26 @@ message SearchInfo {
   // for definition.
   //
   // The value must be a UTF-8 encoded string with a length limit of 5,000
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   //
   // At least one of
   // [search_query][google.cloud.discoveryengine.v1.SearchInfo.search_query] or
   // [PageInfo.page_category][google.cloud.discoveryengine.v1.PageInfo.page_category]
   // is required for `search` events. Other event types should not set this
-  // field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string search_query = 1;
 
   // The order in which products are returned, if applicable.
   //
-  // See [SearchRequest.order_by][] for definition and syntax.
+  // See
+  // [SearchRequest.order_by][google.cloud.discoveryengine.v1.SearchRequest.order_by]
+  // for definition and syntax.
   //
   // The value must be a UTF-8 encoded string with a length limit of 1,000
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   //
   // This can only be set for `search` events. Other event types should not set
-  // this field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string order_by = 2;
 
   // An integer that specifies the current offset for pagination (the 0-indexed
@@ -308,20 +311,22 @@ message SearchInfo {
   // [SearchRequest.offset][google.cloud.discoveryengine.v1.SearchRequest.offset]
   // for definition.
   //
-  // If this field is negative, an INVALID_ARGUMENT is returned.
+  // If this field is negative, an `INVALID_ARGUMENT` is returned.
   //
   // This can only be set for `search` events. Other event types should not set
-  // this field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   optional int32 offset = 3;
 }
 
 // Detailed completion information including completion attribution token and
 // clicked completion info.
 message CompletionInfo {
-  // End user selected [CompleteQueryResponse.CompletionResult.suggestion][].
+  // End user selected
+  // [CompleteQueryResponse.QuerySuggestion.suggestion][google.cloud.discoveryengine.v1.CompleteQueryResponse.QuerySuggestion.suggestion].
   string selected_suggestion = 1;
 
-  // End user selected [CompleteQueryResponse.CompletionResult.suggestion][]
+  // End user selected
+  // [CompleteQueryResponse.QuerySuggestion.suggestion][google.cloud.discoveryengine.v1.CompleteQueryResponse.QuerySuggestion.suggestion]
   // position, starting from 0.
   int32 selected_position = 2;
 }
@@ -389,17 +394,19 @@ message DocumentInfo {
   // `{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];
+    // The [Document][google.cloud.discoveryengine.v1.Document] resource ID.
+    string id = 1;
 
-    // Required. The Document resource full name, of the form:
+    // The [Document][google.cloud.discoveryengine.v1.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}`
-    string name = 2 [
-      (google.api.field_behavior) = REQUIRED,
-      (google.api.resource_reference) = {
-        type: "discoveryengine.googleapis.com/Document"
-      }
-    ];
+    string name = 2 [(google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Document"
+    }];
+
+    // The [Document][google.cloud.discoveryengine.v1.Document] URI - only
+    // allowed for website data stores.
+    string uri = 6;
   }
 
   // Quantity of the Document associated with the user event. Defaults to 1.
@@ -443,11 +450,13 @@ message PanelInfo {
 message MediaInfo {
   // The media progress time in seconds, if applicable.
   // For example, if the end user has finished 90 seconds of a playback video,
-  // then [MediaInfo.media_progress_duration.seconds][Duration.seconds] should
-  // be set to 90.
+  // then
+  // [MediaInfo.media_progress_duration.seconds][google.protobuf.Duration.seconds]
+  // should be set to 90.
   google.protobuf.Duration media_progress_duration = 1;
 
-  // Media progress should be computed using only the media_progress_duration
+  // Media progress should be computed using only the
+  // [media_progress_duration][google.cloud.discoveryengine.v1.MediaInfo.media_progress_duration]
   // relative to the media total length.
   //
   // This value must be between `[0, 1.0]` inclusive.

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

@@ -53,7 +53,7 @@ service UserEventService {
   }
 
   // Writes a single user event from the browser. This uses a GET request to
-  // due to browser restriction of POST-ing to a 3rd party domain.
+  // due to browser restriction of POST-ing to a third-party domain.
   //
   // This method is used only by the Discovery Engine API JavaScript pixel and
   // Google Tag Manager. Users should not call this method directly.
@@ -122,7 +122,7 @@ message CollectUserEventRequest {
 
   // The URL including cgi-parameters but excluding the hash fragment with a
   // length limit of 5,000 characters. This is often more useful than the
-  // referer URL, because many browsers only send the domain for 3rd party
+  // referer URL, because many browsers only send the domain for third-party
   // requests.
   optional string uri = 3;
 

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

@@ -126,3 +126,9 @@ message UserInfo {
   // is set.
   string user_agent = 2;
 }
+
+// Double list.
+message DoubleList {
+  // Double values.
+  repeated double values = 1;
+}

package/build/protos/google/cloud/discoveryengine/v1beta/conversation.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/search_service.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
@@ -75,6 +76,8 @@ message Conversation {
 message Reply {
   // Defines reference in reply.
   message Reference {
+    option deprecated = true;
+
     // URI link reference.
     string uri = 1;
 
@@ -88,11 +91,15 @@ message Reply {
     int32 end = 4;
   }
 
+  // DEPRECATED: use `summary` instead.
   // Text reply.
-  string reply = 1;
+  string reply = 1 [deprecated = true];
 
   // References in the reply.
-  repeated Reference references = 2;
+  repeated Reference references = 2 [deprecated = true];
+
+  // Summary based on search results.
+  SearchResponse.Summary summary = 3;
 }
 
 // Defines context of the conversation

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

@@ -162,6 +162,28 @@ message ConverseConversationRequest {
 
   // Whether to turn on safe search.
   bool safe_search = 6;
+
+  // 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 = 7;
+
+  // A specification for configuring the summary returned in the response.
+  SearchRequest.ContentSearchSpec.SummarySpec summary_spec = 8;
 }
 
 // Response message for
@@ -174,6 +196,9 @@ message ConverseConversationResponse {
   // Updated conversation including the answer.
   Conversation conversation = 2;
 
+  // Suggested related questions.
+  repeated string related_questions = 6;
+
   // Search Results.
   repeated SearchResponse.SearchResult search_results = 3;
 }

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

@@ -262,6 +262,11 @@ message SearchRequest {
     // The condition under which query expansion should occur. Default to
     // [Condition.DISABLED][google.cloud.discoveryengine.v1beta.SearchRequest.QueryExpansionSpec.Condition.DISABLED].
     Condition condition = 1;
+
+    // Whether to pin unexpanded results. If this field is set to true,
+    // unexpanded products are always at the top of the search results, followed
+    // by the expanded results.
+    bool pin_unexpanded_results = 2;
   }
 
   // The specification for query spell correction.
@@ -362,6 +367,10 @@ message SearchRequest {
       // generating summaries for non-summary seeking queries and return
       // fallback messages instead.
       bool ignore_non_summary_seeking_query = 4;
+
+      // Language code for Summary. Use language tags defined by
+      // [BCP47][https://www.rfc-editor.org/rfc/bcp/bcp47.txt].
+      string language_code = 6;
     }
 
     // A specification for configuring the extractive content in a search
@@ -399,10 +408,21 @@ message SearchRequest {
       // If the number of matching segments is less than
       // `max_extractive_segment_count`, return all of the segments. Otherwise,
       // return the `max_extractive_segment_count`.
-      //
-      // Currently one segment is returned for each
-      // [SearchResult][google.cloud.discoveryengine.v1beta.SearchResponse.SearchResult].
       int32 max_extractive_segment_count = 2;
+
+      // Specifies whether to return the confidence score from the extractive
+      // segments in each search result. The default value is `false`.
+      bool return_extractive_segment_score = 3;
+
+      // Specifies whether to also include the adjacent from each selected
+      // segments.
+      // Return at most `num_previous_segments` segments before each selected
+      // segments.
+      int32 num_previous_segments = 4;
+
+      // Return at most `num_next_segments` segments after each selected
+      // segments.
+      int32 num_next_segments = 5;
     }
 
     // If `snippetSpec` is not specified, snippets are not included in the
@@ -418,6 +438,22 @@ message SearchRequest {
     ExtractiveContentSpec extractive_content_spec = 3;
   }
 
+  // The specification that uses customized query embedding vector to do
+  // semantic document retrieval.
+  message EmbeddingSpec {
+    // Embedding vector.
+    message EmbeddingVector {
+      // Embedding field path in schema.
+      string field_path = 1;
+
+      // Query embedding vector.
+      repeated float vector = 2;
+    }
+
+    // The embedding vector used for retrieval. Limit to 1.
+    repeated EmbeddingVector embedding_vectors = 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
@@ -539,6 +575,37 @@ message SearchRequest {
   // A specification for configuring the behavior of content search.
   ContentSearchSpec content_search_spec = 24;
 
+  // Uses the provided embedding to do additional semantic document retrieval.
+  // The retrieval is based on the dot product of
+  // [SearchRequest.embedding_spec.embedding_vectors.vector][] and the document
+  // embedding that is provided in
+  // [SearchRequest.embedding_spec.embedding_vectors.field_path][].
+  //
+  // If [SearchRequest.embedding_spec.embedding_vectors.field_path][] is not
+  // provided, it will use [ServingConfig.embedding_config.field_paths][].
+  EmbeddingSpec embedding_spec = 23;
+
+  // The ranking expression controls the customized ranking on retrieval
+  // documents. This overrides [ServingConfig.ranking_expression][].
+  // The ranking expression is a single function or multiple functions that are
+  // joint 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)`.
+  string ranking_expression = 26;
+
   // Whether to turn on safe search. This is only supported for
   // website search.
   bool safe_search = 20;
@@ -576,6 +643,9 @@ message SearchResponse {
     // The document data snippet in the search response. Only fields that are
     // marked as retrievable are populated.
     Document document = 2;
+
+    // Google provided available scores.
+    map<string, DoubleList> model_scores = 4;
   }
 
   // A facet result.
@@ -629,6 +699,17 @@ message SearchResponse {
 
   // Summary of the top N search result specified by the summary spec.
   message Summary {
+    // Safety Attribute categories and their associated confidence scores.
+    message SafetyAttributes {
+      // The display names of Safety Attribute categories associated with the
+      // generated content. Order matches the Scores.
+      repeated string categories = 1;
+
+      // The confidence scores of the each category, higher
+      // value means higher confidence. Order matches the Categories.
+      repeated float scores = 2;
+    }
+
     // An Enum for summary-skipped reasons.
     enum SummarySkippedReason {
       // Default value. The summary skipped reason is not specified.
@@ -654,6 +735,17 @@ message SearchResponse {
       // For example, the data store contains facts about company A but the
       // user query is asking questions about company B.
       OUT_OF_DOMAIN_QUERY_IGNORED = 3;
+
+      // The potential policy violation case.
+      //
+      // Google skips the summary if there is a potential policy violation
+      // detected. This includes content that may be violent or toxic.
+      POTENTIAL_POLICY_VIOLATION = 4;
+
+      // The LLM addon not enabled case.
+      //
+      // Google skips the summary if the LLM addon is not enabled.
+      LLM_ADDON_NOT_ENABLED = 5;
     }
 
     // The summary content.
@@ -662,6 +754,23 @@ message SearchResponse {
     // Additional summary-skipped reasons. This provides the reason for ignored
     // cases. If nothing is skipped, this field is not set.
     repeated SummarySkippedReason summary_skipped_reasons = 2;
+
+    // A collection of Safety Attribute categories and their associated
+    // confidence scores.
+    SafetyAttributes safety_attributes = 3;
+  }
+
+  // Information describing query expansion including whether expansion has
+  // occurred.
+  message QueryExpansionInfo {
+    // Bool describing whether query expansion has occurred.
+    bool expanded_query = 1;
+
+    // Number of pinned results. This field will only be set when expansion
+    // happens and
+    // [SearchRequest.QueryExpansionSpec.pin_unexpanded_results][google.cloud.discoveryengine.v1beta.SearchRequest.QueryExpansionSpec.pin_unexpanded_results]
+    // is set to true.
+    int64 pinned_result_count = 2;
   }
 
   // A list of matched documents. The order represents the ranking.
@@ -714,4 +823,7 @@ message SearchResponse {
 
   // Controls applied as part of the Control service.
   repeated string applied_controls = 10;
+
+  // Query expansion information for the returned results.
+  QueryExpansionInfo query_expansion_info = 14;
 }

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

@@ -410,6 +410,10 @@ message DocumentInfo {
     string name = 2 [(google.api.resource_reference) = {
       type: "discoveryengine.googleapis.com/Document"
     }];
+
+    // The [Document][google.cloud.discoveryengine.v1beta.Document] URI - only
+    // allowed for website data stores.
+    string uri = 6;
   }
 
   // Quantity of the Document associated with the user event. Defaults to 1.