xref: /aosp_15_r20/external/googleapis/google/cloud/retail/v2alpha/completion_service.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)
1// Copyright 2021 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.retail.v2alpha;
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/retail/v2alpha/common.proto";
24import "google/cloud/retail/v2alpha/import_config.proto";
25import "google/cloud/retail/v2alpha/search_service.proto";
26import "google/longrunning/operations.proto";
27
28option csharp_namespace = "Google.Cloud.Retail.V2Alpha";
29option go_package = "cloud.google.com/go/retail/apiv2alpha/retailpb;retailpb";
30option java_multiple_files = true;
31option java_outer_classname = "CompletionServiceProto";
32option java_package = "com.google.cloud.retail.v2alpha";
33option objc_class_prefix = "RETAIL";
34option php_namespace = "Google\\Cloud\\Retail\\V2alpha";
35option ruby_package = "Google::Cloud::Retail::V2alpha";
36
37// Autocomplete service for retail.
38//
39// This feature is only available for users who have Retail Search enabled.
40// Enable Retail Search on Cloud Console before using this feature.
41service CompletionService {
42  option (google.api.default_host) = "retail.googleapis.com";
43  option (google.api.oauth_scopes) =
44      "https://www.googleapis.com/auth/cloud-platform";
45
46  // Completes the specified prefix with keyword suggestions.
47  //
48  // This feature is only available for users who have Retail Search enabled.
49  // Enable Retail Search on Cloud Console before using this feature.
50  rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
51    option (google.api.http) = {
52      get: "/v2alpha/{catalog=projects/*/locations/*/catalogs/*}:completeQuery"
53    };
54  }
55
56  // Bulk import of processed completion dataset.
57  //
58  // Request processing is asynchronous. Partial updating is not supported.
59  //
60  // The operation is successfully finished only after the imported suggestions
61  // are indexed successfully and ready for serving. The process takes hours.
62  //
63  // This feature is only available for users who have Retail Search enabled.
64  // Enable Retail Search on Cloud Console before using this feature.
65  rpc ImportCompletionData(ImportCompletionDataRequest)
66      returns (google.longrunning.Operation) {
67    option (google.api.http) = {
68      post: "/v2alpha/{parent=projects/*/locations/*/catalogs/*}/completionData:import"
69      body: "*"
70    };
71    option (google.longrunning.operation_info) = {
72      response_type: "google.cloud.retail.v2alpha.ImportCompletionDataResponse"
73      metadata_type: "google.cloud.retail.v2alpha.ImportMetadata"
74    };
75  }
76}
77
78// Autocomplete parameters.
79message CompleteQueryRequest {
80  // Required. Catalog for which the completion is performed.
81  //
82  // Full resource name of catalog, such as
83  // `projects/*/locations/global/catalogs/default_catalog`.
84  string catalog = 1 [
85    (google.api.field_behavior) = REQUIRED,
86    (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" }
87  ];
88
89  // Required. The query used to generate suggestions.
90  //
91  // The maximum number of allowed characters is 255.
92  string query = 2 [(google.api.field_behavior) = REQUIRED];
93
94  // Required field. A unique identifier for tracking visitors. For example,
95  // this could be implemented with an HTTP cookie, which should be able to
96  // uniquely identify a visitor on a single device. This unique identifier
97  // should not change if the visitor logs in or out of the website.
98  //
99  // The field must be a UTF-8 encoded string with a length limit of 128
100  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
101  string visitor_id = 7;
102
103  // Note that this field applies for `user-data` dataset only. For requests
104  // with `cloud-retail` dataset, setting this field has no effect.
105  //
106  // The language filters applied to the output suggestions. If set, it should
107  // contain the language of the query. If not set, suggestions are returned
108  // without considering language restrictions. This is the BCP-47 language
109  // code, such as "en-US" or "sr-Latn". For more information, see [Tags for
110  // Identifying Languages](https://tools.ietf.org/html/bcp47). The maximum
111  // number of language codes is 3.
112  repeated string language_codes = 3;
113
114  // The device type context for completion suggestions. We recommend that you
115  // leave this field empty.
116  //
117  // It can apply different suggestions on different device types, e.g.
118  // `DESKTOP`, `MOBILE`. If it is empty, the suggestions are across all device
119  // types.
120  //
121  // Supported formats:
122  //
123  // * `UNKNOWN_DEVICE_TYPE`
124  //
125  // * `DESKTOP`
126  //
127  // * `MOBILE`
128  //
129  // * A customized string starts with `OTHER_`, e.g. `OTHER_IPHONE`.
130  string device_type = 4;
131
132  // Determines which dataset to use for fetching completion. "user-data" will
133  // use the imported dataset through
134  // [CompletionService.ImportCompletionData][google.cloud.retail.v2alpha.CompletionService.ImportCompletionData].
135  // "cloud-retail" will use the dataset generated by cloud retail based on user
136  // events. If leave empty, it will use the "user-data".
137  //
138  // Current supported values:
139  //
140  // * user-data
141  //
142  // * cloud-retail:
143  //   This option requires enabling auto-learning function first. See
144  //   [guidelines](https://cloud.google.com/retail/docs/completion-overview#generated-completion-dataset).
145  string dataset = 6;
146
147  // Completion max suggestions. If left unset or set to 0, then will fallback
148  // to the configured value
149  // [CompletionConfig.max_suggestions][google.cloud.retail.v2alpha.CompletionConfig.max_suggestions].
150  //
151  // The maximum allowed max suggestions is 20. If it is set higher, it will be
152  // capped by 20.
153  int32 max_suggestions = 5;
154
155  // If true, attribute suggestions are enabled and provided in response.
156  //
157  // This field is only available for "cloud-retail" dataset.
158  bool enable_attribute_suggestions = 9;
159
160  // The entity for customers that may run multiple different entities, domains,
161  // sites or regions, for example, `Google US`, `Google Ads`, `Waymo`,
162  // `google.com`, `youtube.com`, etc.
163  // If this is set, it should be exactly matched with
164  // [UserEvent.entity][google.cloud.retail.v2alpha.UserEvent.entity] to get
165  // per-entity autocomplete results.
166  string entity = 10;
167}
168
169// Response of the autocomplete query.
170message CompleteQueryResponse {
171  // Resource that represents completion results.
172  message CompletionResult {
173    // The suggestion for the query.
174    string suggestion = 1;
175
176    // Custom attributes for the suggestion term.
177    //
178    // * For "user-data", the attributes are additional custom attributes
179    // ingested through BigQuery.
180    //
181    // * For "cloud-retail", the attributes are product attributes generated
182    // by Cloud Retail. It requires
183    // [UserEvent.product_details][google.cloud.retail.v2alpha.UserEvent.product_details]
184    // is imported properly.
185    map<string, CustomAttribute> attributes = 2;
186
187    // Facet information for the suggestion term. Gives the number of items
188    // resulting from a search with this suggestion term for each facet.
189    //
190    // This is an experimental feature for limited customers. Please reach out
191    // to the support team if you would like to receive this information.
192    repeated SearchResponse.Facet facets = 3;
193
194    // Total number of products associated with a search with this suggestion.
195    //
196    // This is an experimental feature for limited customers. Please reach out
197    // to the support team if you would like to receive this information.
198    int32 total_product_count = 4;
199  }
200
201  // Recent search of this user.
202  message RecentSearchResult {
203    // The recent search query.
204    string recent_search = 1;
205  }
206
207  // Resource that represents attribute results.
208  message AttributeResult {
209    // The list of suggestions for the attribute.
210    repeated string suggestions = 1;
211  }
212
213  // Results of the matching suggestions. The result list is ordered and the
214  // first result is top suggestion.
215  repeated CompletionResult completion_results = 1;
216
217  // A unique complete token. This should be included in the
218  // [UserEvent.completion_detail][google.cloud.retail.v2alpha.UserEvent.completion_detail]
219  // for search events resulting from this completion, which enables accurate
220  // attribution of complete model performance.
221  string attribution_token = 2;
222
223  // Matched recent searches of this user. The maximum number of recent searches
224  // is 10. This field is a restricted feature. Contact Retail Search support
225  // team if you are interested in enabling it.
226  //
227  // This feature is only available when
228  // [CompleteQueryRequest.visitor_id][google.cloud.retail.v2alpha.CompleteQueryRequest.visitor_id]
229  // field is set and [UserEvent][google.cloud.retail.v2alpha.UserEvent] is
230  // imported. The recent searches satisfy the follow rules:
231  //
232  //  * They are ordered from latest to oldest.
233  //
234  //  * They are matched with
235  //  [CompleteQueryRequest.query][google.cloud.retail.v2alpha.CompleteQueryRequest.query]
236  //  case insensitively.
237  //
238  //  * They are transformed to lower case.
239  //
240  //  * They are UTF-8 safe.
241  //
242  // Recent searches are deduplicated. More recent searches will be reserved
243  // when duplication happens.
244  repeated RecentSearchResult recent_search_results = 3;
245
246  // A map of matched attribute suggestions. This field is only available for
247  // "cloud-retail" dataset.
248  //
249  // Current supported keys:
250  //
251  // * `brands`
252  //
253  // * `categories`
254  map<string, AttributeResult> attribute_results = 4;
255}
256