Collections#
Classes for representing collections for the Google Cloud Firestore API.
-
class
google.cloud.firestore_v1.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 aClient
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 inpath
is not a string * a document ID inpath
is not a stringTypeError – 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/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
-
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
-
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
-
limit
(count)[source]# Create a limited query with this collection as parent.
See
limit()
for more information on this method.
-
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.
-
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 (Callable[[
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):
- 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
, seeorder_by()
for more information.
- Returns
An “order by” query.
- Return type
-
property
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.
-
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
-
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
-
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 ofRunQueryResponse
messages.Note
The underlying stream of responses will time out after the
max_rpc_timeout_millis
value set in the GAPIC client configuration for theRunQuery
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
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
isNone
or a NaN, then==
is the only allowed operation.
- Returns
A filtered query.
- Return type