@google-cloud/discoveryengine 1.7.0 → 1.9.0

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -70,7 +70,9 @@ message SearchRequest {
     }
   }
 
-  // A struct to define data stores to filter on in a search call.
+  // A struct to define data stores to filter on in a search call and
+  // configurations for those data stores. A maximum of 1 DataStoreSpec per
+  // data_store is allowed. Otherwise, an `INVALID_ARGUMENT` error is returned.
   message DataStoreSpec {
     // Required. Full resource name of
     // [DataStore][google.cloud.discoveryengine.v1alpha.DataStore], such as
@@ -112,7 +114,7 @@ message SearchRequest {
       // Only supported on textual fields. Maximum is 10.
       repeated string prefixes = 4;
 
-      // Only get facet values that contains the given strings. For example,
+      // Only get facet values that contain 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 only contains "Action > 2022" and "Sci-Fi > 2022".
@@ -146,7 +148,7 @@ message SearchRequest {
     // 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
+    // Maximum facet values that are returned for this facet. If
     // unspecified, defaults to 20. The maximum allowed value is 300. Values
     // above 300 are coerced to 300.
     //
@@ -256,7 +258,7 @@ message SearchRequest {
           // specified. The value must be formatted as an XSD `dayTimeDuration`
           // value (a restricted subset of an ISO 8601 duration value). The
           // pattern for this is: `[nD][T[nH][nM][nS]]`.
-          // E.g. `5D`, `3DT12H30M`, `T24H`.
+          // For example, `5D`, `3DT12H30M`, `T24H`.
           FRESHNESS = 2;
         }
 
@@ -375,10 +377,10 @@ message SearchRequest {
       // [Mode.AUTO][google.cloud.discoveryengine.v1alpha.SearchRequest.SpellCorrectionSpec.Mode.AUTO].
       MODE_UNSPECIFIED = 0;
 
-      // Search API will try to find a spell suggestion if there
-      // is any and put in the
+      // Search API tries to find a spelling suggestion. If a suggestion is
+      // found, it is put in the
       // [SearchResponse.corrected_query][google.cloud.discoveryengine.v1alpha.SearchResponse.corrected_query].
-      // The spell suggestion will not be used as the search query.
+      // The spelling suggestion won't be used as the search query.
       SUGGESTION_ONLY = 1;
 
       // Automatic spell correction built by the Search API. Search will
@@ -386,8 +388,8 @@ message SearchRequest {
       AUTO = 2;
     }
 
-    // The mode under which spell correction should take effect to
-    // replace the original search query. Default to
+    // The mode under which spell correction
+    // replaces the original search query. Defaults to
     // [Mode.AUTO][google.cloud.discoveryengine.v1alpha.SearchRequest.SpellCorrectionSpec.Mode.AUTO].
     Mode mode = 1;
   }
@@ -587,11 +589,7 @@ message SearchRequest {
     }
 
     // Specifies the search result mode. If unspecified, the
-    // search result mode is based on
-    // [DataStore.DocumentProcessingConfig.chunking_config][]:
-    // * If [DataStore.DocumentProcessingConfig.chunking_config][] is specified,
-    //   it defaults to `CHUNKS`.
-    // * Otherwise, it defaults to `DOCUMENTS`.
+    // search result mode defaults to `DOCUMENTS`.
     enum SearchResultMode {
       // Default value.
       SEARCH_RESULT_MODE_UNSPECIFIED = 0;
@@ -617,11 +615,7 @@ message SearchRequest {
     ExtractiveContentSpec extractive_content_spec = 3;
 
     // Specifies the search result mode. If unspecified, the
-    // search result mode is based on
-    // [DataStore.DocumentProcessingConfig.chunking_config][]:
-    // * If [DataStore.DocumentProcessingConfig.chunking_config][] is specified,
-    //   it defaults to `CHUNKS`.
-    // * Otherwise, it defaults to `DOCUMENTS`.
+    // search result mode defaults to `DOCUMENTS`.
     SearchResultMode search_result_mode = 4;
 
     // Specifies the chunk spec to be returned from the search response.
@@ -708,7 +702,10 @@ message SearchRequest {
   // If this field is negative, an  `INVALID_ARGUMENT`  is returned.
   int32 offset = 6;
 
-  // A list of data store specs to apply on a search call.
+  // Specs defining dataStores to filter on in a search call and configurations
+  // for those dataStores. This is only considered for engines with multiple
+  // dataStores use case. For single dataStore within an engine, they should
+  // use the specs at the top level.
   repeated DataStoreSpec data_store_specs = 32;
 
   // The filter syntax consists of an expression language for constructing a
@@ -745,7 +742,9 @@ message SearchRequest {
   // The order in which documents are returned. Documents can be ordered by
   // a field in an [Document][google.cloud.discoveryengine.v1alpha.Document]
   // object. Leave it unset if ordered by relevance. `order_by` expression is
-  // case-sensitive. For more information on ordering, see
+  // case-sensitive.
+  //
+  // For more information on ordering for retail search, see
   // [Ordering](https://cloud.google.com/retail/docs/filter-and-order#order)
   //
   // If this field is unrecognizable, an `INVALID_ARGUMENT` is returned.
@@ -765,7 +764,7 @@ message SearchRequest {
 
   // Boost specification to boost certain documents.
   // For more information on boosting, see
-  // [Boosting](https://cloud.google.com/retail/docs/boosting#boost)
+  // [Boosting](https://cloud.google.com/generative-ai-app-builder/docs/boost-search-results)
   BoostSpec boost_spec = 10;
 
   // Additional search parameters.
@@ -774,8 +773,7 @@ message SearchRequest {
   //
   // * `user_country_code`: string. Default empty. If set to non-empty, results
   //    are restricted or boosted based on the location provided.
-  //    Example:
-  //    user_country_code: "au"
+  //    For example, `user_country_code: "au"`
   //
   //    For available codes see [Country
   //    Codes](https://developers.google.com/custom-search/docs/json_api_reference#countryCodes)
@@ -783,8 +781,7 @@ message SearchRequest {
   // * `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.
-  //    Example:
-  //    search_type: 1
+  //    For example, `search_type: 1`
   map<string, google.protobuf.Value> params = 11;
 
   // The query expansion specification that specifies the conditions under which
@@ -886,7 +883,7 @@ message SearchResponse {
     string id = 1;
 
     // The document data snippet in the search response. Only fields that are
-    // marked as retrievable are populated.
+    // marked as `retrievable` are populated.
     Document document = 2;
 
     // The chunk data in the search response if the
@@ -918,7 +915,7 @@ message SearchResponse {
       int64 count = 3;
     }
 
-    // The key for this facet. E.g., "colors" or "price". It matches
+    // The key for this facet. For example, `"colors"` or `"price"`. It matches
     // [SearchRequest.FacetSpec.FacetKey.key][google.cloud.discoveryengine.v1alpha.SearchRequest.FacetSpec.FacetKey.key].
     string key = 1;
 
@@ -934,10 +931,10 @@ message SearchResponse {
   message GuidedSearchResult {
     // Useful attribute for search result refinements.
     message RefinementAttribute {
-      // Attribute key used to refine the results e.g. 'movie_type'.
+      // Attribute key used to refine the results. For example, `"movie_type"`.
       string attribute_key = 1;
 
-      // Attribute value used to refine the results e.g. 'drama'.
+      // Attribute value used to refine the results. For example, `"drama"`.
       string attribute_value = 2;
     }
 
@@ -948,7 +945,7 @@ message SearchResponse {
     repeated string follow_up_questions = 2;
   }
 
-  // Summary of the top N search result specified by the summary spec.
+  // Summary of the top N search results specified by the summary spec.
   message Summary {
     // Safety Attribute categories and their associated confidence scores.
     message SafetyAttributes {

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -20,6 +20,7 @@ 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/custom_tuning_model.proto";
 import "google/cloud/discoveryengine/v1alpha/import_config.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/timestamp.proto";
@@ -52,6 +53,38 @@ service SearchTuningService {
       metadata_type: "google.cloud.discoveryengine.v1alpha.TrainCustomModelMetadata"
     };
   }
+
+  // Gets a list of all the custom models.
+  rpc ListCustomModels(ListCustomModelsRequest)
+      returns (ListCustomModelsResponse) {
+    option (google.api.http) = {
+      get: "/v1alpha/{data_store=projects/*/locations/*/collections/*/dataStores/*}/customModels"
+    };
+  }
+}
+
+// Request message for
+// [SearchTuningService.ListCustomModels][google.cloud.discoveryengine.v1alpha.SearchTuningService.ListCustomModels]
+// method.
+message ListCustomModelsRequest {
+  // Required. The resource name of the parent Data Store, such as
+  // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store`.
+  // This field is used to identify the data store where to fetch the models
+  // from.
+  string data_store = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/DataStore"
+    }
+  ];
+}
+
+// Response message for
+// [SearchTuningService.ListCustomModels][google.cloud.discoveryengine.v1alpha.SearchTuningService.ListCustomModels]
+// method.
+message ListCustomModelsResponse {
+  // List of custom tuning models.
+  repeated CustomTuningModel models = 1;
 }
 
 // Request message for
@@ -118,6 +151,9 @@ message TrainCustomModelRequest {
   // The desired location of errors incurred during the data ingestion and
   // training.
   ImportErrorConfig error_config = 4;
+
+  // If not provided, a UUID will be generated.
+  string model_id = 5;
 }
 
 // Response of the
@@ -143,6 +179,9 @@ message TrainCustomModelResponse {
 
   // The metrics of the trained model.
   map<string, double> metrics = 4;
+
+  // Fully qualified name of the CustomTuningModel.
+  string model_name = 5;
 }
 
 // Metadata related to the progress of the TrainCustomModel operation. This is

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -45,6 +45,9 @@ message Session {
     Query query = 1;
 
     // 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"
     }];

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -129,6 +129,9 @@ message TargetSite {
   // Output only. This is system-generated based on the provided_uri_pattern.
   string generated_uri_pattern = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 
+  // Output only. Root domain of the provided_uri_pattern.
+  string root_domain_uri = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Output only. Site ownership and validity verification status.
   SiteVerificationInfo site_verification_info = 7
       [(google.api.field_behavior) = OUTPUT_ONLY];

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -32,7 +32,7 @@ option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1alpha";
 option ruby_package = "Google::Cloud::DiscoveryEngine::V1alpha";
 
 // UserEvent captures all metadata information Discovery Engine API needs to
-// know about how end users interact with customers' website.
+// know about how end users interact with your website.
 message UserEvent {
   // Required. User event type. Allowed values are:
   //
@@ -74,6 +74,32 @@ message UserEvent {
   // for this field.
   string user_pseudo_id = 2 [(google.api.field_behavior) = REQUIRED];
 
+  // The [Engine][google.cloud.discoveryengine.v1alpha.Engine] resource name, in
+  // the form of
+  // `projects/{project}/locations/{location}/collections/{collection_id}/engines/{engine_id}`.
+  //
+  // Optional. Only required for
+  // [Engine][google.cloud.discoveryengine.v1alpha.Engine] produced user events.
+  // For example, user events from blended search.
+  string engine = 19 [(google.api.resource_reference) = {
+    type: "discoveryengine.googleapis.com/Engine"
+  }];
+
+  // The [DataStore][google.cloud.discoveryengine.v1alpha.DataStore] resource
+  // full name, of the form
+  // `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}`.
+  //
+  // Optional. Only required for user events whose data store can't by
+  // determined by
+  // [UserEvent.engine][google.cloud.discoveryengine.v1alpha.UserEvent.engine]
+  // or
+  // [UserEvent.documents][google.cloud.discoveryengine.v1alpha.UserEvent.documents].
+  // If data store is set in the parent of write/import/collect user event
+  // requests, this field can be omitted.
+  string data_store = 20 [(google.api.resource_reference) = {
+    type: "discoveryengine.googleapis.com/DataStore"
+  }];
+
   // Only required for
   // [UserEventService.ImportUserEvents][google.cloud.discoveryengine.v1alpha.UserEventService.ImportUserEvents]
   // method. Timestamp of when the user event happened.
@@ -196,7 +222,7 @@ message UserEvent {
 
   // A list of identifiers for the independent experiment groups this user event
   // belongs to. This is used to distinguish between user events associated with
-  // different experiment setups on the customer end.
+  // different experiment setups.
   repeated string tag_ids = 15;
 
   // The promotion IDs if this is an event associated with promotions.
@@ -420,7 +446,7 @@ message DocumentInfo {
 
   // Quantity of the Document associated with the user event. Defaults to 1.
   //
-  // For example, this field will be 2 if two quantities of the same Document
+  // For example, this field is 2 if two quantities of the same Document
   // are involved in a `add-to-cart` event.
   //
   // Required for events of the following event types:

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -50,6 +50,10 @@ service UserEventService {
         post: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/userEvents:write"
         body: "user_event"
       }
+      additional_bindings {
+        post: "/v1alpha/{parent=projects/*/locations/*}/userEvents:write"
+        body: "user_event"
+      }
     };
   }
 
@@ -87,7 +91,7 @@ service UserEventService {
     };
   }
 
-  // Bulk import of User events. Request processing might be
+  // Bulk import of user events. Request processing might be
   // synchronous. Events that already exist are skipped.
   // Use this method for backfilling historical user events.
   //
@@ -113,8 +117,16 @@ service UserEventService {
 
 // Request message for WriteUserEvent method.
 message WriteUserEventRequest {
-  // Required. The parent DataStore resource name, such as
+  // Required. The parent resource name.
+  // If the write user event action is applied in
+  // [DataStore][google.cloud.discoveryengine.v1alpha.DataStore] level, the
+  // format is:
   // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}`.
+  // If the write user event action is applied in [Location][] level, for
+  // example, the event with
+  // [Document][google.cloud.discoveryengine.v1alpha.Document] across multiple
+  // [DataStore][google.cloud.discoveryengine.v1alpha.DataStore], the format is:
+  // `projects/{project}/locations/{location}`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -124,6 +136,10 @@ message WriteUserEventRequest {
 
   // Required. User event to write.
   optional UserEvent user_event = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // If set to true, the user event is written asynchronously after
+  // validation, and the API responds without waiting for the write.
+  bool write_async = 3;
 }
 
 // Request message for CollectUserEvent method.

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ package google.cloud.discoveryengine.v1beta;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
@@ -83,6 +84,10 @@ message Answer {
 
       // List of cited chunk contents derived from document content.
       repeated ChunkContent chunk_contents = 4;
+
+      // The structured JSON metadata for the document.
+      // It is populated from the struct data from the Chunk in search result.
+      google.protobuf.Struct struct_data = 5;
     }
 
     // Chunk information.
@@ -102,6 +107,10 @@ message Answer {
 
         // Page identifier.
         string page_identifier = 4;
+
+        // The structured JSON metadata for the document.
+        // It is populated from the struct data from the Chunk in search result.
+        google.protobuf.Struct struct_data = 5;
       }
 
       // Chunk resource name.
@@ -290,7 +299,7 @@ message Answer {
   }
 
   // Immutable. Fully qualified name
-  // `project/*/locations/global/collections/{collection}/engines/{engine}/sessions/*/answers/*`
+  // `projects/{project}/locations/global/collections/{collection}/engines/{engine}/sessions/*/answers/*`
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // The state of the answer generation.

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -94,6 +94,22 @@ enum SolutionType {
   SOLUTION_TYPE_GENERATIVE_CHAT = 4;
 }
 
+// Defines a further subdivision of `SolutionType`.
+// Specifically applies to
+// [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1beta.SolutionType.SOLUTION_TYPE_SEARCH].
+enum SearchUseCase {
+  // Value used when unset. Will not occur in CSS.
+  SEARCH_USE_CASE_UNSPECIFIED = 0;
+
+  // Search use case. Expects the traffic has a non-empty
+  // [query][google.cloud.discoveryengine.v1beta.SearchRequest.query].
+  SEARCH_USE_CASE_SEARCH = 1;
+
+  // Browse use case. Expects the traffic has an empty
+  // [query][google.cloud.discoveryengine.v1beta.SearchRequest.query].
+  SEARCH_USE_CASE_BROWSE = 2;
+}
+
 // Tiers of search features. Different tiers might have different
 // pricing. To learn more, check the pricing documentation.
 enum SearchTier {

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.