feat: expose Firestore PITR fields in Database to stable (#811)

* 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

Source-Link: googleapis/googleapis@fbe1c8e

Source-Link: googleapis/googleapis-gen@5fe704d
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNWZlNzA0ZDk0ZmEyZDlhMWRjZTc1Mjk0MmI3MzA4ODczMTI0YjdkZCJ9

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

google/cloud/firestore_admin_v1/services/firestore_admin/async_client.py

@@ -55,8 +55,10 @@
 from google.cloud.firestore_admin_v1.types import operation as gfa_operation
 from google.cloud.location import locations_pb2  # type: ignore
 from google.longrunning import operations_pb2  # type: ignore
+from google.protobuf import duration_pb2  # type: ignore
 from google.protobuf import empty_pb2  # type: ignore
 from google.protobuf import field_mask_pb2  # type: ignore
+from google.protobuf import timestamp_pb2  # type: ignore
 from .transports.base import FirestoreAdminTransport, DEFAULT_CLIENT_INFO
 from .transports.grpc_asyncio import FirestoreAdminGrpcAsyncIOTransport
 from .client import FirestoreAdminClient
@@ -1201,11 +1203,8 @@ async def sample_export_documents():
             google.api_core.operation_async.AsyncOperation:
                 An object representing a long-running operation.
 
-                The result type for the operation will be
-                :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse`
-                Returned in the
-                [google.longrunning.Operation][google.longrunning.Operation]
-                response field.
+                The result type for the operation will be :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse` Returned in the [google.longrunning.Operation][google.longrunning.Operation]
+                   response field.
 
         """
         # Create or coerce a protobuf request object.

google/cloud/firestore_admin_v1/services/firestore_admin/client.py

@@ -59,8 +59,10 @@
 from google.cloud.firestore_admin_v1.types import operation as gfa_operation
 from google.cloud.location import locations_pb2  # type: ignore
 from google.longrunning import operations_pb2  # type: ignore
+from google.protobuf import duration_pb2  # type: ignore
 from google.protobuf import empty_pb2  # type: ignore
 from google.protobuf import field_mask_pb2  # type: ignore
+from google.protobuf import timestamp_pb2  # type: ignore
 from .transports.base import FirestoreAdminTransport, DEFAULT_CLIENT_INFO
 from .transports.grpc import FirestoreAdminGrpcTransport
 from .transports.grpc_asyncio import FirestoreAdminGrpcAsyncIOTransport
@@ -1432,11 +1434,8 @@ def sample_export_documents():
             google.api_core.operation.Operation:
                 An object representing a long-running operation.
 
-                The result type for the operation will be
-                :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse`
-                Returned in the
-                [google.longrunning.Operation][google.longrunning.Operation]
-                response field.
+                The result type for the operation will be :class:`google.cloud.firestore_admin_v1.types.ExportDocumentsResponse` Returned in the [google.longrunning.Operation][google.longrunning.Operation]
+                   response field.
 
         """
         # Create or coerce a protobuf request object.

google/cloud/firestore_admin_v1/types/database.py

@@ -19,6 +19,9 @@
 
 import proto  # type: ignore
 
+from google.protobuf import duration_pb2  # type: ignore
+from google.protobuf import timestamp_pb2  # type: ignore
+
 
 __protobuf__ = proto.module(
     package="google.firestore.admin.v1",
@@ -39,7 +42,7 @@ class Database(proto.Message):
             ``projects/{project}/databases/{database}``
         location_id (str):
             The location of the database. Available
-            databases are listed at
+            locations are listed at
             https://cloud.google.com/firestore/docs/locations.
         type_ (google.cloud.firestore_admin_v1.types.Database.DatabaseType):
             The type of the database.
@@ -49,6 +52,32 @@ class Database(proto.Message):
         concurrency_mode (google.cloud.firestore_admin_v1.types.Database.ConcurrencyMode):
             The concurrency control mode to use for this
             database.
+        version_retention_period (google.protobuf.duration_pb2.Duration):
+            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.
+        earliest_version_time (google.protobuf.timestamp_pb2.Timestamp):
+            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.
+        point_in_time_recovery_enablement (google.cloud.firestore_admin_v1.types.Database.PointInTimeRecoveryEnablement):
+            Whether to enable the PITR feature on this
+            database.
         app_engine_integration_mode (google.cloud.firestore_admin_v1.types.Database.AppEngineIntegrationMode):
             The App Engine integration mode to use for
             this database.
@@ -120,6 +149,30 @@ class ConcurrencyMode(proto.Enum):
         PESSIMISTIC = 2
         OPTIMISTIC_WITH_ENTITY_GROUPS = 3
 
+    class PointInTimeRecoveryEnablement(proto.Enum):
+        r"""Point In Time Recovery feature enablement.
+
+        Values:
+            POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED (0):
+                Not used.
+            POINT_IN_TIME_RECOVERY_ENABLED (1):
+                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_DISABLED (2):
+                Reads are supported on any version of the
+                data from within the past 1 hour.
+        """
+        POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED = 0
+        POINT_IN_TIME_RECOVERY_ENABLED = 1
+        POINT_IN_TIME_RECOVERY_DISABLED = 2
+
     class AppEngineIntegrationMode(proto.Enum):
         r"""The type of App Engine integration mode.
 
@@ -134,8 +187,11 @@ class AppEngineIntegrationMode(proto.Enum):
                 database, as well as disabling writes to the
                 database.
             DISABLED (2):
-                Appengine has no affect on the ability of
+                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.
         """
         APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED = 0
         ENABLED = 1
@@ -159,6 +215,21 @@ class AppEngineIntegrationMode(proto.Enum):
         number=15,
         enum=ConcurrencyMode,
     )
+    version_retention_period: duration_pb2.Duration = proto.Field(
+        proto.MESSAGE,
+        number=17,
+        message=duration_pb2.Duration,
+    )
+    earliest_version_time: timestamp_pb2.Timestamp = proto.Field(
+        proto.MESSAGE,
+        number=18,
+        message=timestamp_pb2.Timestamp,
+    )
+    point_in_time_recovery_enablement: PointInTimeRecoveryEnablement = proto.Field(
+        proto.ENUM,
+        number=21,
+        enum=PointInTimeRecoveryEnablement,
+    )
     app_engine_integration_mode: AppEngineIntegrationMode = proto.Field(
         proto.ENUM,
         number=19,

google/cloud/firestore_admin_v1/types/firestore_admin.py

@@ -23,6 +23,7 @@
 from google.cloud.firestore_admin_v1.types import field as gfa_field
 from google.cloud.firestore_admin_v1.types import index as gfa_index
 from google.protobuf import field_mask_pb2  # type: ignore
+from google.protobuf import timestamp_pb2  # type: ignore
 
 
 __protobuf__ = proto.module(
@@ -412,6 +413,25 @@ class ExportDocumentsRequest(proto.Message):
             https://cloud.google.com/storage/docs/naming. If the URI is
             a bucket (without a namespace path), a prefix will be
             generated based on the start time.
+        namespace_ids (MutableSequence[str]):
+            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.
+        snapshot_time (google.protobuf.timestamp_pb2.Timestamp):
+            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.
     """
 
     name: str = proto.Field(
@@ -426,6 +446,15 @@ class ExportDocumentsRequest(proto.Message):
         proto.STRING,
         number=3,
     )
+    namespace_ids: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=4,
+    )
+    snapshot_time: timestamp_pb2.Timestamp = proto.Field(
+        proto.MESSAGE,
+        number=5,
+        message=timestamp_pb2.Timestamp,
+    )
 
 
 class ImportDocumentsRequest(proto.Message):
@@ -444,6 +473,16 @@ class ImportDocumentsRequest(proto.Message):
             output_uri_prefix of an ExportDocumentsResponse from an
             export that has completed successfully. See:
             [google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix][google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix].
+        namespace_ids (MutableSequence[str]):
+            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.
     """
 
     name: str = proto.Field(
@@ -458,6 +497,10 @@ class ImportDocumentsRequest(proto.Message):
         proto.STRING,
         number=3,
     )
+    namespace_ids: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=4,
+    )
 
 
 __all__ = tuple(sorted(__protobuf__.manifest))

google/cloud/firestore_admin_v1/types/operation.py

@@ -199,7 +199,7 @@ class ChangeType(proto.Enum):
         )
 
     class TtlConfigDelta(proto.Message):
-        r"""Information about an TTL configuration change.
+        r"""Information about a TTL configuration change.
 
         Attributes:
             change_type (google.cloud.firestore_admin_v1.types.FieldOperationMetadata.TtlConfigDelta.ChangeType):
@@ -291,7 +291,14 @@ class ExportDocumentsMetadata(proto.Message):
         collection_ids (MutableSequence[str]):
             Which collection ids are being exported.
         output_uri_prefix (str):
-            Where the entities are being exported to.
+            Where the documents are being exported to.
+        namespace_ids (MutableSequence[str]):
+            Which namespace ids are being exported.
+        snapshot_time (google.protobuf.timestamp_pb2.Timestamp):
+            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.
     """
 
     start_time: timestamp_pb2.Timestamp = proto.Field(
@@ -327,6 +334,15 @@ class ExportDocumentsMetadata(proto.Message):
         proto.STRING,
         number=7,
     )
+    namespace_ids: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=8,
+    )
+    snapshot_time: timestamp_pb2.Timestamp = proto.Field(
+        proto.MESSAGE,
+        number=9,
+        message=timestamp_pb2.Timestamp,
+    )
 
 
 class ImportDocumentsMetadata(proto.Message):
@@ -352,6 +368,8 @@ class ImportDocumentsMetadata(proto.Message):
             Which collection ids are being imported.
         input_uri_prefix (str):
             The location of the documents being imported.
+        namespace_ids (MutableSequence[str]):
+            Which namespace ids are being imported.
     """
 
     start_time: timestamp_pb2.Timestamp = proto.Field(
@@ -387,6 +405,10 @@ class ImportDocumentsMetadata(proto.Message):
         proto.STRING,
         number=7,
     )
+    namespace_ids: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=8,
+    )
 
 
 class ExportDocumentsResponse(proto.Message):

scripts/fixup_firestore_admin_v1_keywords.py

@@ -48,11 +48,11 @@ class firestore_adminCallTransformer(cst.CSTTransformer):
         'create_database': ('parent', 'database', 'database_id', ),
         'create_index': ('parent', 'index', ),
         'delete_index': ('name', ),
-        'export_documents': ('name', 'collection_ids', 'output_uri_prefix', ),
+        'export_documents': ('name', 'collection_ids', 'output_uri_prefix', 'namespace_ids', 'snapshot_time', ),
         'get_database': ('name', ),
         'get_field': ('name', ),
         'get_index': ('name', ),
-        'import_documents': ('name', 'collection_ids', 'input_uri_prefix', ),
+        'import_documents': ('name', 'collection_ids', 'input_uri_prefix', 'namespace_ids', ),
         'list_databases': ('parent', ),
         'list_fields': ('parent', 'filter', 'page_size', 'page_token', ),
         'list_indexes': ('parent', 'filter', 'page_size', 'page_token', ),