Cloud Firestore API - Class Google::Cloud::Firestore::Client (v2.11.0)

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

Client

The Cloud Firestore Client used is to access and manipulate the collections and documents in the Firestore database.

Inherits

  • Object

Example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

firestore.batch do |b|
  b.update(nyc_ref, { name: "New York City" })
end

Methods

#batch

def batch() { |batch| ... } -> CommitResponse

Perform multiple changes at the same time.

All changes are accumulated in memory until the block completes. Unlike transactions, batches don't lock on document reads, should only fail if users provide preconditions, and are not automatically retried. See Batch.

Yields
  • (batch) — The block for reading data and making changes.
Yield Parameter
  • batch (Batch) — The write batch object for making changes.
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.batch do |b|
  # Set the data for NYC
  b.set("cities/NYC", { name: "New York City" })

  # Update the population for SF
  b.update("cities/SF", { population: 1000000 })

  # Delete LA
  b.delete("cities/LA")
end

#col

def col(collection_path) -> CollectionReference
Aliases

Retrieves a collection.

Parameter
  • collection_path (String) — A string representing the path of the collection, relative to the document root of the database.
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the cities collection
cities_col = firestore.col "cities"

# Get the document for NYC
nyc_ref = cities_col.doc "NYC"

#col_group

def col_group(collection_id) -> CollectionGroup
Aliases

Creates and returns a new collection group that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.

Parameter
  • collection_id (String) — Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash (/).
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the cities collection group query
col_group = firestore.col_group "cities"

col_group.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#collection

def collection(collection_path) -> CollectionReference
Alias Of: #col

Retrieves a collection.

Parameter
  • collection_path (String) — A string representing the path of the collection, relative to the document root of the database.
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the cities collection
cities_col = firestore.col "cities"

# Get the document for NYC
nyc_ref = cities_col.doc "NYC"

#collection_group

def collection_group(collection_id) -> CollectionGroup
Alias Of: #col_group

Creates and returns a new collection group that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.

Parameter
  • collection_id (String) — Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash (/).
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the cities collection group query
col_group = firestore.col_group "cities"

col_group.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#collections

def collections(read_time: nil, &block) { |collection| ... } -> Enumerator<CollectionReference>
Alias Of: #cols

Retrieves an enumerator for the root collections.

Parameter
  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (collections) — The block for accessing the collections.
