xref: /aosp_15_r20/external/googleapis/google/cloud/discoveryengine/v1/search_service.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)
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