Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/firestore_v1/types/firestore.py: 98%

1# -*- coding: utf-8 -*- 

2# Copyright 2023 Google LLC 

3# 

4# Licensed under the Apache License, Version 2.0 (the "License"); 

5# you may not use this file except in compliance with the License. 

6# You may obtain a copy of the License at 

7# 

8# http://www.apache.org/licenses/LICENSE-2.0 

9# 

10# Unless required by applicable law or agreed to in writing, software 

11# distributed under the License is distributed on an "AS IS" BASIS, 

12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

13# See the License for the specific language governing permissions and 

14# limitations under the License. 

15# 

16from __future__ import annotations 

17 

18from typing import MutableMapping, MutableSequence 

19 

20import proto # type: ignore 

21 

22from google.cloud.firestore_v1.types import aggregation_result 

23from google.cloud.firestore_v1.types import common 

24from google.cloud.firestore_v1.types import document as gf_document 

25from google.cloud.firestore_v1.types import query as gf_query 

26from google.cloud.firestore_v1.types import write 

27from google.protobuf import timestamp_pb2 # type: ignore 

28from google.protobuf import wrappers_pb2 # type: ignore 

29from google.rpc import status_pb2 # type: ignore 

30 

31 

32__protobuf__ = proto.module( 

33 package="google.firestore.v1", 

34 manifest={ 

35 "GetDocumentRequest", 

36 "ListDocumentsRequest", 

37 "ListDocumentsResponse", 

38 "CreateDocumentRequest", 

39 "UpdateDocumentRequest", 

40 "DeleteDocumentRequest", 

41 "BatchGetDocumentsRequest", 

42 "BatchGetDocumentsResponse", 

43 "BeginTransactionRequest", 

44 "BeginTransactionResponse", 

45 "CommitRequest", 

46 "CommitResponse", 

47 "RollbackRequest", 

48 "RunQueryRequest", 

49 "RunQueryResponse", 

50 "RunAggregationQueryRequest", 

51 "RunAggregationQueryResponse", 

52 "PartitionQueryRequest", 

53 "PartitionQueryResponse", 

54 "WriteRequest", 

55 "WriteResponse", 

56 "ListenRequest", 

57 "ListenResponse", 

58 "Target", 

59 "TargetChange", 

60 "ListCollectionIdsRequest", 

61 "ListCollectionIdsResponse", 

62 "BatchWriteRequest", 

63 "BatchWriteResponse", 

64 }, 

65) 

66 

67 

68class GetDocumentRequest(proto.Message): 

69 r"""The request for 

70 [Firestore.GetDocument][google.firestore.v1.Firestore.GetDocument]. 

71 

72 This message has `oneof`_ fields (mutually exclusive fields). 

73 For each oneof, at most one member field can be set at the same time. 

74 Setting any member of the oneof automatically clears all other 

75 members. 

76 

77 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

78 

79 Attributes: 

80 name (str): 

81 Required. The resource name of the Document to get. In the 

82 format: 

83 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

84 mask (google.cloud.firestore_v1.types.DocumentMask): 

85 The fields to return. If not set, returns all 

86 fields. 

87 If the document has a field that is not present 

88 in this mask, that field will not be returned in 

89 the response. 

90 transaction (bytes): 

91 Reads the document in a transaction. 

92 

93 This field is a member of `oneof`_ ``consistency_selector``. 

94 read_time (google.protobuf.timestamp_pb2.Timestamp): 

95 Reads the version of the document at the 

96 given time. 

97 This must be a microsecond precision timestamp 

98 within the past one hour, or if Point-in-Time 

99 Recovery is enabled, can additionally be a whole 

100 minute timestamp within the past 7 days. 

101 

102 This field is a member of `oneof`_ ``consistency_selector``. 

103 """ 

104 

105 name: str = proto.Field( 

106 proto.STRING, 

107 number=1, 

108 ) 

109 mask: common.DocumentMask = proto.Field( 

110 proto.MESSAGE, 

111 number=2, 

112 message=common.DocumentMask, 

113 ) 

114 transaction: bytes = proto.Field( 

115 proto.BYTES, 

116 number=3, 

117 oneof="consistency_selector", 

118 ) 

119 read_time: timestamp_pb2.Timestamp = proto.Field( 

120 proto.MESSAGE, 

121 number=5, 

122 oneof="consistency_selector", 

123 message=timestamp_pb2.Timestamp, 

124 ) 

125 

126 

127class ListDocumentsRequest(proto.Message): 

