Cloud Firestore API - Class Google::Cloud::Firestore::DocumentSnapshot (v2.12.0)

Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::DocumentSnapshot.

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.

Inherits

  • Object

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

Methods

#[]

def [](field_path) -> Object
Alias Of: #get

Retrieves the document data.

Parameter
  • 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.
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"

#create_time

def create_time() -> Time
Alias Of: #created_at

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

#created_at

def created_at() -> Time
Aliases

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

#data

def data() -> Hash, nil
Aliases

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.

Returns
  • (Hash, nil) — The document data.
Example 
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

#document_id

def document_id() -> String

The document identifier for the document snapshot.

Returns
  • (String) — document identifier.

#document_path

def document_path() -> String

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

Returns
  • (String) — document path.

#exists?

def exists?() -> Boolean

Determines whether the document exists.

Returns
  • (Boolean) — Whether the document exists.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

#fields

def fields() -> Hash, nil
Alias Of: #data

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.

Returns
  • (Hash, nil) — The document data.
Example 
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

#get

def get(field_path) -> Object
Aliases

Retrieves the document data.

Parameter
  • 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.
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"

#missing?

def missing?() -> Boolean

Determines whether the document is missing.

Returns
  • (Boolean) — Whether the document is missing.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

#parent

def parent() -> CollectionReference

The collection the document snapshot belongs to.

Returns
Example 
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

#read_at

def read_at() -> Time
Aliases

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

#read_time

def read_time() -> Time
Alias Of: #read_at

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

#ref

def ref() -> DocumentReference
Aliases

The document reference object for the data.

Returns
Example 
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

#reference

def reference() -> DocumentReference
Alias Of: #ref

The document reference object for the data.

Returns
Example 
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

#update_time

def update_time() -> Time
Alias Of: #updated_at

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

#updated_at

def updated_at() -> Time
Aliases

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