def on_snapshot(self, callback): """Monitor the documents in this collection. This starts a watch on this collection using a background thread. The provided callback is run on the snapshot of the documents. Args: callback (Callable[[:class:`~google.cloud.firestore.collection.CollectionSnapshot`], NoneType]): a callback to run when a change occurs. Example: from google.cloud import firestore_v1 db = firestore_v1.Client() collection_ref = db.collection(u'users') def on_snapshot(collection_snapshot, changes, read_time): for doc in collection_snapshot.documents: print(u'{} => {}'.format(doc.id, doc.to_dict())) # Watch this collection collection_watch = collection_ref.on_snapshot(on_snapshot) # Terminate this watch collection_watch.unsubscribe() """ return Watch.for_query( query_mod.Query(self), callback, document.DocumentSnapshot, document.DocumentReference, )
def _query(self) -> query_mod.Query: """Query factory. Returns: :class:`~google.cloud.firestore_v1.query.Query` """ return query_mod.Query(self)
def stream(self, transaction=None): """Read the documents in this collection. 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 the query will run in. Yields: :class:`~google.cloud.firestore_v1.document.DocumentSnapshot`: The next document that fulfills the query. """ query = query_mod.Query(self) return query.stream(transaction=transaction)
def offset(self, num_to_skip): """Skip to an offset in a query with this collection as parent. See :meth:`~.firestore_v1.query.Query.offset` for more information on this method. Args: num_to_skip (int): The number of results to skip at the beginning of query results. (Must be non-negative.) Returns: ~.firestore_v1.query.Query: An offset query. """ query = query_mod.Query(self) return query.offset(num_to_skip)
def limit(self, count): """Create a limited query with this collection as parent. See :meth:`~.firestore_v1.query.Query.limit` for more information on this method. Args: count (int): Maximum number of documents to return that match the query. Returns: ~.firestore_v1.query.Query: A limited query. """ query = query_mod.Query(self) return query.limit(count)
def select(self, field_paths): """Create a "select" query with this collection as parent. See :meth:`~.firestore_v1.query.Query.select` for more information on this method. Args: field_paths (Iterable[str, ...]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the query results. Returns: ~.firestore_v1.query.Query: A "projected" query. """ query = query_mod.Query(self) return query.select(field_paths)
def end_at(self, document_fields): """End query at a cursor with this collection as parent. See :meth:`~.firestore_v1.query.Query.end_at` for more information on this method. Args: document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: ~.firestore_v1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.end_at(document_fields)
def end_before(self, document_fields): """End query before a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.end_before` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1.\ document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. """ query = query_mod.Query(self) return query.end_before(document_fields)
def order_by(self, field_path, **kwargs): """Create an "order by" query with this collection as parent. See :meth:`~.firestore_v1.query.Query.order_by` for more information on this method. Args: field_path (str): A field path (``.``-delimited list of field names) on which to order the query results. kwargs (Dict[str, Any]): The keyword arguments to pass along to the query. The only supported keyword is ``direction``, see :meth:`~.firestore_v1.query.Query.order_by` for more information. Returns: ~.firestore_v1.query.Query: An "order by" query. """ query = query_mod.Query(self) return query.order_by(field_path, **kwargs)
def get(self, transaction=None) -> list: """Read the documents in this collection. This sends a ``RunQuery`` RPC and returns a list of documents returned in the stream of ``RunQueryResponse`` messages. Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that this query will run in. 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). Returns: list: The documents in this collection that match the query. """ query = query_mod.Query(self) return query.get(transaction=transaction)
def collection_group(self, collection_id): """ Creates and returns a new Query that includes all documents in the database that are contained in a collection or subcollection with the given collection_id. .. code-block:: python >>> query = firestore.collection_group('mygroup') @param {string} collectionId Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. @returns {Query} The created Query. """ if "/" in collection_id: raise ValueError("Invalid collection_id " + collection_id + ". Collection IDs must not contain '/'.") collection = self.collection(collection_id) return query.Query(collection, all_descendants=True)
def where(self, field_path, op_string, value): """Create a "where" query with this collection as parent. See :meth:`~.firestore_v1.query.Query.where` for more information on this method. Args: field_path (str): A field path (``.``-delimited list of field names) for the field to filter on. op_string (str): A comparison operation in the form of a string. Acceptable values are ``<``, ``<=``, ``==``, ``>=`` and ``>``. value (Any): The value to compare the field against in the filter. If ``value`` is :data:`None` or a NaN, then ``==`` is the only allowed operation. Returns: ~.firestore_v1.query.Query: A filtered query. """ query = query_mod.Query(self) return query.where(field_path, op_string, value)
def limit_to_last(self, count): """Create a limited to last query with this collection as parent. .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit_to_last` will drop previously set `limit`. See :meth:`~google.cloud.firestore_v1.query.Query.limit_to_last` for more information on this method. Args: count (int): Maximum number of documents to return that match the query. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A limited to last query. """ query = query_mod.Query(self) return query.limit_to_last(count)