1 // Copyright 2018 Google Inc.
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 package google.datastore.v1;
19 import "google/api/annotations.proto";
20 import "google/datastore/v1/entity.proto";
21 import "google/datastore/v1/query.proto";
23 option csharp_namespace = "Google.Cloud.Datastore.V1";
24 option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
25 option java_multiple_files = true;
26 option java_outer_classname = "DatastoreProto";
27 option java_package = "com.google.datastore.v1";
28 option php_namespace = "Google\\Cloud\\Datastore\\V1";
30 // Each RPC normalizes the partition IDs of the keys in its input entities,
31 // and always returns entities with keys with normalized partition IDs.
32 // This applies to all keys and entities, including those in values, except keys
33 // with both an empty path and an empty or unset partition ID. Normalization of
34 // input keys sets the project ID (if not already set) to the project ID from
38 // Looks up entities by key.
39 rpc Lookup(LookupRequest) returns (LookupResponse) {
40 option (google.api.http) = {
41 post: "/v1/projects/{project_id}:lookup"
46 // Queries for entities.
47 rpc RunQuery(RunQueryRequest) returns (RunQueryResponse) {
48 option (google.api.http) = {
49 post: "/v1/projects/{project_id}:runQuery"
54 // Begins a new transaction.
55 rpc BeginTransaction(BeginTransactionRequest)
56 returns (BeginTransactionResponse) {
57 option (google.api.http) = {
58 post: "/v1/projects/{project_id}:beginTransaction"
63 // Commits a transaction, optionally creating, deleting or modifying some
65 rpc Commit(CommitRequest) returns (CommitResponse) {
66 option (google.api.http) = {
67 post: "/v1/projects/{project_id}:commit"
72 // Rolls back a transaction.
73 rpc Rollback(RollbackRequest) returns (RollbackResponse) {
74 option (google.api.http) = {
75 post: "/v1/projects/{project_id}:rollback"
80 // Allocates IDs for the given keys, which is useful for referencing an entity
81 // before it is inserted.
82 rpc AllocateIds(AllocateIdsRequest) returns (AllocateIdsResponse) {
83 option (google.api.http) = {
84 post: "/v1/projects/{project_id}:allocateIds"
89 // Prevents the supplied keys' IDs from being auto-allocated by Cloud
91 rpc ReserveIds(ReserveIdsRequest) returns (ReserveIdsResponse) {
92 option (google.api.http) = {
93 post: "/v1/projects/{project_id}:reserveIds"
99 // The request for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup].
100 message LookupRequest {
101 // The ID of the project against which to make the request.
102 string project_id = 8;
104 // The options for this lookup request.
105 ReadOptions read_options = 1;
107 // Keys of entities to look up.
108 repeated Key keys = 3;
111 // The response for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup].
112 message LookupResponse {
113 // Entities found as `ResultType.FULL` entities. The order of results in this
114 // field is undefined and has no relation to the order of the keys in the
116 repeated EntityResult found = 1;
118 // Entities not found as `ResultType.KEY_ONLY` entities. The order of results
119 // in this field is undefined and has no relation to the order of the keys
121 repeated EntityResult missing = 2;
123 // A list of keys that were not looked up due to resource constraints. The
124 // order of results in this field is undefined and has no relation to the
125 // order of the keys in the input.
126 repeated Key deferred = 3;
129 // The request for [Datastore.RunQuery][google.datastore.v1.Datastore.RunQuery].
130 message RunQueryRequest {
131 // The ID of the project against which to make the request.
132 string project_id = 8;
134 // Entities are partitioned into subsets, identified by a partition ID.
135 // Queries are scoped to a single partition.
136 // This partition ID is normalized with the standard default context
138 PartitionId partition_id = 2;
140 // The options for this query.
141 ReadOptions read_options = 1;
143 // The type of query.
148 // The GQL query to run.
149 GqlQuery gql_query = 7;
154 // [Datastore.RunQuery][google.datastore.v1.Datastore.RunQuery].
155 message RunQueryResponse {
156 // A batch of query results (always present).
157 QueryResultBatch batch = 1;
159 // The parsed form of the `GqlQuery` from the request, if it was set.
164 // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
165 message BeginTransactionRequest {
166 // The ID of the project against which to make the request.
167 string project_id = 8;
169 // Options for a new transaction.
170 TransactionOptions transaction_options = 10;
174 // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
175 message BeginTransactionResponse {
176 // The transaction identifier (always present).
177 bytes transaction = 1;
180 // The request for [Datastore.Rollback][google.datastore.v1.Datastore.Rollback].
181 message RollbackRequest {
182 // The ID of the project against which to make the request.
183 string project_id = 8;
185 // The transaction identifier, returned by a call to
186 // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
187 bytes transaction = 1;
191 // [Datastore.Rollback][google.datastore.v1.Datastore.Rollback]. (an empty
193 message RollbackResponse {}
195 // The request for [Datastore.Commit][google.datastore.v1.Datastore.Commit].
196 message CommitRequest {
197 // The modes available for commits.
199 // Unspecified. This value must not be used.
200 MODE_UNSPECIFIED = 0;
202 // Transactional: The mutations are either all applied, or none are applied.
203 // Learn about transactions
204 // [here](https://cloud.google.com/datastore/docs/concepts/transactions).
207 // Non-transactional: The mutations may not apply as all or none.
208 NON_TRANSACTIONAL = 2;
211 // The ID of the project against which to make the request.
212 string project_id = 8;
214 // The type of commit to perform. Defaults to `TRANSACTIONAL`.
217 // Must be set when mode is `TRANSACTIONAL`.
218 oneof transaction_selector {
219 // The identifier of the transaction associated with the commit. A
220 // transaction identifier is returned by a call to
221 // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
222 bytes transaction = 1;
225 // The mutations to perform.
227 // When mode is `TRANSACTIONAL`, mutations affecting a single entity are
228 // applied in order. The following sequences of mutations affecting a single
229 // entity are not permitted in a single `Commit` request:
231 // - `insert` followed by `insert`
232 // - `update` followed by `insert`
233 // - `upsert` followed by `insert`
234 // - `delete` followed by `update`
236 // When mode is `NON_TRANSACTIONAL`, no two mutations may affect a single
238 repeated Mutation mutations = 6;
241 // The response for [Datastore.Commit][google.datastore.v1.Datastore.Commit].
242 message CommitResponse {
243 // The result of performing the mutations.
244 // The i-th mutation result corresponds to the i-th mutation in the request.
245 repeated MutationResult mutation_results = 3;
247 // The number of index entries updated during the commit, or zero if none were
249 int32 index_updates = 4;
253 // [Datastore.AllocateIds][google.datastore.v1.Datastore.AllocateIds].
254 message AllocateIdsRequest {
255 // The ID of the project against which to make the request.
256 string project_id = 8;
258 // A list of keys with incomplete key paths for which to allocate IDs.
259 // No key may be reserved/read-only.
260 repeated Key keys = 1;
264 // [Datastore.AllocateIds][google.datastore.v1.Datastore.AllocateIds].
265 message AllocateIdsResponse {
266 // The keys specified in the request (in the same order), each with
267 // its key path completed with a newly allocated ID.
268 repeated Key keys = 1;
272 // [Datastore.ReserveIds][google.datastore.v1.Datastore.ReserveIds].
273 message ReserveIdsRequest {
274 // The ID of the project against which to make the request.
275 string project_id = 8;
277 // If not empty, the ID of the database against which to make the request.
278 string database_id = 9;
280 // A list of keys with complete key paths whose numeric IDs should not be
282 repeated Key keys = 1;
286 // [Datastore.ReserveIds][google.datastore.v1.Datastore.ReserveIds].
287 message ReserveIdsResponse {}
289 // A mutation to apply to an entity.
291 // The mutation operation.
293 // For `insert`, `update`, and `upsert`:
294 // - The entity's key must not be reserved/read-only.
295 // - No property in the entity may have a reserved name,
296 // not even a property in an entity in a value.
297 // - No value in the entity may have meaning 18,
298 // not even a value in an entity in another value.
300 // The entity to insert. The entity must not already exist.
301 // The entity key's final path element may be incomplete.
304 // The entity to update. The entity must already exist.
305 // Must have a complete key path.
308 // The entity to upsert. The entity may or may not already exist.
309 // The entity key's final path element may be incomplete.
312 // The key of the entity to delete. The entity may or may not already exist.
313 // Must have a complete key path and must not be reserved/read-only.
317 // When set, the server will detect whether or not this mutation conflicts
318 // with the current version of the entity on the server. Conflicting mutations
319 // are not applied, and are marked as such in MutationResult.
320 oneof conflict_detection_strategy {
321 // The version of the entity that this mutation is being applied to. If this
322 // does not match the current version on the server, the mutation conflicts.
323 int64 base_version = 8;
327 // The result of applying a mutation.
328 message MutationResult {
329 // The automatically allocated key.
330 // Set only when the mutation allocated a key.
333 // The version of the entity on the server after processing the mutation. If
334 // the mutation doesn't change anything on the server, then the version will
335 // be the version of the current entity or, if no entity is present, a version
336 // that is strictly greater than the version of any previous entity and less
337 // than the version of any possible future entity.
340 // Whether a conflict was detected for this mutation. Always false when a
341 // conflict detection strategy field is not set in the mutation.
342 bool conflict_detected = 5;
345 // The options shared by read requests.
346 message ReadOptions {
347 // The possible values for read consistencies.
348 enum ReadConsistency {
349 // Unspecified. This value must not be used.
350 READ_CONSISTENCY_UNSPECIFIED = 0;
352 // Strong consistency.
355 // Eventual consistency.
359 // If not specified, lookups and ancestor queries default to
360 // `read_consistency`=`STRONG`, global queries default to
361 // `read_consistency`=`EVENTUAL`.
362 oneof consistency_type {
363 // The non-transactional read consistency to use.
364 // Cannot be set to `STRONG` for global queries.
365 ReadConsistency read_consistency = 1;
367 // The identifier of the transaction in which to read. A
368 // transaction identifier is returned by a call to
369 // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
370 bytes transaction = 2;
374 // Options for beginning a new transaction.
376 // Transactions can be created explicitly with calls to
377 // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]
378 // or implicitly by setting
379 // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
381 message TransactionOptions {
382 // Options specific to read / write transactions.
384 // The transaction identifier of the transaction being retried.
385 bytes previous_transaction = 1;
388 // Options specific to read-only transactions.
391 // The `mode` of the transaction, indicating whether write operations are
394 // The transaction should allow both reads and writes.
395 ReadWrite read_write = 1;
397 // The transaction should only allow reads.
398 ReadOnly read_only = 2;