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



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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:



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

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



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

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:



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

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



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

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