# Cloud Firestore API - Class Google::Cloud::Firestore::Transaction (v3.2.0)

3.2.0 (latest) 3.1.1 3.0.0 2.16.1 2.15.1 2.14.0 2.13.1 2.12.0 2.11.0 2.10.1 2.9.1 2.8.0 2.7.2 2.6.6 Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::Transaction.

## Transaction

A transaction in Cloud Firestore is a set of reads and writes that
execute atomically at a single logical point in time.

All changes are accumulated in memory until the block passed to
[Client#transaction](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client#Google__Cloud__Firestore__Client_transaction_instance_ "Google::Cloud::Firestore::Client#transaction (method)") completes. Transactions will be automatically
retried when documents change before the transaction is committed. See
[Client#transaction](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client#Google__Cloud__Firestore__Client_transaction_instance_ "Google::Cloud::Firestore::Client#transaction (method)").

## Inherits

- Object

## Example

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

city = firestore.col("cities").doc("SF")
city.set({ name: "San Francisco",
           state: "CA",
           country: "USA",
           capital: false,
           population: 860000 })

firestore.transaction do |tx|
  new_population = tx.get(city).data[:population] + 1
  tx.update(city, { population: new_population })
end
```

## Methods

### #client

    def client() -> Client

**Alias Of** : [#firestore](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_firestore_instance_) The client the Cloud Firestore transaction belongs to.
**Returns**

- ([Client](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client)) --- firestore client.

### #create

    def create(doc, data)

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


<br />

The operation will fail if the document already exists.
**Parameters**

- **doc** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference)) --- A string representing the path of the document, or a document reference object.
- **data** (Hash) --- The document's fields and values.
**Examples**

Create a document using a document path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

Create a document using a document reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.transaction do |tx|
  tx.create(nyc_ref, { name: "New York City" })
end
```

Create a document and set a field to server_time:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

### #delete

    def delete(doc, exists: nil, update_time: nil)

Deletes a document from the database.
**Parameters**

- **doc** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-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.
**Examples**

Delete a document using a document path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Delete a document
  tx.delete "cities/NYC"
end
```

Delete a document using a document reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.transaction do |tx|
  # Delete a document
  tx.delete nyc_ref
end
```

Delete a document using `exists`:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Delete a document
  tx.delete "cities/NYC", exists: true
end
```

Delete a document using the `update_time` precondition:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

last_updated_at = Time.now - 42 # 42 seconds ago

firestore.transaction do |tx|
  # Delete a document
  tx.delete "cities/NYC", update_time: last_updated_at
end
```

### #find

    def find(*docs, field_mask: nil) { |document| ... } -> Enumerator<DocumentSnapshot>

**Alias Of** : [#get_all](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_get_all_instance_) Retrieves a list of document snapshots.
**Parameters**

- **docs** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference), Array\<String\|DocumentReference\>) --- One or more strings representing the path of the document, or document reference objects.
- **field_mask** (Array\<String\|FieldPath\>) *(defaults to: nil)* --- One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.


  A field path can either be a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object, or a dotted 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object instead. See [Client#field_path](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client#Google__Cloud__Firestore__Client_field_path_instance_ "Google::Cloud::Firestore::Client#field_path (method)").)
**Yields**

- (documents) --- The block for accessing the document snapshots.
**Yield Parameter**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- (Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- document snapshots list.
**Examples**

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  tx.get_all("cities/NYC", "cities/SF", "cities/LA").each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

Get docs using a field mask:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  cities = ["cities/NYC", "cities/SF", "cities/LA"]
  tx.get_all(*cities, field_mask: :population).each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

### #firestore

    def firestore() -> Client

**Aliases**

- [#client](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_client_instance_)
The client the Cloud Firestore transaction belongs to.
**Returns**

- ([Client](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client)) --- firestore client.

### #get

    def get(obj) { |document| ... } -> DocumentSnapshot, Enumerator<DocumentSnapshot>

**Aliases**

- [#run](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_run_instance_)
Retrieves document snapshots for the given value. Valid values can be
a string representing either a document or a collection of documents,
a document reference object, a collection reference object, or a query
to be run.
**Parameter**

- **obj** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference), [CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference), [Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- A string representing the path of a document or collection, a document reference object, a collection reference object, or a query to run.
**Yields**

- (documents) --- The block for accessing the document snapshots.
**Yield Parameter**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot), Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- A single document snapshot when passed a document path or a document reference object, or a list of document snapshots when passed other valid values.
**Examples**

Get a document snapshot given a document path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get a document snapshot
  nyc_snap = tx.get "cities/NYC"
end
```

Get a document snapshot given a document reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.transaction do |tx|
  # Get a document snapshot
  nyc_snap = tx.get nyc_ref
end
```

Get document snapshots given a collection path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get documents for a collection path
  tx.get("cities").each do |city|
    # Update the city population by 1
    tx.update(city, { population: city[:population] + 1})
  end
end
```

Get document snapshots given a collection reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col :cities

firestore.transaction do |tx|
  # Get documents for a collection
  tx.get(cities_col).each do |city|
    # Update the city population by 1
    tx.update(city, { population: city[:population] + 1})
  end
end
```

Get document snapshots given a query:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).select(:population)

firestore.transaction do |tx|
  # Get/run a query
  tx.get(query).each do |city|
    # Update the city population by 1
    tx.update(city, { population: city[:population] + 1})
  end
end
```

### #get_aggregate

    def get_aggregate(aggregate_query) { |aggregate_snapshot| ... }

Retrieves aggregate query snapshots for the given value. Valid values can be
a string representing either a document or a collection of documents,
a document reference object, a collection reference object, or a query
to be run.
**Parameter**

- **aggregate_query** ([AggregateQuery](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-AggregateQuery)) --- An AggregateQuery object
**Yields**

- (documents) --- The block for accessing the aggregate query snapshot.
**Yield Parameter**

- **aggregate_snapshot** ([AggregateQuerySnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-AggregateQuerySnapshot)) --- An aggregate query snapshot.
**Example**

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

query = firestore.col "cities"

# Create an aggregate query
aq = query.aggregate_query
          .add_count

firestore.transaction do |tx|
  tx.get_aggregate aq do |aggregate_snapshot|
    puts aggregate_snapshot.get
  end
end
```

### #get_all

    def get_all(*docs, field_mask: nil) { |document| ... } -> Enumerator<DocumentSnapshot>

**Aliases**

- [#get_docs](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_get_docs_instance_)
- [#get_documents](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_get_documents_instance_)
- [#find](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_find_instance_)
Retrieves a list of document snapshots.
**Parameters**

- **docs** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference), Array\<String\|DocumentReference\>) --- One or more strings representing the path of the document, or document reference objects.
- **field_mask** (Array\<String\|FieldPath\>) *(defaults to: nil)* --- One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.


  A field path can either be a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object, or a dotted 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object instead. See [Client#field_path](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client#Google__Cloud__Firestore__Client_field_path_instance_ "Google::Cloud::Firestore::Client#field_path (method)").)
**Yields**

- (documents) --- The block for accessing the document snapshots.
**Yield Parameter**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- (Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- document snapshots list.
**Examples**

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  tx.get_all("cities/NYC", "cities/SF", "cities/LA").each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

Get docs using a field mask:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  cities = ["cities/NYC", "cities/SF", "cities/LA"]
  tx.get_all(*cities, field_mask: :population).each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

### #get_docs

    def get_docs(*docs, field_mask: nil) { |document| ... } -> Enumerator<DocumentSnapshot>

**Alias Of** : [#get_all](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_get_all_instance_) Retrieves a list of document snapshots.
**Parameters**

- **docs** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference), Array\<String\|DocumentReference\>) --- One or more strings representing the path of the document, or document reference objects.
- **field_mask** (Array\<String\|FieldPath\>) *(defaults to: nil)* --- One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.


  A field path can either be a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object, or a dotted 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object instead. See [Client#field_path](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client#Google__Cloud__Firestore__Client_field_path_instance_ "Google::Cloud::Firestore::Client#field_path (method)").)
**Yields**

- (documents) --- The block for accessing the document snapshots.
**Yield Parameter**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- (Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- document snapshots list.
**Examples**

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  tx.get_all("cities/NYC", "cities/SF", "cities/LA").each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

Get docs using a field mask:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  cities = ["cities/NYC", "cities/SF", "cities/LA"]
  tx.get_all(*cities, field_mask: :population).each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

### #get_documents

    def get_documents(*docs, field_mask: nil) { |document| ... } -> Enumerator<DocumentSnapshot>

**Alias Of** : [#get_all](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_get_all_instance_) Retrieves a list of document snapshots.
**Parameters**

- **docs** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference), Array\<String\|DocumentReference\>) --- One or more strings representing the path of the document, or document reference objects.
- **field_mask** (Array\<String\|FieldPath\>) *(defaults to: nil)* --- One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.


  A field path can either be a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object, or a dotted 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object instead. See [Client#field_path](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client#Google__Cloud__Firestore__Client_field_path_instance_ "Google::Cloud::Firestore::Client#field_path (method)").)
**Yields**

- (documents) --- The block for accessing the document snapshots.
**Yield Parameter**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- (Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- document snapshots list.
**Examples**

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  tx.get_all("cities/NYC", "cities/SF", "cities/LA").each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

Get docs using a field mask:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get and print city documents
  cities = ["cities/NYC", "cities/SF", "cities/LA"]
  tx.get_all(*cities, field_mask: :population).each do |city|
    puts "#{city.document_id} has #{city[:population]} residents."
  end
end
```

### #run

    def run(obj) { |document| ... } -> DocumentSnapshot, Enumerator<DocumentSnapshot>

**Alias Of** : [#get](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Transaction#Google__Cloud__Firestore__Transaction_get_instance_) Retrieves document snapshots for the given value. Valid values can be
a string representing either a document or a collection of documents,
a document reference object, a collection reference object, or a query
to be run.
**Parameter**

- **obj** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference), [CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference), [Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- A string representing the path of a document or collection, a document reference object, a collection reference object, or a query to run.
**Yields**

- (documents) --- The block for accessing the document snapshots.
**Yield Parameter**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot), Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- A single document snapshot when passed a document path or a document reference object, or a list of document snapshots when passed other valid values.
**Examples**

Get a document snapshot given a document path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get a document snapshot
  nyc_snap = tx.get "cities/NYC"
end
```

Get a document snapshot given a document reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.transaction do |tx|
  # Get a document snapshot
  nyc_snap = tx.get nyc_ref
end
```

Get document snapshots given a collection path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Get documents for a collection path
  tx.get("cities").each do |city|
    # Update the city population by 1
    tx.update(city, { population: city[:population] + 1})
  end
end
```

Get document snapshots given a collection reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col :cities

firestore.transaction do |tx|
  # Get documents for a collection
  tx.get(cities_col).each do |city|
    # Update the city population by 1
    tx.update(city, { population: city[:population] + 1})
  end
end
```

Get document snapshots given a query:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).select(:population)

firestore.transaction do |tx|
  # Get/run a query
  tx.get(query).each do |city|
    # Update the city population by 1
    tx.update(city, { population: city[:population] + 1})
  end
end
```

### #set

    def set(doc, data, merge: nil)

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.


<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-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.
**Examples**

Set a document using a document path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Update a document
  tx.set("cities/NYC", { name: "New York City" })
end
```

Create a document using a document reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.transaction do |tx|
  # Update a document
  tx.set(nyc_ref, { name: "New York City" })
end
```

Set a document and merge all data:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

Set a document and merge only name:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

Set a document and deleting a field using merge:

```ruby
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.transaction do |tx|
  tx.set(nyc_ref, nyc_data, merge: true)
end
```

Set a document and set a field to server_time:

```ruby
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.transaction do |tx|
  tx.set(nyc_ref, nyc_data, merge: true)
end
```

### #transaction_id

    def transaction_id() -> String

The transaction identifier.
**Returns**

- (String) --- transaction identifier.

### #update

    def update(doc, data, update_time: nil)

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


<br />

The operation will fail if the document does not exist.
**Parameters**

- **doc** (String, [DocumentReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object instead.
- **update_time** (Time) *(defaults to: nil)* --- When set, the document must have been last updated at that time. Optional.
**Examples**

Update a document using a document path:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

Directly update a deeply-nested field with a `FieldPath`:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

nested_field_path = firestore.field_path :favorites, :food

firestore.transaction do |tx|
  tx.update("users/frank", { nested_field_path => "Pasta" })
end
```

Update a document using a document reference:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

firestore.transaction do |tx|
  tx.update(nyc_ref, { name: "New York City" })
end
```

Update a document using the `update_time` precondition:

```ruby
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

last_updated_at = Time.now - 42 # 42 seconds ago

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

Update a document and deleting a field:

```ruby
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.transaction do |tx|
  tx.update(nyc_ref, nyc_data)
end
```

Update a document and set a field to server_time:

```ruby
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.transaction do |tx|
  tx.update(nyc_ref, nyc_data)
end
```