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.

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

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



217
218
219
220
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 217

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.

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

    The document data.



135
136
137
138
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 135

def data
  return nil if missing?
  Convert.fields_to_hash grpc.fields, ref.client
end

#document_id ⇒ String

The document identifier for the document snapshot.

Returns:

  • (String) —

    document identifier.



52
53
54
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 52

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.



61
62
63
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 61

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.



264
265
266
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 264

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.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 189

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

  nodes = field_path.fields.map(&:to_sym)
  selected_data = data

  nodes.each do |node|
    unless selected_data.is_a? Hash
      fail ArgumentError,
           "#{field_path.formatted_string} is not contained in the data"
    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.



283
284
285
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 283

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:



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

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



244
245
246
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 244

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:



91
92
93
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 91

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



231
232
233
234
 
# File 'lib/google/cloud/firestore/document_snapshot.rb', line 231

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