Cloud Firestore API - Class Google::Cloud::Firestore::BulkWriter (v2.16.0)

Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::BulkWriter.

BulkWriter

Accumulate and efficiently sends large amounts of document write operations to the server.

BulkWriter can handle large data migrations or updates, buffering records in memory and submitting them to the server in batches of 20.

The submission of batches is internally parallelized with a ThreadPoolExecutor.

Inherits

  • Object

Example

Create a BulkWriter and add a write request:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

bw.create("cities/NYC", { name: "New York City" })

bw.flush
bw.close

Methods

#close

def close() -> nil

Closes the BulkWriter object for new operations. Existing operations will be flushed and the threadpool will shutdown.

Returns
  • (nil)

#create

def create(doc, data) -> Google::Cloud::Firestore::Promise::Future

Creates a document with the provided data (fields and values).

The operation will fail if the document already exists.

Parameters
  • doc (String, DocumentReference) — A string representing the path of the document, or a document reference object.
  • data (Hash) — The document's fields and values.
Returns
Examples

Create a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

bw.create("cities/NYC", { name: "New York City" })

Create a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

bw.create(nyc_ref, { name: "New York City" })

Create a document and set a field to server_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

bw.create(nyc_ref, { name: "New York City",
                       updated_at: firestore.field_server_time })

Get the value of write operation:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

result = bw.create(nyc_ref, { name: "New York City",
                              updated_at: firestore.field_server_time })

bw.close

puts result.value

#delete

def delete(doc, exists: nil, update_time: nil) -> Google::Cloud::Firestore::Promise::Future

Deletes a document from the database.

Parameters
  • doc (String, DocumentReference) — A string representing the path of the document, or a document reference object.
  • exists (Boolean) (defaults to: nil) — Whether the document must exist. When true, the document must exist or an error is raised. Default is false. Optional.
  • update_time (Time) (defaults to: nil) — When set, the document must have been last updated at that time. Optional.
Returns
Examples

Delete a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Delete a document
bw.delete "cities/NYC"

Delete a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Delete a document
bw.delete nyc_ref

Delete a document using exists:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Delete a document
bw.delete "cities/NYC", exists: true

Delete a document using the update_time precondition:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

last_updated_at = Time.now - 42 # 42 seconds ago

# Delete a document
bw.delete "cities/NYC", update_time: last_updated_at

Get the value of write operation:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

last_updated_at = Time.now - 42 # 42 seconds ago

# Delete a document
result = bw.delete "cities/NYC", update_time: last_updated_at

bw.close

puts result.value

#flush

def flush() -> nil

Flushes all the current operation before enqueuing new operations.

Returns
  • (nil)

#initialize

def initialize(client, service, request_threads: nil, batch_threads: nil, retries: nil) -> BulkWriter

Initialize the attributes and start the schedule_operations job

Returns

#set

def set(doc, data, merge: nil) -> Google::Cloud::Firestore::Promise::Future

Writes the provided data (fields and values) to the provided document. If the document does not exist, it will be created. By default, the provided data overwrites existing data, but the provided data can be merged into the existing document using the merge argument.

If you're not sure whether the document exists, use the merge argument to merge the new data with any existing document data to avoid overwriting entire documents.

Parameters
  • doc (String, DocumentReference) — A string representing the path of the document, or a document reference object.
  • data (Hash) — The document's fields and values.
  • merge (Boolean, FieldPath, String, Symbol) (defaults to: nil) — When true, all provided data is merged with the existing document data. When the argument is one or more field path, only the data for fields in this argument is merged with the existing document data. The default is to not merge, but to instead overwrite the existing document data.
Returns
Examples

Set a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Update a document
bw.set("cities/NYC", { name: "New York City" })

Create a document using a document reference:

require "google/cloud/firestore"

bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Update a document
bw.set(nyc_ref, { name: "New York City" })

Set a document and merge all data:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

bw.set("cities/NYC", { name: "New York City" }, merge: true)

Set a document and merge only name:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

bw.set("cities/NYC", { name: "New York City" }, merge: :name)

Set a document and deleting a field using merge:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

nyc_data = { name: "New York City",
             trash: firestore.field_delete }

bw.set(nyc_ref, nyc_data, merge: true)

Set a document and set a field to server_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

nyc_data = { name: "New York City",
             updated_at: firestore.field_server_time }

bw.set(nyc_ref, nyc_data, merge: true)

Get the value of write operation:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

nyc_data = { name: "New York City",
             updated_at: firestore.field_server_time }

result = bw.set(nyc_ref, nyc_data)

bw.close

puts result.value

#update

def update(doc, data, update_time: nil) -> Google::Cloud::Firestore::Promise::Future

Updates the document with the provided data (fields and values). The provided data is merged into the existing document data.

The operation will fail if the document does not exist.

Parameters
  • doc (String, DocumentReference) — A string representing the path of the document, or a document reference object.
  • data (Hash<FieldPath|String|Symbol, Object>) — The document's fields and values.

    The top-level keys in the data hash are considered field paths, and can either be a FieldPath object, or a string representing the nested fields. In other words the string represents individual fields joined by ".". Fields containing ~, *, /, [, ], and . cannot be in a dotted string, and should provided using a FieldPath object instead.

  • update_time (Time) (defaults to: nil) — When set, the document must have been last updated at that time. Optional.
Returns
Examples

Update a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

bw.update("cities/NYC", { name: "New York City" })

Directly update a deeply-nested field with a FieldPath:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

nested_field_path = firestore.field_path :favorites, :food

bw.update("users/frank", { nested_field_path => "Pasta" })

Update a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

bw.update(nyc_ref, { name: "New York City" })

Update a document using the update_time precondition:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

last_updated_at = Time.now - 42 # 42 seconds ago

bw.update("cities/NYC", { name: "New York City" },
           update_time: last_updated_at)

Update a document and deleting a field:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

nyc_data = { name: "New York City",
             trash: firestore.field_delete }

bw.update(nyc_ref, nyc_data)

Update a document and set a field to server_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

nyc_data = { name: "New York City",
             updated_at: firestore.field_server_time }

bw.update(nyc_ref, nyc_data)

Get the value of write operation:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
bw = firestore.bulk_writer

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

nyc_data = { name: "New York City",
             updated_at: firestore.field_server_time }

result = bw.update(nyc_ref, nyc_data)

bw.close

puts result.value

Constants

MAX_RETRY_ATTEMPTS

value: 10