Class: Google::Cloud::Firestore::DocumentReference

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/document_reference.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"

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:



119
120
121
122
123
124
125
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 119

def col collection_path
  if collection_path.to_s.split("/").count.even?
    fail 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

Retrieves a list of 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:



90
91
92
93
94
95
96
97
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 90

def cols
  ensure_service!

  return enum_for(:cols) unless block_given?

  collection_ids = service.list_collections path
  collection_ids.each { |collection_id| yield col(collection_id) }
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:



203
204
205
206
207
208
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 203

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

    Whether the document must exist. When true, the document must exist or an error is raised. Default is false. Optional.

  • update_time (Time) —

    When set, the document must have been last updated at that time. Optional.

Returns:



417
418
419
420
421
422
423
424
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 417

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.



47
48
49
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 47

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.



56
57
58
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 56

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:



144
145
146
147
148
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 144

def get
  ensure_client!

  client.get_all([self]).first
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:



165
166
167
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 165

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

    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:



282
283
284
285
286
287
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 282

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 = Google::Cloud::Firestore::FieldPath.new(
  :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) —

    When set, the document must have been last updated at that time. Optional.

Returns:



366
367
368
369
370
371
372
373
 
# File 'lib/google/cloud/firestore/document_reference.rb', line 366

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