com.google.cloud.firestore

Class BulkWriter

java.lang.Object

com.google.cloud.firestore.BulkWriter

All Implemented Interfaces:

AutoCloseable

@BetaApi
public final class BulkWriter
extends Object
implements AutoCloseable

A Firestore BulkWriter that can be used to perform a large number of writes in parallel.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BulkWriter.WriteErrorCallback A callback set by `addWriteErrorListener()` to be run every time an operation fails and determines if an operation should be retried.
static interface	BulkWriter.WriteResultCallback A callback set by `addWriteResultListener()` to be run every time an operation successfully completes.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_BATCH_SIZE The maximum number of writes that can be in a single batch.
static int	MAX_RETRY_ATTEMPTS The maximum number of retries that will be attempted with backoff before stopping all retry attempts.
static int	RETRY_MAX_BATCH_SIZE The maximum number of writes that can be in a batch containing retries.

Method Summary

Modifier and Type	Method and Description
void	addWriteErrorListener(BulkWriter.WriteErrorCallback onError) Attaches an error handler listener that is run every time a BulkWriter operation fails.
void	addWriteErrorListener(Executor executor, BulkWriter.WriteErrorCallback onError) Attaches an error handler listener that is run every time a BulkWriter operation fails.
void	addWriteResultListener(BulkWriter.WriteResultCallback writeResultCallback) Attaches a listener that is run every time a BulkWriter operation successfully completes.
void	addWriteResultListener(Executor executor, BulkWriter.WriteResultCallback writeResultCallback) Attaches a listener that is run every time a BulkWriter operation successfully completes.
void	close() Commits all enqueued writes and marks the BulkWriter instance as closed.
com.google.api.core.ApiFuture<WriteResult>	create(DocumentReference documentReference, Map<String,Object> fields) Create a document with the provided data.
com.google.api.core.ApiFuture<WriteResult>	create(DocumentReference documentReference, Object pojo) Create a document with the provided data.
com.google.api.core.ApiFuture<WriteResult>	delete(DocumentReference documentReference) Delete a document from the database.
com.google.api.core.ApiFuture<WriteResult>	delete(DocumentReference documentReference, Precondition precondition) Delete a document from the database.
com.google.api.core.ApiFuture<Void>	flush() Commits all writes that have been enqueued up to this point in parallel.
com.google.api.core.ApiFuture<WriteResult>	set(DocumentReference documentReference, Map<String,Object> fields) Write to the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	set(DocumentReference documentReference, Map<String,Object> fields, SetOptions options) Write to the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	set(DocumentReference documentReference, Object pojo) Write to the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	set(DocumentReference documentReference, Object pojo, SetOptions options) Write to the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	update(DocumentReference documentReference, FieldPath fieldPath, Object value, Object... moreFieldsAndValues) Update fields of the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	update(DocumentReference documentReference, Map<String,Object> fields) Update fields of the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	update(DocumentReference documentReference, Map<String,Object> fields, Precondition precondition) Update fields of the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	update(DocumentReference documentReference, Precondition precondition, FieldPath fieldPath, Object value, Object... moreFieldsAndValues) Update fields of the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	update(DocumentReference documentReference, Precondition precondition, String field, Object value, Object... moreFieldsAndValues) Update fields of the document referred to by the provided DocumentReference.
com.google.api.core.ApiFuture<WriteResult>	update(DocumentReference documentReference, String field, Object value, Object... moreFieldsAndValues) Update fields of the document referred to by the provided DocumentReference.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_BATCH_SIZE

public static final int MAX_BATCH_SIZE

The maximum number of writes that can be in a single batch.

See Also:

Constant Field Values

RETRY_MAX_BATCH_SIZE

public static final int RETRY_MAX_BATCH_SIZE

The maximum number of writes that can be in a batch containing retries.

See Also:

Constant Field Values

MAX_RETRY_ATTEMPTS

public static final int MAX_RETRY_ATTEMPTS

The maximum number of retries that will be attempted with backoff before stopping all retry attempts.

See Also:

Constant Field Values

Method Detail

create

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> create(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Map<String,Object> fields)

Create a document with the provided data. This single operation will fail if a document exists at its location.

Parameters:

documentReference - A reference to the document to be created.

fields - A map of the fields and values for the document.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

create

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> create(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Object pojo)

Create a document with the provided data. This single operation will fail if a document exists at its location.

