1// Copyright 2020 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.dataqna.v1alpha; 18 19import "google/api/annotations.proto"; 20import "google/api/field_behavior.proto"; 21import "google/api/resource.proto"; 22import "google/cloud/dataqna/v1alpha/annotated_string.proto"; 23import "google/api/client.proto"; 24 25option csharp_namespace = "Google.Cloud.DataQnA.V1Alpha"; 26option go_package = "cloud.google.com/go/dataqna/apiv1alpha/dataqnapb;dataqnapb"; 27option java_multiple_files = true; 28option java_outer_classname = "AutoSuggestionServiceProto"; 29option java_package = "com.google.cloud.dataqna.v1alpha"; 30option php_namespace = "Google\\Cloud\\DataQnA\\V1alpha"; 31option ruby_package = "Google::Cloud::DataQnA::V1alpha"; 32 33// This stateless API provides automatic suggestions for natural language 34// queries for the data sources in the provided project and location. 35// 36// The service provides a resourceless operation `suggestQueries` that can be 37// called to get a list of suggestions for a given incomplete query and scope 38// (or list of scopes) under which the query is to be interpreted. 39// 40// There are two types of suggestions, ENTITY for single entity suggestions 41// and TEMPLATE for full sentences. By default, both types are returned. 42// 43// Example Request: 44// ``` 45// GetSuggestions({ 46// parent: "locations/us/projects/my-project" 47// scopes: 48// "//bigquery.googleapis.com/projects/my-project/datasets/my-dataset/tables/my-table" 49// query: "top it" 50// }) 51// ``` 52// 53// The service will retrieve information based on the given scope(s) and give 54// suggestions based on that (e.g. "top item" for "top it" if "item" is a known 55// dimension for the provided scope). 56// ``` 57// suggestions { 58// suggestion_info { 59// annotated_suggestion { 60// text_formatted: "top item by sum of usd_revenue_net" 61// markups { 62// type: DIMENSION 63// start_char_index: 4 64// length: 4 65// } 66// markups { 67// type: METRIC 68// start_char_index: 19 69// length: 15 70// } 71// } 72// query_matches { 73// start_char_index: 0 74// length: 6 75// } 76// } 77// suggestion_type: TEMPLATE 78// ranking_score: 0.9 79// } 80// suggestions { 81// suggestion_info { 82// annotated_suggestion { 83// text_formatted: "item" 84// markups { 85// type: DIMENSION 86// start_char_index: 4 87// length: 2 88// } 89// } 90// query_matches { 91// start_char_index: 0 92// length: 6 93// } 94// } 95// suggestion_type: ENTITY 96// ranking_score: 0.8 97// } 98// ``` 99service AutoSuggestionService { 100 option (google.api.default_host) = "dataqna.googleapis.com"; 101 option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; 102 103 // Gets a list of suggestions based on a prefix string. 104 // AutoSuggestion tolerance should be less than 1 second. 105 rpc SuggestQueries(SuggestQueriesRequest) returns (SuggestQueriesResponse) { 106 option (google.api.http) = { 107 post: "/v1alpha/{parent=projects/*/locations/*}:suggestQueries" 108 body: "*" 109 }; 110 } 111} 112 113// Request for query suggestions. 114message SuggestQueriesRequest { 115 // Required. The parent of the suggestion query is the resource denoting the project and 116 // location. 117 string parent = 1 [ 118 (google.api.field_behavior) = REQUIRED, 119 (google.api.resource_reference) = { 120 type: "locations.googleapis.com/Location" 121 } 122 ]; 123 124 // The scopes to which this search is restricted. The only supported scope 125 // pattern is 126 // `//bigquery.googleapis.com/projects/{GCP-PROJECT-ID}/datasets/{DATASET-ID}/tables/{TABLE-ID}`. 127 repeated string scopes = 2; 128 129 // User query for which to generate suggestions. If the query is empty, zero 130 // state suggestions are returned. This allows UIs to display suggestions 131 // right away, helping the user to get a sense of what a query might look 132 // like. 133 string query = 3; 134 135 // The requested suggestion type. Multiple suggestion types can be 136 // requested, but there is no guarantee that the service will return 137 // suggestions for each type. Suggestions for a requested type might rank 138 // lower than suggestions for other types and the service may decide to cut 139 // these suggestions off. 140 repeated SuggestionType suggestion_types = 4; 141} 142 143// A suggestion for a query with a ranking score. 144message Suggestion { 145 // Detailed information about the suggestion. 146 SuggestionInfo suggestion_info = 1; 147 148 // The score of the suggestion. This can be used to define ordering in UI. 149 // The score represents confidence in the suggestion where higher is better. 150 // All score values must be in the range [0, 1). 151 double ranking_score = 2; 152 153 // The type of the suggestion. 154 SuggestionType suggestion_type = 3; 155} 156 157// Detailed information about the suggestion. 158message SuggestionInfo { 159 // MatchInfo describes which part of suggestion matched with data in user 160 // typed query. This can be used to highlight matching parts in the UI. This 161 // is different from the annotations provided in annotated_suggestion. The 162 // annotated_suggestion provides information about the semantic meaning, while 163 // this provides information about how it relates to the input. 164 // 165 // Example: 166 // user query: `top products` 167 // 168 // ``` 169 // annotated_suggestion { 170 // text_formatted = "top product_group" 171 // html_formatted = "top <b>product_group</b>" 172 // markups { 173 // {type: TEXT, start_char_index: 0, length: 3} 174 // {type: DIMENSION, start_char_index: 4, length: 13} 175 // } 176 // } 177 // 178 // query_matches { 179 // { start_char_index: 0, length: 3 } 180 // { start_char_index: 4, length: 7} 181 // } 182 // ``` 183 message MatchInfo { 184 // Unicode character index of the string annotation. 185 int32 start_char_index = 1; 186 187 // Count of unicode characters of this substring. 188 int32 length = 2; 189 } 190 191 // Annotations for the suggestion. This provides information about which part 192 // of the suggestion corresponds to what semantic meaning (e.g. a metric). 193 AnnotatedString annotated_suggestion = 1; 194 195 // Matches between user query and the annotated string. 196 repeated MatchInfo query_matches = 2; 197} 198 199// Response to SuggestQueries. 200message SuggestQueriesResponse { 201 // A list of suggestions. 202 repeated Suggestion suggestions = 1; 203} 204 205// The type of suggestion. 206enum SuggestionType { 207 // No suggestiont type is specified. 208 SUGGESTION_TYPE_UNSPECIFIED = 0; 209 210 // Entity suggestion type. Suggestions are for single entities. 211 ENTITY = 1; 212 213 // Template suggestion type. Suggestions are for full sentences. 214 TEMPLATE = 2; 215} 216