Skip to content

Commit fbe1c8e

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
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
1 parent d7c2571 commit fbe1c8e

5 files changed

Lines changed: 121 additions & 25 deletions

File tree

‎google/firestore/admin/v1/BUILD.bazel‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ proto_library(
3434
"//google/api:field_behavior_proto",
3535
"//google/api:resource_proto",
3636
"//google/longrunning:operations_proto",
37+
"@com_google_protobuf//:duration_proto",
3738
"@com_google_protobuf//:empty_proto",
3839
"@com_google_protobuf//:field_mask_proto",
3940
"@com_google_protobuf//:timestamp_proto",
@@ -227,10 +228,10 @@ php_gapic_library(
227228
name = "admin_php_gapic",
228229
srcs = [":admin_proto_with_info"],
229230
grpc_service_config = "firestore_admin_grpc_service_config.json",
231+
migration_mode = "MIGRATION_MODE_UNSPECIFIED",
230232
rest_numeric_enums = True,
231233
service_yaml = "firestore_v1.yaml",
232234
transport = "grpc+rest",
233-
migration_mode = "MIGRATION_MODE_UNSPECIFIED",
234235
deps = [":admin_php_proto"],
235236
)
236237

‎google/firestore/admin/v1/database.proto‎

Lines changed: 58 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2023 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -18,6 +18,8 @@ package google.firestore.admin.v1;
1818

1919
import "google/api/field_behavior.proto";
2020
import "google/api/resource.proto";
21+
import "google/protobuf/duration.proto";
22+
import "google/protobuf/timestamp.proto";
2123

2224
option csharp_namespace = "Google.Cloud.Firestore.Admin.V1";
2325
option go_package = "cloud.google.com/go/firestore/apiv1/admin/adminpb;adminpb";
@@ -78,6 +80,26 @@ message Database {
7880
OPTIMISTIC_WITH_ENTITY_GROUPS = 3;
7981
}
8082

83+
// Point In Time Recovery feature enablement.
84+
enum PointInTimeRecoveryEnablement {
85+
// Not used.
86+
POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED = 0;
87+
88+
// Reads are supported on selected versions of the data from within the past
89+
// 7 days:
90+
//
91+
// * Reads against any timestamp within the past hour
92+
// * Reads against 1-minute snapshots beyond 1 hour and within 7 days
93+
//
94+
// `version_retention_period` and `earliest_version_time` can be
95+
// used to determine the supported versions.
96+
POINT_IN_TIME_RECOVERY_ENABLED = 1;
97+
98+
// Reads are supported on any version of the data from within the past 1
99+
// hour.
100+
POINT_IN_TIME_RECOVERY_DISABLED = 2;
101+
}
102+
81103
// The type of App Engine integration mode.
82104
enum AppEngineIntegrationMode {
83105
// Not used.
@@ -89,16 +111,18 @@ message Database {
89111
// the database.
90112
ENABLED = 1;
91113

92-
// Appengine has no affect on the ability of this database to serve
114+
// App Engine has no effect on the ability of this database to serve
93115
// requests.
116+
//
117+
// This is the default setting for databases created with the Firestore API.
94118
DISABLED = 2;
95119
}
96120

97121
// The resource name of the Database.
98122
// Format: `projects/{project}/databases/{database}`
99123
string name = 1;
100124

101-
// The location of the database. Available databases are listed at
125+
// The location of the database. Available locations are listed at
102126
// https://cloud.google.com/firestore/docs/locations.
103127
string location_id = 9;
104128

@@ -110,13 +134,40 @@ message Database {
110134
// The concurrency control mode to use for this database.
111135
ConcurrencyMode concurrency_mode = 15;
112136

137+
// Output only. The period during which past versions of data are retained in
138+
// the database.
139+
//
140+
// Any [read][google.firestore.v1.GetDocumentRequest.read_time]
141+
// or [query][google.firestore.v1.ListDocumentsRequest.read_time] can specify
142+
// a `read_time` within this window, and will read the state of the database
143+
// at that time.
144+
//
145+
// If the PITR feature is enabled, the retention period is 7 days. Otherwise,
146+
// the retention period is 1 hour.
147+
google.protobuf.Duration version_retention_period = 17
148+
[(google.api.field_behavior) = OUTPUT_ONLY];
149+
150+
// Output only. The earliest timestamp at which older versions of the data can
151+
// be read from the database. See [version_retention_period] above; this field
152+
// is populated with `now - version_retention_period`.
153+
//
154+
// This value is continuously updated, and becomes stale the moment it is
155+
// queried. If you are using this value to recover data, make sure to account
156+
// for the time from the moment when the value is queried to the moment when
157+
// you initiate the recovery.
158+
google.protobuf.Timestamp earliest_version_time = 18
159+
[(google.api.field_behavior) = OUTPUT_ONLY];
160+
161+
// Whether to enable the PITR feature on this database.
162+
PointInTimeRecoveryEnablement point_in_time_recovery_enablement = 21;
163+
113164
// The App Engine integration mode to use for this database.
114165
AppEngineIntegrationMode app_engine_integration_mode = 19;
115166

116-
// Output only. The key_prefix for this database. This key_prefix is used, in combination
117-
// with the project id ("<key prefix>~<project id>") to construct the
118-
// application id that is returned from the Cloud Datastore APIs in Google App
119-
// Engine first generation runtimes.
167+
// Output only. The key_prefix for this database. This key_prefix is used, in
168+
// combination with the project id ("<key prefix>~<project id>") to construct
169+
// the application id that is returned from the Cloud Datastore APIs in Google
170+
// App Engine first generation runtimes.
120171
//
121172
// This value may be empty in which case the appid to use for URL-encoded keys
122173
// is the project_id (eg: foo instead of v~foo).

‎google/firestore/admin/v1/firestore_admin.proto‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,11 @@ import "google/api/resource.proto";
2323
import "google/firestore/admin/v1/database.proto";
2424
import "google/firestore/admin/v1/field.proto";
2525
import "google/firestore/admin/v1/index.proto";
26+
import "google/firestore/admin/v1/operation.proto";
2627
import "google/longrunning/operations.proto";
2728
import "google/protobuf/empty.proto";
2829
import "google/protobuf/field_mask.proto";
30+
import "google/protobuf/timestamp.proto";
2931

3032
option csharp_namespace = "Google.Cloud.Firestore.Admin.V1";
3133
option go_package = "cloud.google.com/go/firestore/apiv1/admin/adminpb;adminpb";
@@ -485,6 +487,23 @@ message ExportDocumentsRequest {
485487
// If the URI is a bucket (without a namespace path), a prefix will be
486488
// generated based on the start time.
487489
string output_uri_prefix = 3;
490+
491+
// Unspecified means all namespaces. This is the preferred
492+
// usage for databases that don't use namespaces.
493+
//
494+
// An empty string element represents the default namespace. This should be
495+
// used if the database has data in non-default namespaces, but doesn't want
496+
// to include them. Each namespace in this list must be unique.
497+
repeated string namespace_ids = 4;
498+
499+
// The timestamp that corresponds to the version of the database to be
500+
// exported. The timestamp must be in the past, rounded to the minute and not
501+
// older than
502+
// [earliestVersionTime][google.firestore.admin.v1.Database.earliest_version_time].
503+
// If specified, then the exported documents will represent a consistent view
504+
// of the database at the provided time. Otherwise, there are no guarantees
505+
// about the consistency of the exported documents.
506+
google.protobuf.Timestamp snapshot_time = 5;
488507
}
489508

490509
// The request for
@@ -509,4 +528,12 @@ message ImportDocumentsRequest {
509528
// See:
510529
// [google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix][google.firestore.admin.v1.ExportDocumentsResponse.output_uri_prefix].
511530
string input_uri_prefix = 3;
531+
532+
// Unspecified means all namespaces. This is the preferred
533+
// usage for databases that don't use namespaces.
534+
//
535+
// An empty string element represents the default namespace. This should be
536+
// used if the database has data in non-default namespaces, but doesn't want
537+
// to include them. Each namespace in this list must be unique.
538+
repeated string namespace_ids = 4;
512539
}

‎google/firestore/admin/v1/location.proto‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2023 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -25,7 +25,6 @@ option objc_class_prefix = "GCFS";
2525
option php_namespace = "Google\\Cloud\\Firestore\\Admin\\V1";
2626
option ruby_package = "Google::Cloud::Firestore::Admin::V1";
2727

28-
// The metadata message for [google.cloud.location.Location.metadata][google.cloud.location.Location.metadata].
29-
message LocationMetadata {
30-
31-
}
28+
// The metadata message for
29+
// [google.cloud.location.Location.metadata][google.cloud.location.Location.metadata].
30+
message LocationMetadata {}

‎google/firestore/admin/v1/operation.proto‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2023 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@ syntax = "proto3";
1616

1717
package google.firestore.admin.v1;
1818

19+
import "google/api/resource.proto";
1920
import "google/firestore/admin/v1/index.proto";
2021
import "google/protobuf/timestamp.proto";
2122

@@ -28,7 +29,8 @@ option objc_class_prefix = "GCFS";
2829
option php_namespace = "Google\\Cloud\\Firestore\\Admin\\V1";
2930
option ruby_package = "Google::Cloud::Firestore::Admin::V1";
3031

31-
// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
32+
// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
33+
// results from
3234
// [FirestoreAdmin.CreateIndex][google.firestore.admin.v1.FirestoreAdmin.CreateIndex].
3335
message IndexOperationMetadata {
3436
// The time this operation started.
@@ -52,7 +54,8 @@ message IndexOperationMetadata {
5254
Progress progress_bytes = 6;
5355
}
5456

55-
// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
57+
// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
58+
// results from
5659
// [FirestoreAdmin.UpdateField][google.firestore.admin.v1.FirestoreAdmin.UpdateField].
5760
message FieldOperationMetadata {
5861
// Information about an index configuration change.
@@ -76,7 +79,7 @@ message FieldOperationMetadata {
7679
Index index = 2;
7780
}
7881

79-
// Information about an TTL configuration change.
82+
// Information about a TTL configuration change.
8083
message TtlConfigDelta {
8184
// Specifies how the TTL config is changing.
8285
enum ChangeType {
@@ -105,8 +108,9 @@ message FieldOperationMetadata {
105108
// `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_path}`
106109
string field = 3;
107110

108-
// A list of [IndexConfigDelta][google.firestore.admin.v1.FieldOperationMetadata.IndexConfigDelta], which describe the intent of this
109-
// operation.
111+
// A list of
112+
// [IndexConfigDelta][google.firestore.admin.v1.FieldOperationMetadata.IndexConfigDelta],
113+
// which describe the intent of this operation.
110114
repeated IndexConfigDelta index_config_deltas = 4;
111115

112116
// The state of the operation.
@@ -122,7 +126,8 @@ message FieldOperationMetadata {
122126
TtlConfigDelta ttl_config_delta = 8;
123127
}
124128

125-
// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
129+
// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
130+
// results from
126131
// [FirestoreAdmin.ExportDocuments][google.firestore.admin.v1.FirestoreAdmin.ExportDocuments].
127132
message ExportDocumentsMetadata {
128133
// The time this operation started.
@@ -144,11 +149,20 @@ message ExportDocumentsMetadata {
144149
// Which collection ids are being exported.
145150
repeated string collection_ids = 6;
146151

147-
// Where the entities are being exported to.
152+
// Where the documents are being exported to.
148153
string output_uri_prefix = 7;
154+
155+
// Which namespace ids are being exported.
156+
repeated string namespace_ids = 8;
157+
158+
// The timestamp that corresponds to the version of the database that is being
159+
// exported. If unspecified, there are no guarantees about the consistency of
160+
// the documents being exported.
161+
google.protobuf.Timestamp snapshot_time = 9;
149162
}
150163

151-
// Metadata for [google.longrunning.Operation][google.longrunning.Operation] results from
164+
// Metadata for [google.longrunning.Operation][google.longrunning.Operation]
165+
// results from
152166
// [FirestoreAdmin.ImportDocuments][google.firestore.admin.v1.FirestoreAdmin.ImportDocuments].
153167
message ImportDocumentsMetadata {
154168
// The time this operation started.
@@ -172,9 +186,13 @@ message ImportDocumentsMetadata {
172186

173187
// The location of the documents being imported.
174188
string input_uri_prefix = 7;
189+
190+
// Which namespace ids are being imported.
191+
repeated string namespace_ids = 8;
175192
}
176193

177-
// Returned in the [google.longrunning.Operation][google.longrunning.Operation] response field.
194+
// Returned in the [google.longrunning.Operation][google.longrunning.Operation]
195+
// response field.
178196
message ExportDocumentsResponse {
179197
// Location of the output files. This can be used to begin an import
180198
// into Cloud Firestore (this project or another project) after the operation
@@ -212,8 +230,8 @@ enum OperationState {
212230
}
213231

214232
// Describes the progress of the operation.
215-
// Unit of work is generic and must be interpreted based on where [Progress][google.firestore.admin.v1.Progress]
216-
// is used.
233+
// Unit of work is generic and must be interpreted based on where
234+
// [Progress][google.firestore.admin.v1.Progress] is used.
217235
message Progress {
218236
// The amount of work estimated.
219237
int64 estimated_work = 1;

0 commit comments

Comments
 (0)