Interface Firestore (3.21.0)

Version 3.21.0

• 3.21.3 (latest)
• 3.21.1
• 3.20.0
• 3.17.0
• 3.16.3
• 3.15.7
• 3.14.4
• 3.13.2
• 3.12.1
• 3.11.0
• 3.10.0
• 3.9.6
• 3.8.2
• 3.7.10
• 3.6.0
• 3.5.0
• 3.4.2
• 3.3.0
• 3.2.0
• 3.1.0
• 3.0.21

public interface Firestore extends Service<FirestoreOptions>, AutoCloseable

Represents a Firestore Database and is the entry point for all Firestore operations

Implements

com.google.cloud.Service<com.google.cloud.firestore.FirestoreOptions>, AutoCloseable

Methods

<T>runAsyncTransaction(Transaction.AsyncFunction<T> updateFunction)

public abstract ApiFuture<T> <T>runAsyncTransaction(Transaction.AsyncFunction<T> updateFunction)

Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the updateFunction will be retried. If it fails to commit after 5 attempts, the transaction will fail.

Running a transaction places locks all consumed documents. To unblock other clients, the Firestore backend automatically releases all locks after 60 seconds of inactivity and fails all transactions that last longer than 270 seconds (see Firestore Quotas).

Parameter
Name	Description
updateFunction	AsyncFunction<T> The function to execute within the transaction context.

Returns
Type	Description
ApiFuture<T>	An ApiFuture that will be resolved with the result from updateFunction.

<T>runAsyncTransaction(Transaction.AsyncFunction<T> updateFunction, TransactionOptions transactionOptions)

public abstract ApiFuture<T> <T>runAsyncTransaction(Transaction.AsyncFunction<T> updateFunction, TransactionOptions transactionOptions)

Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the updateFunction will be retried. If it fails to commit after the maxmimum number of attemps specified in transactionOptions, the transaction will fail.

Running a transaction places locks all consumed documents. To unblock other clients, the Firestore backend automatically releases all locks after 60 seconds of inactivity and fails all transactions that last longer than 270 seconds (see Firestore Quotas).

Parameters
Name	Description
updateFunction	AsyncFunction<T> The function to execute within the transaction context.
transactionOptions	TransactionOptions

Returns
Type	Description
ApiFuture<T>	An ApiFuture that will be resolved with the result from updateFunction.

<T>runTransaction(Transaction.Function<T> updateFunction)

public abstract ApiFuture<T> <T>runTransaction(Transaction.Function<T> updateFunction)

Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the updateFunction will be retried. If it fails to commit after 5 attempts, the transaction will fail.

Parameter
Name	Description
updateFunction	Function<T> The function to execute within the transaction context.

Returns
Type	Description
ApiFuture<T>	An ApiFuture that will be resolved with the result from updateFunction.

<T>runTransaction(Transaction.Function<T> updateFunction, TransactionOptions transactionOptions)

public abstract ApiFuture<T> <T>runTransaction(Transaction.Function<T> updateFunction, TransactionOptions transactionOptions)

Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the updateFunction will be retried. If it fails to commit after the maxmimum number of attemps specified in transactionOptions, the transaction will fail.

Parameters
Name	Description
updateFunction	Function<T> The function to execute within the transaction context.
transactionOptions	TransactionOptions

Returns
Type	Description
ApiFuture<T>	An ApiFuture that will be resolved with the result from updateFunction.

batch()

public abstract WriteBatch batch()

Gets a Firestore WriteBatch instance that can be used to combine multiple writes.

Returns
Type	Description
WriteBatch	A WriteBatch that operates on this Firestore client.

bulkWriter()

public abstract BulkWriter bulkWriter()

Creates a BulkWriter instance, used for performing multiple writes in parallel. Gradually ramps up writes as specified by the 500/50/5 rule. See Also: <a href=https://cloud.google.com/firestore/docs/best-practices#ramping_up_traffic>Ramping up traffic

Returns
Type	Description
BulkWriter

bulkWriter(BulkWriterOptions options)

public abstract BulkWriter bulkWriter(BulkWriterOptions options)

Creates a BulkWriter instance, used for performing multiple writes in parallel. Gradually ramps up writes as specified by the 500/50/5 rule unless otherwise configured by a BulkWriterOptions object. See Also: <a href=https://cloud.google.com/firestore/docs/best-practices#ramping_up_traffic>Ramping up traffic

Parameter
Name	Description
options	BulkWriterOptions An options object to configure BulkWriter.

Returns
Type	Description
BulkWriter

bundleBuilder()

public abstract FirestoreBundle.Builder bundleBuilder()

Returns a FirestoreBundle.Builder FirestoreBundle.Builder instance using an automatically generated bundle ID. When loaded on clients, client SDKs use the bundle ID and the timestamp associated with the built bundle to tell if it has been loaded already.

Returns
Type	Description
FirestoreBundle.Builder

bundleBuilder(String bundleId)

public abstract FirestoreBundle.Builder bundleBuilder(String bundleId)

Returns a FirestoreBundle.Builder FirestoreBundle.Builder instance for the given bundle ID.

Parameter
Name	Description
bundleId	String The ID of the bundle. When loaded on clients, client SDKs use this id and the timestamp associated with the built bundle to tell if it has been loaded already.

Returns
Type	Description
FirestoreBundle.Builder

close()

public abstract void close()

Closes the gRPC channels associated with this instance and frees up their resources. This method blocks until all channels are closed. Once this method is called, this Firestore client is no longer usable.

Exceptions
Type	Description
Exception

collection(String path)

public abstract CollectionReference collection(String path)

Gets a CollectionReference that refers to the collection at the specified path.

Parameter
Name	Description
path	String A slash-separated path to a collection.