Parameters:

documentReference - A reference to the document to be created.

pojo - The POJO that will be used to populate the document contents.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

delete

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> delete(@Nonnull
                                                                  DocumentReference documentReference)

Delete a document from the database.

Parameters:

documentReference - The DocumentReference to delete.

Returns:

An ApiFuture containing a sentinel value (Timestamp(0)) for the delete operation. Contains a BulkWriterException if the delete fails.

delete

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> delete(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Precondition precondition)

Delete a document from the database.

Parameters:

documentReference - The DocumentReference to delete.

precondition - Precondition to enforce for this delete.

Returns:

An ApiFuture containing a sentinel value (Timestamp(0)) for the delete operation. Contains a BulkWriterException if the delete fails.

set

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull
                                                               DocumentReference documentReference,
                                                               @Nonnull
                                                               Map<String,Object> fields)

Write to the document referred to by the provided DocumentReference. If the document does not exist yet, it will be created.

Parameters:

documentReference - A reference to the document to be set.

fields - A map of the fields and values for the document.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

set

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull
                                                               DocumentReference documentReference,
                                                               @Nonnull
                                                               Map<String,Object> fields,
                                                               @Nonnull
                                                               SetOptions options)

Write to the document referred to by the provided DocumentReference. If the document does not exist yet, it will be created. If you pass a SetOptions, the provided data can be merged into an existing document.

Parameters:

documentReference - A reference to the document to be set.

fields - A map of the fields and values for the document.

options - An object to configure the set behavior.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

set

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull
                                                               DocumentReference documentReference,
                                                               @Nonnull
                                                               Object pojo,
                                                               @Nonnull
                                                               SetOptions options)

Write to the document referred to by the provided DocumentReference. If the document does not exist yet, it will be created. If you pass a SetOptions, the provided data can be merged into an existing document.

Parameters:

documentReference - A reference to the document to be set.

pojo - The POJO that will be used to populate the document contents.

options - An object to configure the set behavior.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

set

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull
                                                               DocumentReference documentReference,
                                                               @Nonnull
                                                               Object pojo)

Write to the document referred to by the provided DocumentReference. If the document does not exist yet, it will be created.

Parameters:

documentReference - A reference to the document to be set.

pojo - The POJO that will be used to populate the document contents.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

update

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Map<String,Object> fields)

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update will fail.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

Parameters:

documentReference - A reference to the document to be updated.

fields - A map of the fields and values for the document.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

update

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Map<String,Object> fields,
                                                                  @Nonnull
                                                                  Precondition precondition)

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update will fail.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

Parameters:

documentReference - A reference to the document to be updated.

fields - A map of the fields and values for the document.

precondition - Precondition to enforce on this update.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

update

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  String field,
                                                                  @Nullable
                                                                  Object value,
                                                                  Object... moreFieldsAndValues)

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update will fail.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

Parameters:

documentReference - A reference to the document to be updated.

field - The first field to set.

value - The first value to set.

moreFieldsAndValues - String and Object pairs with more fields to be set.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

update

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  FieldPath fieldPath,
                                                                  @Nullable
                                                                  Object value,
                                                                  Object... moreFieldsAndValues)

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update will fail.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

Parameters:

documentReference - A reference to the document to be updated.

fieldPath - The first field to set.

value - The first value to set.

moreFieldsAndValues - String and Object pairs with more fields to be set.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

update

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Precondition precondition,
                                                                  @Nonnull
                                                                  String field,
                                                                  @Nullable
                                                                  Object value,
                                                                  Object... moreFieldsAndValues)

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update will fail.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

Parameters:

documentReference - A reference to the document to be updated.

field - The first field to set.

value - The first value to set.

moreFieldsAndValues - String and Object pairs with more fields to be set.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

update

@Nonnull
public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull
                                                                  DocumentReference documentReference,
                                                                  @Nonnull
                                                                  Precondition precondition,
                                                                  @Nonnull
                                                                  FieldPath fieldPath,
                                                                  @Nullable
                                                                  Object value,
                                                                  Object... moreFieldsAndValues)

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update will fail.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

Parameters:

documentReference - A reference to the document to be updated.

precondition - Precondition to enforce on this update.

fieldPath - The first field to set.

value - The first value to set.

moreFieldsAndValues - String and Object pairs with more fields to be set.

Returns:

