As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Bundles

Classes for representing bundles for the Google Cloud Firestore API.

class google.cloud.firestore_bundle.bundle.FirestoreBundle(name: str)

Bases: object

A group of serialized documents and queries, suitable for longterm storage or query resumption.

If any queries are added to this bundle, all associated documents will be loaded and stored in memory for serialization.

Usage:

from google.cloud.firestore import Client, _helpers
from google.cloud.firestore_bundle import FirestoreBundle

db = Client()
bundle = FirestoreBundle('my-bundle')
bundle.add_named_query('all-users', db.collection('users')._query())
bundle.add_named_query(
    'top-ten-hamburgers',
    db.collection('hamburgers').limit(limit=10),
)
serialized: str = bundle.build()

# Store somewhere like a Google Cloud Storage bucket for retrieval by
# a client SDK.

Parameters

name (str) – The Id of the bundle.

add_document(snapshot: google.cloud.firestore_v1.base_document.DocumentSnapshot) → google.cloud.firestore_bundle.bundle.FirestoreBundle

Adds a document to the bundle.

Parameters

snapshot (DocumentSnapshot) – The fully-loaded Firestore document to be preserved.

Example:

from google.cloud import firestore

db = firestore.Client()
collection_ref = db.collection(u'users')

bundle = firestore.FirestoreBundle('my bundle')
bundle.add_document(collection_ref.documents('some_id').get())

Returns

self

Return type

FirestoreBundle

add_named_query(name: str, query: google.cloud.firestore_v1.base_query.BaseQuery) → google.cloud.firestore_bundle.bundle.FirestoreBundle

Adds a query to the bundle, referenced by the provided name.

Parameters

• name (str) – The name by which the provided query should be referenced.

• query (Query) – Query of documents to be fully loaded and stored in the bundle for future access.

Example:

from google.cloud import firestore

db = firestore.Client()
collection_ref = db.collection(u'users')

bundle = firestore.FirestoreBundle('my bundle')
bundle.add_named_query('all the users', collection_ref._query())

Returns

self

Return type

FirestoreBundle

Raises

• ValueError – If anything other than a BaseQuery (e.g., a Collection) is supplied. If you have a Collection, call its _query() method to get what this method expects.

• ValueError – If the supplied name has already been added.

build() → str

Iterates over the bundle’s stored documents and queries and produces a single length-prefixed json string suitable for long-term storage.

Example:

from google.cloud import firestore

db = firestore.Client()
collection_ref = db.collection(u'users')

bundle = firestore.FirestoreBundle('my bundle')
bundle.add_named_query('app-users', collection_ref._query())

serialized_bundle: str = bundle.build()

# Now upload `serialized_bundle` to Google Cloud Storage, store it
# in Memorystore, or any other storage solution.

Returns

The length-prefixed string representation of this bundle’

contents.

Return type

str