feat: publish proto definitions for SUM/AVG in Datastore

Google APIs · copybara-github · commit 6148e5b6f91a · 2023-08-01T10:34:52.000-07:00
PiperOrigin-RevId: 552847139
diff --git a/google/datastore/v1/datastore.proto b/google/datastore/v1/datastore.proto
@@ -578,9 +578,12 @@ message ReadOptions {
     // [RunQueryResponse.transaction][google.datastore.v1.RunQueryResponse.transaction].
     TransactionOptions new_transaction = 3;
 
-    // Reads entities as they were at the given time. This may not be older
-    // than 270 seconds.  This value is only supported for Cloud Firestore in
-    // Datastore mode.
+    // Reads entities as they were at the given time. This value is only
+    // supported for Cloud Firestore in Datastore mode.
+    //
+    // This must be a microsecond precision timestamp within the past one hour,
+    // or if Point-in-Time Recovery is enabled, can additionally be a whole
+    // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 4;
   }
 }
@@ -602,7 +605,10 @@ message TransactionOptions {
   // Options specific to read-only transactions.
   message ReadOnly {
     // Reads entities at the given time.
-    // This may not be older than 60 seconds.
+    //
+    // This must be a microsecond precision timestamp within the past one hour,
+    // or if Point-in-Time Recovery is enabled, can additionally be a whole
+    // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 1;
   }
 
diff --git a/google/datastore/v1/datastore_v1.yaml b/google/datastore/v1/datastore_v1.yaml
@@ -11,11 +11,6 @@ documentation:
   summary: |-
     Accesses the schemaless NoSQL database to provide fully managed, robust,
     scalable storage for your application.
-  rules:
-  - selector: google.longrunning.Operations.ListOperations
-    description: |-
-      Lists operations that match the specified filter in the request. If
-      the server doesn't support this method, it returns `UNIMPLEMENTED`.
 
 backend:
   rules:
diff --git a/google/datastore/v1/query.proto b/google/datastore/v1/query.proto
@@ -163,10 +163,58 @@ message AggregationQuery {
           [(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
@@ -342,8 +390,9 @@ message PropertyFilter {
     //
     // Requires:
     //
-    // * That `value` is a non-empty `ArrayValue` with at most 10 values.
-    // * No other `IN` or `NOT_IN` is in the same query.
+    // * 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`.
@@ -359,15 +408,15 @@ message PropertyFilter {
     // Requires:
     //
     // * That `value` is an entity key.
-    // * No other `HAS_ANCESTOR` is in the same query.
+    // * 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 `IN`, `NOT_IN`, `NOT_EQUAL` is in the same query.
+    // * No other `OR`, `IN`, `NOT_IN`, `NOT_EQUAL` is in the same query.
     // * That `field` comes first in the `order_by`.
     NOT_IN = 13;
   }
