Collections#

Classes for representing collections for the Google Cloud Firestore API.

class google.cloud.firestore_v1beta1.collection.CollectionReference(*path, **kwargs)[source]#

Bases: object

A reference to a collection in a Firestore database.

The collection may already exist or this class can facilitate creation of documents within the collection.

Parameters:
  • path (Tuple[str, ..]) – The components in the collection path. This is a series of strings representing each collection and sub-collection ID, as well as the document IDs for any documents that contain a sub-collection.
  • kwargs (dict) – The keyword arguments for the constructor. The only supported keyword is client and it must be a Client if provided. It represents the client that created this collection reference.
Raises:
  • ValueError – if
    • the path is empty
    • there are an even number of elements
    • a collection ID in path is not a string
    • a document ID in path is not a string
  • TypeError – If a keyword other than client is used.
add(document_data, document_id=None)[source]#

Create a document in the Firestore database with the provided data.

Parameters:
  • document_data (dict) – Property names and values to use for creating the document.
  • document_id (Optional[str]) – The document identifier within the current collection. If not provided, an ID will be automatically assigned by the server (the assigned ID will be a random 20 character string composed of digits, uppercase and lowercase letters).
Returns:

Pair of

  • The update_time when the document was created (or overwritten).
  • A document reference for the created document.

Return type:

Tuple[google.protobuf.timestamp_pb2.Timestamp, DocumentReference]

Raises:

Conflict – If document_id is provided and the document already exists.

document(document_id=None)[source]#

Create a sub-document underneath the current collection.

Parameters:document_id (Optional[str]) – The document identifier within the current collection. If not provided, will default to a random 20 character string composed of digits, uppercase and lowercase and letters.
Returns:The child document.
Return type:DocumentReference
end_at(document_fields)[source]#

End query at a cursor with this collection as parent.

See end_at() for more information on this method.

Parameters:document_fields (Union[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:A query with cursor.
Return type:Query
end_before(document_fields)[source]#

End query before a cursor with this collection as parent.

See end_before() for more information on this method.

Parameters:document_fields (Union[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:A query with cursor.
Return type:Query
get(transaction=None)[source]#

Deprecated alias for stream().

id#

The collection identifier.

Returns:The last component of the path.
Return type:str
limit(count)[source]#

Create a limited query with this collection as parent.

See limit() for more information on this method.

Parameters:count (int) – Maximum number of documents to return that match the query.
Returns:A limited query.
Return type:Query
list_documents(page_size=None)[source]#

List all subdocuments of the current collection.

Parameters:
  • page_size (Optional[int]]) – The maximum number of documents
  • each page of results from this request. Non-positive values (in) –
  • ignored. Defaults to a sensible value set by the API. (are) –
Returns:

iterator of subdocuments of the current collection. If the collection does not exist at the time of snapshot, the iterator will be empty

Return type:

Sequence[DocumentReference]

offset(num_to_skip)[source]#

Skip to an offset in a query with this collection as parent.

See offset() for more information on this method.

Parameters:num_to_skip (int) – The number of results to skip at the beginning of query results. (Must be non-negative.)
Returns:An offset query.
Return type:Query
on_snapshot(callback)[source]#

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.

Parameters:callback (CollectionSnapshot) – a callback to run when a change occurs.

Example

from google.cloud import firestore_v1beta1

db = firestore_v1beta1.Client() collection_ref = db.collection(u’users’)

def on_snapshot(collection_snapshot):
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()

order_by(field_path, **kwargs)[source]#

Create an “order by” query with this collection as parent.

See order_by() for more information on this method.

Parameters:
  • 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 order_by() for more information.
Returns:

An “order by” query.

Return type:

Query

parent#

Document that owns the current collection.

Returns:The parent document, if the current collection is not a top-level collection.
Return type:Optional[DocumentReference]
select(field_paths)[source]#

Create a “select” query with this collection as parent.

See select() for more information on this method.

Parameters: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:A “projected” query.
Return type:Query
start_after(document_fields)[source]#

Start query after a cursor with this collection as parent.

See start_after() for more information on this method.

Parameters:document_fields (Union[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:A query with cursor.
Return type:Query
start_at(document_fields)[source]#

Start query at a cursor with this collection as parent.

See start_at() for more information on this method.

Parameters:document_fields (Union[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:A query with cursor.
Return type:Query
stream(transaction=None)[source]#

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).

Parameters:transaction (Optional[ Transaction]) – An existing transaction that the query will run in.
Yields:~.firestore_v1beta1.document.DocumentSnapshot – The next document that fulfills the query.
where(field_path, op_string, value)[source]#

Create a “where” query with this collection as parent.

See where() for more information on this method.

Parameters:
  • 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 None or a NaN, then == is the only allowed operation.
Returns:

A filtered query.

Return type:

Query