128 r"""The request for 

129 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments]. 

130 

131 This message has `oneof`_ fields (mutually exclusive fields). 

132 For each oneof, at most one member field can be set at the same time. 

133 Setting any member of the oneof automatically clears all other 

134 members. 

135 

136 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

137 

138 Attributes: 

139 parent (str): 

140 Required. The parent resource name. In the format: 

141 ``projects/{project_id}/databases/{database_id}/documents`` 

142 or 

143 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

144 

145 For example: 

146 ``projects/my-project/databases/my-database/documents`` or 

147 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` 

148 collection_id (str): 

149 Optional. The collection ID, relative to ``parent``, to 

150 list. 

151 

152 For example: ``chatrooms`` or ``messages``. 

153 

154 This is optional, and when not provided, Firestore will list 

155 documents from all collections under the provided 

156 ``parent``. 

157 page_size (int): 

158 Optional. The maximum number of documents to 

159 return in a single response. 

160 Firestore may return fewer than this value. 

161 page_token (str): 

162 Optional. A page token, received from a previous 

163 ``ListDocuments`` response. 

164 

165 Provide this to retrieve the subsequent page. When 

166 paginating, all other parameters (with the exception of 

167 ``page_size``) must match the values set in the request that 

168 generated the page token. 

169 order_by (str): 

170 Optional. The optional ordering of the documents to return. 

171 

172 For example: ``priority desc, __name__ desc``. 

173 

174 This mirrors the 

175 [``ORDER BY``][google.firestore.v1.StructuredQuery.order_by] 

176 used in Firestore queries but in a string representation. 

177 When absent, documents are ordered based on 

178 ``__name__ ASC``. 

179 mask (google.cloud.firestore_v1.types.DocumentMask): 

180 Optional. The fields to return. If not set, 

181 returns all fields. 

182 If a document has a field that is not present in 

183 this mask, that field will not be returned in 

184 the response. 

185 transaction (bytes): 

186 Perform the read as part of an already active 

187 transaction. 

188 

189 This field is a member of `oneof`_ ``consistency_selector``. 

190 read_time (google.protobuf.timestamp_pb2.Timestamp): 

191 Perform the read at the provided time. 

192 

193 This must be a microsecond precision timestamp 

194 within the past one hour, or if Point-in-Time 

195 Recovery is enabled, can additionally be a whole 

196 minute timestamp within the past 7 days. 

197 

198 This field is a member of `oneof`_ ``consistency_selector``. 

199 show_missing (bool): 

200 If the list should show missing documents. 

201 

202 A document is missing if it does not exist, but there are 

203 sub-documents nested underneath it. When true, such missing 

204 documents will be returned with a key but will not have 

205 fields, 

206 [``create_time``][google.firestore.v1.Document.create_time], 

207 or 

208 [``update_time``][google.firestore.v1.Document.update_time] 

209 set. 

210 

211 Requests with ``show_missing`` may not specify ``where`` or 

212 ``order_by``. 

213 """ 

214 

215 parent: str = proto.Field( 

216 proto.STRING, 

217 number=1, 

218 ) 

219 collection_id: str = proto.Field( 

220 proto.STRING, 

221 number=2, 

222 ) 

223 page_size: int = proto.Field( 

224 proto.INT32, 

225 number=3, 

226 ) 

227 page_token: str = proto.Field( 

228 proto.STRING, 

229 number=4, 

230 ) 

231 order_by: str = proto.Field( 

232 proto.STRING, 

233 number=6, 

234 ) 

235 mask: common.DocumentMask = proto.Field( 

236 proto.MESSAGE, 

237 number=7, 

238 message=common.DocumentMask, 

239 ) 

240 transaction: bytes = proto.Field( 

241 proto.BYTES, 

242 number=8, 

243 oneof="consistency_selector", 

244 ) 

245 read_time: timestamp_pb2.Timestamp = proto.Field( 

246 proto.MESSAGE, 

247 number=10, 

248 oneof="consistency_selector", 

249 message=timestamp_pb2.Timestamp, 

250 ) 

251 show_missing: bool = proto.Field( 

252 proto.BOOL, 

253 number=12, 

254 ) 

255 

256 

257class ListDocumentsResponse(proto.Message): 

258 r"""The response for 

259 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments]. 

260 

261 Attributes: 

262 documents (MutableSequence[google.cloud.firestore_v1.types.Document]): 

263 The Documents found. 

264 next_page_token (str): 

265 A token to retrieve the next page of 

266 documents. 

267 If this field is omitted, there are no 

268 subsequent pages. 

269 """ 

270 

271 @property 

272 def raw_page(self): 

273 return self 

274 

275 documents: MutableSequence[gf_document.Document] = proto.RepeatedField( 

276 proto.MESSAGE, 

277 number=1, 

278 message=gf_document.Document, 

279 ) 

