@google-cloud/discoveryengine 1.8.0 → 1.9.0

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

@@ -142,9 +142,9 @@ message ListSchemasRequest {
   // to return. The service may return fewer than this value.
   //
   // If unspecified, at most 100
-  // [Schema][google.cloud.discoveryengine.v1beta.Schema]s will be returned.
+  // [Schema][google.cloud.discoveryengine.v1beta.Schema]s are returned.
   //
-  // The maximum value is 1000; values above 1000 will be coerced to 1000.
+  // The maximum value is 1000; values above 1000 are set to 1000.
   int32 page_size = 2;
 
   // A page token, received from a previous
@@ -189,7 +189,7 @@ message CreateSchemaRequest {
   Schema schema = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Required. The ID to use for the
-  // [Schema][google.cloud.discoveryengine.v1beta.Schema], which will become the
+  // [Schema][google.cloud.discoveryengine.v1beta.Schema], which becomes the
   // final component of the
   // [Schema.name][google.cloud.discoveryengine.v1beta.Schema.name].
   //
@@ -209,8 +209,8 @@ message UpdateSchemaRequest {
 
   // If set to true, and the
   // [Schema][google.cloud.discoveryengine.v1beta.Schema] is not found, a new
-  // [Schema][google.cloud.discoveryengine.v1beta.Schema] will be created. In
-  // this situation, `update_mask` is ignored.
+  // [Schema][google.cloud.discoveryengine.v1beta.Schema] is created. In this
+  // situation, `update_mask` is ignored.
   bool allow_missing = 3;
 }
 

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

@@ -69,7 +69,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.v1beta.DataStore], such as
@@ -111,7 +113,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".
@@ -145,7 +147,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.
     //
@@ -255,7 +257,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;
         }
 
@@ -374,10 +376,10 @@ message SearchRequest {
       // [Mode.AUTO][google.cloud.discoveryengine.v1beta.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.v1beta.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
@@ -385,8 +387,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.v1beta.SearchRequest.SpellCorrectionSpec.Mode.AUTO].
     Mode mode = 1;
   }
@@ -441,7 +443,10 @@ message SearchRequest {
       // of results returned is less than `summaryResultCount`, the summary is
       // generated from all of the results.
       //
-      // At most 10 results can be used to generate a summary.
+      // At most 10 results for documents mode, or 50 for chunks mode, can be
+      // used to generate a summary. The chunks mode is used when
+      // [SearchRequest.ContentSearchSpec.search_result_mode][] is set to
+      // [CHUNKS][SearchRequest.ContentSearchSpec.SearchResultMode.CHUNKS].
       int32 summary_result_count = 1;
 
       // Specifies whether to include citations in the summary. The default
@@ -652,7 +657,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
@@ -689,7 +697,9 @@ message SearchRequest {
   // The order in which documents are returned. Documents can be ordered by
   // a field in an [Document][google.cloud.discoveryengine.v1beta.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.
@@ -709,7 +719,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.
@@ -718,8 +728,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)
@@ -727,8 +736,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
@@ -827,7 +835,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;
 
     // Google provided available scores.
@@ -853,7 +861,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.v1beta.SearchRequest.FacetSpec.FacetKey.key].
     string key = 1;
 
@@ -869,10 +877,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;
     }
 
@@ -883,7 +891,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 {
@@ -1094,8 +1102,6 @@ message SearchResponse {
   // Controls applied as part of the Control service.
   repeated string applied_controls = 10;
 
-  // Debug information specifically related to forward geocoding issues arising
-  // from Geolocation Search.
   repeated GeoSearchDebugInfo geo_search_debug_info = 16;
 
   // Query expansion information for the returned results.

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

@@ -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/v1beta/custom_tuning_model.proto";
 import "google/cloud/discoveryengine/v1beta/import_config.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/timestamp.proto";
@@ -52,6 +53,38 @@ service SearchTuningService {
       metadata_type: "google.cloud.discoveryengine.v1beta.TrainCustomModelMetadata"
     };
   }
+
+  // Gets a list of all the custom models.
+  rpc ListCustomModels(ListCustomModelsRequest)
+      returns (ListCustomModelsResponse) {
+    option (google.api.http) = {
+      get: "/v1beta/{data_store=projects/*/locations/*/collections/*/dataStores/*}/customModels"
+    };
+  }
+}
+
+// Request message for
+// [SearchTuningService.ListCustomModels][google.cloud.discoveryengine.v1beta.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.v1beta.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/v1beta/session.proto

@@ -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"
     }];
@@ -60,7 +63,7 @@ message Session {
   }
 
   // Immutable. Fully qualified name
-  // `project/*/locations/global/collections/{collection}/engines/{engine}/sessions/*`
+  // `projects/{project}/locations/global/collections/{collection}/engines/{engine}/sessions/*`
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // The state of the session.

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

@@ -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/v1beta/user_event.proto

@@ -32,7 +32,7 @@ option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
 option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";
 
 // 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,31 @@ message UserEvent {
   // for this field.
   string user_pseudo_id = 2 [(google.api.field_behavior) = REQUIRED];
 
+  // The [Engine][google.cloud.discoveryengine.v1beta.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.v1beta.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.v1beta.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.v1beta.UserEvent.engine] or
+  // [UserEvent.documents][google.cloud.discoveryengine.v1beta.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.v1beta.UserEventService.ImportUserEvents]
   // method. Timestamp of when the user event happened.
@@ -196,7 +221,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.
@@ -419,7 +444,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/v1beta/user_event_service.proto

@@ -49,6 +49,10 @@ service UserEventService {
         post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/userEvents:write"
         body: "user_event"
       }
+      additional_bindings {
+        post: "/v1beta/{parent=projects/*/locations/*}/userEvents:write"
+        body: "user_event"
+      }
     };
   }
 
@@ -66,7 +70,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.
   //
@@ -92,8 +96,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.v1beta.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.v1beta.Document] across multiple
+  // [DataStore][google.cloud.discoveryengine.v1beta.DataStore], the format is:
+  // `projects/{project}/locations/{location}`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -103,6 +115,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.