An ApiFuture containing the result of the write. Contains a BulkWriterException if the write fails.

flush

@Nonnull
public com.google.api.core.ApiFuture<Void> flush()

Commits all writes that have been enqueued up to this point in parallel.

Returns an ApiFuture that completes when all currently queued operations have been committed. The ApiFuture will never return an error since the results for each individual operation are conveyed via their individual ApiFutures.

The ApiFuture completes immediately if there are no pending writes. Otherwise, the ApiFuture waits for all previously issued writes, but it does not wait for writes that were added after the method is called. If you want to wait for additional writes, call `flush()` again.

Returns:

An ApiFuture that completes when all enqueued writes up to this point have been committed.

close

public void close()
           throws InterruptedException,
                  ExecutionException

Commits all enqueued writes and marks the BulkWriter instance as closed.

After calling `close()`, calling any method will return an error. Any retries scheduled with `addWriteErrorListener()` will be run before `close()` completes.

This method completes when there are no more pending writes. Calling this method will send all requests.

Specified by:

close in interface AutoCloseable

Throws:

InterruptedException

ExecutionException

addWriteResultListener

public void addWriteResultListener(BulkWriter.WriteResultCallback writeResultCallback)

Attaches a listener that is run every time a BulkWriter operation successfully completes. The listener will be run before `close()` completes.

For example, see the sample code: BulkWriter bulkWriter = firestore.bulkWriter(); bulkWriter.addWriteResultListener( (DocumentReference documentReference, WriteResult result) -> { System.out.println( "Successfully executed write on document: " + documentReference + " at: " + result.getUpdateTime()); } );

Parameters:

writeResultCallback - A callback to be called every time a BulkWriter operation successfully completes.

addWriteResultListener

public void addWriteResultListener(@Nonnull
                                   Executor executor,
                                   BulkWriter.WriteResultCallback writeResultCallback)

Attaches a listener that is run every time a BulkWriter operation successfully completes.

The executor cannot be changed once writes have been enqueued onto the BulkWriter.

For example, see the sample code: BulkWriter bulkWriter = firestore.bulkWriter(); bulkWriter.addWriteResultListener( (DocumentReference documentReference, WriteResult result) -> { System.out.println( "Successfully executed write on document: " + documentReference + " at: " + result.getUpdateTime()); } );

Parameters:

executor - The executor to run the provided callback on.

writeResultCallback - A callback to be called every time a BulkWriter operation successfully completes.

addWriteErrorListener

public void addWriteErrorListener(BulkWriter.WriteErrorCallback onError)

Attaches an error handler listener that is run every time a BulkWriter operation fails.

BulkWriter has a default error handler that retries UNAVAILABLE and ABORTED errors up to a maximum of 10 failed attempts. When an error handler is specified, the default error handler will be overwritten.

For example, see the sample code: BulkWriter bulkWriter = firestore.bulkWriter(); bulkWriter.addWriteErrorListener( (BulkWriterException error) -> { if (error.getStatus() == Status.UNAVAILABLE && error.getFailedAttempts() < MAX_RETRY_ATTEMPTS) { return true; } else { System.out.println("Failed write at document: " + error.getDocumentReference()); return false; } } );

Parameters:

onError - A callback to be called every time a BulkWriter operation fails. Returning `true` will retry the operation. Returning `false` will stop the retry loop.

addWriteErrorListener

public void addWriteErrorListener(@Nonnull
                                  Executor executor,
                                  BulkWriter.WriteErrorCallback onError)

Attaches an error handler listener that is run every time a BulkWriter operation fails.

The executor cannot be changed once writes have been enqueued onto the BulkWriter.

BulkWriter has a default error handler that retries UNAVAILABLE and ABORTED errors up to a maximum of 10 failed attempts. When an error handler is specified, the default error handler will be overwritten.

For example, see the sample code: BulkWriter bulkWriter = firestore.bulkWriter(); bulkWriter.addWriteErrorListener( (BulkWriterException error) -> { if (error.getStatus() == Status.UNAVAILABLE && error.getFailedAttempts() < MAX_RETRY_ATTEMPTS) { return true; } else { System.out.println("Failed write at document: " + error.getDocumentReference()); return false; } } );

Parameters:

executor - The executor to run the provided callback on.

onError - A callback to be called every time a BulkWriter operation fails. Returning `true` will retry the operation. Returning `false` will stop the retry loop.