Yield Parameter
Returns
  • (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the root collections
firestore.cols.each do |col|
  puts col.collection_id
end
 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
read_time = Time.now

# Get the root collections
firestore.cols(read_time: read_time).each do |col|
  puts col.collection_id
end

#cols

def cols(read_time: nil, &block) { |collection| ... } -> Enumerator<CollectionReference>
Aliases

Retrieves an enumerator for the root collections.

Parameter
  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (collections) — The block for accessing the collections.
Yield Parameter
Returns
  • (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the root collections
firestore.cols.each do |col|
  puts col.collection_id
end
 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
read_time = Time.now

# Get the root collections
firestore.cols(read_time: read_time).each do |col|
  puts col.collection_id
end

#database_id

def database_id() -> String

The database identifier for the Cloud Firestore database.

Returns
  • (String) — database identifier.

#doc

def doc(document_path) -> DocumentReference
Aliases

Retrieves a document reference.

Parameter
  • document_path (String) — A string representing the path of the document, relative to the document root of the database.
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document
nyc_ref = firestore.doc "cities/NYC"

puts nyc_ref.document_id

#document

def document(document_path) -> DocumentReference
Alias Of: #doc

Retrieves a document reference.

Parameter
  • document_path (String) — A string representing the path of the document, relative to the document root of the database.
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document
nyc_ref = firestore.doc "cities/NYC"

puts nyc_ref.document_id

#document_id

def document_id() -> FieldPath

Creates a field path object representing the sentinel ID of a document. It can be used in queries to sort or filter by the document ID. See FieldPath.document_id.

Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.order(firestore.document_id)
                  .start_at("NYC")

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#field_array_delete

def field_array_delete(*values) -> FieldValue

Creates a sentinel value to indicate the removal of the given values with an array.

Parameter
  • values (Object) — The values to remove from the array. Required.
Returns
  • (FieldValue) — The array delete field value object.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

array_delete = firestore.field_array_delete 7, 8, 9

nyc_ref.update({ name: "New York City",
                 lucky_numbers: array_delete })

#field_array_union

def field_array_union(*values) -> FieldValue

Creates a sentinel value to indicate the union of the given values with an array.

Parameter
  • values (Object) — The values to add to the array. Required.
Returns
  • (FieldValue) — The array union field value object.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

array_union = firestore.field_array_union 1, 2, 3

nyc_ref.update({ name: "New York City",
                 lucky_numbers: array_union })

#field_delete

def field_delete() -> FieldValue

Creates a field value object representing the deletion of a field in document data.

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

#field_increment

def field_increment(value) -> FieldValue

Creates a sentinel value to indicate the addition the given value to the field's current value.

If the field's current value is not an integer or a double value (Numeric), or if the field does not yet exist, the transformation will set the field to the given value. If either of the given value or the current field value are doubles, both values will be interpreted as doubles. Double arithmetic and representation of double values follow IEEE 754 semantics. If there is positive/negative integer overflow, the field is resolved to the largest magnitude positive/negative integer.

Parameter
  • value (Numeric) — The value to add to the given value. Required.
Returns
  • (FieldValue) — The increment field value object.
Raises
  • (ArgumentError) — if the value is not a Numeric.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to increment by 1.
increment_value = firestore.field_increment 1

nyc_ref.update({ name: "New York City",
                 population: increment_value })

#field_maximum

def field_maximum(value) -> FieldValue

Creates a sentinel value to indicate the setting the field to the maximum of its current value and the given value.

If the field is not an integer or double (Numeric), or if the field does not yet exist, the transformation will set the field to the given value. If a maximum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the larger operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and zero input value is always the stored value. The maximum of any numeric value x and NaN is NaN.

Parameter
  • value (Numeric) — The value to compare against the given value to calculate the maximum value to set. Required.
Returns
  • (FieldValue) — The maximum field value object.
Raises
  • (ArgumentError) — if the value is not a Numeric.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to be at maximum 4,000,000.
maximum_value = firestore.field_maximum 4000000

nyc_ref.update({ name: "New York City",
                 population: maximum_value })

#field_minimum

def field_minimum(value) -> FieldValue

Creates a sentinel value to indicate the setting the field to the minimum of its current value and the given value.

If the field is not an integer or double (Numeric), or if the field does not yet exist, the transformation will set the field to the input value. If a minimum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the smaller operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and zero input value is always the stored value. The minimum of any numeric value x and NaN is NaN.

Parameter
  • value (Numeric) — The value to compare against the given value to calculate the minimum value to set. Required.
Returns
  • (FieldValue) — The minimum field value object.
Raises
  • (ArgumentError) — if the value is not a Numeric.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to be at minimum 1,000,000.
minimum_value = firestore.field_minimum 1000000

nyc_ref.update({ name: "New York City",
                 population: minimum_value })

#field_path

def field_path(*fields) -> FieldPath

Creates a field path object representing a nested field for document data.

Parameter
  • fields (String, Symbol, Array<String|Symbol>) — One or more strings representing the path of the data to select. Each field must be provided separately.
Returns
Example 
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"

#field_server_time

def field_server_time() -> FieldValue

Creates a field value object representing set a field's value to the server timestamp when accessing the document data.

Returns
  • (FieldValue) — The server time field value object.
Example 
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 })

#find

def find(*docs, field_mask: nil, read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Alias Of: #get_all

Retrieves a list of document snapshots.

Parameters
  • docs (String, DocumentReference, Array<String|DocumentReference>) — One or more strings representing the path of the document, or document reference objects.
  • field_mask (Array<String|FieldPath>) (defaults to: nil) — One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.

    A field path can either be a FieldPath object, or a dotted 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. (See #field_path.)

  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (documents) — The block for accessing the document snapshots.
Yield Parameter
Returns
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a field mask:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, field_mask: [:population]).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a read_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

read_time = Time.now

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, read_time: read_time).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#get_all

def get_all(*docs, field_mask: nil, read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Aliases

Retrieves a list of document snapshots.

Parameters
  • docs (String, DocumentReference, Array<String|DocumentReference>) — One or more strings representing the path of the document, or document reference objects.
  • field_mask (Array<String|FieldPath>) (defaults to: nil) — One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.

    A field path can either be a FieldPath object, or a dotted 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. (See #field_path.)

  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (documents) — The block for accessing the document snapshots.
Yield Parameter
Returns
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a field mask:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, field_mask: [:population]).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a read_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

read_time = Time.now

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, read_time: read_time).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#get_docs

