# Cloud Firestore API - Class Google::Cloud::Firestore::DocumentReference (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::DocumentReference.

## DocumentReference

A document reference object refers to a document location in a Cloud
Firestore database and can be used to write or read data. A document
resource at the referenced location may or may not exist.

## Inherits

- Object

## Example

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

firestore = Google::Cloud::Firestore.new

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

## Methods

### #col

    def col(collection_path) -> CollectionReference

**Aliases**

- [#collection](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_collection_instance_)
Retrieves a collection nested under the document snapshot.
**Parameter**

- **collection_path** (String) --- A string representing the path of the collection, relative to the document.
**Returns**

- ([CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)) --- A collection.
**Example**

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

firestore = Google::Cloud::Firestore.new

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

# Get precincts sub-collection
precincts_col = nyc_ref.col "precincts"
```

### #collection

    def collection(collection_path) -> CollectionReference

**Alias Of** : [#col](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_col_instance_) Retrieves a collection nested under the document snapshot.
**Parameter**

- **collection_path** (String) --- A string representing the path of the collection, relative to the document.
**Returns**

- ([CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)) --- A collection.
**Example**

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

firestore = Google::Cloud::Firestore.new

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

# Get precincts sub-collection
precincts_col = nyc_ref.col "precincts"
```

### #collections

    def collections(read_time: nil, &block) { |collection| ... } -> Enumerator<CollectionReference>

**Alias Of** : [#cols](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_cols_instance_) Retrieves an enumerator for the collections nested under the document snapshot.
**Parameter**

- **read_time** (Time) *(defaults to: nil)* --- Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
**Yields**

- (collections) --- The block for accessing the collections.
**Yield Parameter**

- **collection** ([CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)) --- A collection reference object.
**Returns**

- (Enumerator\<[CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)\>) --- An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.cols.each do |col|
  puts col.collection_id
end
```

Get collection with read time

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

firestore = Google::Cloud::Firestore.new

read_time = Time.now

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

nyc_ref.cols(read_time: read_time).each do |col|
  puts col.collection_id
end
```

### #cols

    def cols(read_time: nil, &block) { |collection| ... } -> Enumerator<CollectionReference>

**Aliases**

- [#collections](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_collections_instance_)
- [#list_collections](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_list_collections_instance_)
Retrieves an enumerator for the collections nested under the document snapshot.
**Parameter**

- **read_time** (Time) *(defaults to: nil)* --- Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
**Yields**

- (collections) --- The block for accessing the collections.
**Yield Parameter**

- **collection** ([CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)) --- A collection reference object.
**Returns**

- (Enumerator\<[CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)\>) --- An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.cols.each do |col|
  puts col.collection_id
end
```

Get collection with read time

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

firestore = Google::Cloud::Firestore.new

read_time = Time.now

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

nyc_ref.cols(read_time: read_time).each do |col|
  puts col.collection_id
end
```

### #create

    def create(data) -> CommitResponse::WriteResult

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


<br />

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

- **data** (Hash) --- The document's fields and values.
**Returns**

- ([CommitResponse::WriteResult](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CommitResponse-WriteResult)) --- The result of the change.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

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

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"

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

### #delete

    def delete(exists: nil, update_time: nil) -> CommitResponse::WriteResult

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

- **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**

- ([CommitResponse::WriteResult](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CommitResponse-WriteResult)) --- The result of the change.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.delete
```

Delete a document using `exists`:

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.delete exists: true
```

Delete a document using the `update_time` precondition:

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

firestore = Google::Cloud::Firestore.new

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

last_updated_at = Time.now - 42 # 42 seconds ago
nyc_ref.delete update_time: last_updated_at
```

### #document_id

    def document_id() -> String

The document identifier for the document resource.
**Returns**

- (String) --- document identifier.

### #document_path

    def document_path() -> String

A string representing the path of the document, relative to the
document root of the database.
**Returns**

- (String) --- document path.

### #get

    def get() -> DocumentSnapshot

Retrieve the document data.
**Returns**

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

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

firestore = Google::Cloud::Firestore.new

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

nyc_snap = nyc_ref.get
nyc_snap[:population] #=> 1000000
```

### #list_collections

    def list_collections(read_time: nil, &block) { |collection| ... } -> Enumerator<CollectionReference>

**Alias Of** : [#cols](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_cols_instance_) Retrieves an enumerator for the collections nested under the document snapshot.
**Parameter**

- **read_time** (Time) *(defaults to: nil)* --- Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
**Yields**

- (collections) --- The block for accessing the collections.
**Yield Parameter**

- **collection** ([CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)) --- A collection reference object.
**Returns**

- (Enumerator\<[CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)\>) --- An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.cols.each do |col|
  puts col.collection_id
end
```

Get collection with read time

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

firestore = Google::Cloud::Firestore.new

read_time = Time.now

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

nyc_ref.cols(read_time: read_time).each do |col|
  puts col.collection_id
end
```

### #listen

    def listen(&callback) { |snapshot| ... } -> DocumentListener

**Aliases**

- [#on_snapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_on_snapshot_instance_)
Listen to this document reference for changes.
**Yields**

- (callback) --- The block for accessing the document snapshot.
**Yield Parameter**

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

- ([DocumentListener](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentListener)) --- The ongoing listen operation on the document reference.
**Raises**

- (ArgumentError)
**Example**

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

firestore = Google::Cloud::Firestore.new

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

listener = nyc_ref.listen do |snapshot|
  puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
end

# When ready, stop the listen operation and close the stream.
listener.stop
```

### #on_snapshot

    def on_snapshot(&callback) { |snapshot| ... } -> DocumentListener

**Alias Of** : [#listen](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentReference#Google__Cloud__Firestore__DocumentReference_listen_instance_) Listen to this document reference for changes.
**Yields**

- (callback) --- The block for accessing the document snapshot.
**Yield Parameter**

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

- ([DocumentListener](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentListener)) --- The ongoing listen operation on the document reference.
**Raises**

- (ArgumentError)
**Example**

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

firestore = Google::Cloud::Firestore.new

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

listener = nyc_ref.listen do |snapshot|
  puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
end

# When ready, stop the listen operation and close the stream.
listener.stop
```

### #parent

    def parent() -> CollectionReference

The collection the document reference belongs to.
**Returns**

- ([CollectionReference](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CollectionReference)) --- parent collection.
**Example**

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

firestore = Google::Cloud::Firestore.new

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

cities_col = nyc_ref.parent
```

### #set

    def set(data, merge: nil) -> CommitResponse::WriteResult

Write the provided data (fields and values) to the 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**

- **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.
**Returns**

- ([CommitResponse::WriteResult](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CommitResponse-WriteResult)) --- The result of the change.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.set({ name: "New York City" })
```

Set a document and merge all data:

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.set({ name: "New York City" }, merge: true)
```

Set a document and merge only name:

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

firestore = Google::Cloud::Firestore.new

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

nyc_ref.set({ name: "New York City" }, merge: :name)
```

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_ref.set({ name: "New York City",
              trash: firestore.field_delete }, merge: true)
```

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_ref.set({ name: "New York City",
              updated_at: firestore.field_server_time })
```

### #update

    def update(data, update_time: nil) -> CommitResponse::WriteResult

Update 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**

- **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.
**Returns**

- ([CommitResponse::WriteResult](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-CommitResponse-WriteResult)) --- The result of the change.
**Examples**

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

firestore = Google::Cloud::Firestore.new

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

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

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

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

firestore = Google::Cloud::Firestore.new

user_ref = firestore.doc "users/frank"

nested_field_path = firestore.field_path :favorites, :food
user_ref.update({ nested_field_path => "Pasta" })
```

Update a document using the `update_time` precondition:

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

firestore = Google::Cloud::Firestore.new

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

last_updated_at = Time.now - 42 # 42 seconds ago

nyc_ref.update({ name: "New York City" },
                 update_time: last_updated_at)
```

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_ref.update({ name: "New York City",
                 trash: firestore.field_delete })
```

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_ref.update({ name: "New York City",
                 updated_at: firestore.field_server_time })
```