googleapis/google/cloud/retail/v2beta/completion_service.proto

// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.retail.v2beta;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/retail/v2beta/common.proto";
import "google/cloud/retail/v2beta/import_config.proto";
import "google/longrunning/operations.proto";

option csharp_namespace = "Google.Cloud.Retail.V2Beta";
option go_package = "google.golang.org/genproto/googleapis/cloud/retail/v2beta;retail";
option java_multiple_files = true;
option java_outer_classname = "CompletionServiceProto";
option java_package = "com.google.cloud.retail.v2beta";
option objc_class_prefix = "RETAIL";
option php_namespace = "Google\\Cloud\\Retail\\V2beta";
option ruby_package = "Google::Cloud::Retail::V2beta";

// Auto-completion service for retail.
//
// This feature is only available for users who have Retail Search enabled.
// Please submit a form [here](https://cloud.google.com/contact) to contact
// cloud sales if you are interested in using Retail Search.
service CompletionService {
  option (google.api.default_host) = "retail.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Completes the specified prefix with keyword suggestions.
  //
  // This feature is only available for users who have Retail Search enabled.
  // Please submit a form [here](https://cloud.google.com/contact) to contact
  // cloud sales if you are interested in using Retail Search.
  rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
    option (google.api.http) = {
      get: "/v2beta/{catalog=projects/*/locations/*/catalogs/*}:completeQuery"
    };
  }

  // Bulk import of processed completion dataset.
  //
  // Request processing may be synchronous. Partial updating is not supported.
  //
  // This feature is only available for users who have Retail Search enabled.
  // Please submit a form [here](https://cloud.google.com/contact) to contact
  // cloud sales if you are interested in using Retail Search.
  rpc ImportCompletionData(ImportCompletionDataRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2beta/{parent=projects/*/locations/*/catalogs/*}/completionData:import"
      body: "*"
    };
    option (google.longrunning.operation_info) = {
      response_type: "google.cloud.retail.v2beta.ImportCompletionDataResponse"
      metadata_type: "google.cloud.retail.v2beta.ImportMetadata"
    };
  }
}

// Auto-complete parameters.
message CompleteQueryRequest {
  // Required. Catalog for which the completion is performed.
  //
  // Full resource name of catalog, such as
  // `projects/*/locations/global/catalogs/default_catalog`.
  string catalog = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" }
  ];

  // Required. The query used to generate suggestions.
  //
  // The maximum number of allowed characters is 255.
  string query = 2 [(google.api.field_behavior) = REQUIRED];

  // A unique identifier for tracking visitors. For example, this could be
  // implemented with an HTTP cookie, which should be able to uniquely identify
  // a visitor on a single device. This unique identifier should not change if
  // the visitor logs in or out of the website.
  //
  // The field must be a UTF-8 encoded string with a length limit of 128
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  string visitor_id = 7;

  // The list of languages of the query. This is
  // the BCP-47 language code, such as "en-US" or "sr-Latn".
  // For more information, see
  // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47).
  //
  // The maximum number of allowed characters is 255.
  // Only "en-US" is currently supported.
  repeated string language_codes = 3;

  // The device type context for completion suggestions.
  // It is useful to apply different suggestions on different device types, e.g.
  // DESKTOP, MOBILE. If it is empty, the suggestions are across all device
  // types.
  //
  // Supported formats:
  //
  // * UNKNOWN_DEVICE_TYPE
  //
  // * DESKTOP
  //
  // * MOBILE
  //
  // * A customized string starts with OTHER_, e.g. OTHER_IPHONE.
  string device_type = 4;

  // Determines which dataset to use for fetching completion. "user-data" will
  // use the imported dataset through
  // [CompletionService.ImportCompletionData][google.cloud.retail.v2beta.CompletionService.ImportCompletionData].
  // "cloud-retail" will use the dataset generated by cloud retail based on user
  // events. If leave empty, it will use the "user-data".
  //
  // Current supported values:
  //
  // * user-data
  //
  // * cloud-retail
  //   This option requires additional allowlisting. Before using cloud-retail,
  //   contact Cloud Retail support team first.
  string dataset = 6;

  // Completion max suggestions. If left unset or set to 0, then will fallback
  // to the configured value [CompletionConfig.max_suggestions][].
  //
  // The maximum allowed max suggestions is 20. If it is set higher, it will be
  // capped by 20.
  int32 max_suggestions = 5;
}

// Response of the auto-complete query.
message CompleteQueryResponse {
  // Resource that represents completion results.
  message CompletionResult {
    // The suggestion for the query.
    string suggestion = 1;

    // Additional custom attributes ingested through BigQuery.
    map<string, CustomAttribute> attributes = 2;
  }

  // Recent search of this user.
  message RecentSearchResult {
    // The recent search query.
    string recent_search = 1;
  }

  // Results of the matching suggestions. The result list is ordered and the
  // first result is top suggestion.
  repeated CompletionResult completion_results = 1;

  // A unique complete token. This should be included in the
  // [SearchRequest][google.cloud.retail.v2beta.SearchRequest] resulting from
  // this completion, which enables accurate attribution of complete model
  // performance.
  string attribution_token = 2;

  // Matched recent searches of this user. The maximum number of recent searches
  // is 10. This field is a restricted feature. Contact Retail Search support
  // team if you are interested in enabling it.
  //
  // This feature is only available when
  // [CompleteQueryRequest.visitor_id][google.cloud.retail.v2beta.CompleteQueryRequest.visitor_id]
  // field is set and [UserEvent][google.cloud.retail.v2beta.UserEvent] is
  // imported. The recent searches satisfy the follow rules:
  //  * They are ordered from latest to oldest.
  //  * They are matched with
  //  [CompleteQueryRequest.query][google.cloud.retail.v2beta.CompleteQueryRequest.query]
  //  case insensitively.
  //  * They are transformed to lower cases.
  //  * They are UTF-8 safe.
  //
  // Recent searches are deduplicated. More recent searches will be reserved
  // when duplication happens.
  repeated RecentSearchResult recent_search_results = 3;
}