Add datastore v1 protos, update v1beta1
This commit is contained in:
Jacob Geiger
parent
06aca80043
commit
0ebdb62d8b
|
|
@ -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
|
||||
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
|
|
@ -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<string, Value> properties = 3;
|
||||
}
|
||||
|
|
@ -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<string, GqlQueryParameter> 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;
|
||||
}
|
||||
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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<string, GqlQueryParameter> 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue