feat: Add OR query support (#1064)

* docs: changing format of the jsdoc links

PiperOrigin-RevId: 509352615

Source-Link: googleapis/googleapis@b737d30

Source-Link: googleapis/googleapis-gen@8efadf3
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOGVmYWRmM2Q1ODc4MGVhMWM1NTAyNjhkNDZhM2RjNzAxYmEzN2ZjZiJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* feat: Add `OR` query support
docs: Minor documentation formatting and cleanup

PiperOrigin-RevId: 509848726

Source-Link: googleapis/googleapis@b9351b4

Source-Link: googleapis/googleapis-gen@99317db
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOTkzMTdkYjY4MjcxODVlOGNhZThlZWI0NjEzN2NkODFjZDJkNmE1NCJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

protos/google/datastore/v1/aggregation_result.proto

@@ -36,9 +36,10 @@ option ruby_package = "Google::Cloud::Datastore::V1";
 message AggregationResult {
   // The result of the aggregation functions, ex: `COUNT(*) AS total_entities`.
   //
-  // The key is the [alias][google.datastore.v1.AggregationQuery.Aggregation.alias]
-  // assigned to the aggregation function on input and the size of this map
-  // equals the number of aggregation functions in the query.
+  // The key is the
+  // [alias][google.datastore.v1.AggregationQuery.Aggregation.alias] assigned to
+  // the aggregation function on input and the size of this map equals the
+  // number of aggregation functions in the query.
   map<string, Value> aggregate_properties = 2;
 }
 

protos/google/datastore/v1/datastore.proto

@@ -194,7 +194,9 @@ message LookupResponse {
   // The identifier of the transaction that was started as part of this Lookup
   // request.
   //
-  // Set only when [ReadOptions.begin_transaction][] was set in
+  // Set only when
+  // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
+  // was set in
   // [LookupRequest.read_options][google.datastore.v1.LookupRequest.read_options].
   bytes transaction = 5;
 
@@ -244,7 +246,9 @@ message RunQueryResponse {
   // The identifier of the transaction that was started as part of this
   // RunQuery request.
   //
-  // Set only when [ReadOptions.begin_transaction][] was set in
+  // Set only when
+  // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
+  // was set in
   // [RunQueryRequest.read_options][google.datastore.v1.RunQueryRequest.read_options].
   bytes transaction = 5;
 }
@@ -292,7 +296,9 @@ message RunAggregationQueryResponse {
   // The identifier of the transaction that was started as part of this
   // RunAggregationQuery request.
   //
-  // Set only when [ReadOptions.begin_transaction][] was set in
+  // Set only when
+  // [ReadOptions.new_transaction][google.datastore.v1.ReadOptions.new_transaction]
+  // was set in
   // [RunAggregationQueryRequest.read_options][google.datastore.v1.RunAggregationQueryRequest.read_options].
   bytes transaction = 5;
 }
@@ -378,8 +384,7 @@ message CommitRequest {
 
     // Options for beginning a new transaction for this request.
     // The transaction is committed when the request completes. If specified,
-    // [TransactionOptions.mode][google.datastore.v1.TransactionOptions.mode]
-    // must be
+    // [TransactionOptions.mode][google.datastore.v1.TransactionOptions] must be
     // [TransactionOptions.ReadWrite][google.datastore.v1.TransactionOptions.ReadWrite].
     TransactionOptions single_use_transaction = 10;
   }
@@ -517,6 +522,9 @@ message MutationResult {
   // than the version of any possible future entity.
   int64 version = 4;
 
+  // The create time of the entity. This field will not be set after a 'delete'.
+  google.protobuf.Timestamp create_time = 7;
+
   // The update time of the entity on the server after processing the mutation.
   // If the mutation doesn't change anything on the server, then the timestamp
   // will be the update timestamp of the current entity. This field will not be

protos/google/datastore/v1/entity.proto

@@ -46,7 +46,8 @@ option ruby_package = "Google::Cloud::Datastore::V1";
 //
 // 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.
+// 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;
@@ -159,8 +160,8 @@ message 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 most 1,000,000 bytes.
+    // When `exclude_from_indexes` is false (it is indexed) , may have at most
+    // 1500 bytes. Otherwise, may be set to at most 1,000,000 bytes.
     string string_value = 17;
 
     // A blob value.

protos/google/datastore/v1/query.proto

@@ -56,17 +56,23 @@ 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.v1.EntityResult.ResultType.FULL] entity
-  // results.
+  // 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.
+  // 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.
+  // 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;
 
@@ -118,7 +124,8 @@ message Query {
   google.protobuf.Int32Value limit = 12;
 }
 
-// Datastore query for running an aggregation over a [Query][google.datastore.v1.Query].
+// Datastore query for running an aggregation over a
+// [Query][google.datastore.v1.Query].
 message AggregationQuery {
   // Defines a aggregation that produces a single result.
   message Aggregation {
@@ -127,7 +134,8 @@ message AggregationQuery {
     // 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.
+      // 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.
@@ -146,7 +154,8 @@ message AggregationQuery {
       // Requires:
       //
       // * Must be non-negative when present.
-      google.protobuf.Int64Value up_to = 1 [(google.api.field_behavior) = OPTIONAL];
+      google.protobuf.Int64Value up_to = 1
+          [(google.api.field_behavior) = OPTIONAL];
     }
 
     // The type of aggregation to perform, required.
@@ -155,7 +164,8 @@ message AggregationQuery {
       Count count = 1;
     }
 
-    // Optional. Optional name of the property to store the result of the aggregation.
+    // 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:
@@ -187,7 +197,8 @@ message AggregationQuery {
     // Requires:
     //
     // * Must be unique across all aggregation aliases.
-    // * Conform to [entity property name][google.datastore.v1.Entity.properties] limitations.
+    // * Conform to [entity property
+    // name][google.datastore.v1.Entity.properties] limitations.
     string alias = 7 [(google.api.field_behavior) = OPTIONAL];
   }
 
@@ -197,12 +208,14 @@ message AggregationQuery {
     Query nested_query = 1;
   }
 
-  // Optional. Series of aggregations to apply over the results of the `nested_query`.
+  // 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];
+  repeated Aggregation aggregations = 3
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // A representation of a kind.
@@ -266,6 +279,9 @@ message CompositeFilter {
 
     // 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.
@@ -338,6 +354,7 @@ message PropertyFilter {
     // Requires:
     //
     // * That `value` is an entity key.
+    // * No other `HAS_ANCESTOR` is in the same query.
     HAS_ANCESTOR = 11;
 
     // The value of the `property` is not in the given array.