def get_docs(*docs, field_mask: nil, read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Alias Of: #get_all

Retrieves a list of document snapshots.

Parameters
  • docs (String, DocumentReference, Array<String|DocumentReference>) — One or more strings representing the path of the document, or document reference objects.
  • field_mask (Array<String|FieldPath>) (defaults to: nil) — One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.

    A field path can either be a FieldPath object, or a dotted 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. (See #field_path.)

  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (documents) — The block for accessing the document snapshots.
Yield Parameter
Returns
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a field mask:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, field_mask: [:population]).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a read_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

read_time = Time.now

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, read_time: read_time).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#get_documents

def get_documents(*docs, field_mask: nil, read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Alias Of: #get_all

Retrieves a list of document snapshots.

Parameters
  • docs (String, DocumentReference, Array<String|DocumentReference>) — One or more strings representing the path of the document, or document reference objects.
  • field_mask (Array<String|FieldPath>) (defaults to: nil) — One or more field path values, representing the fields of the document to be returned. If a document has a field that is not present in this mask, that field will not be returned in the response. All fields are returned when the mask is not set.

    A field path can either be a FieldPath object, or a dotted 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. (See #field_path.)

  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (documents) — The block for accessing the document snapshots.
Yield Parameter
Returns
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a field mask:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, field_mask: [:population]).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Get docs using a read_time:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

read_time = Time.now

# Get and print city documents
cities = ["cities/NYC", "cities/SF", "cities/LA"]
firestore.get_all(cities, read_time: read_time).each do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

#list_collections

def list_collections(read_time: nil, &block) { |collection| ... } -> Enumerator<CollectionReference>
Alias Of: #cols

Retrieves an enumerator for the root collections.

Parameter
  • read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
Yields
  • (collections) — The block for accessing the collections.
Yield Parameter
Returns
  • (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get the root collections
firestore.cols.each do |col|
  puts col.collection_id
end
 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
read_time = Time.now

# Get the root collections
firestore.cols(read_time: read_time).each do |col|
  puts col.collection_id
end

#project_id

def project_id() -> String

The project identifier for the Cloud Firestore database.

Returns
  • (String) — project identifier.

#read_only_transaction

def read_only_transaction(read_time: nil) { |transaction| ... } -> Object

Create a transaction to perform multiple reads that are executed atomically at a single logical point in time in a database.

All changes are accumulated in memory until the block completes. Transactions will be automatically retried when documents change before the transaction is committed. See Transaction.

Parameter
  • read_time (Time) (defaults to: nil) — The maximum number of retries for transactions failed due to errors. Default is 5. Optional.
Yields
  • (transaction) — The block for reading data.
Yield Parameter
  • transaction (Transaction) — The transaction object for making changes.
Returns
  • (Object) — The return value of the provided yield block
Example

Read only transaction with read time

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

read_time = Time.now

firestore.read_only_transaction(read_time: read_time) do |tx|
  # Get a document snapshot
  nyc_snap = tx.get nyc_ref
end

#transaction

def transaction(max_retries: nil, commit_response: nil) { |transaction| ... } -> Object, CommitResponse

Create a transaction to perform multiple reads and writes that are executed atomically at a single logical point in time in a database.

All changes are accumulated in memory until the block completes. Transactions will be automatically retried when documents change before the transaction is committed. See Transaction.

Parameters
  • max_retries (Integer) (defaults to: nil) — The maximum number of retries for transactions failed due to errors. Default is 5. Optional.
  • commit_response (Boolean) (defaults to: nil) — When true, the return value from this method will be a Google::Cloud::Firestore::CommitResponse object with a commit_time attribute. Otherwise, the return value from this method will be the return value of the provided yield block. Default is false. Optional.
Yields
  • (transaction) — The block for reading data and making changes.
Yield Parameter
  • transaction (Transaction) — The transaction object for making changes.
Returns
  • (Object, CommitResponse) — The return value of the provided yield block, or if commit_response is provided and true, the CommitResponse object from the commit operation.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

firestore.transaction do |tx|
  # Set the data for NYC
  tx.set("cities/NYC", { name: "New York City" })

  # Update the population for SF
  tx.update("cities/SF", { population: 1000000 })

  # Delete LA
  tx.delete("cities/LA")
end