google/datastore/v1/query.proto - platform/external/googleapis - Git at Google

 // Copyright 2023 Google LLC
 //
 // 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/field_behavior.proto";
 import "google/datastore/v1/entity.proto";
 import "google/protobuf/timestamp.proto";
 import "google/protobuf/wrappers.proto";

 option csharp_namespace = "Google.Cloud.Datastore.V1";
 option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
 option java_multiple_files = true;
 option java_outer_classname = "QueryProto";
 option java_package = "com.google.datastore.v1";
 option php_namespace = "Google\\Cloud\\Datastore\\V1";
 option ruby_package = "Google::Cloud::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;

   // The time at which the entity was created.
   // This field is set for
   // [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
   // If this entity is missing, this field will not be set.
   google.protobuf.Timestamp create_time = 6;

   // The time at which the entity was last changed.
   // This field is set for
   // [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
   // If this entity is missing, this field will not be set.
   google.protobuf.Timestamp update_time = 5;

   // 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).
   //
   // Requires:
   //
   // * If `order` is specified, the set of distinct on properties must appear
   // before the non-distinct on properties in `order`.
   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;
 }

 // Datastore query for running an aggregation over a
 // [Query][google.datastore.v1.Query].
 message AggregationQuery {
   // Defines an aggregation that produces a single result.
   message Aggregation {
     // Count of entities that match the query.
     //
     // The `COUNT(*)` aggregation function operates on the entire entity
     // so it does not require a field reference.
     message Count {
       // Optional. Optional constraint on the maximum number of entities to
       // count.
       //
       // This provides a way to set an upper bound on the number of entities
       // to scan, limiting latency, and cost.
       //
       // Unspecified is interpreted as no bound.
       //
       // If a zero value is provided, a count result of zero should always be
       // expected.
       //
       // High-Level Example:
       //
       // ```
       // AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
       // ```
       //
       // Requires:
       //
       // * Must be non-negative when present.
       google.protobuf.Int64Value up_to = 1
           [(google.api.field_behavior) = OPTIONAL];
     }

     // Sum of the values of the requested property.
     //
     // * Only numeric values will be aggregated. All non-numeric values
     // including `NULL` are skipped.
     //
     // * If the aggregated values contain `NaN`, returns `NaN`. Infinity math
     // follows IEEE-754 standards.
     //
     // * If the aggregated value set is empty, returns 0.
     //
     // * Returns a 64-bit integer if all aggregated numbers are integers and the
     // sum result does not overflow. Otherwise, the result is returned as a
     // double. Note that even if all the aggregated values are integers, the
     // result is returned as a double if it cannot fit within a 64-bit signed
     // integer. When this occurs, the returned value will lose precision.
     //
     // * When underflow occurs, floating-point aggregation is non-deterministic.
     // This means that running the same query repeatedly without any changes to
     // the underlying values could produce slightly different results each
     // time. In those cases, values should be stored as integers over
     // floating-point numbers.
     message Sum {
       // The property to aggregate on.
       PropertyReference property = 1;
     }

     // Average of the values of the requested property.
     //
     // * Only numeric values will be aggregated. All non-numeric values
     // including `NULL` are skipped.
     //
     // * If the aggregated values contain `NaN`, returns `NaN`. Infinity math
     // follows IEEE-754 standards.
     //
     // * If the aggregated value set is empty, returns `NULL`.
     //
     // * Always returns the result as a double.
     message Avg {
       // The property to aggregate on.
       PropertyReference property = 1;
     }

     // The type of aggregation to perform, required.
     oneof operator {
       // Count aggregator.
       Count count = 1;

       // Sum aggregator.
       Sum sum = 2;

       // Average aggregator.
       Avg avg = 3;
     }

     // Optional. Optional name of the property to store the result of the
     // aggregation.
     //
     // If not provided, Datastore will pick a default name following the format
     // `property_<incremental_id++>`. For example:
     //
     // ```
     // AGGREGATE
     //   COUNT_UP_TO(1) AS count_up_to_1,
     //   COUNT_UP_TO(2),
     //   COUNT_UP_TO(3) AS count_up_to_3,
     //   COUNT(*)
     // OVER (
     //   ...
     // );
     // ```
     //
     // becomes:
     //
     // ```
     // AGGREGATE
     //   COUNT_UP_TO(1) AS count_up_to_1,
     //   COUNT_UP_TO(2) AS property_1,
     //   COUNT_UP_TO(3) AS count_up_to_3,
     //   COUNT(*) AS property_2
     // OVER (
     //   ...
     // );
     // ```
     //
     // Requires:
     //
     // * Must be unique across all aggregation aliases.
     // * Conform to [entity property
     // name][google.datastore.v1.Entity.properties] limitations.
     string alias = 7 [(google.api.field_behavior) = OPTIONAL];
   }

   // The base query to aggregate over.
   oneof query_type {
     // Nested query for aggregation
     Query nested_query = 1;
   }

   // Optional. Series of aggregations to apply over the results of the
   // `nested_query`.
   //
   // Requires:
   //
   // * A minimum of one and maximum of five aggregations per query.
   repeated Aggregation aggregations = 3
       [(google.api.field_behavior) = OPTIONAL];
 }

 // 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 {
   // A reference to a property.
   //
   // Requires:
   //
   // * MUST be a dot-delimited (`.`) string of segments, where each segment
   // conforms to [entity property name][google.datastore.v1.Entity.properties]
   // limitations.
   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;

     // Documents are required to satisfy at least one of the combined filters.
     OR = 2;
   }

   // The operator for combining multiple filters.
   Operator op = 1;

   // The list of filters to combine.
   //
   // Requires:
   //
   // * At least one filter is present.
   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;

     // The given `property` is less than the given `value`.
     //
     // Requires:
     //
     // * That `property` comes first in `order_by`.
     LESS_THAN = 1;

     // The given `property` is less than or equal to the given `value`.
     //
     // Requires:
     //
     // * That `property` comes first in `order_by`.
     LESS_THAN_OR_EQUAL = 2;

     // The given `property` is greater than the given `value`.
     //
     // Requires:
     //
     // * That `property` comes first in `order_by`.
     GREATER_THAN = 3;

     // The given `property` is greater than or equal to the given `value`.
     //
     // Requires:
     //
     // * That `property` comes first in `order_by`.
     GREATER_THAN_OR_EQUAL = 4;

     // The given `property` is equal to the given `value`.
     EQUAL = 5;

     // The given `property` is equal to at least one value in the given array.
     //
     // Requires:
     //
     // * That `value` is a non-empty `ArrayValue`, subject to disjunction
     //   limits.
     // * No `NOT_IN` is in the same query.
     IN = 6;

     // The given `property` is not equal to the given `value`.
     //
     // Requires:
     //
     // * No other `NOT_EQUAL` or `NOT_IN` is in the same query.
     // * That `property` comes first in the `order_by`.
     NOT_EQUAL = 9;

     // Limit the result set to the given entity and its descendants.
     //
     // Requires:
     //
     // * That `value` is an entity key.
     // * All evaluated disjunctions must have the same `HAS_ANCESTOR` filter.
     HAS_ANCESTOR = 11;

     // The value of the `property` is not in the given array.
     //
     // Requires:
     //
     // * That `value` is a non-empty `ArrayValue` with at most 10 values.
     // * No other `OR`, `IN`, `NOT_IN`, `NOT_EQUAL` is in the same query.
     // * That `field` comes first in the `order_by`.
     NOT_IN = 13;
   }

   // 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 is finished, and there are no more results.
     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.
   // The value will be zero for eventually consistent queries.
   int64 snapshot_version = 7;

   // Read timestamp 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 timestamp. Each batch's read timestamp
   // is valid for all preceding batches.
   // This value will not be set for eventually consistent queries in Cloud
   // Datastore.
   google.protobuf.Timestamp read_time = 8;
 }
	// Copyright 2023 Google LLC
	//
	// 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/field_behavior.proto";
	import "google/datastore/v1/entity.proto";
	import "google/protobuf/timestamp.proto";
	import "google/protobuf/wrappers.proto";

	option csharp_namespace = "Google.Cloud.Datastore.V1";
	option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
	option java_multiple_files = true;
	option java_outer_classname = "QueryProto";
	option java_package = "com.google.datastore.v1";
	option php_namespace = "Google\\Cloud\\Datastore\\V1";
	option ruby_package = "Google::Cloud::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;

	// The time at which the entity was created.
	// This field is set for
	// [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
	// If this entity is missing, this field will not be set.
	google.protobuf.Timestamp create_time = 6;

	// The time at which the entity was last changed.
	// This field is set for
	// [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
	// If this entity is missing, this field will not be set.
	google.protobuf.Timestamp update_time = 5;

	// 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).
	//
	// Requires:
	//
	// * If `order` is specified, the set of distinct on properties must appear
	// before the non-distinct on properties in `order`.
	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;
	}

	// Datastore query for running an aggregation over a
	// [Query][google.datastore.v1.Query].
	message AggregationQuery {
	// Defines an aggregation that produces a single result.
	message Aggregation {
	// Count of entities that match the query.
	//
	// The `COUNT(*)` aggregation function operates on the entire entity
	// so it does not require a field reference.
	message Count {
	// Optional. Optional constraint on the maximum number of entities to
	// count.
	//
	// This provides a way to set an upper bound on the number of entities
	// to scan, limiting latency, and cost.
	//
	// Unspecified is interpreted as no bound.
	//
	// If a zero value is provided, a count result of zero should always be
	// expected.
	//
	// High-Level Example:
	//
	// ```
	// AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
	// ```
	//
	// Requires:
	//
	// * Must be non-negative when present.
	google.protobuf.Int64Value up_to = 1
	[(google.api.field_behavior) = OPTIONAL];
	}

	// Sum of the values of the requested property.
	//
	// * Only numeric values will be aggregated. All non-numeric values
	// including `NULL` are skipped.
	//
	// * If the aggregated values contain `NaN`, returns `NaN`. Infinity math
	// follows IEEE-754 standards.
	//
	// * If the aggregated value set is empty, returns 0.
	//
	// * Returns a 64-bit integer if all aggregated numbers are integers and the
	// sum result does not overflow. Otherwise, the result is returned as a
	// double. Note that even if all the aggregated values are integers, the
	// result is returned as a double if it cannot fit within a 64-bit signed
	// integer. When this occurs, the returned value will lose precision.
	//
	// * When underflow occurs, floating-point aggregation is non-deterministic.
	// This means that running the same query repeatedly without any changes to
	// the underlying values could produce slightly different results each
	// time. In those cases, values should be stored as integers over
	// floating-point numbers.
	message Sum {
	// The property to aggregate on.
	PropertyReference property = 1;
	}

	// Average of the values of the requested property.
	//
	// * Only numeric values will be aggregated. All non-numeric values
	// including `NULL` are skipped.
	//
	// * If the aggregated values contain `NaN`, returns `NaN`. Infinity math
	// follows IEEE-754 standards.
	//
	// * If the aggregated value set is empty, returns `NULL`.
	//
	// * Always returns the result as a double.
	message Avg {
	// The property to aggregate on.
	PropertyReference property = 1;
	}

	// The type of aggregation to perform, required.
	oneof operator {
	// Count aggregator.
	Count count = 1;

	// Sum aggregator.
	Sum sum = 2;

	// Average aggregator.
	Avg avg = 3;
	}

	// Optional. Optional name of the property to store the result of the
	// aggregation.
	//
	// If not provided, Datastore will pick a default name following the format
	// `property_<incremental_id++>`. For example:
	//
	// ```
	// AGGREGATE
	// COUNT_UP_TO(1) AS count_up_to_1,
	// COUNT_UP_TO(2),
	// COUNT_UP_TO(3) AS count_up_to_3,
	// COUNT(*)
	// OVER (
	// ...
	// );
	// ```
	//
	// becomes:
	//
	// ```
	// AGGREGATE
	// COUNT_UP_TO(1) AS count_up_to_1,
	// COUNT_UP_TO(2) AS property_1,
	// COUNT_UP_TO(3) AS count_up_to_3,
	// COUNT(*) AS property_2
	// OVER (
	// ...
	// );
	// ```
	//
	// Requires:
	//
	// * Must be unique across all aggregation aliases.
	// * Conform to [entity property
	// name][google.datastore.v1.Entity.properties] limitations.
	string alias = 7 [(google.api.field_behavior) = OPTIONAL];
	}

	// The base query to aggregate over.
	oneof query_type {
	// Nested query for aggregation
	Query nested_query = 1;
	}

	// Optional. Series of aggregations to apply over the results of the
	// `nested_query`.
	//
	// Requires:
	//
	// * A minimum of one and maximum of five aggregations per query.
	repeated Aggregation aggregations = 3
	[(google.api.field_behavior) = OPTIONAL];
	}

	// 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 {
	// A reference to a property.
	//
	// Requires:
	//
	// * MUST be a dot-delimited (`.`) string of segments, where each segment
	// conforms to [entity property name][google.datastore.v1.Entity.properties]
	// limitations.
	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;

	// Documents are required to satisfy at least one of the combined filters.
	OR = 2;
	}

	// The operator for combining multiple filters.
	Operator op = 1;

	// The list of filters to combine.
	//
	// Requires:
	//
	// * At least one filter is present.
	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;

	// The given `property` is less than the given `value`.
	//
	// Requires:
	//
	// * That `property` comes first in `order_by`.
	LESS_THAN = 1;

	// The given `property` is less than or equal to the given `value`.
	//
	// Requires:
	//
	// * That `property` comes first in `order_by`.
	LESS_THAN_OR_EQUAL = 2;

	// The given `property` is greater than the given `value`.
	//
	// Requires:
	//
	// * That `property` comes first in `order_by`.
	GREATER_THAN = 3;

	// The given `property` is greater than or equal to the given `value`.
	//
	// Requires:
	//
	// * That `property` comes first in `order_by`.
	GREATER_THAN_OR_EQUAL = 4;

	// The given `property` is equal to the given `value`.
	EQUAL = 5;

	// The given `property` is equal to at least one value in the given array.
	//
	// Requires:
	//
	// * That `value` is a non-empty `ArrayValue`, subject to disjunction
	// limits.
	// * No `NOT_IN` is in the same query.
	IN = 6;

	// The given `property` is not equal to the given `value`.
	//
	// Requires:
	//
	// * No other `NOT_EQUAL` or `NOT_IN` is in the same query.
	// * That `property` comes first in the `order_by`.
	NOT_EQUAL = 9;

	// Limit the result set to the given entity and its descendants.
	//
	// Requires:
	//
	// * That `value` is an entity key.
	// * All evaluated disjunctions must have the same `HAS_ANCESTOR` filter.
	HAS_ANCESTOR = 11;

	// The value of the `property` is not in the given array.
	//
	// Requires:
	//
	// * That `value` is a non-empty `ArrayValue` with at most 10 values.
	// * No other `OR`, `IN`, `NOT_IN`, `NOT_EQUAL` is in the same query.
	// * That `field` comes first in the `order_by`.
	NOT_IN = 13;
	}

	// 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 is finished, and there are no more results.
	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.
	// The value will be zero for eventually consistent queries.
	int64 snapshot_version = 7;

	// Read timestamp 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 timestamp. Each batch's read timestamp
	// is valid for all preceding batches.
	// This value will not be set for eventually consistent queries in Cloud
	// Datastore.
	google.protobuf.Timestamp read_time = 8;
	}