280 next_page_token: str = proto.Field( 

281 proto.STRING, 

282 number=2, 

283 ) 

284 

285 

286class CreateDocumentRequest(proto.Message): 

287 r"""The request for 

288 [Firestore.CreateDocument][google.firestore.v1.Firestore.CreateDocument]. 

289 

290 Attributes: 

291 parent (str): 

292 Required. The parent resource. For example: 

293 ``projects/{project_id}/databases/{database_id}/documents`` 

294 or 

295 ``projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}`` 

296 collection_id (str): 

297 Required. The collection ID, relative to ``parent``, to 

298 list. For example: ``chatrooms``. 

299 document_id (str): 

300 The client-assigned document ID to use for 

301 this document. 

302 Optional. If not specified, an ID will be 

303 assigned by the service. 

304 document (google.cloud.firestore_v1.types.Document): 

305 Required. The document to create. ``name`` must not be set. 

306 mask (google.cloud.firestore_v1.types.DocumentMask): 

307 The fields to return. If not set, returns all 

308 fields. 

309 If the document has a field that is not present 

310 in this mask, that field will not be returned in 

311 the response. 

312 """ 

313 

314 parent: str = proto.Field( 

315 proto.STRING, 

316 number=1, 

317 ) 

318 collection_id: str = proto.Field( 

319 proto.STRING, 

320 number=2, 

321 ) 

322 document_id: str = proto.Field( 

323 proto.STRING, 

324 number=3, 

325 ) 

326 document: gf_document.Document = proto.Field( 

327 proto.MESSAGE, 

328 number=4, 

329 message=gf_document.Document, 

330 ) 

331 mask: common.DocumentMask = proto.Field( 

332 proto.MESSAGE, 

333 number=5, 

334 message=common.DocumentMask, 

335 ) 

336 

337 

338class UpdateDocumentRequest(proto.Message): 

339 r"""The request for 

340 [Firestore.UpdateDocument][google.firestore.v1.Firestore.UpdateDocument]. 

341 

342 Attributes: 

343 document (google.cloud.firestore_v1.types.Document): 

344 Required. The updated document. 

345 Creates the document if it does not already 

346 exist. 

347 update_mask (google.cloud.firestore_v1.types.DocumentMask): 

348 The fields to update. 

349 None of the field paths in the mask may contain 

350 a reserved name. 

351 

352 If the document exists on the server and has 

353 fields not referenced in the mask, they are left 

354 unchanged. 

355 Fields referenced in the mask, but not present 

356 in the input document, are deleted from the 

357 document on the server. 

358 mask (google.cloud.firestore_v1.types.DocumentMask): 

359 The fields to return. If not set, returns all 

360 fields. 

361 If the document has a field that is not present 

362 in this mask, that field will not be returned in 

363 the response. 

364 current_document (google.cloud.firestore_v1.types.Precondition): 

365 An optional precondition on the document. 

366 The request will fail if this is set and not met 

367 by the target document. 

368 """ 

369 

370 document: gf_document.Document = proto.Field( 

371 proto.MESSAGE, 

372 number=1, 

373 message=gf_document.Document, 

374 ) 

375 update_mask: common.DocumentMask = proto.Field( 

376 proto.MESSAGE, 

377 number=2, 

378 message=common.DocumentMask, 

379 ) 

380 mask: common.DocumentMask = proto.Field( 

381 proto.MESSAGE, 

382 number=3, 

383 message=common.DocumentMask, 

384 ) 

385 current_document: common.Precondition = proto.Field( 

386 proto.MESSAGE, 

387 number=4, 

388 message=common.Precondition, 

389 ) 

390 

391 

392class DeleteDocumentRequest(proto.Message): 

393 r"""The request for 

394 [Firestore.DeleteDocument][google.firestore.v1.Firestore.DeleteDocument]. 

395 

396 Attributes: 

397 name (str): 

398 Required. The resource name of the Document to delete. In 

399 the format: 

400 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

401 current_document (google.cloud.firestore_v1.types.Precondition): 

402 An optional precondition on the document. 

403 The request will fail if this is set and not met 

404 by the target document. 

405 """ 

406 

407 name: str = proto.Field( 

408 proto.STRING, 

409 number=1, 

410 ) 

411 current_document: common.Precondition = proto.Field( 

412 proto.MESSAGE, 

413 number=2, 

414 message=common.Precondition, 

415 ) 

416 

417 

418class BatchGetDocumentsRequest(proto.Message): 

