Class: Google::Cloud::Firestore::DocumentReference

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/document_reference.rb,
lib/google/cloud/firestore/document_reference/list.rb

Overview

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.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

Defined Under Namespace

Classes: List

Access collapse

Modifications collapse

Instance Method Summary collapse

Instance Method Details

#col(collection_path) ⇒ CollectionReference Also known as: collection

Retrieves a collection nested under the document snapshot.

Examples:

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"

Parameters:

  • collection_path (String) —

    A string representing the path of the collection, relative to the document.

Returns:



140
141
142
143
144
145
146
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 140

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

#cols(read_time: nil) {|collections| ... } ⇒ Enumerator<CollectionReference> Also known as: collections, list_collections

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

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

Parameters:

  • 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 Parameters:

Returns:

  • (Enumerator<CollectionReference>) —

    An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.



111
112
113
114
115
116
117
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 111

def cols read_time: nil, &block
  ensure_service!
  grpc = service.list_collections path, read_time: read_time
  cols_enum = CollectionReferenceList.from_grpc(grpc, client, path, read_time: read_time).all
  cols_enum.each(&block) if block_given?
  cols_enum
end

#create(data) ⇒ CommitResponse::WriteResult

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

The operation will fail if the document already exists.

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

Parameters:

  • data (Hash) —

    The document's fields and values.

Returns:



257
258
259
260
261
262
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 257

def create data
  ensure_client!

  resp = client.batch { |b| b.create self, data }
  resp.write_results.first
end

#delete(exists: nil, update_time: nil) ⇒ CommitResponse::WriteResult

Deletes a document from the database.

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

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:



469
470
471
472
473
474
475
476
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 469

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 ⇒ String

The document identifier for the document resource.

Returns:

  • (String) —

    document identifier.



50
51
52
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 50

def document_id
  path.split("/").last
end

#document_path ⇒ String

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

Returns:

  • (String) —

    document path.



59
60
61
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 59

def document_path
  path.split("/", 6).last
end

#get ⇒ DocumentSnapshot

Retrieve the document data.

Examples:

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

Returns:



165
166
167
168
169
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 165

def get
  ensure_client!

  client.get_all([self]).first
end

#listen {|callback| ... } ⇒ DocumentListener Also known as: on_snapshot

Listen to this document reference for changes.

Examples:

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

Yields:

  • (callback) —

    The block for accessing the document snapshot.

Yield Parameters:

Returns:

  • (DocumentListener) —

    The ongoing listen operation on the document reference.

Raises:

  • (ArgumentError) 


195
196
197
198
199
200
201
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 195

def listen &callback
  raise ArgumentError, "callback required" if callback.nil?

  ensure_client!

  DocumentListener.new(self, &callback).start
end

#parent ⇒ CollectionReference

The collection the document reference belongs to.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

cities_col = nyc_ref.parent

Returns:



219
220
221
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 219

def parent
  CollectionReference.from_path parent_path, client
end

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

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

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:



336
337
338
339
340
341
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 336

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

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

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:



418
419
420
421
422
423
424
425
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 418

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