com.google.cloud.firestore

Interface Firestore

All Superinterfaces:

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

@InternalExtensionOnly
public interface Firestore
extends com.google.cloud.Service<FirestoreOptions>, AutoCloseable

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

Method Summary

Modifier and Type	Method and Description
WriteBatch	batch() Gets a Firestore WriteBatch instance that can be used to combine multiple writes.
BulkWriter	bulkWriter() Creates a BulkWriter instance, used for performing multiple writes in parallel.
BulkWriter	bulkWriter(BulkWriterOptions options) Creates a BulkWriter instance, used for performing multiple writes in parallel.
FirestoreBundle.Builder	bundleBuilder() Returns a FirestoreBundle.Builder FirestoreBundle.Builder instance using an automatically generated bundle ID.
FirestoreBundle.Builder	bundleBuilder(String bundleId) Returns a FirestoreBundle.Builder FirestoreBundle.Builder instance for the given bundle ID.
void	close() Closes the gRPC channels associated with this instance and frees up their resources.
CollectionReference	collection(String path) Gets a CollectionReference that refers to the collection at the specified path.
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}.
DocumentReference	document(String path) Gets a DocumentReference that refers to the document at the specified path.
com.google.api.core.ApiFuture<List<DocumentSnapshot>>	getAll(DocumentReference... documentReferences) Retrieves multiple documents from Firestore.
com.google.api.core.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.
void	getAll(DocumentReference[] documentReferences, FieldMask fieldMask, com.google.api.gax.rpc.ApiStreamObserver<DocumentSnapshot> responseObserver) Retrieves multiple documents from Firestore while optionally applying a field mask to reduce the amount of data transmitted.
Iterable<CollectionReference>	listCollections() Fetches the root collections that are associated with this Firestore database.
com.google.api.core.ApiFuture<Void>	recursiveDelete(CollectionReference reference) Recursively deletes all documents and subcollections at and under the specified level.
com.google.api.core.ApiFuture<Void>	recursiveDelete(CollectionReference reference, BulkWriter bulkWriter) Recursively deletes all documents and subcollections at and under the specified level.
com.google.api.core.ApiFuture<Void>	recursiveDelete(DocumentReference reference) Recursively deletes all documents and subcollections at and under the specified level.
com.google.api.core.ApiFuture<Void>	recursiveDelete(DocumentReference reference, BulkWriter bulkWriter) Recursively deletes all documents and subcollections at and under the specified level.
<T> com.google.api.core.ApiFuture<T>	runAsyncTransaction(Transaction.AsyncFunction<T> updateFunction) Executes the given updateFunction and then attempts to commit the changes applied within the transaction.
<T> com.google.api.core.ApiFuture<T>	runAsyncTransaction(Transaction.AsyncFunction<T> updateFunction, TransactionOptions transactionOptions) Executes the given updateFunction and then attempts to commit the changes applied within the transaction.
<T> com.google.api.core.ApiFuture<T>	runTransaction(Transaction.Function<T> updateFunction) Executes the given updateFunction and then attempts to commit the changes applied within the transaction.
<T> com.google.api.core.ApiFuture<T>	runTransaction(Transaction.Function<T> updateFunction, TransactionOptions transactionOptions) Executes the given updateFunction and then attempts to commit the changes applied within the transaction.
void	shutdown() Initiates an orderly shutdown in which previously submitted work is finished, but no new work will be accepted.
void	shutdownNow() Attempts to stop all actively executing work and halts the processing of waiting work.

Methods inherited from interface com.google.cloud.Service

getOptions

Method Detail

collection

@Nonnull
CollectionReference collection(@Nonnull
                                        String path)

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

Parameters:

path - A slash-separated path to a collection.

Returns:

The CollectionReference instance.

document

@Nonnull
DocumentReference document(@Nonnull
                                    String path)

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

Parameters:

path - A slash-separated path to a document.

Returns:

The DocumentReference instance.

listCollections

@Nonnull
Iterable<CollectionReference> listCollections()

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

Returns:

An Iterable that can be used to fetch all collections.

Throws:

FirestoreException - if the Iterable could not be initialized.

collectionGroup

CollectionGroup collectionGroup(@Nonnull
                                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}.

