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

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/document_reference.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"

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:



120
121
122
123
124
125
126
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 120

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 {|collections| ... } ⇒ Enumerator<CollectionReference> Also known as: collections

Retrieves a list of 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

Yields:

  • (collections) —

    The block for accessing the collections.

Yield Parameters:

Returns:



91
92
93
94
95
96
97
98
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 91

def cols
  ensure_service!

  return enum_for(:cols) unless block_given?

  collection_ids = service.list_collections path
  collection_ids.each { |collection_id| yield col(collection_id) }
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:



238
239
240
241
242
243
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 238

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

    Whether the document must exist. When true, the document must exist or an error is raised. Default is false. Optional.

  • update_time (Time) —

    When set, the document must have been last updated at that time. Optional.

Returns:



450
451
452
453
454
455
456
457
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 450

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.



48
49
50
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 48

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.



57
58
59
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 57

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:



145
146
147
148
149
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 145

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


176
177
178
179
180
181
182
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 176

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:



200
201
202
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 200

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

    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:



317
318
319
320
321
322
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 317

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

    When set, the document must have been last updated at that time. Optional.

Returns:



399
400
401
402
403
404
405
406
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 399

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