1// Copyright 2022 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.discoveryengine.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/cloud/discoveryengine/v1/common.proto"; 24import "google/cloud/discoveryengine/v1/document.proto"; 25import "google/protobuf/struct.proto"; 26 27option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1"; 28option go_package = "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb;discoveryenginepb"; 29option java_multiple_files = true; 30option java_outer_classname = "SearchServiceProto"; 31option java_package = "com.google.cloud.discoveryengine.v1"; 32option objc_class_prefix = "DISCOVERYENGINE"; 33option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1"; 34option ruby_package = "Google::Cloud::DiscoveryEngine::V1"; 35 36// Service for search. 37service SearchService { 38 option (google.api.default_host) = "discoveryengine.googleapis.com"; 39 option (google.api.oauth_scopes) = 40 "https://www.googleapis.com/auth/cloud-platform"; 41 42 // Performs a search. 43 rpc Search(SearchRequest) returns (SearchResponse) { 44 option (google.api.http) = { 45 post: "/v1/{serving_config=projects/*/locations/*/dataStores/*/servingConfigs/*}:search" 46 body: "*" 47 additional_bindings { 48 post: "/v1/{serving_config=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:search" 49 body: "*" 50 } 51 additional_bindings { 52 post: "/v1/{serving_config=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:search" 53 body: "*" 54 } 55 }; 56 } 57} 58 59// Request message for 60// [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search] 61// method. 62message SearchRequest { 63 // Specifies the image query input. 64 message ImageQuery { 65 oneof image { 66 // Base64 encoded image bytes. Supported image formats: JPEG, PNG, and 67 // BMP. 68 string image_bytes = 1; 69 } 70 } 71 72 // A struct to define data stores to filter on in a search call. 73 message DataStoreSpec { 74 // Required. Full resource name of 75 // [DataStore][google.cloud.discoveryengine.v1.DataStore], such as 76 // `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}`. 77 string data_store = 1 [ 78 (google.api.field_behavior) = REQUIRED, 79 (google.api.resource_reference) = { 80 type: "discoveryengine.googleapis.com/DataStore" 81 } 82 ]; 83 } 84 85 // A facet specification to perform faceted search. 86 message FacetSpec { 87 // Specifies how a facet is computed. 88 message FacetKey { 89 // Required. Supported textual and numerical facet keys in 90 // [Document][google.cloud.discoveryengine.v1.Document] object, over which 91 // the facet values are computed. Facet key is case-sensitive. 92 string key = 1 [(google.api.field_behavior) = REQUIRED]; 93 94 // Set only if values should be bucketed into intervals. Must be set 95 // for facets with numerical values. Must not be set for facet with text 96 // values. Maximum number of intervals is 30. 97 repeated Interval intervals = 2; 98 99 // Only get facet for the given restricted values. Only supported on 100 // textual fields. For example, suppose "category" has three values 101 // "Action > 2022", "Action > 2021" and "Sci-Fi > 2022". If set 102 // "restricted_values" to "Action > 2022", the "category" facet only 103 // contains "Action > 2022". Only supported on textual fields. Maximum 104 // is 10. 105 repeated string restricted_values = 3; 106 107 // Only get facet values that start with the given string prefix. For 108 // example, suppose "category" has three values "Action > 2022", 109 // "Action > 2021" and "Sci-Fi > 2022". If set "prefixes" to "Action", the 110 // "category" facet only contains "Action > 2022" and "Action > 2021". 111 // Only supported on textual fields. Maximum is 10. 112 repeated string prefixes = 4; 113 114 // Only get facet values that contains the given strings. For example, 115 // suppose "category" has three values "Action > 2022", 116 // "Action > 2021" and "Sci-Fi > 2022". If set "contains" to "2022", the 117 // "category" facet only contains "Action > 2022" and "Sci-Fi > 2022". 118 // Only supported on textual fields. Maximum is 10. 119 repeated string contains = 5; 120 121 // True to make facet keys case insensitive when getting faceting 122 // values with prefixes or contains; false otherwise. 123 bool case_insensitive = 6; 124 125 // The order in which documents are returned. 126 // 127 // Allowed values are: 128 // 129 // * "count desc", which means order by 130 // [SearchResponse.Facet.values.count][google.cloud.discoveryengine.v1.SearchResponse.Facet.FacetValue.count] 131 // descending. 132 // 133 // * "value desc", which means order by 134 // [SearchResponse.Facet.values.value][google.cloud.discoveryengine.v1.SearchResponse.Facet.FacetValue.value] 135 // descending. 136 // Only applies to textual facets. 137 // 138 // If not set, textual values are sorted in [natural 139 // order](https://en.wikipedia.org/wiki/Natural_sort_order); numerical 140 // intervals are sorted in the order given by 141 // [FacetSpec.FacetKey.intervals][google.cloud.discoveryengine.v1.SearchRequest.FacetSpec.FacetKey.intervals]. 142 string order_by = 7; 143 } 144 145 // Required. The facet key specification. 146 FacetKey facet_key = 1 [(google.api.field_behavior) = REQUIRED]; 147 148 // Maximum of facet values that should be returned for this facet. If 149 // unspecified, defaults to 20. The maximum allowed value is 300. Values 150 // above 300 are coerced to 300. 151 // 152 // If this field is negative, an `INVALID_ARGUMENT` is returned. 153 int32 limit = 2; 154 155 // List of keys to exclude when faceting. 156 // 157 // 158 // By default, 159 // [FacetKey.key][google.cloud.discoveryengine.v1.SearchRequest.FacetSpec.FacetKey.key] 160 // is not excluded from the filter unless it is listed in this field. 161 // 162 // Listing a facet key in this field allows its values to appear as facet 163 // results, even when they are filtered out of search results. Using this 164 // field does not affect what search results are returned. 165 // 166 // For example, suppose there are 100 documents with the color facet "Red" 167 // and 200 documents with the color facet "Blue". A query containing the 168 // filter "color:ANY("Red")" and having "color" as 169 // [FacetKey.key][google.cloud.discoveryengine.v1.SearchRequest.FacetSpec.FacetKey.key] 170 // would by default return only "Red" documents in the search results, and 171 // also return "Red" with count 100 as the only color facet. Although there 172 // are also blue documents available, "Blue" would not be shown as an 173 // available facet value. 174 // 175 // If "color" is listed in "excludedFilterKeys", then the query returns the 176 // facet values "Red" with count 100 and "Blue" with count 200, because the 177 // "color" key is now excluded from the filter. Because this field doesn't 178 // affect search results, the search results are still correctly filtered to 179 // return only "Red" documents. 180 // 181 // A maximum of 100 values are allowed. Otherwise, an `INVALID_ARGUMENT` 182 // error is returned. 183 repeated string excluded_filter_keys = 3; 184 185 // Enables dynamic position for this facet. If set to true, the position of 186 // this facet among all facets in the response is determined automatically. 187 // If dynamic facets are enabled, it is ordered together. 188 // If set to false, the position of this facet in the 189 // response is the same as in the request, and it is ranked before 190 // the facets with dynamic position enable and all dynamic facets. 191 // 192 // For example, you may always want to have rating facet returned in 193 // the response, but it's not necessarily to always display the rating facet 194 // at the top. In that case, you can set enable_dynamic_position to true so 195 // that the position of rating facet in response is determined 196 // automatically. 197 // 198 // Another example, assuming you have the following facets in the request: 199 // 200 // * "rating", enable_dynamic_position = true 201 // 202 // * "price", enable_dynamic_position = false 203 // 204 // * "brands", enable_dynamic_position = false 205 // 206 // And also you have a dynamic facets enabled, which generates a facet 207 // `gender`. Then the final order of the facets in the response can be 208 // ("price", "brands", "rating", "gender") or ("price", "brands", "gender", 209 // "rating") depends on how API orders "gender" and "rating" facets. 210 // However, notice that "price" and "brands" are always 211 // ranked at first and second position because their enable_dynamic_position 212 // is false. 213 bool enable_dynamic_position = 4; 214 } 215 216 // Boost specification to boost certain documents. 217 message BoostSpec { 218 // Boost applies to documents which match a condition. 219 message ConditionBoostSpec { 220 // An expression which specifies a boost condition. The syntax and 221 // supported fields are the same as a filter expression. See 222 // [SearchRequest.filter][google.cloud.discoveryengine.v1.SearchRequest.filter] 223 // for detail syntax and limitations. 224 // 225 // Examples: 226 // 227 // * To boost documents with document ID "doc_1" or "doc_2", and 228 // color "Red" or "Blue": 229 // `(document_id: ANY("doc_1", "doc_2")) AND (color: ANY("Red", "Blue"))` 230 string condition = 1; 231 232 // Strength of the condition boost, which should be in [-1, 1]. Negative 233 // boost means demotion. Default is 0.0. 234 // 235 // Setting to 1.0 gives the document a big promotion. However, it does 236 // not necessarily mean that the boosted document will be the top result 237 // at all times, nor that other documents will be excluded. Results 238 // could still be shown even when none of them matches the condition. 239 // And results that are significantly more relevant to the search query 240 // can still trump your heavily favored but irrelevant documents. 241 // 242 // Setting to -1.0 gives the document a big demotion. However, results 243 // that are deeply relevant might still be shown. The document will have 244 // an upstream battle to get a fairly high ranking, but it is not 245 // blocked out completely. 246 // 247 // Setting to 0.0 means no boost applied. The boosting condition is 248 // ignored. Only one of the (condition, boost) combination or the 249 // boost_control_spec below are set. If both are set then the global boost 250 // is ignored and the more fine-grained boost_control_spec is applied. 251 float boost = 2; 252 } 253 254 // Condition boost specifications. If a document matches multiple conditions 255 // in the specifictions, boost scores from these specifications are all 256 // applied and combined in a non-linear way. Maximum number of 257 // specifications is 20. 258 repeated ConditionBoostSpec condition_boost_specs = 1; 259 } 260 261 // Specification to determine under which conditions query expansion should 262 // occur. 263 message QueryExpansionSpec { 264 // Enum describing under which condition query expansion should occur. 265 enum Condition { 266 // Unspecified query expansion condition. In this case, server behavior 267 // defaults to 268 // [Condition.DISABLED][google.cloud.discoveryengine.v1.SearchRequest.QueryExpansionSpec.Condition.DISABLED]. 269 CONDITION_UNSPECIFIED = 0; 270 271 // Disabled query expansion. Only the exact search query is used, even if 272 // [SearchResponse.total_size][google.cloud.discoveryengine.v1.SearchResponse.total_size] 273 // is zero. 274 DISABLED = 1; 275 276 // Automatic query expansion built by the Search API. 277 AUTO = 2; 278 } 279 280 // The condition under which query expansion should occur. Default to 281 // [Condition.DISABLED][google.cloud.discoveryengine.v1.SearchRequest.QueryExpansionSpec.Condition.DISABLED]. 282 Condition condition = 1; 283 284 // Whether to pin unexpanded results. If this field is set to true, 285 // unexpanded products are always at the top of the search results, followed 286 // by the expanded results. 287 bool pin_unexpanded_results = 2; 288 } 289 290 // The specification for query spell correction. 291 message SpellCorrectionSpec { 292 // Enum describing under which mode spell correction should occur. 293 enum Mode { 294 // Unspecified spell correction mode. In this case, server behavior 295 // defaults to 296 // [Mode.AUTO][google.cloud.discoveryengine.v1.SearchRequest.SpellCorrectionSpec.Mode.AUTO]. 297 MODE_UNSPECIFIED = 0; 298 299 // Search API will try to find a spell suggestion if there 300 // is any and put in the 301 // [SearchResponse.corrected_query][google.cloud.discoveryengine.v1.SearchResponse.corrected_query]. 302 // The spell suggestion will not be used as the search query. 303 SUGGESTION_ONLY = 1; 304 305 // Automatic spell correction built by the Search API. Search will 306 // be based on the corrected query if found. 307 AUTO = 2; 308 } 309 310 // The mode under which spell correction should take effect to 311 // replace the original search query. Default to 312 // [Mode.AUTO][google.cloud.discoveryengine.v1.SearchRequest.SpellCorrectionSpec.Mode.AUTO]. 313 Mode mode = 1; 314 } 315 316 // A specification for configuring the behavior of content search. 317 message ContentSearchSpec { 318 // A specification for configuring snippets in a search response. 319 message SnippetSpec { 320 // [DEPRECATED] This field is deprecated. To control snippet return, use 321 // `return_snippet` field. For backwards compatibility, we will return 322 // snippet if max_snippet_count > 0. 323 int32 max_snippet_count = 1 [deprecated = true]; 324 325 // [DEPRECATED] This field is deprecated and will have no affect on the 326 // snippet. 327 bool reference_only = 2 [deprecated = true]; 328 329 // If `true`, then return snippet. If no snippet can be generated, we 330 // return "No snippet is available for this page." A `snippet_status` with 331 // `SUCCESS` or `NO_SNIPPET_AVAILABLE` will also be returned. 332 bool return_snippet = 3; 333 } 334 335 // A specification for configuring a summary returned in a search 336 // response. 337 message SummarySpec { 338 // Specification of the prompt to use with the model. 339 message ModelPromptSpec { 340 // Text at the beginning of the prompt that instructs the assistant. 341 // Examples are available in the user guide. 342 string preamble = 1; 343 } 344 345 // Specification of the model. 346 message ModelSpec { 347 // The model version used to generate the summary. 348 // 349 // Supported values are: 350 // 351 // * `stable`: string. Default value when no value is specified. Uses a 352 // generally available, fine-tuned model. For more information, see 353 // [Answer generation model versions and 354 // lifecycle](https://cloud.google.com/generative-ai-app-builder/docs/answer-generation-models). 355 // * `preview`: string. (Public preview) Uses a preview model. For more 356 // information, see 357 // [Answer generation model versions and 358 // lifecycle](https://cloud.google.com/generative-ai-app-builder/docs/answer-generation-models). 359 string version = 1; 360 } 361 362 // The number of top results to generate the summary from. If the number 363 // of results returned is less than `summaryResultCount`, the summary is 364 // generated from all of the results. 365 // 366 // At most 10 results for documents mode, or 50 for chunks mode, can be 367 // used to generate a summary. The chunks mode is used when 368 // [SearchRequest.ContentSearchSpec.search_result_mode][] is set to 369 // [CHUNKS][SearchRequest.ContentSearchSpec.SearchResultMode.CHUNKS]. 370 int32 summary_result_count = 1; 371 372 // Specifies whether to include citations in the summary. The default 373 // value is `false`. 374 // 375 // When this field is set to `true`, summaries include in-line citation 376 // numbers. 377 // 378 // Example summary including citations: 379 // 380 // BigQuery is Google Cloud's fully managed and completely serverless 381 // enterprise data warehouse [1]. BigQuery supports all data types, works 382 // across clouds, and has built-in machine learning and business 383 // intelligence, all within a unified platform [2, 3]. 384 // 385 // The citation numbers refer to the returned search results and are 386 // 1-indexed. For example, [1] means that the sentence is attributed to 387 // the first search result. [2, 3] means that the sentence is attributed 388 // to both the second and third search results. 389 bool include_citations = 2; 390 391 // Specifies whether to filter out adversarial queries. The default value 392 // is `false`. 393 // 394 // Google employs search-query classification to detect adversarial 395 // queries. No summary is returned if the search query is classified as an 396 // adversarial query. For example, a user might ask a question regarding 397 // negative comments about the company or submit a query designed to 398 // generate unsafe, policy-violating output. If this field is set to 399 // `true`, we skip generating summaries for adversarial queries and return 400 // fallback messages instead. 401 bool ignore_adversarial_query = 3; 402 403 // Specifies whether to filter out queries that are not summary-seeking. 404 // The default value is `false`. 405 // 406 // Google employs search-query classification to detect summary-seeking 407 // queries. No summary is returned if the search query is classified as a 408 // non-summary seeking query. For example, `why is the sky blue` and `Who 409 // is the best soccer player in the world?` are summary-seeking queries, 410 // but `SFO airport` and `world cup 2026` are not. They are most likely 411 // navigational queries. If this field is set to `true`, we skip 412 // generating summaries for non-summary seeking queries and return 413 // fallback messages instead. 414 bool ignore_non_summary_seeking_query = 4; 415 416 // If specified, the spec will be used to modify the prompt provided to 417 // the LLM. 418 ModelPromptSpec model_prompt_spec = 5; 419 420 // Language code for Summary. Use language tags defined by 421 // [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). 422 // Note: This is an experimental feature. 423 string language_code = 6; 424 425 // If specified, the spec will be used to modify the model specification 426 // provided to the LLM. 427 ModelSpec model_spec = 7; 428 429 // If true, answer will be generated from most relevant chunks from top 430 // search results. This feature will improve summary quality. 431 // Note that with this feature enabled, not all top search results 432 // will be referenced and included in the reference list, so the citation 433 // source index only points to the search results listed in the reference 434 // list. 435 bool use_semantic_chunks = 8; 436 } 437 438 // A specification for configuring the extractive content in a search 439 // response. 440 message ExtractiveContentSpec { 441 // The maximum number of extractive answers returned in each search 442 // result. 443 // 444 // An extractive answer is a verbatim answer extracted from the original 445 // document, which provides a precise and contextually relevant answer to 446 // the search query. 447 // 448 // If the number of matching answers is less than the 449 // `max_extractive_answer_count`, return all of the answers. Otherwise, 450 // return the `max_extractive_answer_count`. 451 // 452 // At most five answers are returned for each 453 // [SearchResult][google.cloud.discoveryengine.v1.SearchResponse.SearchResult]. 454 int32 max_extractive_answer_count = 1; 455 456 // The max number of extractive segments returned in each search result. 457 // Only applied if the 458 // [DataStore][google.cloud.discoveryengine.v1.DataStore] is set to 459 // [DataStore.ContentConfig.CONTENT_REQUIRED][google.cloud.discoveryengine.v1.DataStore.ContentConfig.CONTENT_REQUIRED] 460 // or 461 // [DataStore.solution_types][google.cloud.discoveryengine.v1.DataStore.solution_types] 462 // is 463 // [SOLUTION_TYPE_CHAT][google.cloud.discoveryengine.v1.SolutionType.SOLUTION_TYPE_CHAT]. 464 // 465 // An extractive segment is a text segment extracted from the original 466 // document that is relevant to the search query, and, in general, more 467 // verbose than an extractive answer. The segment could then be used as 468 // input for LLMs to generate summaries and answers. 469 // 470 // If the number of matching segments is less than 471 // `max_extractive_segment_count`, return all of the segments. Otherwise, 472 // return the `max_extractive_segment_count`. 473 int32 max_extractive_segment_count = 2; 474 475 // Specifies whether to return the confidence score from the extractive 476 // segments in each search result. This feature is available only for new 477 // or allowlisted data stores. To allowlist your data store, 478 // contact your Customer Engineer. The default value is `false`. 479 bool return_extractive_segment_score = 3; 480 481 // Specifies whether to also include the adjacent from each selected 482 // segments. 483 // Return at most `num_previous_segments` segments before each selected 484 // segments. 485 int32 num_previous_segments = 4; 486 487 // Return at most `num_next_segments` segments after each selected 488 // segments. 489 int32 num_next_segments = 5; 490 } 491 492 // If `snippetSpec` is not specified, snippets are not included in the 493 // search response. 494 SnippetSpec snippet_spec = 1; 495 496 // If `summarySpec` is not specified, summaries are not included in the 497 // search response. 498 SummarySpec summary_spec = 2; 499 500 // If there is no extractive_content_spec provided, there will be no 501 // extractive answer in the search response. 502 ExtractiveContentSpec extractive_content_spec = 3; 503 } 504 505 // Required. The resource name of the Search serving config, such as 506 // `projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config`, 507 // or 508 // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config`. 509 // This field is used to identify the serving configuration name, set 510 // of models used to make the search. 511 string serving_config = 1 [ 512 (google.api.field_behavior) = REQUIRED, 513 (google.api.resource_reference) = { 514 type: "discoveryengine.googleapis.com/ServingConfig" 515 } 516 ]; 517 518 // The branch resource name, such as 519 // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0`. 520 // 521 // Use `default_branch` as the branch ID or leave this field empty, to search 522 // documents under the default branch. 523 string branch = 2 [(google.api.resource_reference) = { 524 type: "discoveryengine.googleapis.com/Branch" 525 }]; 526 527 // Raw search query. 528 string query = 3; 529 530 // Raw image query. 531 ImageQuery image_query = 19; 532 533 // Maximum number of [Document][google.cloud.discoveryengine.v1.Document]s to 534 // return. The maximum allowed value depends on the data type. Values above 535 // the maximum value are coerced to the maximum value. 536 // 537 // * Websites with basic indexing: Default `10`, Maximum `25`. 538 // * Websites with advanced indexing: Default `25`, Maximum `50`. 539 // * Other: Default `50`, Maximum `100`. 540 // 541 // If this field is negative, an `INVALID_ARGUMENT` is returned. 542 int32 page_size = 4; 543 544 // A page token received from a previous 545 // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search] 546 // call. Provide this to retrieve the subsequent page. 547 // 548 // When paginating, all other parameters provided to 549 // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search] 550 // must match the call that provided the page token. Otherwise, an 551 // `INVALID_ARGUMENT` error is returned. 552 string page_token = 5; 553 554 // A 0-indexed integer that specifies the current offset (that is, starting 555 // result location, amongst the 556 // [Document][google.cloud.discoveryengine.v1.Document]s deemed by the API as 557 // relevant) in search results. This field is only considered if 558 // [page_token][google.cloud.discoveryengine.v1.SearchRequest.page_token] is 559 // unset. 560 // 561 // If this field is negative, an `INVALID_ARGUMENT` is returned. 562 int32 offset = 6; 563 564 // A list of data store specs to apply on a search call. 565 repeated DataStoreSpec data_store_specs = 32; 566 567 // The filter syntax consists of an expression language for constructing a 568 // predicate from one or more fields of the documents being filtered. Filter 569 // expression is case-sensitive. 570 // 571 // If this field is unrecognizable, an `INVALID_ARGUMENT` is returned. 572 // 573 // Filtering in Vertex AI Search is done by mapping the LHS filter key to a 574 // key property defined in the Vertex AI Search backend -- this mapping is 575 // defined by the customer in their schema. For example a media customer might 576 // have a field 'name' in their schema. In this case the filter would look 577 // like this: filter --> name:'ANY("king kong")' 578 // 579 // For more information about filtering including syntax and filter 580 // operators, see 581 // [Filter](https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata) 582 string filter = 7; 583 584 // The default filter that is applied when a user performs a search without 585 // checking any filters on the search page. 586 // 587 // The filter applied to every search request when quality improvement such as 588 // query expansion is needed. In the case a query does not have a sufficient 589 // amount of results this filter will be used to determine whether or not to 590 // enable the query expansion flow. The original filter will still be used for 591 // the query expanded search. 592 // This field is strongly recommended to achieve high search quality. 593 // 594 // For more information about filter syntax, see 595 // [SearchRequest.filter][google.cloud.discoveryengine.v1.SearchRequest.filter]. 596 string canonical_filter = 29; 597 598 // The order in which documents are returned. Documents can be ordered by 599 // a field in an [Document][google.cloud.discoveryengine.v1.Document] object. 600 // Leave it unset if ordered by relevance. `order_by` expression is 601 // case-sensitive. For more information on ordering, see 602 // [Ordering](https://cloud.google.com/retail/docs/filter-and-order#order) 603 // 604 // If this field is unrecognizable, an `INVALID_ARGUMENT` is returned. 605 string order_by = 8; 606 607 // Information about the end user. 608 // Highly recommended for analytics. 609 // [UserInfo.user_agent][google.cloud.discoveryengine.v1.UserInfo.user_agent] 610 // is used to deduce `device_type` for analytics. 611 UserInfo user_info = 21; 612 613 // Facet specifications for faceted search. If empty, no facets are returned. 614 // 615 // A maximum of 100 values are allowed. Otherwise, an `INVALID_ARGUMENT` 616 // error is returned. 617 repeated FacetSpec facet_specs = 9; 618 619 // Boost specification to boost certain documents. 620 // For more information on boosting, see 621 // [Boosting](https://cloud.google.com/retail/docs/boosting#boost) 622 BoostSpec boost_spec = 10; 623 624 // Additional search parameters. 625 // 626 // For public website search only, supported values are: 627 // 628 // * `user_country_code`: string. Default empty. If set to non-empty, results 629 // are restricted or boosted based on the location provided. 630 // Example: 631 // user_country_code: "au" 632 // 633 // For available codes see [Country 634 // Codes](https://developers.google.com/custom-search/docs/json_api_reference#countryCodes) 635 // 636 // * `search_type`: double. Default empty. Enables non-webpage searching 637 // depending on the value. The only valid non-default value is 1, 638 // which enables image searching. 639 // Example: 640 // search_type: 1 641 map<string, google.protobuf.Value> params = 11; 642 643 // The query expansion specification that specifies the conditions under which 644 // query expansion occurs. 645 QueryExpansionSpec query_expansion_spec = 13; 646 647 // The spell correction specification that specifies the mode under 648 // which spell correction takes effect. 649 SpellCorrectionSpec spell_correction_spec = 14; 650 651 // A unique identifier for tracking visitors. For example, this could be 652 // implemented with an HTTP cookie, which should be able to uniquely identify 653 // a visitor on a single device. This unique identifier should not change if 654 // the visitor logs in or out of the website. 655 // 656 // This field should NOT have a fixed value such as `unknown_visitor`. 657 // 658 // This should be the same identifier as 659 // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1.UserEvent.user_pseudo_id] 660 // and 661 // [CompleteQueryRequest.user_pseudo_id][google.cloud.discoveryengine.v1.CompleteQueryRequest.user_pseudo_id] 662 // 663 // The field must be a UTF-8 encoded string with a length limit of 128 664 // characters. Otherwise, an `INVALID_ARGUMENT` error is returned. 665 string user_pseudo_id = 15; 666 667 // A specification for configuring the behavior of content search. 668 ContentSearchSpec content_search_spec = 24; 669 670 // Whether to turn on safe search. This is only supported for 671 // website search. 672 bool safe_search = 20; 673 674 // The user labels applied to a resource must meet the following requirements: 675 // 676 // * Each resource can have multiple labels, up to a maximum of 64. 677 // * Each label must be a key-value pair. 678 // * Keys have a minimum length of 1 character and a maximum length of 63 679 // characters and cannot be empty. Values can be empty and have a maximum 680 // length of 63 characters. 681 // * Keys and values can contain only lowercase letters, numeric characters, 682 // underscores, and dashes. All characters must use UTF-8 encoding, and 683 // international characters are allowed. 684 // * The key portion of a label must be unique. However, you can use the same 685 // key with multiple resources. 686 // * Keys must start with a lowercase letter or international character. 687 // 688 // See [Google Cloud 689 // Document](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements) 690 // for more details. 691 map<string, string> user_labels = 22; 692} 693 694// Response message for 695// [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search] 696// method. 697message SearchResponse { 698 // Represents the search results. 699 message SearchResult { 700 // [Document.id][google.cloud.discoveryengine.v1.Document.id] of the 701 // searched [Document][google.cloud.discoveryengine.v1.Document]. 702 string id = 1; 703 704 // The document data snippet in the search response. Only fields that are 705 // marked as retrievable are populated. 706 Document document = 2; 707 } 708 709 // A facet result. 710 message Facet { 711 // A facet value which contains value names and their count. 712 message FacetValue { 713 // A facet value which contains values. 714 oneof facet_value { 715 // Text value of a facet, such as "Black" for facet "colors". 716 string value = 1; 717 718 // Interval value for a facet, such as [10, 20) for facet "price". It 719 // matches 720 // [SearchRequest.FacetSpec.FacetKey.intervals][google.cloud.discoveryengine.v1.SearchRequest.FacetSpec.FacetKey.intervals]. 721 Interval interval = 2; 722 } 723 724 // Number of items that have this facet value. 725 int64 count = 3; 726 } 727 728 // The key for this facet. E.g., "colors" or "price". It matches 729 // [SearchRequest.FacetSpec.FacetKey.key][google.cloud.discoveryengine.v1.SearchRequest.FacetSpec.FacetKey.key]. 730 string key = 1; 731 732 // The facet values for this field. 733 repeated FacetValue values = 2; 734 735 // Whether the facet is dynamically generated. 736 bool dynamic_facet = 3; 737 } 738 739 // Summary of the top N search result specified by the summary spec. 740 message Summary { 741 // Safety Attribute categories and their associated confidence scores. 742 message SafetyAttributes { 743 // The display names of Safety Attribute categories associated with the 744 // generated content. Order matches the Scores. 745 repeated string categories = 1; 746 747 // The confidence scores of the each category, higher 748 // value means higher confidence. Order matches the Categories. 749 repeated float scores = 2; 750 } 751 752 // Citation metadata. 753 message CitationMetadata { 754 // Citations for segments. 755 repeated Citation citations = 1; 756 } 757 758 // Citation info for a segment. 759 message Citation { 760 // Index indicates the start of the segment, measured in bytes/unicode. 761 int64 start_index = 1; 762 763 // End of the attributed segment, exclusive. 764 int64 end_index = 2; 765 766 // Citation sources for the attributed segment. 767 repeated CitationSource sources = 3; 768 } 769 770 // Citation source. 771 message CitationSource { 772 // Document reference index from SummaryWithMetadata.references. 773 // It is 0-indexed and the value will be zero if the reference_index is 774 // not set explicitly. 775 int64 reference_index = 4; 776 } 777 778 // Document reference. 779 message Reference { 780 // Chunk content. 781 message ChunkContent { 782 // Chunk textual content. 783 string content = 1; 784 785 // Page identifier. 786 string page_identifier = 2; 787 } 788 789 // Title of the document. 790 string title = 1; 791 792 // Required. 793 // [Document.name][google.cloud.discoveryengine.v1.Document.name] of the 794 // document. Full resource name of the referenced document, in the format 795 // `projects/*/locations/*/collections/*/dataStores/*/branches/*/documents/*`. 796 string document = 2 [ 797 (google.api.field_behavior) = REQUIRED, 798 (google.api.resource_reference) = { 799 type: "discoveryengine.googleapis.com/Document" 800 } 801 ]; 802 803 // Cloud Storage or HTTP uri for the document. 804 string uri = 3; 805 806 // List of cited chunk contents derived from document content. 807 repeated ChunkContent chunk_contents = 4; 808 } 809 810 // Summary with metadata information. 811 message SummaryWithMetadata { 812 // Summary text with no citation information. 813 string summary = 1; 814 815 // Citation metadata for given summary. 816 CitationMetadata citation_metadata = 2; 817 818 // Document References. 819 repeated Reference references = 3; 820 } 821 822 // An Enum for summary-skipped reasons. 823 enum SummarySkippedReason { 824 // Default value. The summary skipped reason is not specified. 825 SUMMARY_SKIPPED_REASON_UNSPECIFIED = 0; 826 827 // The adversarial query ignored case. 828 // 829 // Only populated when 830 // [SummarySpec.ignore_adversarial_query][google.cloud.discoveryengine.v1.SearchRequest.ContentSearchSpec.SummarySpec.ignore_adversarial_query] 831 // is set to `true`. 832 ADVERSARIAL_QUERY_IGNORED = 1; 833 834 // The non-summary seeking query ignored case. 835 // 836 // Only populated when 837 // [SummarySpec.ignore_non_summary_seeking_query][google.cloud.discoveryengine.v1.SearchRequest.ContentSearchSpec.SummarySpec.ignore_non_summary_seeking_query] 838 // is set to `true`. 839 NON_SUMMARY_SEEKING_QUERY_IGNORED = 2; 840 841 // The out-of-domain query ignored case. 842 // 843 // Google skips the summary if there are no high-relevance search results. 844 // For example, the data store contains facts about company A but the 845 // user query is asking questions about company B. 846 OUT_OF_DOMAIN_QUERY_IGNORED = 3; 847 848 // The potential policy violation case. 849 // 850 // Google skips the summary if there is a potential policy violation 851 // detected. This includes content that may be violent or toxic. 852 POTENTIAL_POLICY_VIOLATION = 4; 853 854 // The LLM addon not enabled case. 855 // 856 // Google skips the summary if the LLM addon is not enabled. 857 LLM_ADDON_NOT_ENABLED = 5; 858 } 859 860 // The summary content. 861 string summary_text = 1; 862 863 // Additional summary-skipped reasons. This provides the reason for ignored 864 // cases. If nothing is skipped, this field is not set. 865 repeated SummarySkippedReason summary_skipped_reasons = 2; 866 867 // A collection of Safety Attribute categories and their associated 868 // confidence scores. 869 SafetyAttributes safety_attributes = 3; 870 871 // Summary with metadata information. 872 SummaryWithMetadata summary_with_metadata = 4; 873 } 874 875 // Information describing query expansion including whether expansion has 876 // occurred. 877 message QueryExpansionInfo { 878 // Bool describing whether query expansion has occurred. 879 bool expanded_query = 1; 880 881 // Number of pinned results. This field will only be set when expansion 882 // happens and 883 // [SearchRequest.QueryExpansionSpec.pin_unexpanded_results][google.cloud.discoveryengine.v1.SearchRequest.QueryExpansionSpec.pin_unexpanded_results] 884 // is set to true. 885 int64 pinned_result_count = 2; 886 } 887 888 // A list of matched documents. The order represents the ranking. 889 repeated SearchResult results = 1; 890 891 // Results of facets requested by user. 892 repeated Facet facets = 2; 893 894 // The estimated total count of matched items irrespective of pagination. The 895 // count of [results][google.cloud.discoveryengine.v1.SearchResponse.results] 896 // returned by pagination may be less than the 897 // [total_size][google.cloud.discoveryengine.v1.SearchResponse.total_size] 898 // that matches. 899 int32 total_size = 3; 900 901 // A unique search token. This should be included in the 902 // [UserEvent][google.cloud.discoveryengine.v1.UserEvent] logs resulting from 903 // this search, which enables accurate attribution of search model 904 // performance. 905 string attribution_token = 4; 906 907 // The URI of a customer-defined redirect page. If redirect action is 908 // triggered, no search is performed, and only 909 // [redirect_uri][google.cloud.discoveryengine.v1.SearchResponse.redirect_uri] 910 // and 911 // [attribution_token][google.cloud.discoveryengine.v1.SearchResponse.attribution_token] 912 // are set in the response. 913 string redirect_uri = 12; 914 915 // A token that can be sent as 916 // [SearchRequest.page_token][google.cloud.discoveryengine.v1.SearchRequest.page_token] 917 // to retrieve the next page. If this field is omitted, there are no 918 // subsequent pages. 919 string next_page_token = 5; 920 921 // Contains the spell corrected query, if found. If the spell correction type 922 // is AUTOMATIC, then the search results are based on corrected_query. 923 // Otherwise the original query is used for search. 924 string corrected_query = 7; 925 926 // A summary as part of the search results. 927 // This field is only returned if 928 // [SearchRequest.ContentSearchSpec.summary_spec][google.cloud.discoveryengine.v1.SearchRequest.ContentSearchSpec.summary_spec] 929 // is set. 930 Summary summary = 9; 931 932 // Query expansion information for the returned results. 933 QueryExpansionInfo query_expansion_info = 14; 934} 935