Class: Google::Cloud::Firestore::DocumentSnapshot

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/document_snapshot.rb

Overview

DocumentSnapshot

A document snapshot object is an immutable representation for a document in a Cloud Firestore database.

The snapshot can reference a non-existing document.

See Google::Cloud::Firestore::DocumentReference#get, Google::Cloud::Firestore::DocumentReference#listen, Query#get, Query#listen, and QuerySnapshot#docs.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Get the document data
nyc_snap[:population] #=> 1000000

Listen to a document reference for changes:

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

Access collapse

Data collapse

Instance Method Summary collapse

Instance Method Details

#created_at ⇒ Time Also known as: create_time

The time at which the document was created.

This value increases when a document is deleted then recreated.

Returns:

  • (Time) —

    The time the document was was created



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

def created_at
  return nil if missing?
  Convert.timestamp_to_time grpc.create_time
end

#data ⇒ Hash? Also known as: fields

Retrieves the document data. When the document exists the data hash is frozen and will not allow any changes. When the document does not exist nil will be returned.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

nyc_snap = firestore.doc("cities/NYC").get

# Get the document data
nyc_snap.data[:population] #=> 1000000

Returns:

  • (Hash, nil) —

    The document data.



156
157
158
159
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 156

def data
  return nil if missing?
  @data ||= Convert.fields_to_hash(grpc.fields, ref.client).freeze
end

#document_id ⇒ String

The document identifier for the document snapshot.

Returns:

  • (String) —

    document identifier.



71
72
73
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 71

def document_id
  ref.document_id
end

#document_path ⇒ String

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

Returns:

  • (String) —

    document path.



80
81
82
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 80

def document_path
  ref.document_path
end

#exists? ⇒ Boolean

Determines whether the document exists.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

nyc_snap = firestore.doc("cities/NYC").get

# Does NYC exist?
nyc_snap.exists? #=> true

Returns:

  • (Boolean) —

    Whether the document exists.



287
288
289
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 287

def exists?
  !missing?
end

#get(field_path) ⇒ Object Also known as: []

Retrieves the document data.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

nyc_snap = firestore.doc("cities/NYC").get

nyc_snap.get(:population) #=> 1000000

Accessing data using []:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

nyc_snap = firestore.doc("cities/NYC").get

nyc_snap[:population] #=> 1000000

Nested data can be accessing with field path:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

frank_snap = firestore.doc("users/frank").get

frank_snap.get("favorites.food") #=> "Pizza"

Nested data can be accessing with FieldPath object:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

user_snap = firestore.doc("users/frank").get

nested_field_path = firestore.field_path :favorites, :food
user_snap.get(nested_field_path) #=> "Pizza"

Parameters:

  • field_path (FieldPath, String, Symbol) —

    A field path representing the path of the data to select. A field path can represent as a string of individual fields joined by ".". Fields containing ~, *, /, [, ], and . cannot be in a dotted string, and should provided using a FieldPath object instead.

Returns:

  • (Object) —

    The data at the field path.



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 210

def get field_path
  unless field_path.is_a? FieldPath
    field_path = FieldPath.parse field_path
  end

  nodes = field_path.fields.map(&:to_sym)
  return ref if nodes == [:__name__]

  selected_data = data
  nodes.each do |node|
    unless selected_data.is_a? Hash
      err_msg = "#{field_path.formatted_string} is not " \
                "contained in the data"
      raise ArgumentError, err_msg
    end
    selected_data = selected_data[node]
  end
  selected_data
end

#missing? ⇒ Boolean

Determines whether the document is missing.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

atlantis_snap = firestore.doc("cities/Atlantis").get

# Does Atlantis exist?
atlantis_snap.missing? #=> true

Returns:

  • (Boolean) —

    Whether the document is missing.



306
307
308
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 306

def missing?
  grpc.nil?
end

#parent ⇒ CollectionReference

The collection the document snapshot belongs to.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Get the document's parent collection
cities_col = nyc_snap.parent

Returns:



131
132
133
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 131

def parent
  ref.parent
end

#read_at ⇒ Time Also known as: read_time

The time at which the document was read.

This value is set even if the document does not exist.

Returns:

  • (Time) —

    The time the document was read



267
268
269
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 267

def read_at
  @read_at
end

#ref ⇒ DocumentReference Also known as: reference

The document reference object for the data.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Get the document reference
nyc_ref = nyc_snap.ref

Returns:



110
111
112
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 110

def ref
  @ref
end

#updated_at ⇒ Time Also known as: update_time

The time at which the document was last changed.

This value is initally set to the created_at on document creation, and increases each time the document is updated.

Returns:

  • (Time) —

    The time the document was was last changed



254
255
256
257
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 254

def updated_at
  return nil if missing?
  Convert.timestamp_to_time grpc.update_time
end