419 r"""The request for 

420 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments]. 

421 

422 This message has `oneof`_ fields (mutually exclusive fields). 

423 For each oneof, at most one member field can be set at the same time. 

424 Setting any member of the oneof automatically clears all other 

425 members. 

426 

427 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

428 

429 Attributes: 

430 database (str): 

431 Required. The database name. In the format: 

432 ``projects/{project_id}/databases/{database_id}``. 

433 documents (MutableSequence[str]): 

434 The names of the documents to retrieve. In the format: 

435 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

436 The request will fail if any of the document is not a child 

437 resource of the given ``database``. Duplicate names will be 

438 elided. 

439 mask (google.cloud.firestore_v1.types.DocumentMask): 

440 The fields to return. If not set, returns all 

441 fields. 

442 If a document has a field that is not present in 

443 this mask, that field will not be returned in 

444 the response. 

445 transaction (bytes): 

446 Reads documents in a transaction. 

447 

448 This field is a member of `oneof`_ ``consistency_selector``. 

449 new_transaction (google.cloud.firestore_v1.types.TransactionOptions): 

450 Starts a new transaction and reads the 

451 documents. Defaults to a read-only transaction. 

452 The new transaction ID will be returned as the 

453 first response in the stream. 

454 

455 This field is a member of `oneof`_ ``consistency_selector``. 

456 read_time (google.protobuf.timestamp_pb2.Timestamp): 

457 Reads documents as they were at the given 

458 time. 

459 This must be a microsecond precision timestamp 

460 within the past one hour, or if Point-in-Time 

461 Recovery is enabled, can additionally be a whole 

462 minute timestamp within the past 7 days. 

463 

464 This field is a member of `oneof`_ ``consistency_selector``. 

465 """ 

466 

467 database: str = proto.Field( 

468 proto.STRING, 

469 number=1, 

470 ) 

471 documents: MutableSequence[str] = proto.RepeatedField( 

472 proto.STRING, 

473 number=2, 

474 ) 

475 mask: common.DocumentMask = proto.Field( 

476 proto.MESSAGE, 

477 number=3, 

478 message=common.DocumentMask, 

479 ) 

480 transaction: bytes = proto.Field( 

481 proto.BYTES, 

482 number=4, 

483 oneof="consistency_selector", 

484 ) 

485 new_transaction: common.TransactionOptions = proto.Field( 

486 proto.MESSAGE, 

487 number=5, 

488 oneof="consistency_selector", 

489 message=common.TransactionOptions, 

490 ) 

491 read_time: timestamp_pb2.Timestamp = proto.Field( 

492 proto.MESSAGE, 

493 number=7, 

494 oneof="consistency_selector", 

495 message=timestamp_pb2.Timestamp, 

496 ) 

497 

498 

499class BatchGetDocumentsResponse(proto.Message): 

500 r"""The streamed response for 

501 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments]. 

502 

503 This message has `oneof`_ fields (mutually exclusive fields). 

504 For each oneof, at most one member field can be set at the same time. 

505 Setting any member of the oneof automatically clears all other 

506 members. 

507 

508 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

509 

510 Attributes: 

511 found (google.cloud.firestore_v1.types.Document): 

512 A document that was requested. 

513 

514 This field is a member of `oneof`_ ``result``. 

515 missing (str): 

516 A document name that was requested but does not exist. In 

517 the format: 

518 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

519 

520 This field is a member of `oneof`_ ``result``. 

521 transaction (bytes): 

522 The transaction that was started as part of this request. 

523 Will only be set in the first response, and only if 

524 [BatchGetDocumentsRequest.new_transaction][google.firestore.v1.BatchGetDocumentsRequest.new_transaction] 

525 was set in the request. 

526 read_time (google.protobuf.timestamp_pb2.Timestamp): 

527 The time at which the document was read. This may be 

528 monotically increasing, in this case the previous documents 

529 in the result stream are guaranteed not to have changed 

530 between their read_time and this one. 

531 """ 

532 

533 found: gf_document.Document = proto.Field( 

534 proto.MESSAGE, 

535 number=1, 

536 oneof="result", 

537 message=gf_document.Document, 

538 ) 

539 missing: str = proto.Field( 

540 proto.STRING, 

541 number=2, 

542 oneof="result", 

543 ) 

544 transaction: bytes = proto.Field( 

545 proto.BYTES, 

546 number=3, 

547 ) 

548 read_time: timestamp_pb2.Timestamp = proto.Field( 

549 proto.MESSAGE, 

550 number=4, 

551 message=timestamp_pb2.Timestamp, 

552 ) 

553 

554 

555class BeginTransactionRequest(proto.Message): 

