def _prep_batch_get( self, field_paths: Iterable[str] = None, transaction=None, retry: retries.Retry = None, timeout: float = None, ) -> Tuple[dict, dict]: """Shared setup for async/sync :meth:`get`.""" if isinstance(field_paths, str): raise ValueError( "'field_paths' must be a sequence of paths, not a string.") if field_paths is not None: mask = common.DocumentMask(field_paths=sorted(field_paths)) else: mask = None request = { "database": self._client._database_string, "documents": [self._document_path], "mask": mask, "transaction": _helpers.get_transaction_id(transaction), } kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout) return request, kwargs
async def stream( self, transaction=None ) -> AsyncGenerator[async_document.DocumentSnapshot, None]: """Read the documents in the collection that match this query. This sends a ``RunQuery`` RPC and then returns an iterator which consumes each document returned in the stream of ``RunQueryResponse`` messages. .. note:: The underlying stream of responses will time out after the ``max_rpc_timeout_millis`` value set in the GAPIC client configuration for the ``RunQuery`` API. Snapshots not consumed from the iterator before that point will be lost. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that this query will run in. Yields: :class:`~google.cloud.firestore_v1.async_document.DocumentSnapshot`: The next document that fulfills the query. """ if self._limit_to_last: raise ValueError( "Query results for queries that include limit_to_last() " "constraints cannot be streamed. Use Query.get() instead." ) parent_path, expected_prefix = self._parent._parent_info() response_iterator = await self._client._firestore_api.run_query( request={ "parent": parent_path, "structured_query": self._to_protobuf(), "transaction": _helpers.get_transaction_id(transaction), }, metadata=self._client._rpc_metadata, ) async for response in response_iterator: if self._all_descendants: snapshot = _collection_group_query_response_to_snapshot( response, self._parent ) else: snapshot = _query_response_to_snapshot( response, self._parent, expected_prefix ) if snapshot is not None: yield snapshot
async def get_all( self, references: list, field_paths: Iterable[str] = None, transaction=None, ) -> AsyncGenerator[DocumentSnapshot, Any]: """Retrieve a batch of documents. .. note:: Documents returned by this method are not guaranteed to be returned in the same order that they are given in ``references``. .. note:: If multiple ``references`` refer to the same document, the server will only return one result. See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: references (List[.AsyncDocumentReference, ...]): Iterable of document references to be retrieved. field_paths (Optional[Iterable[str, ...]]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. transaction (Optional[:class:`~google.cloud.firestore_v1.async_transaction.AsyncTransaction`]): An existing transaction that these ``references`` will be retrieved in. Yields: .DocumentSnapshot: The next document snapshot that fulfills the query, or :data:`None` if the document does not exist. """ document_paths, reference_map = _reference_info(references) mask = _get_doc_mask(field_paths) response_iterator = await self._firestore_api.batch_get_documents( request={ "database": self._database_string, "documents": document_paths, "mask": mask, "transaction": _helpers.get_transaction_id(transaction), }, metadata=self._rpc_metadata, ) async for get_doc_response in response_iterator: yield _parse_batch_get(get_doc_response, reference_map, self)
def get_all(self, references, field_paths=None, transaction=None): """Retrieve a batch of documents. .. note:: Documents returned by this method are not guaranteed to be returned in the same order that they are given in ``references``. .. note:: If multiple ``references`` refer to the same document, the server will only return one result. See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: references (List[.DocumentReference, ...]): Iterable of document references to be retrieved. field_paths (Optional[Iterable[str, ...]]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. transaction (Optional[~.firestore_v1.transaction.\ Transaction]): An existing transaction that these ``references`` will be retrieved in. Yields: .DocumentSnapshot: The next document snapshot that fulfills the query, or :data:`None` if the document does not exist. """ document_paths, reference_map = _reference_info(references) mask = _get_doc_mask(field_paths) response_iterator = self._firestore_api.batch_get_documents( self._database_string, document_paths, mask, transaction=_helpers.get_transaction_id(transaction), metadata=self._rpc_metadata, ) for get_doc_response in response_iterator: yield _parse_batch_get(get_doc_response, reference_map, self)
def stream(self, transaction=None): """Read the documents in the collection that match this query. This sends a ``RunQuery`` RPC and then returns an iterator which consumes each document returned in the stream of ``RunQueryResponse`` messages. .. note:: The underlying stream of responses will time out after the ``max_rpc_timeout_millis`` value set in the GAPIC client configuration for the ``RunQuery`` API. Snapshots not consumed from the iterator before that point will be lost. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that this query will run in. Yields: :class:`~google.cloud.firestore_v1.document.DocumentSnapshot`: The next document that fulfills the query. """ parent_path, expected_prefix = self._parent._parent_info() response_iterator = self._client._firestore_api.run_query( parent_path, self._to_protobuf(), transaction=_helpers.get_transaction_id(transaction), metadata=self._client._rpc_metadata, ) for response in response_iterator: if self._all_descendants: snapshot = _collection_group_query_response_to_snapshot( response, self._parent ) else: snapshot = _query_response_to_snapshot( response, self._parent, expected_prefix ) if snapshot is not None: yield snapshot
def _prep_stream( self, transaction=None, retry: retries.Retry = None, timeout: float = None, ) -> Tuple[dict, str, dict]: """Shared setup for async / sync :meth:`stream`""" if self._limit_to_last: raise ValueError( "Query results for queries that include limit_to_last() " "constraints cannot be streamed. Use Query.get() instead." ) parent_path, expected_prefix = self._parent._parent_info() request = { "parent": parent_path, "structured_query": self._to_protobuf(), "transaction": _helpers.get_transaction_id(transaction), } kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout) return request, expected_prefix, kwargs
def _prep_get_all( self, references: list, field_paths: Iterable[str] = None, transaction: BaseTransaction = None, retry: retries.Retry = None, timeout: float = None, ) -> Tuple[dict, dict, dict]: """Shared setup for async/sync :meth:`get_all`.""" document_paths, reference_map = _reference_info(references) mask = _get_doc_mask(field_paths) request = { "database": self._database_string, "documents": document_paths, "mask": mask, "transaction": _helpers.get_transaction_id(transaction), } kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout) return request, reference_map, kwargs
def get(self, field_paths=None, transaction=None): """Retrieve a snapshot of the current document. See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: field_paths (Optional[Iterable[str, ...]]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that this reference will be retrieved in. Returns: :class:`~google.cloud.firestore_v1.document.DocumentSnapshot`: A snapshot of the current document. If the document does not exist at the time of the snapshot is taken, the snapshot's :attr:`reference`, :attr:`data`, :attr:`update_time`, and :attr:`create_time` attributes will all be ``None`` and its :attr:`exists` attribute will be ``False``. """ if isinstance(field_paths, six.string_types): raise ValueError("'field_paths' must be a sequence of paths, not a string.") if field_paths is not None: mask = common_pb2.DocumentMask(field_paths=sorted(field_paths)) else: mask = None firestore_api = self._client._firestore_api try: document_pb = firestore_api.get_document( self._document_path, mask=mask, transaction=_helpers.get_transaction_id(transaction), metadata=self._client._rpc_metadata, ) except exceptions.NotFound: data = None exists = False create_time = None update_time = None else: data = _helpers.decode_dict(document_pb.fields, self._client) exists = True create_time = document_pb.create_time update_time = document_pb.update_time return DocumentSnapshot( reference=self, data=data, exists=exists, read_time=None, # No server read_time available create_time=create_time, update_time=update_time, )
def get(self, field_paths=None, transaction=None) -> DocumentSnapshot: """Retrieve a snapshot of the current document. See :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: field_paths (Optional[Iterable[str, ...]]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that this reference will be retrieved in. Returns: :class:`~google.cloud.firestore_v1.base_document.DocumentSnapshot`: A snapshot of the current document. If the document does not exist at the time of the snapshot is taken, the snapshot's :attr:`reference`, :attr:`data`, :attr:`update_time`, and :attr:`create_time` attributes will all be ``None`` and its :attr:`exists` attribute will be ``False``. """ if isinstance(field_paths, str): raise ValueError("'field_paths' must be a sequence of paths, not a string.") if field_paths is not None: mask = common.DocumentMask(field_paths=sorted(field_paths)) else: mask = None firestore_api = self._client._firestore_api try: document_pb = firestore_api.get_document( request={ "name": self._document_path, "mask": mask, "transaction": _helpers.get_transaction_id(transaction), }, metadata=self._client._rpc_metadata, ) except exceptions.NotFound: data = None exists = False create_time = None update_time = None else: data = _helpers.decode_dict(document_pb.fields, self._client) exists = True create_time = document_pb.create_time update_time = document_pb.update_time return DocumentSnapshot( reference=self, data=data, exists=exists, read_time=None, # No server read_time available create_time=create_time, update_time=update_time, )