Cloud Firestore API - Class Google::Cloud::Firestore::DocumentReference (v2.15.0)

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

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

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

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

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
Returns
  • (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
Examples 
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

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

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
Returns
  • (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
Examples 
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

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

The operation will fail if the document already exists.

Parameter
  • data (Hash) — The document's fields and values.
Returns
Examples 
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:

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
Examples 
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:

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:

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

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
Returns
  • (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
Examples 
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

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

Listen to this document reference for changes.

Yields
  • (callback) — The block for accessing the document snapshot.
Yield Parameter
Returns
  • (DocumentListener) — The ongoing listen operation on the document reference.
Raises
  • (ArgumentError)
Example 
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

Listen to this document reference for changes.

Yields
  • (callback) — The block for accessing the document snapshot.
Yield Parameter
Returns
  • (DocumentListener) — The ongoing listen operation on the document reference.
Raises
  • (ArgumentError)
Example 
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
Example 
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.

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, 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 
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:

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:

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:

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:

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.

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 object instead.

  • update_time (Time) (defaults to: nil) — When set, the document must have been last updated at that time. Optional.
Returns
Examples 
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:

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:

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:

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:

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 })