// Copyright 2013 Google Inc. All Rights Reserved. | |
// | |
// The datastore v1 service proto definitions | |
syntax = "proto2" ; | |
package api . services.datastore ; | |
option java_package = "com.google.api.services.datastore" ; | |
// An identifier for a particular subset of entities. | |
// | |
// Entities are partitioned into various subsets, each used by different | |
// datasets and different namespaces within a dataset and so forth. | |
// | |
// All input partition IDs are normalized before use. | |
// A partition ID is normalized as follows: | |
// If the partition ID is unset or is set to an empty partition ID, replace it | |
// with the context partition ID. | |
// Otherwise, if the partition ID has no dataset ID, assign it the context | |
// partition ID's dataset ID. | |
// Unless otherwise documented, the context partition ID has the dataset ID set | |
// to the context dataset ID and no other partition dimension set. | |
// | |
// A partition ID is empty if all of its fields are unset. | |
// | |
// Partition dimension: | |
// A dimension may be unset. | |
// A dimension's value must never be "". | |
// A dimension's value must match [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. | |
// | |
// Dataset ID: | |
// A dataset id's value must never be "". | |
// A dataset id's value must match | |
// ([a-z\d\-]{1,100}~)?([a-z\d][a-z\d\-\.]{0,99}:)?([a-z\d][a-z\d\-]{0,99} | |
message PartitionId { | |
// The dataset ID. | |
optional string dataset_id = 3 ; | |
// The namespace. | |
optional string namespace = 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 { | |
// Entities are partitioned into subsets, currently identified by a dataset | |
// (usually implicitly specified by the project) and namespace ID. | |
// Queries are scoped to a single partition. | |
optional PartitionId partition_id = 1 ; | |
// A (kind, ID/name) pair used to construct a key path. | |
// | |
// At most one of name or ID may be set. | |
// If either 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 500 characters. | |
// Cannot be "". | |
required string kind = 1 ; | |
// The ID of the entity. | |
// Never equal to zero. Values less than zero are discouraged and will not | |
// be supported in the future. | |
optional int64 id = 2 ; | |
// The name of the entity. | |
// A name matching regex "__.*__" is reserved/read-only. | |
// A name must not be more than 500 characters. | |
// Cannot be "". | |
optional string name = 3 ; | |
} | |
// 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 <em>root entity</em>, the second element identifies | |
// a <em>child</em> of the root entity, the third element a child of the | |
// second entity, and so forth. The entities identified by all prefixes of | |
// the path are called the element's <em>ancestors</em>. | |
// 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. A path can never | |
// be empty. | |
repeated PathElement path_element = 2 ; | |
} | |
// A message that can hold any of the supported value types and associated | |
// metadata. | |
// | |
// At most one of the <type>Value fields may be set. | |
// If none are set the value is "null". | |
// | |
message Value { | |
// A boolean value. | |
optional bool boolean_value = 1 ; | |
// An integer value. | |
optional int64 integer_value = 2 ; | |
// A double value. | |
optional double double_value = 3 ; | |
// A timestamp value. | |
optional int64 timestamp_microseconds_value = 4 ; | |
// A key value. | |
optional Key key_value = 5 ; | |
// A blob key value. | |
optional string blob_key_value = 16 ; | |
// A UTF-8 encoded string value. | |
optional string string_value = 17 ; | |
// A blob value. | |
optional bytes blob_value = 18 ; | |
// An entity value. | |
// May have no key. | |
// May have a key with an incomplete key path. | |
// May have a reserved/read-only key. | |
optional Entity entity_value = 6 ; | |
// A list value. | |
// Cannot contain another list value. | |
// Cannot also have a meaning and indexing set. | |
repeated Value list_value = 7 ; | |
// The <code>meaning</code> field is reserved and should not be used. | |
optional int32 meaning = 14 ; | |
// If the value should be indexed. | |
// | |
// The <code>indexed</code> property may be set for a | |
// <code>null</code> value. | |
// When <code>indexed</code> is <code>true</code>, <code>stringValue</code> | |
// is limited to 500 characters and the blob value is limited to 500 bytes. | |
// Exception: If meaning is set to 2, string_value is limited to 2038 | |
// characters regardless of indexed. | |
// When indexed is true, meaning 15 and 22 are not allowed, and meaning 16 | |
// will be ignored on input (and will never be set on output). | |
// Input values by default have <code>indexed</code> set to | |
// <code>true</code>; however, you can explicitly set <code>indexed</code> to | |
// <code>true</code> if you want. (An output value never has | |
// <code>indexed</code> explicitly set to <code>true</code>.) If a value is | |
// itself an entity, it cannot have <code>indexed</code> set to | |
// <code>true</code>. | |
// Exception: An entity value with meaning 9, 20 or 21 may be indexed. | |
optional bool indexed = 15 [ default = true ]; | |
} | |
// An entity property. | |
message Property { | |
// The name of the property. | |
// 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. | |
// Cannot be "". | |
required string name = 1 ; | |
// The value(s) of the property. | |
// Each value can have only one value property populated. For example, | |
// you cannot have a values list of <code>{ value: { integerValue: 22, | |
// stringValue: "a" } }</code>, but you can have <code>{ value: { listValue: | |
// [ { integerValue: 22 }, { stringValue: "a" } ] }</code>. | |
required Value value = 4 ; | |
} | |
// An entity. | |
// | |
// An entity is limited to 1 megabyte when stored. That <em>roughly</em> | |
// 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 <code>Value.entityValue</code> may have no key). | |
// An entity's kind is its key's path's last element's kind, | |
// or null if it has no key. | |
optional Key key = 1 ; | |
// The entity's properties. | |
// Each property's name must be unique for its entity. | |
repeated Property property = 2 ; | |
} | |
// The result of fetching an entity from the datastore. | |
message EntityResult { | |
// Specifies what data the 'entity' field contains. | |
// A ResultType is either implied (for example, in LookupResponse.found it | |
// is always FULL) or specified by context (for example, in message | |
// QueryResultBatch, field 'entity_result_type' specifies a ResultType | |
// for all the values in field 'entity_result'). | |
enum ResultType { | |
FULL = 1 ; // The entire entity. | |
PROJECTION = 2 ; // A projected subset of properties. | |
// The entity may have no key. | |
// A property value may have meaning 18. | |
KEY_ONLY = 3 ; // Only the key. | |
} | |
// The resulting entity. | |
required Entity entity = 1 ; | |
} | |
// A query. | |
message Query { | |
// The projection to return. If not set the entire entity is returned. | |
repeated PropertyExpression projection = 2 ; | |
// The kinds to query (if empty, returns entities from all kinds). | |
repeated KindExpression kind = 3 ; | |
// The filter to apply (optional). | |
optional Filter filter = 4 ; | |
// The order to apply to the query results (if empty, order is unspecified). | |
repeated PropertyOrder order = 5 ; | |
// The properties to group by (if empty, no grouping is applied to the | |
// result set). | |
repeated PropertyReference group_by = 6 ; | |
// A starting point for the query results. Optional. Query cursors are | |
// returned in query result batches. | |
optional bytes /* serialized QueryCursor */ start_cursor = 7 ; | |
// An ending point for the query results. Optional. Query cursors are | |
// returned in query result batches. | |
optional bytes /* serialized QueryCursor */ end_cursor = 8 ; | |
// The number of results to skip. Applies before limit, but after all other | |
// constraints (optional, defaults to 0). | |
optional int32 offset = 10 [ default = 0 ]; | |
// The maximum number of results to return. Applies after all other | |
// constraints. Optional. | |
optional int32 limit = 11 ; | |
} | |
// A representation of a kind. | |
message KindExpression { | |
// The name of the kind. | |
required string name = 1 ; | |
} | |
// A reference to a property relative to the kind expressions. | |
// exactly. | |
message PropertyReference { | |
// The name of the property. | |
required string name = 2 ; | |
} | |
// A representation of a property in a projection. | |
message PropertyExpression { | |
enum AggregationFunction { | |
FIRST = 1 ; | |
} | |
// The property to project. | |
required PropertyReference property = 1 ; | |
// The aggregation function to apply to the property. Optional. | |
// Can only be used when grouping by at least one property. Must | |
// then be set on all properties in the projection that are not | |
// being grouped by. | |
optional AggregationFunction aggregation_function = 2 ; | |
} | |
// The desired order for a specific property. | |
message PropertyOrder { | |
enum Direction { | |
ASCENDING = 1 ; | |
DESCENDING = 2 ; | |
} | |
// The property to order by. | |
required PropertyReference property = 1 ; | |
// The direction to order by. | |
optional Direction direction = 2 [ default = ASCENDING ]; | |
} | |
// A holder for any type of filter. Exactly one field should be specified. | |
message Filter { | |
// A composite filter. | |
optional CompositeFilter composite_filter = 1 ; | |
// A filter on a property. | |
optional PropertyFilter property_filter = 2 ; | |
} | |
// A filter that merges the multiple other filters using the given operation. | |
message CompositeFilter { | |
enum Operator { | |
AND = 1 ; | |
} | |
// The operator for combining multiple filters. | |
required Operator operator = 1 ; | |
// The list of filters to combine. | |
// Must contain at least one filter. | |
repeated Filter filter = 2 ; | |
} | |
// A filter on a specific property. | |
message PropertyFilter { | |
enum Operator { | |
LESS_THAN = 1 ; | |
LESS_THAN_OR_EQUAL = 2 ; | |
GREATER_THAN = 3 ; | |
GREATER_THAN_OR_EQUAL = 4 ; | |
EQUAL = 5 ; | |
HAS_ANCESTOR = 11 ; | |
} | |
// The property to filter by. | |
required PropertyReference property = 1 ; | |
// The operator to filter by. | |
required Operator operator = 2 ; | |
// The value to compare the property to. | |
required Value value = 3 ; | |
} | |
// A GQL query. | |
message GqlQuery { | |
required string query_string = 1 ; | |
// When false, the query string must not contain a literal. | |
optional bool allow_literal = 2 [ default = false ]; | |
// A named argument must set field GqlQueryArg.name. | |
// No two named arguments may have the same name. | |
// For each non-reserved named binding site in the query string, | |
// there must be a named argument with that name, | |
// but not necessarily the inverse. | |
repeated GqlQueryArg name_arg = 3 ; | |
// Numbered binding site @1 references the first numbered argument, | |
// effectively using 1-based indexing, rather than the usual 0. | |
// A numbered argument must NOT set field GqlQueryArg.name. | |
// For each binding site numbered i in query_string, | |
// there must be an ith numbered argument. | |
// The inverse must also be true. | |
repeated GqlQueryArg number_arg = 4 ; | |
} | |
// A binding argument for a GQL query. | |
// Exactly one of fields value and cursor must be set. | |
message GqlQueryArg { | |
// Must match regex "[A-Za-z_$][A-Za-z_$0-9]*". | |
// Must not match regex "__.*__". | |
// Must not be "". | |
optional string name = 1 ; | |
optional Value value = 2 ; | |
optional bytes cursor = 3 ; | |
} | |
// A batch of results produced by a query. | |
message QueryResultBatch { | |
// The possible values for the 'more_results' field. | |
enum MoreResultsType { | |
NOT_FINISHED = 1 ; // There are additional batches to fetch from this query. | |
MORE_RESULTS_AFTER_LIMIT = 2 ; // The query is finished, but there are more | |
// results after the limit. | |
NO_MORE_RESULTS = 3 ; // The query has been exhausted. | |
} | |
// The result type for every entity in entityResults. | |
required EntityResult.ResultType entity_result_type = 1 ; | |
// The results for this batch. | |
repeated EntityResult entity_result = 2 ; | |
// A cursor that points to the position after the last result in the batch. | |
// May be absent. | |
optional bytes /* serialized QueryCursor */ end_cursor = 4 ; | |
// The state of the query after the current batch. | |
required MoreResultsType more_results = 5 ; | |
// The number of results skipped because of <code>Query.offset</code>. | |
optional int32 skipped_results = 6 ; | |
} | |
// A set of changes to apply. | |
// | |
// No entity in this message may have a reserved property name, | |
// not even a property in an entity in a value. | |
// No value in this message may have meaning 18, | |
// not even a value in an entity in another value. | |
// | |
// If entities with duplicate keys are present, an arbitrary choice will | |
// be made as to which is written. | |
message Mutation { | |
// Entities to upsert. | |
// Each upserted entity's key must have a complete path and | |
// must not be reserved/read-only. | |
repeated Entity upsert = 1 ; | |
// Entities to update. | |
// Each updated entity's key must have a complete path and | |
// must not be reserved/read-only. | |
repeated Entity update = 2 ; | |
// Entities to insert. | |
// Each inserted entity's key must have a complete path and | |
// must not be reserved/read-only. | |
repeated Entity insert = 3 ; | |
// Insert entities with a newly allocated ID. | |
// Each inserted entity's key must omit the final identifier in its path and | |
// must not be reserved/read-only. | |
repeated Entity insert_auto_id = 4 ; | |
// Keys of entities to delete. | |
// Each key must have a complete key path and must not be reserved/read-only. | |
repeated Key delete = 5 ; | |
// Ignore a user specified read-only period. Optional. | |
optional bool force = 6 ; | |
} | |
// The result of applying a mutation. | |
message MutationResult { | |
// Number of index writes. | |
required int32 index_updates = 1 ; | |
// Keys for <code>insertAutoId</code> entities. One per entity from the | |
// request, in the same order. | |
repeated Key insert_auto_id_key = 2 ; | |
} | |
// Options shared by read requests. | |
message ReadOptions { | |
enum ReadConsistency { | |
DEFAULT = 0 ; | |
STRONG = 1 ; | |
EVENTUAL = 2 ; | |
} | |
// The read consistency to use. | |
// Cannot be set when transaction is set. | |
// Lookup and ancestor queries default to STRONG, global queries default to | |
// EVENTUAL and cannot be set to STRONG. | |
optional ReadConsistency read_consistency = 1 [ default = DEFAULT ]; | |
// The transaction to use. Optional. | |
optional bytes /* serialized Transaction */ transaction = 2 ; | |
} | |
// The request for Lookup. | |
message LookupRequest { | |
// Options for this lookup request. Optional. | |
optional ReadOptions read_options = 1 ; | |
// Keys of entities to look up from the datastore. | |
repeated Key key = 3 ; | |
} | |
// The response for Lookup. | |
message LookupResponse { | |
// The order of results in these fields is undefined and has no relation to | |
// the order of the keys in the input. | |
// Entities found as ResultType.FULL entities. | |
repeated EntityResult found = 1 ; | |
// Entities not found as ResultType.KEY_ONLY entities. | |
repeated EntityResult missing = 2 ; | |
// A list of keys that were not looked up due to resource constraints. | |
repeated Key deferred = 3 ; | |
} | |
// The request for RunQuery. | |
message RunQueryRequest { | |
// The options for this query. | |
optional ReadOptions read_options = 1 ; | |
// Entities are partitioned into subsets, identified by a dataset (usually | |
// implicitly specified by the project) and namespace ID. Queries are scoped | |
// to a single partition. | |
// This partition ID is normalized with the standard default context | |
// partition ID, but all other partition IDs in RunQueryRequest are | |
// normalized with this partition ID as the context partition ID. | |
optional PartitionId partition_id = 2 ; | |
// The query to run. | |
// Either this field or field gql_query must be set, but not both. | |
optional Query query = 3 ; | |
// The GQL query to run. | |
// Either this field or field query must be set, but not both. | |
optional GqlQuery gql_query = 7 ; | |
} | |
// The response for RunQuery. | |
message RunQueryResponse { | |
// A batch of query results (always present). | |
optional QueryResultBatch batch = 1 ; | |
} | |
// The request for BeginTransaction. | |
message BeginTransactionRequest { | |
enum IsolationLevel { | |
SNAPSHOT = 0 ; // Read from a consistent snapshot. Concurrent transactions | |
// conflict if their mutations conflict. For example: | |
// Read(A),Write(B) may not conflict with Read(B),Write(A), | |
// but Read(B),Write(B) does conflict with Read(B),Write(B). | |
SERIALIZABLE = 1 ; // Read from a consistent snapshot. Concurrent | |
// transactions conflict if they cannot be serialized. | |
// For example Read(A),Write(B) does conflict with | |
// Read(B),Write(A) but Read(A) may not conflict with | |
// Write(A). | |
} | |
// The transaction isolation level. | |
optional IsolationLevel isolation_level = 1 [ default = SNAPSHOT ]; | |
} | |
// The response for BeginTransaction. | |
message BeginTransactionResponse { | |
// The transaction identifier (always present). | |
optional bytes /* serialized Transaction */ transaction = 1 ; | |
} | |
// The request for Rollback. | |
message RollbackRequest { | |
// The transaction identifier, returned by a call to | |
// <code>beginTransaction</code>. | |
required bytes /* serialized Transaction */ transaction = 1 ; | |
} | |
// The response for Rollback. | |
message RollbackResponse { | |
// Empty | |
} | |
// The request for Commit. | |
message CommitRequest { | |
enum Mode { | |
TRANSACTIONAL = 1 ; | |
NON_TRANSACTIONAL = 2 ; | |
} | |
// The transaction identifier, returned by a call to | |
// <code>beginTransaction</code>. Must be set when mode is TRANSACTIONAL. | |
optional bytes /* serialized Transaction */ transaction = 1 ; | |
// The mutation to perform. Optional. | |
optional Mutation mutation = 2 ; | |
// The type of commit to perform. Either TRANSACTIONAL or NON_TRANSACTIONAL. | |
optional Mode mode = 5 [ default = TRANSACTIONAL ]; | |
} | |
// The response for Commit. | |
message CommitResponse { | |
// The result of performing the mutation (if any). | |
optional MutationResult mutation_result = 1 ; | |
} | |
// The request for AllocateIds. | |
message AllocateIdsRequest { | |
// A list of keys with incomplete key paths to allocate IDs for. | |
// No key may be reserved/read-only. | |
repeated Key key = 1 ; | |
} | |
// The response for 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 key = 1 ; | |
} | |
// Each rpc normalizes the partition IDs of the keys in its input entities, | |
// and always returns entities with keys with normalized partition IDs. | |
// (Note that applies to all entities, including entities in values.) | |
service DatastoreService { | |
// Look up some entities by key. | |
rpc Lookup ( LookupRequest ) returns ( LookupResponse ) { | |
}; | |
// Query for entities. | |
rpc RunQuery ( RunQueryRequest ) returns ( RunQueryResponse ) { | |
}; | |
// Begin a new transaction. | |
rpc BeginTransaction ( BeginTransactionRequest ) returns ( BeginTransactionResponse ) { | |
}; | |
// Commit a transaction, optionally creating, deleting or modifying some | |
// entities. | |
rpc Commit ( CommitRequest ) returns ( CommitResponse ) { | |
}; | |
// Roll back a transaction. | |
rpc Rollback ( RollbackRequest ) returns ( RollbackResponse ) { | |
}; | |
// Allocate IDs for incomplete keys (useful for referencing an entity before | |
// it is inserted). | |
rpc AllocateIds ( AllocateIdsRequest ) returns ( AllocateIdsResponse ) { | |
}; | |
} |