Returns
Type	Description
CollectionReference	The CollectionReference instance.

collectionGroup(String collectionId)

public abstract CollectionGroup collectionGroup(String collectionId)

Creates and returns a new CollectionGroup that includes all documents in the database that are contained in a collection or subcollection with the given @code{collectionId}.

Parameter
Name	Description
collectionId	String 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
Type	Description
CollectionGroup	The created Query.

document(String path)

public abstract DocumentReference document(String path)

Gets a DocumentReference that refers to the document at the specified path.

Parameter
Name	Description
path	String A slash-separated path to a document.

Returns
Type	Description
DocumentReference	The DocumentReference instance.

getAll(DocumentReference[] documentReferences)

public abstract ApiFuture<List<DocumentSnapshot>> getAll(DocumentReference[] documentReferences)

Retrieves multiple documents from Firestore.

Parameter
Name	Description
documentReferences	DocumentReference[] List of Document References to fetch.

Returns
Type	Description
ApiFuture<List<DocumentSnapshot>>

getAll(DocumentReference[] documentReferences, FieldMask fieldMask)

public abstract ApiFuture<List<DocumentSnapshot>> getAll(DocumentReference[] documentReferences, FieldMask fieldMask)

Retrieves multiple documents from Firestore, while optionally applying a field mask to reduce the amount of data transmitted.

Parameters
Name	Description
documentReferences	DocumentReference[] Array with Document References to fetch.
fieldMask	FieldMask If set, specifies the subset of fields to return.

Returns
Type	Description
ApiFuture<List<DocumentSnapshot>>

getAll(DocumentReference[] documentReferences, FieldMask fieldMask, ApiStreamObserver<DocumentSnapshot> responseObserver)

public abstract void getAll(DocumentReference[] documentReferences, FieldMask fieldMask, ApiStreamObserver<DocumentSnapshot> responseObserver)

Retrieves multiple documents from Firestore while optionally applying a field mask to reduce the amount of data transmitted. Returned documents will be out of order.

Parameters
Name	Description
documentReferences	DocumentReference[] Array with Document References to fetch.
fieldMask	FieldMask If not null, specifies the subset of fields to return.
responseObserver	ApiStreamObserver<DocumentSnapshot> The observer to be notified when DocumentSnapshot details arrive.

listCollections()

public abstract Iterable<CollectionReference> listCollections()

Fetches the root collections that are associated with this Firestore database.

Returns
Type	Description
Iterable<CollectionReference>	An Iterable that can be used to fetch all collections.

recursiveDelete(CollectionReference reference)

public abstract ApiFuture<Void> recursiveDelete(CollectionReference reference)

Beta

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Recursively deletes all documents and subcollections at and under the specified level.

If any delete fails, the ApiFuture contains an error with an error message containing the number of failed deletes and the stack trace of the last failed delete. The provided reference is deleted regardless of whether all deletes succeeded.

recursiveDelete() uses a BulkWriter instance with default settings to perform the deletes. To customize throttling rates or add success/error callbacks, pass in a custom BulkWriter instance.

Parameter
Name	Description
reference	CollectionReference The reference of the collection to delete.

Returns
Type	Description
ApiFuture<Void>	An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

recursiveDelete(CollectionReference reference, BulkWriter bulkWriter)

public abstract ApiFuture<Void> recursiveDelete(CollectionReference reference, BulkWriter bulkWriter)

Beta

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Recursively deletes all documents and subcollections at and under the specified level.

If any delete fails, the ApiFuture contains an error with an error message containing the number of failed deletes and the stack trace of the last failed delete. The provided reference is deleted regardless of whether all deletes succeeded.

recursiveDelete() uses a BulkWriter instance with default settings to perform the deletes. To customize throttling rates or add success/error callbacks, pass in a custom BulkWriter instance.

Parameters
Name	Description
reference	CollectionReference The reference of the collection to delete.
bulkWriter	BulkWriter A custom BulkWriter instance used to perform the deletes.

Returns
Type	Description
ApiFuture<Void>	An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

recursiveDelete(DocumentReference reference)

public abstract ApiFuture<Void> recursiveDelete(DocumentReference reference)

Beta

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Recursively deletes all documents and subcollections at and under the specified level.

If any delete fails, the ApiFuture contains an error with an error message containing the number of failed deletes and the stack trace of the last failed delete. The provided reference is deleted regardless of whether all deletes succeeded.

recursiveDelete() uses a BulkWriter instance with default settings to perform the deletes. To customize throttling rates or add success/error callbacks, pass in a custom BulkWriter instance.

Parameter
Name	Description
reference	DocumentReference The reference of the document to delete.

Returns
Type	Description
ApiFuture<Void>	An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

recursiveDelete(DocumentReference reference, BulkWriter bulkWriter)

public abstract ApiFuture<Void> recursiveDelete(DocumentReference reference, BulkWriter bulkWriter)

Beta

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Recursively deletes all documents and subcollections at and under the specified level.

If any delete fails, the ApiFuture contains an error with an error message containing the number of failed deletes and the stack trace of the last failed delete. The provided reference is deleted regardless of whether all deletes succeeded.

recursiveDelete() uses a BulkWriter instance with default settings to perform the deletes. To customize throttling rates or add success/error callbacks, pass in a custom BulkWriter instance.

Parameters
Name	Description
reference	DocumentReference The reference of the document to delete.
bulkWriter	BulkWriter A custom BulkWriter instance used to perform the deletes.

Returns
Type	Description
ApiFuture<Void>	An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

shutdown()

public abstract void shutdown()

Initiates an orderly shutdown in which previously submitted work is finished, but no new work will be accepted.

shutdownNow()

public abstract void shutdownNow()

Attempts to stop all actively executing work and halts the processing of waiting work.