feat: New PropertyMask field which allows partial commits, lookups, and query results (#1455)

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

PiperOrigin-RevId: 635449160

Source-Link: googleapis/googleapis@dde0ec1

Source-Link: https://github.com/googleapis/googleapis-gen/commit/8caa60d9aea82964a19cdf8faf91384911db8bdd
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOGNhYTYwZDlhZWE4Mjk2NGExOWNkZjhmYWY5MTM4NDkxMWRiOGJkZCJ9

* 🦉 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]

proto-google-cloud-datastore-v1/src/main/java/com/google/datastore/v1/DatastoreProto.java

@@ -170,4 +170,54 @@ public interface LookupRequestOrBuilder
    * </code>
    */
   com.google.datastore.v1.KeyOrBuilder getKeysOrBuilder(int index);
+
+  /**
+   *
+   *
+   * <pre>
+   * 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.
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 5;</code>
+   *
+   * @return Whether the propertyMask field is set.
+   */
+  boolean hasPropertyMask();
+  /**
+   *
+   *
+   * <pre>
+   * 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.
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 5;</code>
+   *
+   * @return The propertyMask.
+   */
+  com.google.datastore.v1.PropertyMask getPropertyMask();
+  /**
+   *
+   *
+   * <pre>
+   * 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.
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 5;</code>
+   */
+  com.google.datastore.v1.PropertyMaskOrBuilder getPropertyMaskOrBuilder();
 }

proto-google-cloud-datastore-v1/src/main/java/com/google/datastore/v1/LookupRequest.java

@@ -246,6 +246,62 @@ public interface MutationOrBuilder
    */
   com.google.protobuf.TimestampOrBuilder getUpdateTimeOrBuilder();
 
+  /**
+   *
+   *
+   * <pre>
+   * 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.
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 9;</code>
+   *
+   * @return Whether the propertyMask field is set.
+   */
+  boolean hasPropertyMask();
+  /**
+   *
+   *
+   * <pre>
+   * 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.
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 9;</code>
+   *
+   * @return The propertyMask.
+   */
+  com.google.datastore.v1.PropertyMask getPropertyMask();
+  /**
+   *
+   *
+   * <pre>
+   * 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.
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 9;</code>
+   */
+  com.google.datastore.v1.PropertyMaskOrBuilder getPropertyMaskOrBuilder();
+
   com.google.datastore.v1.Mutation.OperationCase getOperationCase();
 
   com.google.datastore.v1.Mutation.ConflictDetectionStrategyCase getConflictDetectionStrategyCase();

proto-google-cloud-datastore-v1/src/main/java/com/google/datastore/v1/LookupRequestOrBuilder.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2024 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
+ *
+ *     https://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.
+ */
+// Generated by the protocol buffer compiler.  DO NOT EDIT!
+// source: google/datastore/v1/datastore.proto
+
+// Protobuf Java Version: 3.25.3
+package com.google.datastore.v1;
+
+public interface PropertyMaskOrBuilder
+    extends
+    // @@protoc_insertion_point(interface_extends:google.datastore.v1.PropertyMask)
+    com.google.protobuf.MessageOrBuilder {
+
+  /**
+   *
+   *
+   * <pre>
+   * 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 `&#92;`, 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].
+   * </pre>
+   *
+   * <code>repeated string paths = 1;</code>
+   *
+   * @return A list containing the paths.
+   */
+  java.util.List<java.lang.String> getPathsList();
+  /**
+   *
+   *
+   * <pre>
+   * 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 `&#92;`, 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].
+   * </pre>
+   *
+   * <code>repeated string paths = 1;</code>
+   *
+   * @return The count of paths.
+   */
+  int getPathsCount();
+  /**
+   *
+   *
+   * <pre>
+   * 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 `&#92;`, 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].
+   * </pre>
+   *
+   * <code>repeated string paths = 1;</code>
+   *
+   * @param index The index of the element to return.
+   * @return The paths at the given index.
+   */
+  java.lang.String getPaths(int index);
+  /**
+   *
+   *
+   * <pre>
+   * 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 `&#92;`, 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].
+   * </pre>
+   *
+   * <code>repeated string paths = 1;</code>
+   *
+   * @param index The index of the value to return.
+   * @return The bytes of the paths at the given index.
+   */
+  com.google.protobuf.ByteString getPathsBytes(int index);
+}

proto-google-cloud-datastore-v1/src/main/java/com/google/datastore/v1/Mutation.java

@@ -229,6 +229,53 @@ public interface RunQueryRequestOrBuilder
    */
   com.google.datastore.v1.GqlQueryOrBuilder getGqlQueryOrBuilder();
 
+  /**
+   *
+   *
+   * <pre>
+   * The properties to return.
+   * This field must not be set for a projection query.
+   *
+   * See
+   * [LookupRequest.property_mask][google.datastore.v1.LookupRequest.property_mask].
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 10;</code>
+   *
+   * @return Whether the propertyMask field is set.
+   */
+  boolean hasPropertyMask();
+  /**
+   *
+   *
+   * <pre>
+   * The properties to return.
+   * This field must not be set for a projection query.
+   *
+   * See
+   * [LookupRequest.property_mask][google.datastore.v1.LookupRequest.property_mask].
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 10;</code>
+   *
+   * @return The propertyMask.
+   */
+  com.google.datastore.v1.PropertyMask getPropertyMask();
+  /**
+   *
+   *
+   * <pre>
+   * The properties to return.
+   * This field must not be set for a projection query.
+   *
+   * See
+   * [LookupRequest.property_mask][google.datastore.v1.LookupRequest.property_mask].
+   * </pre>
+   *
+   * <code>.google.datastore.v1.PropertyMask property_mask = 10;</code>
+   */
+  com.google.datastore.v1.PropertyMaskOrBuilder getPropertyMaskOrBuilder();
+
   /**
    *
    *

proto-google-cloud-datastore-v1/src/main/java/com/google/datastore/v1/MutationOrBuilder.java

@@ -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.