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.
- (batch) — The block for reading data and making changes.
- batch (Batch) — The write batch object for making changes.
- (CommitResponse) — The response from committing the changes.
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
#bulk_writer
def bulk_writer(request_threads: nil, batch_threads: nil, retries: nil) -> Google::Cloud::Firestore::BulkWriter
Create a bulk writer to perform multiple writes that are executed parallely.
be retried (with exponential delay) before being marked as failure. Max attempts are 15. Optional
- request_threads (Integer) (defaults to: nil) — The number of threads used for handling requests. Default is 2. Optional.
- batch_threads (Integer) (defaults to: nil) — The number of threads used for processing batches. Default is 4. Optional.
- retries (Integer) (defaults to: nil) — The number of times a failed write request will
- (Google::Cloud::Firestore::BulkWriter) — Returns an object of bulk writer.
Initializing a BulkWriter with all the configurations.
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new bw = firestore.bulk_writer bulk_write_result = bw.create "doc_ref", request_threads: 4, batch_threads: 10, retries: 10
#col
def col(collection_path) -> CollectionReference
Retrieves a collection.
- collection_path (String) — A string representing the path of the collection, relative to the document root of the database.
- (CollectionReference) — A collection.
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
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.
-
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 (
/
).
- (CollectionGroup) — The created collection group.
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
Retrieves a collection.
- collection_path (String) — A string representing the path of the collection, relative to the document root of the database.
- (CollectionReference) — A collection.
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
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.
-
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 (
/
).
- (CollectionGroup) — The created collection group.
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>
Retrieves an enumerator for the root collections.
- read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
- (collections) — The block for accessing the collections.
- collection (CollectionReference) — A collection reference object.
- (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
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>
Retrieves an enumerator for the root collections.
- read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
- (collections) — The block for accessing the collections.
- collection (CollectionReference) — A collection reference object.
- (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
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.
- (String) — database identifier.
#doc
def doc(document_path) -> DocumentReference
Retrieves a document reference.
- document_path (String) — A string representing the path of the document, relative to the document root of the database.
- (DocumentReference) — A document.
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
Retrieves a document reference.
- document_path (String) — A string representing the path of the document, relative to the document root of the database.
- (DocumentReference) — A document.
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.
- (FieldPath) — The field path object.
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.
- values (Object) — The values to remove from the array. Required.
- (FieldValue) — The array delete field value object.
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.
- values (Object) — The values to add to the array. Required.
- (FieldValue) — The array union field value object.
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.
- (FieldValue) — The delete field value object.
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.
- value (Numeric) — The value to add to the given value. Required.
- (FieldValue) — The increment field value object.
- (ArgumentError) — if the value is not a Numeric.
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.
- value (Numeric) — The value to compare against the given value to calculate the maximum value to set. Required.
- (FieldValue) — The maximum field value object.
- (ArgumentError) — if the value is not a Numeric.
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.
- value (Numeric) — The value to compare against the given value to calculate the minimum value to set. Required.
- (FieldValue) — The minimum field value object.
- (ArgumentError) — if the value is not a Numeric.
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.
- fields (String, Symbol, Array<String|Symbol>) — One or more strings representing the path of the data to select. Each field must be provided separately.
- (FieldPath) — The field path 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"
#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.
- (FieldValue) — The server time field value object.
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 })
#filter
def filter(field, operator, value) -> Google::Cloud::Firestore::Filter
Creates a filter object.
-
field (FieldPath, String, Symbol) — A field path to filter
results with.
If a FieldPath object is not provided then the field will be
treated as a dotted string, meaning the string represents individual
fields joined by ".". Fields containing
~
,*
,/
,[
,]
, and.
cannot be in a dotted string, and should provided using a FieldPath object instead. -
operator (String, Symbol) —
The operation to compare the field to. Acceptable values include:
- less than:
<
,lt
- less than or equal:
<=
,lte
- greater than:
>
,gt
- greater than or equal:
>=
,gte
- equal:
=
,==
,eq
,eql
,is
- not equal:
!=
- in:
in
- not in:
not-in
,not_in
- array contains:
array-contains
,array_contains
- less than:
-
value (Object) —
The value to compare the property to. Defaults to nil. Possible values are:
- Integer
- Float/BigDecimal
- String
- Boolean
- Array
- Date/Time
- StringIO
- Google::Cloud::Datastore::Key
- Google::Cloud::Datastore::Entity
- nil
- (Google::Cloud::Firestore::Filter) — New filter object.
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Create a filter filter = firestore.filter(:population, :>=, 1000000)
#find
def find(*docs, field_mask: nil, read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Retrieves a list of document snapshots.
- 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
- (documents) — The block for accessing the document snapshots.
- document (DocumentSnapshot) — A document snapshot.
- (Enumerator<DocumentSnapshot>) — document snapshots list.
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>
Retrieves a list of document snapshots.
- 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
- (documents) — The block for accessing the document snapshots.
- document (DocumentSnapshot) — A document snapshot.
- (Enumerator<DocumentSnapshot>) — document snapshots list.
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>
Retrieves a list of document snapshots.
- 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
- (documents) — The block for accessing the document snapshots.
- document (DocumentSnapshot) — A document snapshot.
- (Enumerator<DocumentSnapshot>) — document snapshots list.
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>
Retrieves a list of document snapshots.
- 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
- (documents) — The block for accessing the document snapshots.
- document (DocumentSnapshot) — A document snapshot.
- (Enumerator<DocumentSnapshot>) — document snapshots list.
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>
Retrieves an enumerator for the root collections.
- read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
- (collections) — The block for accessing the collections.
- collection (CollectionReference) — A collection reference object.
- (Enumerator<CollectionReference>) — An enumerator of collection references. If a block is provided, this is the same enumerator that is accessed through the block.
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.
- (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.
- read_time (Time) (defaults to: nil) — The maximum number of retries for transactions failed due to errors. Default is 5. Optional.
- (transaction) — The block for reading data.
- transaction (Transaction) — The transaction object for making changes.
- (Object) — The return value of the provided yield block
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.
- 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 aGoogle::Cloud::Firestore::CommitResponse
object with acommit_time
attribute. Otherwise, the return value from this method will be the return value of the provided yield block. Default isfalse
. Optional.
- (transaction) — The block for reading data and making changes.
- transaction (Transaction) — The transaction object for making changes.
-
(Object, CommitResponse) — The return value of the provided
yield block, or if
commit_response
is provided and true, theCommitResponse
object from the commit operation.
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