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:



123
124
125
126
127
128
129
 
# 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

#cols {|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

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.



94
95
96
97
98
99
100
 
# 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

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



240
241
242
243
244
245
 
# 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) ⇒ 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:



452
453
454
455
456
457
458
459
 
# 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 ⇒ 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:



148
149
150
151
152
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 148

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) 


178
179
180
181
182
183
184
 
# 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

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



202
203
204
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 202

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:



319
320
321
322
323
324
 
# 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) ⇒ 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:



401
402
403
404
405
406
407
408
 
# 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