556 r"""The request for 

557 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction]. 

558 

559 Attributes: 

560 database (str): 

561 Required. The database name. In the format: 

562 ``projects/{project_id}/databases/{database_id}``. 

563 options (google.cloud.firestore_v1.types.TransactionOptions): 

564 The options for the transaction. 

565 Defaults to a read-write transaction. 

566 """ 

567 

568 database: str = proto.Field( 

569 proto.STRING, 

570 number=1, 

571 ) 

572 options: common.TransactionOptions = proto.Field( 

573 proto.MESSAGE, 

574 number=2, 

575 message=common.TransactionOptions, 

576 ) 

577 

578 

579class BeginTransactionResponse(proto.Message): 

580 r"""The response for 

581 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction]. 

582 

583 Attributes: 

584 transaction (bytes): 

585 The transaction that was started. 

586 """ 

587 

588 transaction: bytes = proto.Field( 

589 proto.BYTES, 

590 number=1, 

591 ) 

592 

593 

594class CommitRequest(proto.Message): 

595 r"""The request for 

596 [Firestore.Commit][google.firestore.v1.Firestore.Commit]. 

597 

598 Attributes: 

599 database (str): 

600 Required. The database name. In the format: 

601 ``projects/{project_id}/databases/{database_id}``. 

602 writes (MutableSequence[google.cloud.firestore_v1.types.Write]): 

603 The writes to apply. 

604 

605 Always executed atomically and in order. 

606 transaction (bytes): 

607 If set, applies all writes in this 

608 transaction, and commits it. 

609 """ 

610 

611 database: str = proto.Field( 

612 proto.STRING, 

613 number=1, 

614 ) 

615 writes: MutableSequence[write.Write] = proto.RepeatedField( 

616 proto.MESSAGE, 

617 number=2, 

618 message=write.Write, 

619 ) 

620 transaction: bytes = proto.Field( 

621 proto.BYTES, 

622 number=3, 

623 ) 

624 

625 

626class CommitResponse(proto.Message): 

627 r"""The response for 

628 [Firestore.Commit][google.firestore.v1.Firestore.Commit]. 

629 

630 Attributes: 

631 write_results (MutableSequence[google.cloud.firestore_v1.types.WriteResult]): 

632 The result of applying the writes. 

633 

634 This i-th write result corresponds to the i-th 

635 write in the request. 

636 commit_time (google.protobuf.timestamp_pb2.Timestamp): 

637 The time at which the commit occurred. Any read with an 

638 equal or greater ``read_time`` is guaranteed to see the 

639 effects of the commit. 

640 """ 

641 

642 write_results: MutableSequence[write.WriteResult] = proto.RepeatedField( 

643 proto.MESSAGE, 

644 number=1, 

645 message=write.WriteResult, 

646 ) 

647 commit_time: timestamp_pb2.Timestamp = proto.Field( 

648 proto.MESSAGE, 

649 number=2, 

650 message=timestamp_pb2.Timestamp, 

651 ) 

652 

653 

654class RollbackRequest(proto.Message): 

655 r"""The request for 

656 [Firestore.Rollback][google.firestore.v1.Firestore.Rollback]. 

657 

658 Attributes: 

659 database (str): 

660 Required. The database name. In the format: 

661 ``projects/{project_id}/databases/{database_id}``. 

662 transaction (bytes): 

663 Required. The transaction to roll back. 

664 """ 

665 

666 database: str = proto.Field( 

667 proto.STRING, 

668 number=1, 

669 ) 

670 transaction: bytes = proto.Field( 

671 proto.BYTES, 

672 number=2, 

673 ) 

674 

675 

676class RunQueryRequest(proto.Message): 

677 r"""The request for 

678 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery]. 

679 

680 This message has `oneof`_ fields (mutually exclusive fields). 

681 For each oneof, at most one member field can be set at the same time. 

682 Setting any member of the oneof automatically clears all other 

683 members. 

684 

685 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

686 

687 Attributes: 

688 parent (str): 

689 Required. The parent resource name. In the format: 

690 ``projects/{project_id}/databases/{database_id}/documents`` 

691 or 

692 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

693 For example: 

694 ``projects/my-project/databases/my-database/documents`` or 

695 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` 

696 structured_query (google.cloud.firestore_v1.types.StructuredQuery): 

697 A structured query. 

698 

699 This field is a member of `oneof`_ ``query_type``. 

700 transaction (bytes): 

701 Run the query within an already active 

702 transaction. 

703 The value here is the opaque transaction ID to 

704 execute the query in. 

705 

706 This field is a member of `oneof`_ ``consistency_selector``. 

707 new_transaction (google.cloud.firestore_v1.types.TransactionOptions): 

708 Starts a new transaction and reads the 

709 documents. Defaults to a read-only transaction. 

710 The new transaction ID will be returned as the 

711 first response in the stream. 

712 

713 This field is a member of `oneof`_ ``consistency_selector``. 

714 read_time (google.protobuf.timestamp_pb2.Timestamp): 

715 Reads documents as they were at the given 

716 time. 

717 This must be a microsecond precision timestamp 

718 within the past one hour, or if Point-in-Time 

719 Recovery is enabled, can additionally be a whole 

720 minute timestamp within the past 7 days. 

721 

722 This field is a member of `oneof`_ ``consistency_selector``. 

723 """ 