Parameters:

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:

The created Query.

runTransaction

@Nonnull
<T> com.google.api.core.ApiFuture<T> runTransaction(@Nonnull
                                                             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.

Parameters:

updateFunction - The function to execute within the transaction context.

Returns:

An ApiFuture that will be resolved with the result from updateFunction.

runTransaction

@Nonnull
<T> com.google.api.core.ApiFuture<T> runTransaction(@Nonnull
                                                             Transaction.Function<T> updateFunction,
                                                             @Nonnull
                                                             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:

updateFunction - The function to execute within the transaction context.

Returns:

An ApiFuture that will be resolved with the result from updateFunction.

runAsyncTransaction

@Nonnull
<T> com.google.api.core.ApiFuture<T> runAsyncTransaction(@Nonnull
                                                                  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).

Parameters:

updateFunction - The function to execute within the transaction context.

Returns:

An ApiFuture that will be resolved with the result from updateFunction.

runAsyncTransaction

@Nonnull
<T> com.google.api.core.ApiFuture<T> runAsyncTransaction(@Nonnull
                                                                  Transaction.AsyncFunction<T> updateFunction,
                                                                  @Nonnull
                                                                  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:

updateFunction - The function to execute within the transaction context.

Returns:

An ApiFuture that will be resolved with the result from updateFunction.

getAll

@Nonnull
com.google.api.core.ApiFuture<List<DocumentSnapshot>> getAll(@Nonnull
                                                                      DocumentReference... documentReferences)

Retrieves multiple documents from Firestore.

Parameters:

documentReferences - List of Document References to fetch.

getAll

@Nonnull
com.google.api.core.ApiFuture<List<DocumentSnapshot>> getAll(@Nonnull
                                                                      DocumentReference[] documentReferences,
                                                                      @Nullable
                                                                      FieldMask fieldMask)

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

Parameters:

documentReferences - Array with Document References to fetch.

fieldMask - If set, specifies the subset of fields to return.

getAll

void getAll(@Nonnull
            DocumentReference[] documentReferences,
            @Nullable
            FieldMask fieldMask,
            com.google.api.gax.rpc.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:

documentReferences - Array with Document References to fetch.

fieldMask - If not null, specifies the subset of fields to return.

responseObserver - The observer to be notified when DocumentSnapshot details arrive.

batch

@Nonnull
WriteBatch batch()

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

Returns:

A WriteBatch that operates on this Firestore client.

bulkWriter

@BetaApi
 @Nonnull
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:

Ramping up traffic

bulkWriter

@BetaApi
 @Nonnull
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.

Parameters:

options - An options object to configure BulkWriter.

See Also:

Ramping up traffic

recursiveDelete

@BetaApi
 @Nonnull
com.google.api.core.ApiFuture<Void> recursiveDelete(CollectionReference reference)

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:

reference - The reference of the collection to delete.

Returns:

An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

recursiveDelete

@BetaApi
 @Nonnull
com.google.api.core.ApiFuture<Void> recursiveDelete(CollectionReference reference,
                                                                       BulkWriter bulkWriter)

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:

reference - The reference of the collection to delete.

bulkWriter - A custom BulkWriter instance used to perform the deletes.

Returns:

An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

recursiveDelete

@BetaApi
 @Nonnull
com.google.api.core.ApiFuture<Void> recursiveDelete(DocumentReference reference)

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:

reference - The reference of the document to delete.

Returns:

An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

recursiveDelete

@BetaApi
 @Nonnull
com.google.api.core.ApiFuture<Void> recursiveDelete(DocumentReference reference,
                                                                       BulkWriter bulkWriter)

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:

reference - The reference of the document to delete.

bulkWriter - A custom BulkWriter instance used to perform the deletes.

Returns:

An ApiFuture that completes when all deletes have been performed. The future fails with an error if any of the deletes fail.

bundleBuilder

@Nonnull
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.

bundleBuilder

@Nonnull
FirestoreBundle.Builder bundleBuilder(@Nonnull
                                               String bundleId)

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

Parameters:

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

close

void close()
    throws Exception

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.

Specified by:

close in interface AutoCloseable

Throws:

Exception

shutdown

void shutdown()

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

shutdownNow

void shutdownNow()

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