feat: expose Firestore PITR fields in Database to stable

feat: expose Firestore snapshot_time field in export API to stable
feat: expose Firestore namespace ID fields in import/export APIs to stable
docs: assorted typo fixes and whitespace updates

PiperOrigin-RevId: 587811576

google/firestore/admin/v1/BUILD.bazel

@@ -34,6 +34,7 @@ proto_library(
         "//google/api:field_behavior_proto",
         "//google/api:resource_proto",
         "//google/longrunning:operations_proto",
+        "@com_google_protobuf//:duration_proto",
         "@com_google_protobuf//:empty_proto",
         "@com_google_protobuf//:field_mask_proto",
         "@com_google_protobuf//:timestamp_proto",
@@ -227,10 +228,10 @@ php_gapic_library(
     name = "admin_php_gapic",
     srcs = [":admin_proto_with_info"],
     grpc_service_config = "firestore_admin_grpc_service_config.json",
+    migration_mode = "MIGRATION_MODE_UNSPECIFIED",
     rest_numeric_enums = True,
     service_yaml = "firestore_v1.yaml",
     transport = "grpc+rest",
-    migration_mode = "MIGRATION_MODE_UNSPECIFIED",
     deps = [":admin_php_proto"],
 )
 

google/firestore/admin/v1/database.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -18,6 +18,8 @@ package google.firestore.admin.v1;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Firestore.Admin.V1";
 option go_package = "cloud.google.com/go/firestore/apiv1/admin/adminpb;adminpb";
@@ -78,6 +80,26 @@ message Database {
     OPTIMISTIC_WITH_ENTITY_GROUPS = 3;
   }
 
+  // Point In Time Recovery feature enablement.
+  enum PointInTimeRecoveryEnablement {
+    // Not used.
+    POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED = 0;
+
+    // Reads are supported on selected versions of the data from within the past
+    // 7 days:
+    //
+    // * Reads against any timestamp within the past hour
+    // * Reads against 1-minute snapshots beyond 1 hour and within 7 days
+    //
+    // `version_retention_period` and `earliest_version_time` can be
+    // used to determine the supported versions.
+    POINT_IN_TIME_RECOVERY_ENABLED = 1;
+
+    // Reads are supported on any version of the data from within the past 1
+    // hour.
+    POINT_IN_TIME_RECOVERY_DISABLED = 2;
+  }
+
   // The type of App Engine integration mode.
   enum AppEngineIntegrationMode {
     // Not used.
@@ -89,16 +111,18 @@ message Database {
     // the database.
     ENABLED = 1;
 
-    // Appengine has no affect on the ability of this database to serve
+    // App Engine has no effect on the ability of this database to serve
     // requests.
+    //
+    // This is the default setting for databases created with the Firestore API.
     DISABLED = 2;
   }
 
   // The resource name of the Database.
   // Format: `projects/{project}/databases/{database}`
   string name = 1;
 
-  // The location of the database. Available databases are listed at
+  // The location of the database. Available locations are listed at
   // https://cloud.google.com/firestore/docs/locations.
   string location_id = 9;
 
@@ -110,13 +134,40 @@ message Database {
   // The concurrency control mode to use for this database.
   ConcurrencyMode concurrency_mode = 15;
 
+  // Output only. The period during which past versions of data are retained in
+  // the database.
+  //
+  // Any [read][google.firestore.v1.GetDocumentRequest.read_time]
+  // or [query][google.firestore.v1.ListDocumentsRequest.read_time] can specify
+  // a `read_time` within this window, and will read the state of the database
+  // at that time.
+  //
+  // If the PITR feature is enabled, the retention period is 7 days. Otherwise,
+  // the retention period is 1 hour.
+  google.protobuf.Duration version_retention_period = 17
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The earliest timestamp at which older versions of the data can
+  // be read from the database. See [version_retention_period] above; this field
+  // is populated with `now - version_retention_period`.
+  //
+  // This value is continuously updated, and becomes stale the moment it is
+  // queried. If you are using this value to recover data, make sure to account
+  // for the time from the moment when the value is queried to the moment when
+  // you initiate the recovery.
+  google.protobuf.Timestamp earliest_version_time = 18
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Whether to enable the PITR feature on this database.
+  PointInTimeRecoveryEnablement point_in_time_recovery_enablement = 21;
+
   // The App Engine integration mode to use for this database.
   AppEngineIntegrationMode app_engine_integration_mode = 19;
 
-  // Output only. The key_prefix for this database. This key_prefix is used, in combination
-  // with the project id ("<key prefix>~<project id>") to construct the
-  // application id that is returned from the Cloud Datastore APIs in Google App
-  // Engine first generation runtimes.
+  // Output only. The key_prefix for this database. This key_prefix is used, in
+  // combination with the project id ("<key prefix>~<project id>") to construct
+  // the application id that is returned from the Cloud Datastore APIs in Google
+  // App Engine first generation runtimes.
   //
   // This value may be empty in which case the appid to use for URL-encoded keys
   // is the project_id (eg: foo instead of v~foo).

google/firestore/admin/v1/firestore_admin.proto

@@ -23,9 +23,11 @@ import "google/api/resource.proto";
 import "google/firestore/admin/v1/database.proto";
 import "google/firestore/admin/v1/field.proto";
 import "google/firestore/admin/v1/index.proto";
+import "google/firestore/admin/v1/operation.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
+import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Firestore.Admin.V1";
 option go_package = "cloud.google.com/go/firestore/apiv1/admin/adminpb;adminpb";
@@ -485,6 +487,23 @@ message ExportDocumentsRequest {
   // If the URI is a bucket (without a namespace path), a prefix will be
   // generated based on the start time.
   string output_uri_prefix = 3;
+
+  // Unspecified means all namespaces. This is the preferred
+  // usage for databases that don't use namespaces.
+  //
+  // An empty string element represents the default namespace. This should be
+  // used if the database has data in non-default namespaces, but doesn't want
+  // to include them. Each namespace in this list must be unique.
+  repeated string namespace_ids = 4;
+
+  // The timestamp that corresponds to the version of the database to be
+  // exported. The timestamp must be in the past, rounded to the minute and not
+  // older than
+  // [earliestVersionTime][google.firestore.admin.v1.Database.earliest_version_time].
+  // If specified, then the exported documents will represent a consistent view
+  // of the database at the provided time. Otherwise, there are no guarantees
+  // about the consistency of the exported documents.
+  google.protobuf.Timestamp snapshot_time = 5;
 }
 
 // The request for
@@ -509,4 +528,12 @@ message ImportDocumentsRequest {
   // See:
   // [google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix][google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix].
   string input_uri_prefix = 3;
+
+  // Unspecified means all namespaces. This is the preferred
+  // usage for databases that don't use namespaces.
+  //
+  // An empty string element represents the default namespace. This should be
+  // used if the database has data in non-default namespaces, but doesn't want
+  // to include them. Each namespace in this list must be unique.
+  repeated string namespace_ids = 4;
 }

google/firestore/admin/v1/location.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -25,7 +25,6 @@ option objc_class_prefix = "GCFS";
 option php_namespace = "Google\\Cloud\\Firestore\\Admin\\V1";
 option ruby_package = "Google::Cloud::Firestore::Admin::V1";
 
-// The metadata message for [google.cloud.location.Location.metadata][google.cloud.location.Location.metadata].
-message LocationMetadata {
-
-}
+// The metadata message for
+// [google.cloud.location.Location.metadata][google.cloud.location.Location.metadata].
+message LocationMetadata {}

google/firestore/admin/v1/operation.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.firestore.admin.v1;
 
+import "google/api/resource.proto";
 import "google/firestore/admin/v1/index.proto";
 import "google/protobuf/timestamp.proto";
 
@@ -28,7 +29,8 @@ option objc_class_prefix = "GCFS";
 option php_namespace = "Google\\Cloud\\Firestore\\Admin\\V1";
 option ruby_package = "Google::Cloud::Firestore::Admin::V1";
 
-// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
+// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
+// results from
 // [FirestoreAdmin.CreateIndex][google.firestore.admin.v1.FirestoreAdmin.CreateIndex].
 message IndexOperationMetadata {
   // The time this operation started.
@@ -52,7 +54,8 @@ message IndexOperationMetadata {
   Progress progress_bytes = 6;
 }
 
-// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
+// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
+// results from
 // [FirestoreAdmin.UpdateField][google.firestore.admin.v1.FirestoreAdmin.UpdateField].
 message FieldOperationMetadata {
   // Information about an index configuration change.
@@ -76,7 +79,7 @@ message FieldOperationMetadata {
     Index index = 2;
   }
 
-  // Information about an TTL configuration change.
+  // Information about a TTL configuration change.
   message TtlConfigDelta {
     // Specifies how the TTL config is changing.
     enum ChangeType {
@@ -105,8 +108,9 @@ message FieldOperationMetadata {
   // `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_path}`
   string field = 3;
 
-  // A list of [IndexConfigDelta][google.firestore.admin.v1.FieldOperationMetadata.IndexConfigDelta], which describe the intent of this
-  // operation.
+  // A list of
+  // [IndexConfigDelta][google.firestore.admin.v1.FieldOperationMetadata.IndexConfigDelta],
+  // which describe the intent of this operation.
   repeated IndexConfigDelta index_config_deltas = 4;
 
   // The state of the operation.
@@ -122,7 +126,8 @@ message FieldOperationMetadata {
   TtlConfigDelta ttl_config_delta = 8;
 }
 
-// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
+// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
+// results from
 // [FirestoreAdmin.ExportDocuments][google.firestore.admin.v1.FirestoreAdmin.ExportDocuments].
 message ExportDocumentsMetadata {
   // The time this operation started.
@@ -144,11 +149,20 @@ message ExportDocumentsMetadata {
   // Which collection ids are being exported.
   repeated string collection_ids = 6;
 
-  // Where the entities are being exported to.
+  // Where the documents are being exported to.
   string output_uri_prefix = 7;
+
+  // Which namespace ids are being exported.
+  repeated string namespace_ids = 8;
+
+  // The timestamp that corresponds to the version of the database that is being
+  // exported. If unspecified, there are no guarantees about the consistency of
+  // the documents being exported.
+  google.protobuf.Timestamp snapshot_time = 9;
 }
 
-// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
+// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
+// results from
 // [FirestoreAdmin.ImportDocuments][google.firestore.admin.v1.FirestoreAdmin.ImportDocuments].
 message ImportDocumentsMetadata {
   // The time this operation started.
@@ -172,9 +186,13 @@ message ImportDocumentsMetadata {
 
   // The location of the documents being imported.
   string input_uri_prefix = 7;
+
+  // Which namespace ids are being imported.
+  repeated string namespace_ids = 8;
 }
 
-// Returned in the [google.longrunning.Operation][google.longrunning.Operation] response field.
+// Returned in the [google.longrunning.Operation][google.longrunning.Operation]
+// response field.
 message ExportDocumentsResponse {
   // Location of the output files. This can be used to begin an import
   // into Cloud Firestore (this project or another project) after the operation
@@ -212,8 +230,8 @@ enum OperationState {
 }
 
 // Describes the progress of the operation.
-// Unit of work is generic and must be interpreted based on where [Progress][google.firestore.admin.v1.Progress]
-// is used.
+// Unit of work is generic and must be interpreted based on where
+// [Progress][google.firestore.admin.v1.Progress] is used.
 message Progress {
   // The amount of work estimated.
   int64 estimated_work = 1;