724 

725 parent: str = proto.Field( 

726 proto.STRING, 

727 number=1, 

728 ) 

729 structured_query: gf_query.StructuredQuery = proto.Field( 

730 proto.MESSAGE, 

731 number=2, 

732 oneof="query_type", 

733 message=gf_query.StructuredQuery, 

734 ) 

735 transaction: bytes = proto.Field( 

736 proto.BYTES, 

737 number=5, 

738 oneof="consistency_selector", 

739 ) 

740 new_transaction: common.TransactionOptions = proto.Field( 

741 proto.MESSAGE, 

742 number=6, 

743 oneof="consistency_selector", 

744 message=common.TransactionOptions, 

745 ) 

746 read_time: timestamp_pb2.Timestamp = proto.Field( 

747 proto.MESSAGE, 

748 number=7, 

749 oneof="consistency_selector", 

750 message=timestamp_pb2.Timestamp, 

751 ) 

752 

753 

754class RunQueryResponse(proto.Message): 

755 r"""The response for 

756 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery]. 

757 

758 

759 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

760 

761 Attributes: 

762 transaction (bytes): 

763 The transaction that was started as part of this request. 

764 Can only be set in the first response, and only if 

765 [RunQueryRequest.new_transaction][google.firestore.v1.RunQueryRequest.new_transaction] 

766 was set in the request. If set, no other fields will be set 

767 in this response. 

768 document (google.cloud.firestore_v1.types.Document): 

769 A query result, not set when reporting 

770 partial progress. 

771 read_time (google.protobuf.timestamp_pb2.Timestamp): 

772 The time at which the document was read. This may be 

773 monotonically increasing; in this case, the previous 

774 documents in the result stream are guaranteed not to have 

775 changed between their ``read_time`` and this one. 

776 

777 If the query returns no results, a response with 

778 ``read_time`` and no ``document`` will be sent, and this 

779 represents the time at which the query was run. 

780 skipped_results (int): 

781 The number of results that have been skipped 

782 due to an offset between the last response and 

783 the current response. 

784 done (bool): 

785 If present, Firestore has completely finished 

786 the request and no more documents will be 

787 returned. 

788 

789 This field is a member of `oneof`_ ``continuation_selector``. 

790 """ 

791 

792 transaction: bytes = proto.Field( 

793 proto.BYTES, 

794 number=2, 

795 ) 

796 document: gf_document.Document = proto.Field( 

797 proto.MESSAGE, 

798 number=1, 

799 message=gf_document.Document, 

800 ) 

801 read_time: timestamp_pb2.Timestamp = proto.Field( 

802 proto.MESSAGE, 

803 number=3, 

804 message=timestamp_pb2.Timestamp, 

805 ) 

806 skipped_results: int = proto.Field( 

807 proto.INT32, 

808 number=4, 

809 ) 

810 done: bool = proto.Field( 

811 proto.BOOL, 

812 number=6, 

813 oneof="continuation_selector", 

814 ) 

815 

816 

817class RunAggregationQueryRequest(proto.Message): 

818 r"""The request for 

819 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery]. 

820 

821 This message has `oneof`_ fields (mutually exclusive fields). 

822 For each oneof, at most one member field can be set at the same time. 

823 Setting any member of the oneof automatically clears all other 

824 members. 

825 

826 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

827 

828 Attributes: 

829 parent (str): 

830 Required. The parent resource name. In the format: 

831 ``projects/{project_id}/databases/{database_id}/documents`` 

832 or 

833 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

834 For example: 

835 ``projects/my-project/databases/my-database/documents`` or 

836 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` 

837 structured_aggregation_query (google.cloud.firestore_v1.types.StructuredAggregationQuery): 

838 An aggregation query. 

839 

840 This field is a member of `oneof`_ ``query_type``. 

841 transaction (bytes): 

842 Run the aggregation within an already active 

843 transaction. 

844 The value here is the opaque transaction ID to 

845 execute the query in. 

846 

847 This field is a member of `oneof`_ ``consistency_selector``. 

848 new_transaction (google.cloud.firestore_v1.types.TransactionOptions): 

849 Starts a new transaction as part of the 

850 query, defaulting to read-only. 

851 The new transaction ID will be returned as the 

852 first response in the stream. 

853 

854 This field is a member of `oneof`_ ``consistency_selector``. 

855 read_time (google.protobuf.timestamp_pb2.Timestamp): 

856 Executes the query at the given timestamp. 

857 

858 This must be a microsecond precision timestamp 

859 within the past one hour, or if Point-in-Time 

860 Recovery is enabled, can additionally be a whole 

861 minute timestamp within the past 7 days. 

862 

863 This field is a member of `oneof`_ ``consistency_selector``. 

864 """ 

