feat: expose the 'auto_commit_transaction' option for the ExecutePipeline API

feat: expose the 'concurrency_mode' option for the Cloud Firestore API
chore: Firestore.executePipeline to not retry on `DEADLINE_EXCEEDED`
docs: A comment for message `TransactionOptions` is changed to better detail the new 'concurrency_mode' option.
docs: A comment for field `parent` in message `.google.firestore.v1.ListCollectionIdsRequest` is changed to describe how to list top-level collections.
docs: A comment for field `order_by` in message `.google.firestore.v1.StructuredQuery` is updated to describe default behavior for ENTERPRISE edition databases

PiperOrigin-RevId: 929318392

google/firestore/v1/common.proto

@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.firestore.v1;
 
+import "google/api/field_behavior.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Firestore.V1";
@@ -56,13 +57,33 @@ message Precondition {
 
 // Options for creating a new transaction.
 message TransactionOptions {
+  // The type of concurrency control mode for transactions.
+  enum ConcurrencyMode {
+    // Start the transaction with the database-level default concurrency mode.
+    CONCURRENCY_MODE_UNSPECIFIED = 0;
+
+    // Use optimistic concurrency control for the new transaction.
+    OPTIMISTIC = 1;
+
+    // Use pessimistic concurrency control for the new transaction.
+    PESSIMISTIC = 2;
+  }
+
   // Options for a transaction that can be used to read and write documents.
-  //
-  // Firestore does not allow 3rd party auth requests to create read-write.
-  // transactions.
   message ReadWrite {
     // An optional transaction to retry.
     bytes retry_transaction = 1;
+
+    // Optional. The concurrency control mode to use for this transaction.
+    //
+    // A database is able to use different concurrency modes for different
+    // transactions simultaneously.
+    //
+    // 3rd party auth requests are only allowed to create optimistic
+    // read-write transactions and must specify that here even if the
+    // database-level setting is already configured to optimistic.
+    ConcurrencyMode concurrency_mode = 2
+        [(google.api.field_behavior) = OPTIONAL];
   }
 
   // Options for a transaction that can only be used to read documents.

google/firestore/v1/firestore.proto

@@ -678,6 +678,11 @@ message ExecutePipelineRequest {
     // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 7;
   }
+
+  // Optional. Automatically commits the transaction after the pipeline has been
+  // executed. Only permitted in combination with `transaction` or
+  // `new_transaction`.
+  bool auto_commit_transaction = 9 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for [Firestore.Execute][].
@@ -1163,6 +1168,9 @@ message ListCollectionIdsRequest {
   // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
   // For example:
   // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
+  //
+  // Use `projects/{project_id}/databases/{database_id}/documents` to list
+  // top-level collections.
   string parent = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The maximum number of results to return.

google/firestore/v1/firestore_grpc_service_config.json

@@ -44,7 +44,23 @@
         {
           "service": "google.firestore.v1.Firestore",
           "method": "RunAggregationQuery"
-        },
+        }
+      ],
+      "timeout": "300s",
+      "retryPolicy": {
+        "maxAttempts": 5,
+        "initialBackoff": "0.100s",
+        "maxBackoff": "60s",
+        "backoffMultiplier": 1.3,
+        "retryableStatusCodes": [
+          "UNAVAILABLE",
+          "INTERNAL",
+          "DEADLINE_EXCEEDED"
+        ]
+      }
+    },
+    {
+      "name": [
         {
           "service": "google.firestore.v1.Firestore",
           "method": "ExecutePipeline"
@@ -58,8 +74,7 @@
         "backoffMultiplier": 1.3,
         "retryableStatusCodes": [
           "UNAVAILABLE",
-          "INTERNAL",
-          "DEADLINE_EXCEEDED"
+          "INTERNAL"
         ]
       }
     },

google/firestore/v1/firestore_v1.yaml

@@ -19,13 +19,21 @@ documentation:
   - selector: google.cloud.location.Locations.ListLocations
     description: |-
       Lists information about the supported locations for this service.
-      This method can be called in two ways:
 
-      *   **List all public locations:** Use the path `GET /v1/locations`.
-      *   **List project-visible locations:** Use the path
-      `GET /v1/projects/{project_id}/locations`. This may include public
-      locations as well as private or other locations specifically visible
-      to the project.
+      This method lists locations based on the resource scope provided in
+      the [ListLocationsRequest.name][google.cloud.location.ListLocationsRequest.name] field: *
+      **Global locations**: If `name` is empty, the method lists the
+      public locations available to all projects. * **Project-specific
+      locations**: If `name` follows the format
+      `projects/{project}`, the method lists locations visible to that
+      specific project. This includes public, private, or other
+      project-specific locations enabled for the project.
+
+      For gRPC and client library implementations, the resource name is
+      passed as the `name` field. For direct service calls, the resource
+      name is
+      incorporated into the request path based on the specific service
+      implementation and version.
 
 http:
   rules:

google/firestore/v1/query.proto

@@ -346,9 +346,12 @@ message StructuredQuery {
 
   // The order to apply to the query results.
   //
-  // Firestore allows callers to provide a full ordering, a partial ordering, or
-  // no ordering at all. In all cases, Firestore guarantees a stable ordering
-  // through the following rules:
+  // Callers can provide a full ordering, a partial ordering, or no ordering at
+  // all. While Firestore will always respect the provided order, the behavior
+  // for queries without a full ordering is different per database edition:
+  //
+  // In Standard edition, Firestore guarantees a stable ordering through the
+  // following rules:
   //
   //  * The `order_by` is required to reference all fields used with an
   //    inequality filter.
@@ -364,6 +367,13 @@ message StructuredQuery {
   //  * `WHERE a > 1` becomes `WHERE a > 1 ORDER BY a ASC, __name__ ASC`
   //  * `WHERE __name__ > ... AND a > 1` becomes
   //     `WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC`
+  //
+  // In Enterprise edition, Firestore does not guarantee a stable ordering.
+  // Instead it will pick the most efficient ordering based on the indexes
+  // available at the time of query execution. This will result in a different
+  // ordering for queries that are otherwise identical. To ensure a stable
+  // ordering, always include a unique field in the `order_by` clause, such as
+  // `__name__`.
   repeated Order order_by = 4;
 
   // A potential prefix of a position in the result set to start the query at.