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.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

Attributes

client[RW]

@private The firestore client object.

Public Class Methods

from_path(path, client) click to toggle source

@private New DocumentReference object from a path.

# File lib/google/cloud/firestore/document_reference.rb, line 471
def self.from_path path, client
  new.tap do |r|
    r.client = client
    r.instance_variable_set :@path, path
  end
end

Public Instance Methods

<=>(other) click to toggle source

@private

# File lib/google/cloud/firestore/document_reference.rb, line 464
def <=> other
  return nil unless other.is_a? self.class
  ResourcePath.from_path(path) <=> ResourcePath.from_path(other.path)
end
col(collection_path) click to toggle source

Retrieves a collection nested under the document snapshot.

@param [String] collection_path A string representing the path of

the collection, relative to the document.

@return [CollectionReference] A collection.

@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"
# File lib/google/cloud/firestore/document_reference.rb, line 123
def col collection_path
  if collection_path.to_s.split("/").count.even?
    raise ArgumentError, "collection_path must refer to a collection."
  end

  CollectionReference.from_path "#{path}/#{collection_path}", client
end
Also aliased as: collection
collection(collection_path)
Alias for: col
collections(&block)
Alias for: cols
cols(&block) click to toggle source

Retrieves an enumerator for the collections nested under the document snapshot.

@yield [collections] The block for accessing the collections. @yieldparam [CollectionReference] collection A collection reference object.

@return [Enumerator<CollectionReference>] An enumerator of collection references. If a block is provided, this

is the same enumerator that is accessed through the block.

@example

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
# File lib/google/cloud/firestore/document_reference.rb, line 94
def cols &block
  ensure_service!
  grpc = service.list_collections path
  cols_enum = CollectionReferenceList.from_grpc(grpc, client, path).all
  cols_enum.each(&block) if block_given?
  cols_enum
end
Also aliased as: collections, list_collections
create(data) click to toggle source

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

The operation will fail if the document already exists.

@param [Hash] data The document's fields and values.

@return [CommitResponse::WriteResult] The result of the change.

@example

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

@example 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 })
# File lib/google/cloud/firestore/document_reference.rb, line 240
def create data
  ensure_client!

  resp = client.batch { |b| b.create self, data }
  resp.write_results.first
end
delete(exists: nil, update_time: nil) click to toggle source

Deletes a document from the database.

@param [Boolean] exists Whether the document must exist. When `true`,

the document must exist or an error is raised. Default is `false`.
Optional.

@param [Time] update_time When set, the document must have been last

updated at that time. Optional.

@return [CommitResponse::WriteResult] The result of the change.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

nyc_ref.delete

@example 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

@example 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
# File lib/google/cloud/firestore/document_reference.rb, line 452
def delete exists: nil, update_time: nil
  ensure_client!

  resp = client.batch do |b|
    b.delete self, exists: exists, update_time: update_time
  end
  resp.write_results.first
end
document_id() click to toggle source

The document identifier for the document resource.

@return [String] document identifier.

# File lib/google/cloud/firestore/document_reference.rb, line 50
def document_id
  path.split("/").last
end
document_path() click to toggle source

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

@return [String] document path.

# File lib/google/cloud/firestore/document_reference.rb, line 59
def document_path
  path.split("/", 6).last
end
get() click to toggle source

Retrieve the document data.

@return [DocumentSnapshot] document snapshot.

@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
# File lib/google/cloud/firestore/document_reference.rb, line 148
def get
  ensure_client!

  client.get_all([self]).first
end
list_collections(&block)
Alias for: cols
listen(&callback) click to toggle source

Listen to this document reference for changes.

@yield [callback] The block for accessing the document snapshot. @yieldparam [DocumentSnapshot] snapshot A document snapshot.

@return [DocumentListener] The ongoing listen operation on the

document reference.

@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
# File lib/google/cloud/firestore/document_reference.rb, line 178
def listen &callback
  raise ArgumentError, "callback required" if callback.nil?

  ensure_client!

  DocumentListener.new(self, &callback).start
end
Also aliased as: on_snapshot
on_snapshot(&callback)
Alias for: listen
parent() click to toggle source

The collection the document reference belongs to.

@return [CollectionReference] parent collection.

@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
# File lib/google/cloud/firestore/document_reference.rb, line 202
def parent
  CollectionReference.from_path parent_path, client
end
path() click to toggle source

@private A string representing the full path of the document resource.

@return [String] document resource path.

# File lib/google/cloud/firestore/document_reference.rb, line 67
def path
  @path
end
set(data, merge: nil) click to toggle source

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.

@param [Hash] data The document's fields and values. @param [Boolean, FieldPath, String, Symbol] merge 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.

@return [CommitResponse::WriteResult] The result of the change.

@example

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

@example 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)

@example 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)

@example 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)

@example 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 })
# File lib/google/cloud/firestore/document_reference.rb, line 319
def set data, merge: nil
  ensure_client!

  resp = client.batch { |b| b.set self, data, merge: merge }
  resp.write_results.first
end
update(data, update_time: nil) click to toggle source

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.

@param [Hash<FieldPath|String|Symbol, Object>] data 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.

@param [Time] update_time When set, the document must have been last

updated at that time. Optional.

@return [CommitResponse::WriteResult] The result of the change.

@example

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

@example 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" })

@example 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)

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

@example 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 })
# File lib/google/cloud/firestore/document_reference.rb, line 401
def update data, update_time: nil
  ensure_client!

  resp = client.batch do |b|
    b.update self, data, update_time: update_time
  end
  resp.write_results.first
end

Protected Instance Methods

ensure_client!() click to toggle source

@private Raise an error unless an database available.

# File lib/google/cloud/firestore/document_reference.rb, line 496
def ensure_client!
  raise "Must have active connection to service" unless client
end
ensure_service!() click to toggle source

@private Raise an error unless an active connection to the service is available.

# File lib/google/cloud/firestore/document_reference.rb, line 503
def ensure_service!
  raise "Must have active connection to service" unless service
end
parent_path() click to toggle source

@private

# File lib/google/cloud/firestore/document_reference.rb, line 482
def parent_path
  path.split("/")[0...-1].join "/"
end
service() click to toggle source

@private The client's Service object.

# File lib/google/cloud/firestore/document_reference.rb, line 488
def service
  ensure_client!

  client.service
end