865 

866 parent: str = proto.Field( 

867 proto.STRING, 

868 number=1, 

869 ) 

870 structured_aggregation_query: gf_query.StructuredAggregationQuery = proto.Field( 

871 proto.MESSAGE, 

872 number=2, 

873 oneof="query_type", 

874 message=gf_query.StructuredAggregationQuery, 

875 ) 

876 transaction: bytes = proto.Field( 

877 proto.BYTES, 

878 number=4, 

879 oneof="consistency_selector", 

880 ) 

881 new_transaction: common.TransactionOptions = proto.Field( 

882 proto.MESSAGE, 

883 number=5, 

884 oneof="consistency_selector", 

885 message=common.TransactionOptions, 

886 ) 

887 read_time: timestamp_pb2.Timestamp = proto.Field( 

888 proto.MESSAGE, 

889 number=6, 

890 oneof="consistency_selector", 

891 message=timestamp_pb2.Timestamp, 

892 ) 

893 

894 

895class RunAggregationQueryResponse(proto.Message): 

896 r"""The response for 

897 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery]. 

898 

899 Attributes: 

900 result (google.cloud.firestore_v1.types.AggregationResult): 

901 A single aggregation result. 

902 

903 Not present when reporting partial progress. 

904 transaction (bytes): 

905 The transaction that was started as part of 

906 this request. 

907 Only present on the first response when the 

908 request requested to start a new transaction. 

909 read_time (google.protobuf.timestamp_pb2.Timestamp): 

910 The time at which the aggregate result was computed. This is 

911 always monotonically increasing; in this case, the previous 

912 AggregationResult in the result stream are guaranteed not to 

913 have changed between their ``read_time`` and this one. 

914 

915 If the query returns no results, a response with 

916 ``read_time`` and no ``result`` will be sent, and this 

917 represents the time at which the query was run. 

918 """ 

919 

920 result: aggregation_result.AggregationResult = proto.Field( 

921 proto.MESSAGE, 

922 number=1, 

923 message=aggregation_result.AggregationResult, 

924 ) 

925 transaction: bytes = proto.Field( 

926 proto.BYTES, 

927 number=2, 

928 ) 

929 read_time: timestamp_pb2.Timestamp = proto.Field( 

930 proto.MESSAGE, 

931 number=3, 

932 message=timestamp_pb2.Timestamp, 

933 ) 

934 

935 

936class PartitionQueryRequest(proto.Message): 

937 r"""The request for 

938 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery]. 

939 

940 

941 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

942 

943 Attributes: 

944 parent (str): 

945 Required. The parent resource name. In the format: 

946 ``projects/{project_id}/databases/{database_id}/documents``. 

947 Document resource names are not supported; only database 

948 resource names can be specified. 

949 structured_query (google.cloud.firestore_v1.types.StructuredQuery): 

950 A structured query. 

951 Query must specify collection with all 

952 descendants and be ordered by name ascending. 

953 Other filters, order bys, limits, offsets, and 

954 start/end cursors are not supported. 

955 

956 This field is a member of `oneof`_ ``query_type``. 

957 partition_count (int): 

958 The desired maximum number of partition 

959 points. The partitions may be returned across 

960 multiple pages of results. The number must be 

961 positive. The actual number of partitions 

962 returned may be fewer. 

963 

964 For example, this may be set to one fewer than 

965 the number of parallel queries to be run, or in 

966 running a data pipeline job, one fewer than the 

967 number of workers or compute instances 

968 available. 

969 page_token (str): 

970 The ``next_page_token`` value returned from a previous call 

971 to PartitionQuery that may be used to get an additional set 

972 of results. There are no ordering guarantees between sets of 

973 results. Thus, using multiple sets of results will require 

974 merging the different result sets. 

975 

976 For example, two subsequent calls using a page_token may 

977 return: 

978 

979 - cursor B, cursor M, cursor Q 

980 - cursor A, cursor U, cursor W 

981 

982 To obtain a complete result set ordered with respect to the 

983 results of the query supplied to PartitionQuery, the results 

984 sets should be merged: cursor A, cursor B, cursor M, cursor 

985 Q, cursor U, cursor W 

986 page_size (int): 

987 The maximum number of partitions to return in this call, 

988 subject to ``partition_count``. 

989 

990 For example, if ``partition_count`` = 10 and ``page_size`` = 

991 8, the first call to PartitionQuery will return up to 8 

992 partitions and a ``next_page_token`` if more results exist. 

993 A second call to PartitionQuery will return up to 2 

994 partitions, to complete the total of 10 specified in 

995 ``partition_count``. 

996 read_time (google.protobuf.timestamp_pb2.Timestamp): 

997 Reads documents as they were at the given 

998 time. 

999 This must be a microsecond precision timestamp 

1000 within the past one hour, or if Point-in-Time 

1001 Recovery is enabled, can additionally be a whole 

1002 minute timestamp within the past 7 days. 

1003 

1004 This field is a member of `oneof`_ ``consistency_selector``. 

1005 """ 

