Class: Google::Cloud::Firestore::Batch

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/batch.rb

Overview

Batch

A batch in Cloud Firestore is a set of writes that execute atomically at a single logical point in time in a database.

All changes are accumulated in memory until the block passed to Database#batch completes. Unlike transactions, batches don't lock on document reads, should only fail if users provide preconditions, and are not automatically retried.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  # Set the data for NYC
  b.set("cities/NYC", { name: "New York City" })

  # Update the population for SF
  b.update("cities/SF", { population: 1000000 })

  # Delete LA
  b.delete("cities/LA")
end

See Also:

Modifications collapse

Instance Method Summary collapse

Instance Method Details

#create(doc, data) ⇒ Object

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

The batch will fail if the document already exists.

Examples:

Create a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.create("cities/NYC", { name: "New York City" })
end

Create a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.batch do |b|
  b.create(nyc_ref, { name: "New York City" })
end

Create a document and set a field to server_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.batch do |b|
  b.create(nyc_ref, { name: "New York City",
                      updated_at: firestore.field_server_time })
end

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.



117
118
119
120
121
122
123
124
125
 
# File 'lib/google/cloud/firestore/batch.rb', line 117

def create doc, data
  ensure_not_closed!

  doc_path = coalesce_doc_path_argument doc

  @writes << Convert.writes_for_create(doc_path, data)

  nil
end

#delete(doc, exists: nil, update_time: nil) ⇒ Object

Deletes a document from the database.

Examples:

Delete a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.delete "cities/NYC"
end

Delete a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.batch do |b|
  b.delete nyc_ref
end

Delete a document using exists:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.delete "cities/NYC", exists: true
end

Delete a document using the update_time precondition:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

last_updated_at = Time.now - 42 # 42 seconds ago

firestore.batch do |b|
  b.delete "cities/NYC", update_time: last_updated_at
end

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.



383
384
385
386
387
388
389
390
391
392
393
 
# File 'lib/google/cloud/firestore/batch.rb', line 383

def delete doc, exists: nil, update_time: nil
  ensure_not_closed!

  doc_path = coalesce_doc_path_argument doc

  @writes << Convert.write_for_delete(
    doc_path, exists: exists, update_time: update_time
  )

  nil
end

#firestore ⇒ Client Also known as: client

The client the Cloud Firestore batch belongs to.

Returns:

  • (Client) —

    firestore client.



67
68
69
 
# File 'lib/google/cloud/firestore/batch.rb', line 67

def firestore
  @client
end

#set(doc, data, merge: nil) ⇒ Object

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

Examples:

Set a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.set("cities/NYC", { name: "New York City" })
end

Create a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.batch do |b|
  b.set(nyc_ref, { name: "New York City" })
end

Set a document and merge all data:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.set("cities/NYC", { name: "New York City" }, merge: true)
end

Set a document and merge only name:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.set("cities/NYC", { name: "New York City" }, merge: :name)
end

Set a document and deleting a field using merge:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

firestore.batch do |b|
  b.set(nyc_ref, nyc_data, merge: true)
end

Set a document and set a field to server_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

firestore.batch do |b|
  b.set(nyc_ref, nyc_data, merge: true)
end

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.



216
217
218
219
220
221
222
223
224
 
# File 'lib/google/cloud/firestore/batch.rb', line 216

def set doc, data, merge: nil
  ensure_not_closed!

  doc_path = coalesce_doc_path_argument doc

  @writes << Convert.writes_for_set(doc_path, data, merge: merge)

  nil
end

#update(doc, data, update_time: nil) ⇒ Object

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

The batch will fail if the document does not exist.

Examples:

Update a document using a document path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  b.update("cities/NYC", { name: "New York City" })
end

Directly update a deeply-nested field with a FieldPath:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

nested_field_path = firestore.field_path :favorites, :food

firestore.batch do |b|
  b.update("users/frank", { nested_field_path => "Pasta" })
end

Update a document using a document reference:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.batch do |b|
  b.update(nyc_ref, { name: "New York City" })
end

Update a document using the update_time precondition:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

last_updated_at = Time.now - 42 # 42 seconds ago

firestore.batch do |b|
  b.update("cities/NYC", { name: "New York City" },
           update_time: last_updated_at)
end

Update a document and deleting a field:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

firestore.batch do |b|
  b.update(nyc_ref, nyc_data)
end

Update a document and set a field to server_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

firestore.batch do |b|
  b.update(nyc_ref, nyc_data)
end

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.



320
321
322
323
324
325
326
327
328
329
 
# File 'lib/google/cloud/firestore/batch.rb', line 320

def update doc, data, update_time: nil
  ensure_not_closed!

  doc_path = coalesce_doc_path_argument doc

  @writes << Convert.writes_for_update(doc_path, data,
                                       update_time: update_time)

  nil
end