From 0ebdb62d8b693a975e35bba437d891357d5afa6c Mon Sep 17 00:00:00 2001 From: Jacob Geiger Date: Tue, 16 Aug 2016 10:53:24 -0700 Subject: [PATCH] Add datastore v1 protos, update v1beta1 --- google/datastore/README.md | 56 ---- google/datastore/v1/datastore.proto | 316 +++++++++++++++++++++++ google/datastore/v1/entity.proto | 201 ++++++++++++++ google/datastore/v1/query.proto | 306 ++++++++++++++++++++++ google/datastore/v1beta3/datastore.proto | 30 +-- google/datastore/v1beta3/query.proto | 30 ++- 6 files changed, 854 insertions(+), 85 deletions(-) delete mode 100644 google/datastore/README.md create mode 100644 google/datastore/v1/datastore.proto create mode 100644 google/datastore/v1/entity.proto create mode 100644 google/datastore/v1/query.proto diff --git a/google/datastore/README.md b/google/datastore/README.md deleted file mode 100644 index 97e33d34..00000000 --- a/google/datastore/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Google Cloud Datastore Overview - -## API - -This file describes the API for [Google Cloud Datastore][0]. Google Cloud Datastore -is a fully managed, schemaless, non-relational datastore accessible through -Google APIs infrastructure. It provides a rich set of query capabilities, -supports atomic transactions, and automatically scales up and down in response -to load. - -The API is deliberately low-level to map to the underlying Datastore RPC model -and provide more flexibility to developers and higher level library -implementers. - -## Client libraries - -The Datastore can be used with many client libraries. Getting started -guides for the different libraries are available on the [Getting Started][1] -page. - -## Features - -The Datastore is a schemaless NoSQL datastore providing robust, -scalable storage for your application, with the following features: - -* No planned downtime -* Atomic transactions -* High availability of reads and writes -* Strong consistency for reads and ancestor queries -* Eventual consistency for all other queries - -The Datastore replicates data across multiple datacenters using a system -based on the Paxos algorithm. This provides a high level of availability for -reads and writes. Most queries are eventually consistent. - -## Data Model - -* **Entity**: An entity has one or more *properties*, named values of one of - several supported data types: for instance, a property can be a string, an - integer, or a reference to another entity. Each entity is identified by its - *kind*, which categorizes the entity for the purpose of queries, and a *key* - that uniquely identifies it within its kind. - -* **Key**: Each entity belongs to a specific kind, which categorizes it for - the purpose of queries. In addition, each entity has its own key which - uniquely identifies it. The key consists of a kind, an identifier, and an - optional [ancestor path][2]. - -* **Transaction**: The Datastore can execute multiple operations in a single - transaction. By definition, a transaction cannot succeed unless every one - of its operations succeeds; if any of the operations fails, the transaction - is automatically rolled back. - -[0]: https://cloud.google.com/datastore/ -[1]: https://cloud.google.com/datastore/docs/getstarted -[2]: https://cloud.google.com/datastore/docs/concepts/overview#Datastore_Ancestor_paths diff --git a/google/datastore/v1/datastore.proto b/google/datastore/v1/datastore.proto new file mode 100644 index 00000000..5881e9a1 --- /dev/null +++ b/google/datastore/v1/datastore.proto @@ -0,0 +1,316 @@ +// Copyright 2016 Google Inc. +// +// 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.datastore.v1; + +import "google/api/annotations.proto"; +import "google/datastore/v1/entity.proto"; +import "google/datastore/v1/query.proto"; + +option java_multiple_files = true; +option java_outer_classname = "DatastoreProto"; +option java_package = "com.google.datastore.v1"; + + +// Each RPC normalizes the partition IDs of the keys in its input entities, +// and always returns entities with keys with normalized partition IDs. +// This applies to all keys and entities, including those in values, except keys +// with both an empty path and an empty or unset partition ID. Normalization of +// input keys sets the project ID (if not already set) to the project ID from +// the request. +// +service Datastore { + // Looks up entities by key. + rpc Lookup(LookupRequest) returns (LookupResponse) { + option (google.api.http) = { post: "/v1/projects/{project_id}:lookup" body: "*" }; + } + + // Queries for entities. + rpc RunQuery(RunQueryRequest) returns (RunQueryResponse) { + option (google.api.http) = { post: "/v1/projects/{project_id}:runQuery" body: "*" }; + } + + // Begins a new transaction. + rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) { + option (google.api.http) = { post: "/v1/projects/{project_id}:beginTransaction" body: "*" }; + } + + // Commits a transaction, optionally creating, deleting or modifying some + // entities. + rpc Commit(CommitRequest) returns (CommitResponse) { + option (google.api.http) = { post: "/v1/projects/{project_id}:commit" body: "*" }; + } + + // Rolls back a transaction. + rpc Rollback(RollbackRequest) returns (RollbackResponse) { + option (google.api.http) = { post: "/v1/projects/{project_id}:rollback" body: "*" }; + } + + // Allocates IDs for the given keys, which is useful for referencing an entity + // before it is inserted. + rpc AllocateIds(AllocateIdsRequest) returns (AllocateIdsResponse) { + option (google.api.http) = { post: "/v1/projects/{project_id}:allocateIds" body: "*" }; + } +} + +// The request for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup]. +message LookupRequest { + // The ID of the project against which to make the request. + string project_id = 8; + + // The options for this lookup request. + ReadOptions read_options = 1; + + // Keys of entities to look up. + repeated Key keys = 3; +} + +// The response for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup]. +message LookupResponse { + // Entities found as `ResultType.FULL` entities. The order of results in this + // field is undefined and has no relation to the order of the keys in the + // input. + repeated EntityResult found = 1; + + // Entities not found as `ResultType.KEY_ONLY` entities. The order of results + // in this field is undefined and has no relation to the order of the keys + // in the input. + repeated EntityResult missing = 2; + + // A list of keys that were not looked up due to resource constraints. The + // order of results in this field is undefined and has no relation to the + // order of the keys in the input. + repeated Key deferred = 3; +} + +// The request for [Datastore.RunQuery][google.datastore.v1.Datastore.RunQuery]. +message RunQueryRequest { + // The ID of the project against which to make the request. + string project_id = 8; + + // Entities are partitioned into subsets, identified by a partition ID. + // Queries are scoped to a single partition. + // This partition ID is normalized with the standard default context + // partition ID. + PartitionId partition_id = 2; + + // The options for this query. + ReadOptions read_options = 1; + + // The type of query. + oneof query_type { + // The query to run. + Query query = 3; + + // The GQL query to run. + GqlQuery gql_query = 7; + } +} + +// The response for [Datastore.RunQuery][google.datastore.v1.Datastore.RunQuery]. +message RunQueryResponse { + // A batch of query results (always present). + QueryResultBatch batch = 1; + + // The parsed form of the `GqlQuery` from the request, if it was set. + Query query = 2; +} + +// The request for [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]. +message BeginTransactionRequest { + // The ID of the project against which to make the request. + string project_id = 8; +} + +// The response for [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]. +message BeginTransactionResponse { + // The transaction identifier (always present). + bytes transaction = 1; +} + +// The request for [Datastore.Rollback][google.datastore.v1.Datastore.Rollback]. +message RollbackRequest { + // The ID of the project against which to make the request. + string project_id = 8; + + // The transaction identifier, returned by a call to + // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]. + bytes transaction = 1; +} + +// The response for [Datastore.Rollback][google.datastore.v1.Datastore.Rollback]. +// (an empty message). +message RollbackResponse { + +} + +// The request for [Datastore.Commit][google.datastore.v1.Datastore.Commit]. +message CommitRequest { + // The modes available for commits. + enum Mode { + // Unspecified. This value must not be used. + MODE_UNSPECIFIED = 0; + + // Transactional: The mutations are either all applied, or none are applied. + // Learn about transactions [here](https://cloud.google.com/datastore/docs/concepts/transactions). + TRANSACTIONAL = 1; + + // Non-transactional: The mutations may not apply as all or none. + NON_TRANSACTIONAL = 2; + } + + // The ID of the project against which to make the request. + string project_id = 8; + + // The type of commit to perform. Defaults to `TRANSACTIONAL`. + Mode mode = 5; + + // Must be set when mode is `TRANSACTIONAL`. + oneof transaction_selector { + // The identifier of the transaction associated with the commit. A + // transaction identifier is returned by a call to + // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]. + bytes transaction = 1; + } + + // The mutations to perform. + // + // When mode is `TRANSACTIONAL`, mutations affecting a single entity are + // applied in order. The following sequences of mutations affecting a single + // entity are not permitted in a single `Commit` request: + // + // - `insert` followed by `insert` + // - `update` followed by `insert` + // - `upsert` followed by `insert` + // - `delete` followed by `update` + // + // When mode is `NON_TRANSACTIONAL`, no two mutations may affect a single + // entity. + repeated Mutation mutations = 6; +} + +// The response for [Datastore.Commit][google.datastore.v1.Datastore.Commit]. +message CommitResponse { + // The result of performing the mutations. + // The i-th mutation result corresponds to the i-th mutation in the request. + repeated MutationResult mutation_results = 3; + + // The number of index entries updated during the commit, or zero if none were + // updated. + int32 index_updates = 4; +} + +// The request for [Datastore.AllocateIds][google.datastore.v1.Datastore.AllocateIds]. +message AllocateIdsRequest { + // The ID of the project against which to make the request. + string project_id = 8; + + // A list of keys with incomplete key paths for which to allocate IDs. + // No key may be reserved/read-only. + repeated Key keys = 1; +} + +// The response for [Datastore.AllocateIds][google.datastore.v1.Datastore.AllocateIds]. +message AllocateIdsResponse { + // The keys specified in the request (in the same order), each with + // its key path completed with a newly allocated ID. + repeated Key keys = 1; +} + +// A mutation to apply to an entity. +message Mutation { + // The mutation operation. + // + // For `insert`, `update`, and `upsert`: + // - The entity's key must not be reserved/read-only. + // - No property in the entity may have a reserved name, + // not even a property in an entity in a value. + // - No value in the entity may have meaning 18, + // not even a value in an entity in another value. + oneof operation { + // The entity to insert. The entity must not already exist. + // The entity key's final path element may be incomplete. + Entity insert = 4; + + // The entity to update. The entity must already exist. + // Must have a complete key path. + Entity update = 5; + + // The entity to upsert. The entity may or may not already exist. + // The entity key's final path element may be incomplete. + Entity upsert = 6; + + // The key of the entity to delete. The entity may or may not already exist. + // Must have a complete key path and must not be reserved/read-only. + Key delete = 7; + } + + // When set, the server will detect whether or not this mutation conflicts + // with the current version of the entity on the server. Conflicting mutations + // are not applied, and are marked as such in MutationResult. + oneof conflict_detection_strategy { + // The version of the entity that this mutation is being applied to. If this + // does not match the current version on the server, the mutation conflicts. + int64 base_version = 8; + } +} + +// The result of applying a mutation. +message MutationResult { + // The automatically allocated key. + // Set only when the mutation allocated a key. + Key key = 3; + + // The version of the entity on the server after processing the mutation. If + // the mutation doesn't change anything on the server, then the version will + // be the version of the current entity or, if no entity is present, a version + // that is strictly greater than the version of any previous entity and less + // than the version of any possible future entity. + int64 version = 4; + + // Whether a conflict was detected for this mutation. Always false when a + // conflict detection strategy field is not set in the mutation. + bool conflict_detected = 5; +} + +// The options shared by read requests. +message ReadOptions { + // The possible values for read consistencies. + enum ReadConsistency { + // Unspecified. This value must not be used. + READ_CONSISTENCY_UNSPECIFIED = 0; + + // Strong consistency. + STRONG = 1; + + // Eventual consistency. + EVENTUAL = 2; + } + + // If not specified, lookups and ancestor queries default to + // `read_consistency`=`STRONG`, global queries default to + // `read_consistency`=`EVENTUAL`. + oneof consistency_type { + // The non-transactional read consistency to use. + // Cannot be set to `STRONG` for global queries. + ReadConsistency read_consistency = 1; + + // The identifier of the transaction in which to read. A + // transaction identifier is returned by a call to + // [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction]. + bytes transaction = 2; + } +} diff --git a/google/datastore/v1/entity.proto b/google/datastore/v1/entity.proto new file mode 100644 index 00000000..a0e7d391 --- /dev/null +++ b/google/datastore/v1/entity.proto @@ -0,0 +1,201 @@ +// Copyright 2016 Google Inc. +// +// 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.datastore.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/type/latlng.proto"; + +option java_multiple_files = true; +option java_outer_classname = "EntityProto"; +option java_package = "com.google.datastore.v1"; + + +// A partition ID identifies a grouping of entities. The grouping is always +// by project and namespace, however the namespace ID may be empty. +// +// A partition ID contains several dimensions: +// project ID and namespace ID. +// +// Partition dimensions: +// +// - May be `""`. +// - Must be valid UTF-8 bytes. +// - Must have values that match regex `[A-Za-z\d\.\-_]{1,100}` +// If the value of any dimension matches regex `__.*__`, the partition is +// reserved/read-only. +// A reserved/read-only partition ID is forbidden in certain documented +// contexts. +// +// Foreign partition IDs (in which the project ID does +// not match the context project ID ) are discouraged. +// Reads and writes of foreign partition IDs may fail if the project is not in an active state. +message PartitionId { + // The ID of the project to which the entities belong. + string project_id = 2; + + // If not empty, the ID of the namespace to which the entities belong. + string namespace_id = 4; +} + +// A unique identifier for an entity. +// If a key's partition ID or any of its path kinds or names are +// reserved/read-only, the key is reserved/read-only. +// A reserved/read-only key is forbidden in certain documented contexts. +message Key { + // A (kind, ID/name) pair used to construct a key path. + // + // If either name or ID is set, the element is complete. + // If neither is set, the element is incomplete. + message PathElement { + // The kind of the entity. + // A kind matching regex `__.*__` is reserved/read-only. + // A kind must not contain more than 1500 bytes when UTF-8 encoded. + // Cannot be `""`. + string kind = 1; + + // The type of ID. + oneof id_type { + // The auto-allocated ID of the entity. + // Never equal to zero. Values less than zero are discouraged and may not + // be supported in the future. + int64 id = 2; + + // The name of the entity. + // A name matching regex `__.*__` is reserved/read-only. + // A name must not be more than 1500 bytes when UTF-8 encoded. + // Cannot be `""`. + string name = 3; + } + } + + // Entities are partitioned into subsets, currently identified by a project + // ID and namespace ID. + // Queries are scoped to a single partition. + PartitionId partition_id = 1; + + // The entity path. + // An entity path consists of one or more elements composed of a kind and a + // string or numerical identifier, which identify entities. The first + // element identifies a _root entity_, the second element identifies + // a _child_ of the root entity, the third element identifies a child of the + // second entity, and so forth. The entities identified by all prefixes of + // the path are called the element's _ancestors_. + // + // An entity path is always fully complete: *all* of the entity's ancestors + // are required to be in the path along with the entity identifier itself. + // The only exception is that in some documented cases, the identifier in the + // last path element (for the entity) itself may be omitted. For example, + // the last path element of the key of `Mutation.insert` may have no + // identifier. + // + // A path can never be empty, and a path can have at most 100 elements. + repeated PathElement path = 2; +} + +// An array value. +message ArrayValue { + // Values in the array. + // The order of this array may not be preserved if it contains a mix of + // indexed and unindexed values. + repeated Value values = 1; +} + +// A message that can hold any of the supported value types and associated +// metadata. +message Value { + // Must have a value set. + oneof value_type { + // A null value. + google.protobuf.NullValue null_value = 11; + + // A boolean value. + bool boolean_value = 1; + + // An integer value. + int64 integer_value = 2; + + // A double value. + double double_value = 3; + + // A timestamp value. + // When stored in the Datastore, precise only to microseconds; + // any additional precision is rounded down. + google.protobuf.Timestamp timestamp_value = 10; + + // A key value. + Key key_value = 5; + + // A UTF-8 encoded string value. + // When `exclude_from_indexes` is false (it is indexed) , may have at most 1500 bytes. + // Otherwise, may be set to at least 1,000,000 bytes. + string string_value = 17; + + // A blob value. + // May have at most 1,000,000 bytes. + // When `exclude_from_indexes` is false, may have at most 1500 bytes. + // In JSON requests, must be base64-encoded. + bytes blob_value = 18; + + // A geo point value representing a point on the surface of Earth. + google.type.LatLng geo_point_value = 8; + + // An entity value. + // + // - May have no key. + // - May have a key with an incomplete key path. + // - May have a reserved/read-only key. + Entity entity_value = 6; + + // An array value. + // Cannot contain another array value. + // A `Value` instance that sets field `array_value` must not set fields + // `meaning` or `exclude_from_indexes`. + ArrayValue array_value = 9; + } + + // The `meaning` field should only be populated for backwards compatibility. + int32 meaning = 14; + + // If the value should be excluded from all indexes including those defined + // explicitly. + bool exclude_from_indexes = 19; +} + +// A Datastore data object. +// +// An entity is limited to 1 megabyte when stored. That _roughly_ +// corresponds to a limit of 1 megabyte for the serialized form of this +// message. +message Entity { + // The entity's key. + // + // An entity must have a key, unless otherwise documented (for example, + // an entity in `Value.entity_value` may have no key). + // An entity's kind is its key path's last element's kind, + // or null if it has no key. + Key key = 1; + + // The entity's properties. + // The map's keys are property names. + // A property name matching regex `__.*__` is reserved. + // A reserved property name is forbidden in certain documented contexts. + // The name must not contain more than 500 characters. + // The name cannot be `""`. + map properties = 3; +} diff --git a/google/datastore/v1/query.proto b/google/datastore/v1/query.proto new file mode 100644 index 00000000..e6dba2b2 --- /dev/null +++ b/google/datastore/v1/query.proto @@ -0,0 +1,306 @@ +// Copyright 2016 Google Inc. +// +// 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.datastore.v1; + +import "google/api/annotations.proto"; +import "google/datastore/v1/entity.proto"; +import "google/protobuf/wrappers.proto"; +import "google/type/latlng.proto"; + +option java_multiple_files = true; +option java_outer_classname = "QueryProto"; +option java_package = "com.google.datastore.v1"; + + +// The result of fetching an entity from Datastore. +message EntityResult { + // Specifies what data the 'entity' field contains. + // A `ResultType` is either implied (for example, in `LookupResponse.missing` + // from `datastore.proto`, it is always `KEY_ONLY`) or specified by context + // (for example, in message `QueryResultBatch`, field `entity_result_type` + // specifies a `ResultType` for all the values in field `entity_results`). + enum ResultType { + // Unspecified. This value is never used. + RESULT_TYPE_UNSPECIFIED = 0; + + // The key and properties. + FULL = 1; + + // A projected subset of properties. The entity may have no key. + PROJECTION = 2; + + // Only the key. + KEY_ONLY = 3; + } + + // The resulting entity. + Entity entity = 1; + + // The version of the entity, a strictly positive number that monotonically + // increases with changes to the entity. + // + // This field is set for [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity + // results. + // + // For [missing][google.datastore.v1.LookupResponse.missing] entities in `LookupResponse`, this + // is the version of the snapshot that was used to look up the entity, and it + // is always set except for eventually consistent reads. + int64 version = 4; + + // A cursor that points to the position after the result entity. + // Set only when the `EntityResult` is part of a `QueryResultBatch` message. + bytes cursor = 3; +} + +// A query for entities. +message Query { + // The projection to return. Defaults to returning all properties. + repeated Projection projection = 2; + + // The kinds to query (if empty, returns entities of all kinds). + // Currently at most 1 kind may be specified. + repeated KindExpression kind = 3; + + // The filter to apply. + Filter filter = 4; + + // The order to apply to the query results (if empty, order is unspecified). + repeated PropertyOrder order = 5; + + // The properties to make distinct. The query results will contain the first + // result for each distinct combination of values for the given properties + // (if empty, all results are returned). + repeated PropertyReference distinct_on = 6; + + // A starting point for the query results. Query cursors are + // returned in query result batches and + // [can only be used to continue the same query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets). + bytes start_cursor = 7; + + // An ending point for the query results. Query cursors are + // returned in query result batches and + // [can only be used to limit the same query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets). + bytes end_cursor = 8; + + // The number of results to skip. Applies before limit, but after all other + // constraints. Optional. Must be >= 0 if specified. + int32 offset = 10; + + // The maximum number of results to return. Applies after all other + // constraints. Optional. + // Unspecified is interpreted as no limit. + // Must be >= 0 if specified. + google.protobuf.Int32Value limit = 12; +} + +// A representation of a kind. +message KindExpression { + // The name of the kind. + string name = 1; +} + +// A reference to a property relative to the kind expressions. +message PropertyReference { + // The name of the property. + // If name includes "."s, it may be interpreted as a property name path. + string name = 2; +} + +// A representation of a property in a projection. +message Projection { + // The property to project. + PropertyReference property = 1; +} + +// The desired order for a specific property. +message PropertyOrder { + // The sort direction. + enum Direction { + // Unspecified. This value must not be used. + DIRECTION_UNSPECIFIED = 0; + + // Ascending. + ASCENDING = 1; + + // Descending. + DESCENDING = 2; + } + + // The property to order by. + PropertyReference property = 1; + + // The direction to order by. Defaults to `ASCENDING`. + Direction direction = 2; +} + +// A holder for any type of filter. +message Filter { + // The type of filter. + oneof filter_type { + // A composite filter. + CompositeFilter composite_filter = 1; + + // A filter on a property. + PropertyFilter property_filter = 2; + } +} + +// A filter that merges multiple other filters using the given operator. +message CompositeFilter { + // A composite filter operator. + enum Operator { + // Unspecified. This value must not be used. + OPERATOR_UNSPECIFIED = 0; + + // The results are required to satisfy each of the combined filters. + AND = 1; + } + + // The operator for combining multiple filters. + Operator op = 1; + + // The list of filters to combine. + // Must contain at least one filter. + repeated Filter filters = 2; +} + +// A filter on a specific property. +message PropertyFilter { + // A property filter operator. + enum Operator { + // Unspecified. This value must not be used. + OPERATOR_UNSPECIFIED = 0; + + // Less than. + LESS_THAN = 1; + + // Less than or equal. + LESS_THAN_OR_EQUAL = 2; + + // Greater than. + GREATER_THAN = 3; + + // Greater than or equal. + GREATER_THAN_OR_EQUAL = 4; + + // Equal. + EQUAL = 5; + + // Has ancestor. + HAS_ANCESTOR = 11; + } + + // The property to filter by. + PropertyReference property = 1; + + // The operator to filter by. + Operator op = 2; + + // The value to compare the property to. + Value value = 3; +} + +// A [GQL query](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). +message GqlQuery { + // A string of the format described + // [here](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). + string query_string = 1; + + // When false, the query string must not contain any literals and instead must + // bind all values. For example, + // `SELECT * FROM Kind WHERE a = 'string literal'` is not allowed, while + // `SELECT * FROM Kind WHERE a = @value` is. + bool allow_literals = 2; + + // For each non-reserved named binding site in the query string, there must be + // a named parameter with that name, but not necessarily the inverse. + // + // Key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex + // `__.*__`, and must not be `""`. + map named_bindings = 5; + + // Numbered binding site @1 references the first numbered parameter, + // effectively using 1-based indexing, rather than the usual 0. + // + // For each binding site numbered i in `query_string`, there must be an i-th + // numbered parameter. The inverse must also be true. + repeated GqlQueryParameter positional_bindings = 4; +} + +// A binding parameter for a GQL query. +message GqlQueryParameter { + // The type of parameter. + oneof parameter_type { + // A value parameter. + Value value = 2; + + // A query cursor. Query cursors are returned in query + // result batches. + bytes cursor = 3; + } +} + +// A batch of results produced by a query. +message QueryResultBatch { + // The possible values for the `more_results` field. + enum MoreResultsType { + // Unspecified. This value is never used. + MORE_RESULTS_TYPE_UNSPECIFIED = 0; + + // There may be additional batches to fetch from this query. + NOT_FINISHED = 1; + + // The query is finished, but there may be more results after the limit. + MORE_RESULTS_AFTER_LIMIT = 2; + + // The query is finished, but there may be more results after the end + // cursor. + MORE_RESULTS_AFTER_CURSOR = 4; + + // The query has been exhausted. + NO_MORE_RESULTS = 3; + } + + // The number of results skipped, typically because of an offset. + int32 skipped_results = 6; + + // A cursor that points to the position after the last skipped result. + // Will be set when `skipped_results` != 0. + bytes skipped_cursor = 3; + + // The result type for every entity in `entity_results`. + EntityResult.ResultType entity_result_type = 1; + + // The results for this batch. + repeated EntityResult entity_results = 2; + + // A cursor that points to the position after the last result in the batch. + bytes end_cursor = 4; + + // The state of the query after the current batch. + MoreResultsType more_results = 5; + + // The version number of the snapshot this batch was returned from. + // This applies to the range of results from the query's `start_cursor` (or + // the beginning of the query if no cursor was given) to this batch's + // `end_cursor` (not the query's `end_cursor`). + // + // In a single transaction, subsequent query result batches for the same query + // can have a greater snapshot version number. Each batch's snapshot version + // is valid for all preceding batches. + int64 snapshot_version = 7; +} diff --git a/google/datastore/v1beta3/datastore.proto b/google/datastore/v1beta3/datastore.proto index 570b7b74..3f4f1e4c 100644 --- a/google/datastore/v1beta3/datastore.proto +++ b/google/datastore/v1beta3/datastore.proto @@ -66,7 +66,7 @@ service Datastore { } } -// The request for [google.datastore.v1beta3.Datastore.Lookup][google.datastore.v1beta3.Datastore.Lookup]. +// The request for [Datastore.Lookup][google.datastore.v1beta3.Datastore.Lookup]. message LookupRequest { // The ID of the project against which to make the request. string project_id = 8; @@ -78,7 +78,7 @@ message LookupRequest { repeated Key keys = 3; } -// The response for [google.datastore.v1beta3.Datastore.Lookup][google.datastore.v1beta3.Datastore.Lookup]. +// The response for [Datastore.Lookup][google.datastore.v1beta3.Datastore.Lookup]. message LookupResponse { // Entities found as `ResultType.FULL` entities. The order of results in this // field is undefined and has no relation to the order of the keys in the @@ -96,7 +96,7 @@ message LookupResponse { repeated Key deferred = 3; } -// The request for [google.datastore.v1beta3.Datastore.RunQuery][google.datastore.v1beta3.Datastore.RunQuery]. +// The request for [Datastore.RunQuery][google.datastore.v1beta3.Datastore.RunQuery]. message RunQueryRequest { // The ID of the project against which to make the request. string project_id = 8; @@ -120,7 +120,7 @@ message RunQueryRequest { } } -// The response for [google.datastore.v1beta3.Datastore.RunQuery][google.datastore.v1beta3.Datastore.RunQuery]. +// The response for [Datastore.RunQuery][google.datastore.v1beta3.Datastore.RunQuery]. message RunQueryResponse { // A batch of query results (always present). QueryResultBatch batch = 1; @@ -129,35 +129,35 @@ message RunQueryResponse { Query query = 2; } -// The request for [google.datastore.v1beta3.Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. +// The request for [Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. message BeginTransactionRequest { // The ID of the project against which to make the request. string project_id = 8; } -// The response for [google.datastore.v1beta3.Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. +// The response for [Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. message BeginTransactionResponse { // The transaction identifier (always present). bytes transaction = 1; } -// The request for [google.datastore.v1beta3.Datastore.Rollback][google.datastore.v1beta3.Datastore.Rollback]. +// The request for [Datastore.Rollback][google.datastore.v1beta3.Datastore.Rollback]. message RollbackRequest { // The ID of the project against which to make the request. string project_id = 8; // The transaction identifier, returned by a call to - // [google.datastore.v1beta3.Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. + // [Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. bytes transaction = 1; } -// The response for [google.datastore.v1beta3.Datastore.Rollback][google.datastore.v1beta3.Datastore.Rollback] +// The response for [Datastore.Rollback][google.datastore.v1beta3.Datastore.Rollback]. // (an empty message). message RollbackResponse { } -// The request for [google.datastore.v1beta3.Datastore.Commit][google.datastore.v1beta3.Datastore.Commit]. +// The request for [Datastore.Commit][google.datastore.v1beta3.Datastore.Commit]. message CommitRequest { // The modes available for commits. enum Mode { @@ -182,7 +182,7 @@ message CommitRequest { oneof transaction_selector { // The identifier of the transaction associated with the commit. A // transaction identifier is returned by a call to - // [BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. + // [Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. bytes transaction = 1; } @@ -202,7 +202,7 @@ message CommitRequest { repeated Mutation mutations = 6; } -// The response for [google.datastore.v1beta3.Datastore.Commit][google.datastore.v1beta3.Datastore.Commit]. +// The response for [Datastore.Commit][google.datastore.v1beta3.Datastore.Commit]. message CommitResponse { // The result of performing the mutations. // The i-th mutation result corresponds to the i-th mutation in the request. @@ -213,7 +213,7 @@ message CommitResponse { int32 index_updates = 4; } -// The request for [google.datastore.v1beta3.Datastore.AllocateIds][google.datastore.v1beta3.Datastore.AllocateIds]. +// The request for [Datastore.AllocateIds][google.datastore.v1beta3.Datastore.AllocateIds]. message AllocateIdsRequest { // The ID of the project against which to make the request. string project_id = 8; @@ -223,7 +223,7 @@ message AllocateIdsRequest { repeated Key keys = 1; } -// The response for [google.datastore.v1beta3.Datastore.AllocateIds][google.datastore.v1beta3.Datastore.AllocateIds]. +// The response for [Datastore.AllocateIds][google.datastore.v1beta3.Datastore.AllocateIds]. message AllocateIdsResponse { // The keys specified in the request (in the same order), each with // its key path completed with a newly allocated ID. @@ -310,7 +310,7 @@ message ReadOptions { // The identifier of the transaction in which to read. A // transaction identifier is returned by a call to - // [BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. + // [Datastore.BeginTransaction][google.datastore.v1beta3.Datastore.BeginTransaction]. bytes transaction = 2; } } diff --git a/google/datastore/v1beta3/query.proto b/google/datastore/v1beta3/query.proto index 3e606496..004c9a47 100644 --- a/google/datastore/v1beta3/query.proto +++ b/google/datastore/v1beta3/query.proto @@ -53,11 +53,12 @@ message EntityResult { // The version of the entity, a strictly positive number that monotonically // increases with changes to the entity. // - // This field is set for [`FULL`] - // [google.datastore.v1beta3.EntityResult.ResultType.FULL] entity results. - // For [missing][google.datastore.v1beta3.LookupResponse.missing] entities in - // `LookupResponse`, this is the version of the snapshot that was used to look - // up the entity, and it is always set except for eventually consistent reads. + // This field is set for [`FULL`][google.datastore.v1beta3.EntityResult.ResultType.FULL] entity + // results. + // + // For [missing][google.datastore.v1beta3.LookupResponse.missing] entities in `LookupResponse`, this + // is the version of the snapshot that was used to look up the entity, and it + // is always set except for eventually consistent reads. int64 version = 4; // A cursor that points to the position after the result entity. @@ -219,24 +220,24 @@ message GqlQuery { // [here](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). string query_string = 1; - // When false, the query string must not contain any literals and instead - // must bind all values. For example, + // When false, the query string must not contain any literals and instead must + // bind all values. For example, // `SELECT * FROM Kind WHERE a = 'string literal'` is not allowed, while // `SELECT * FROM Kind WHERE a = @value` is. bool allow_literals = 2; - // For each non-reserved named binding site in the query string, - // there must be a named parameter with that name, - // but not necessarily the inverse. + // For each non-reserved named binding site in the query string, there must be + // a named parameter with that name, but not necessarily the inverse. + // // Key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex // `__.*__`, and must not be `""`. map named_bindings = 5; // Numbered binding site @1 references the first numbered parameter, // effectively using 1-based indexing, rather than the usual 0. - // For each binding site numbered i in `query_string`, - // there must be an i-th numbered parameter. - // The inverse must also be true. + // + // For each binding site numbered i in `query_string`, there must be an i-th + // numbered parameter. The inverse must also be true. repeated GqlQueryParameter positional_bindings = 4; } @@ -266,7 +267,8 @@ message QueryResultBatch { // The query is finished, but there may be more results after the limit. MORE_RESULTS_AFTER_LIMIT = 2; - // The query is finished, but there may be more results after the end cursor. + // The query is finished, but there may be more results after the end + // cursor. MORE_RESULTS_AFTER_CURSOR = 4; // The query has been exhausted.