feat: New PropertyMask field which allows partial commits, lookups, and query results

Google APIs · copybara-github · commit dde0ec1f36cb · 2024-05-20T07:28:07.000-07:00
PiperOrigin-RevId: 635449160
diff --git a/google/datastore/v1/datastore.proto b/google/datastore/v1/datastore.proto
@@ -173,6 +173,14 @@ message LookupRequest {
 
   // Required. Keys of entities to look up.
   repeated Key keys = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // The properties to return. Defaults to returning all properties.
+  //
+  // If this field is set and an entity has a property not referenced in the
+  // mask, it will be absent from [LookupResponse.found.entity.properties][].
+  //
+  // The entity's key is always returned.
+  PropertyMask property_mask = 5;
 }
 
 // The response for [Datastore.Lookup][google.datastore.v1.Datastore.Lookup].
@@ -234,6 +242,13 @@ message RunQueryRequest {
     GqlQuery gql_query = 7;
   }
 
+  // The properties to return.
+  // This field must not be set for a projection query.
+  //
+  // See
+  // [LookupRequest.property_mask][google.datastore.v1.LookupRequest.property_mask].
+  PropertyMask property_mask = 10;
+
   // Optional. Explain options for the query. If set, additional query
   // statistics will be returned. If not, only query results will be returned.
   ExplainOptions explain_options = 12 [(google.api.field_behavior) = OPTIONAL];
@@ -526,6 +541,16 @@ message Mutation {
     // mutation conflicts.
     google.protobuf.Timestamp update_time = 11;
   }
+
+  // The properties to write in this mutation.
+  // None of the properties in the mask may have a reserved name, except for
+  // `__key__`.
+  // This field is ignored for `delete`.
+  //
+  // If the entity already exists, only properties referenced in the mask are
+  // updated, others are left untouched.
+  // Properties referenced in the mask but not in the entity are deleted.
+  PropertyMask property_mask = 9;
 }
 
 // The result of applying a mutation.
@@ -555,6 +580,23 @@ message MutationResult {
   bool conflict_detected = 5;
 }
 
+// The set of arbitrarily nested property paths used to restrict an operation to
+// only a subset of properties in an entity.
+message PropertyMask {
+  // The paths to the properties covered by this mask.
+  //
+  // A path is a list of property names separated by dots (`.`), for example
+  // `foo.bar` means the property `bar` inside the entity property `foo` inside
+  // the entity associated with this path.
+  //
+  // If a property name contains a dot `.` or a backslash `\`, then that
+  // name must be escaped.
+  //
+  // A path must not be empty, and may not reference a value inside an
+  // [array value][google.datastore.v1.Value.array_value].
+  repeated string paths = 1;
+}
+
 // The options shared by read requests.
 message ReadOptions {
   // The possible values for read consistencies.
