xref: /aosp_15_r20/external/googleapis/google/cloud/dataqna/v1alpha/question_service.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9) 
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/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/cloud/dataqna/v1alpha/question.proto";
24import "google/cloud/dataqna/v1alpha/user_feedback.proto";
25import "google/protobuf/field_mask.proto";
26
27option csharp_namespace = "Google.Cloud.DataQnA.V1Alpha";
28option go_package = "cloud.google.com/go/dataqna/apiv1alpha/dataqnapb;dataqnapb";
29option java_multiple_files = true;
30option java_outer_classname = "QuestionServiceProto";
31option java_package = "com.google.cloud.dataqna.v1alpha";
32option php_namespace = "Google\\Cloud\\DataQnA\\V1alpha";
33option ruby_package = "Google::Cloud::DataQnA::V1alpha";
34
35// Service to interpret natural language queries.
36// The service allows to create `Question` resources that are interpreted and
37// are filled with one or more interpretations if the question could be
38// interpreted. Once a `Question` resource is created and has at least one
39// interpretation, an interpretation can be chosen for execution, which
40// triggers a query to the backend (for BigQuery, it will create a job).
41// Upon successful execution of that interpretation, backend specific
42// information will be returned so that the client can retrieve the results
43// from the backend.
44//
45// The `Question` resources are named `projects/*/locations/*/questions/*`.
46//
47// The `Question` resource has a singletion sub-resource `UserFeedback` named
48// `projects/*/locations/*/questions/*/userFeedback`, which allows access to
49// user feedback.
50service QuestionService {
51  option (google.api.default_host) = "dataqna.googleapis.com";
52  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
53
54  // Gets a previously created question.
55  rpc GetQuestion(GetQuestionRequest) returns (Question) {
56    option (google.api.http) = {
57      get: "/v1alpha/{name=projects/*/locations/*/questions/*}"
58    };
59    option (google.api.method_signature) = "name";
60  }
61
62  // Creates a question.
63  rpc CreateQuestion(CreateQuestionRequest) returns (Question) {
64    option (google.api.http) = {
65      post: "/v1alpha/{parent=projects/*/locations/*}/questions"
66      body: "question"
67    };
68    option (google.api.method_signature) = "parent,question";
69  }
70
71  // Executes an interpretation.
72  rpc ExecuteQuestion(ExecuteQuestionRequest) returns (Question) {
73    option (google.api.http) = {
74      post: "/v1alpha/{name=projects/*/locations/*/questions/*}:execute"
75      body: "*"
76    };
77    option (google.api.method_signature) = "name,interpretation_index";
78  }
79
80  // Gets previously created user feedback.
81  rpc GetUserFeedback(GetUserFeedbackRequest) returns (UserFeedback) {
82    option (google.api.http) = {
83      get: "/v1alpha/{name=projects/*/locations/*/questions/*/userFeedback}"
84    };
85    option (google.api.method_signature) = "name";
86  }
87
88  // Updates user feedback. This creates user feedback if there was none before
89  // (upsert).
90  rpc UpdateUserFeedback(UpdateUserFeedbackRequest) returns (UserFeedback) {
91    option (google.api.http) = {
92      patch: "/v1alpha/{user_feedback.name=projects/*/locations/*/questions/*/userFeedback}"
93      body: "user_feedback"
94    };
95    option (google.api.method_signature) = "user_feedback,update_mask";
96  }
97}
98
99// A request to get a previously created question.
100message GetQuestionRequest {
101  // Required. The unique identifier for the question.
102  // Example: `projects/foo/locations/bar/questions/1234`
103  string name = 1 [
104    (google.api.field_behavior) = REQUIRED,
105    (google.api.resource_reference) = {
106      type: "dataqna.googleapis.com/Question"
107    }
108  ];
109
110  // The list of fields to be retrieved.
111  google.protobuf.FieldMask read_mask = 2;
112}
113
114// Request to create a question resource.
115message CreateQuestionRequest {
116  // Required. The name of the project this data source reference belongs to.
117  // Example: `projects/foo/locations/bar`
118  string parent = 1 [
119    (google.api.field_behavior) = REQUIRED,
120    (google.api.resource_reference) = {
121      type: "locations.googleapis.com/Location"
122    }
123  ];
124
125  // Required. The question to create.
126  Question question = 2 [(google.api.field_behavior) = REQUIRED];
127}
128
129// Request to execute an interpretation.
130message ExecuteQuestionRequest {
131  // Required. The unique identifier for the question.
132  // Example: `projects/foo/locations/bar/questions/1234`
133  string name = 1 [(google.api.field_behavior) = REQUIRED];
134
135  // Required. Index of the interpretation to execute.
136  int32 interpretation_index = 2 [(google.api.field_behavior) = REQUIRED];
137}
138
139// Request to get user feedback.
140message GetUserFeedbackRequest {
141  // Required. The unique identifier for the user feedback.
142  // User feedback is a singleton resource on a Question.
143  // Example: `projects/foo/locations/bar/questions/1234/userFeedback`
144  string name = 1 [
145    (google.api.field_behavior) = REQUIRED,
146    (google.api.resource_reference) = {
147      type: "dataqna.googleapis.com/UserFeedback"
148    }
149  ];
150}
151
152// Request to updates user feedback.
153message UpdateUserFeedbackRequest {
154  // Required. The user feedback to update. This can be called even if there is no
155  // user feedback so far.
156  // The feedback's name field is used to identify the user feedback (and the
157  // corresponding question) to update.
158  UserFeedback user_feedback = 1 [(google.api.field_behavior) = REQUIRED];
159
160  // The list of fields to be updated.
161  google.protobuf.FieldMask update_mask = 2;
162}
163