1006 

1007 parent: str = proto.Field( 

1008 proto.STRING, 

1009 number=1, 

1010 ) 

1011 structured_query: gf_query.StructuredQuery = proto.Field( 

1012 proto.MESSAGE, 

1013 number=2, 

1014 oneof="query_type", 

1015 message=gf_query.StructuredQuery, 

1016 ) 

1017 partition_count: int = proto.Field( 

1018 proto.INT64, 

1019 number=3, 

1020 ) 

1021 page_token: str = proto.Field( 

1022 proto.STRING, 

1023 number=4, 

1024 ) 

1025 page_size: int = proto.Field( 

1026 proto.INT32, 

1027 number=5, 

1028 ) 

1029 read_time: timestamp_pb2.Timestamp = proto.Field( 

1030 proto.MESSAGE, 

1031 number=6, 

1032 oneof="consistency_selector", 

1033 message=timestamp_pb2.Timestamp, 

1034 ) 

1035 

1036 

1037class PartitionQueryResponse(proto.Message): 

1038 r"""The response for 

1039 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery]. 

1040 

1041 Attributes: 

1042 partitions (MutableSequence[google.cloud.firestore_v1.types.Cursor]): 

1043 Partition results. Each partition is a split point that can 

1044 be used by RunQuery as a starting or end point for the query 

1045 results. The RunQuery requests must be made with the same 

1046 query supplied to this PartitionQuery request. The partition 

1047 cursors will be ordered according to same ordering as the 

1048 results of the query supplied to PartitionQuery. 

1049 

1050 For example, if a PartitionQuery request returns partition 

1051 cursors A and B, running the following three queries will 

1052 return the entire result set of the original query: 

1053 

1054 - query, end_at A 

1055 - query, start_at A, end_at B 

1056 - query, start_at B 

1057 

1058 An empty result may indicate that the query has too few 

1059 results to be partitioned, or that the query is not yet 

1060 supported for partitioning. 

1061 next_page_token (str): 

1062 A page token that may be used to request an additional set 

1063 of results, up to the number specified by 

1064 ``partition_count`` in the PartitionQuery request. If blank, 

1065 there are no more results. 

1066 """ 

1067 

1068 @property 

1069 def raw_page(self): 

1070 return self 

1071 

1072 partitions: MutableSequence[gf_query.Cursor] = proto.RepeatedField( 

1073 proto.MESSAGE, 

1074 number=1, 

1075 message=gf_query.Cursor, 

1076 ) 

1077 next_page_token: str = proto.Field( 

1078 proto.STRING, 

1079 number=2, 

1080 ) 

1081 

1082 

1083class WriteRequest(proto.Message): 

1084 r"""The request for 

1085 [Firestore.Write][google.firestore.v1.Firestore.Write]. 

1086 

1087 The first request creates a stream, or resumes an existing one from 

1088 a token. 

1089 

1090 When creating a new stream, the server replies with a response 

1091 containing only an ID and a token, to use in the next request. 

1092 

1093 When resuming a stream, the server first streams any responses later 

1094 than the given token, then a response containing only an up-to-date 

1095 token, to use in the next request. 

1096 

1097 Attributes: 

1098 database (str): 

1099 Required. The database name. In the format: 

1100 ``projects/{project_id}/databases/{database_id}``. This is 

1101 only required in the first message. 

1102 stream_id (str): 

1103 The ID of the write stream to resume. 

1104 This may only be set in the first message. When 

1105 left empty, a new write stream will be created.