Cloud Firestore API - Class Google::Cloud::Firestore::Query (v3.1.0)

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

Query

Represents a query to the Firestore API.

Instances of this class are immutable. All methods that refine the query return new instances.

Inherits

  • Object

Examples

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).select(:population)

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

Listen to a query for changes:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).order(:population, :desc)

listener = query.listen do |snapshot|
  puts "The query snapshot has #{snapshot.docs.count} documents "
  puts "and has #{snapshot.changes.count} changes."
end

# When ready, stop the listen operation and close the stream.
listener.stop

Methods

.from_json

def self.from_json(json, client) -> Query

Deserializes a JSON text string serialized from this class and returns it as a new instance. See also #to_json.

Parameters
Returns
  • (Query) — A new query equal to the original query used to create the JSON text string.
Raises
  • (ArgumentError)
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).select(:population)

json = query.to_json

new_query = Google::Cloud::Firestore::Query.from_json json, firestore

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

#aggregate_query

def aggregate_query() -> AggregateQuery

Creates an AggregateQuery object for the query.

Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create an aggregate query
aggregate_query = query.aggregate_query

#end_at

def end_at(*values) -> Query

Ends query results at a set of field values. The field values can be specified explicitly as arguments, or can be specified implicitly by providing a DocumentSnapshot object instead. The result set will include the document specified by values.

If the current query already has specified end_before or end_at, this will overwrite it.

The values are associated with the field paths that have been provided to order, and must match the same sort order. An ArgumentError will be raised if more explicit values are given than are present in order.

Parameter
  • values (DocumentSnapshot, Object, Array<Object>) — The field values to end the query at.
Returns
  • (Query) — New query with end_at called on it.
Raises
  • (ArgumentError)
Examples

Ending a query at a document reference id

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.order(firestore.document_id)
                  .end_at(nyc_doc_id)

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

Ending a query at a document reference object

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"
nyc_doc_id = "NYC"
nyc_ref = cities_col.doc nyc_doc_id

# Create a query
query = cities_col.order(firestore.document_id)
                  .end_at(nyc_ref)

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

Ending a query at multiple explicit values

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(:population, :desc)
                  .order(:name)
                  .end_at(1000000, "New York City")

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

Ending a query at a DocumentSnapshot

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Create a query
query = cities_col.order(:population, :desc)
                  .order(:name)
                  .end_at(nyc_snap)

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

#end_before

def end_before(*values) -> Query

Ends query results before a set of field values. The field values can be specified explicitly as arguments, or can be specified implicitly by providing a DocumentSnapshot object instead. The result set will not include the document specified by values.

If the current query already has specified end_before or end_at, this will overwrite it.

The values are associated with the field paths that have been provided to order, and must match the same sort order. An ArgumentError will be raised if more explicit values are given than are present in order.

Parameter
  • values (DocumentSnapshot, Object, Array<Object>) — The field values to end the query before.
Returns
  • (Query) — New query with end_before called on it.
Raises
  • (ArgumentError)
Examples

Ending a query before a document reference id

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.order(firestore.document_id)
                  .end_before(nyc_doc_id)

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

Ending a query before a document reference object

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"
nyc_doc_id = "NYC"
nyc_ref = cities_col.doc nyc_doc_id

# Create a query
query = cities_col.order(firestore.document_id)
                  .end_before(nyc_ref)

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

Ending a query before multiple explicit values

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(:population, :desc)
                  .order(:name)
                  .end_before(1000000, "New York City")

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

Ending a query before a DocumentSnapshot

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Create a query
query = cities_col.order(:population, :desc)
                  .order(:name)
                  .end_before(nyc_snap)

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

#explain

def explain(read_time: false, analyze: false) -> QueryExplainResult

Retrieves the query explanation for the query. By default the query is only planned, not executed. returning only metrics from the planning stages. If analyze is set to true the query will be planned and executed, returning the full query results alongside both planning and execution stage metrics.

Unlike the Enumerator object that is returned from the Query#get, iterating over QueryExplainResult multiple times will not result in multiple requests to the server. The first set of results will be saved and re-used instead. This is to avoid the situations where the metrics change unpredictably when results are looked at.

Parameters
  • read_time (Time) (defaults to: false) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
  • analyze (Boolean) (defaults to: false) — Whether to execute the query and return the execution stage metrics in addition to planning metrics. If set to false the query will be planned only and will return planning stage metrics without results. If set to true the query will be executed, and will return the query results, planning stage metrics, and execution stage metrics. Defaults to false.
Returns
Examples

Iterating over results multiple times

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).where(:population, :>, 100000)
explanation_result = query.explain analyze: true
results = explanation_result.to_a
results_2 = explanation_result.to_a # same results, no re-query

Getting only the planning stage metrics for the query

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).where(:population, :>, 100000)

# Get the execution plan without running the query
explain_result = query.explain
metrics = explain_result.explain_metrics
puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary

Getting planning and execution stage metrics, as well as query results

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).where(:population, :>, 100000)

# Run the query and return metrics from the planning and execution stages
explain_result = query.explain analyze: true
metrics = explain_result.explain_metrics
puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
puts "Results returned: #{metrics.execution_stats.results_returned}" if metrics&.execution_stats
results = explain_result.to_a

#get

def get(read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Aliases

Retrieves document snapshots for the query.

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
  • (documents) — The block for accessing the document snapshots.
Yield Parameter
Returns
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.select(:population)

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

Get query with read time

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.select(:population)

read_time = Time.now

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

#limit

def limit(num) -> Query

Limits a query to return only the first matching documents.

If the current query already has a limit set, this will overwrite it.

Parameter
  • num (Integer) — The maximum number of results to return.
Returns
  • (Query) — New query with limit called on it.
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(:name, :desc).offset(10).limit(5)

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

#limit_to_last

def limit_to_last(num) -> Query

Limits a query to return only the last matching documents.

You must specify at least one "order by" clause for limitToLast queries. (See #order.)

Results for limit_to_last queries are only available once all documents are received. Hence, limit_to_last queries cannot be streamed using #listen.

Parameter
  • num (Integer) — The maximum number of results to return.
Returns
  • (Query) — New query with limit_to_last called on it.
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(:name, :desc).limit_to_last(5)

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

#listen

def listen(&callback) { |snapshot| ... } -> QueryListener
Aliases

Listen to this query for changes.

Yields
  • (callback) — The block for accessing the query snapshot.
Yield Parameter
Returns
Raises
  • (ArgumentError)
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).order(:population, :desc)

listener = query.listen do |snapshot|
  puts "The query snapshot has #{snapshot.docs.count} documents "
  puts "and has #{snapshot.changes.count} changes."
end

# When ready, stop the listen operation and close the stream.
listener.stop

#offset

def offset(num) -> Query

Skips to an offset in a query. If the current query already has specified an offset, this will overwrite it.

Parameter
  • num (Integer) — The number of results to skip.
Returns
  • (Query) — New query with offset called on it.
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.limit(5).offset(10)

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

#on_snapshot

def on_snapshot(&callback) { |snapshot| ... } -> QueryListener
Alias Of: #listen

Listen to this query for changes.

Yields
  • (callback) — The block for accessing the query snapshot.
Yield Parameter
Returns
Raises
  • (ArgumentError)
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).order(:population, :desc)

listener = query.listen do |snapshot|
  puts "The query snapshot has #{snapshot.docs.count} documents "
  puts "and has #{snapshot.changes.count} changes."
end

# When ready, stop the listen operation and close the stream.
listener.stop

#order

def order(field, direction = :asc) -> Query
Aliases

Specifies an "order by" clause on a field.

Parameters
  • field (FieldPath, String, Symbol) — A field path to order 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.

  • direction (String, Symbol) — The direction to order the results by. Values that start with "a" are considered ascending. Values that start with "d" are considered descending. Default is ascending. Optional.
Returns
  • (Query) — New query with order called on it.
Examples 
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(:name)

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

Order by name descending:

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(:name, :desc)

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

#order_by

def order_by(field, direction = :asc) -> Query
Alias Of: #order

Specifies an "order by" clause on a field.

Parameters
  • field (FieldPath, String, Symbol) — A field path to order 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.

  • direction (String, Symbol) — The direction to order the results by. Values that start with "a" are considered ascending. Values that start with "d" are considered descending. Default is ascending. Optional.
Returns
  • (Query) — New query with order called on it.
Examples 
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(:name)

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

Order by name descending:

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(:name, :desc)

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

#run

def run(read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Alias Of: #get

Retrieves document snapshots for the query.

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
  • (documents) — The block for accessing the document snapshots.
Yield Parameter
Returns
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.select(:population)

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

Get query with read time

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.select(:population)

read_time = Time.now

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

#select

def select(*fields) -> Query

Restricts documents matching the query to return only data for the provided fields.

Parameter
  • fields (FieldPath, String, Symbol, Array<FieldPath|String|Symbol>) — A field path to filter results with and return only the specified fields. One or more field paths can be specified.

    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.

Returns
  • (Query) — New query with select called on it.
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.select(:population)

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

#start_after

def start_after(*values) -> Query

Starts query results after a set of field values. The field values can be specified explicitly as arguments, or can be specified implicitly by providing a DocumentSnapshot object instead. The result set will not include the document specified by values.

If the current query already has specified start_at or start_after, this will overwrite it.

The values are associated with the field paths that have been provided to order, and must match the same sort order. An ArgumentError will be raised if more explicit values are given than are present in order.

Parameter
  • values (DocumentSnapshot, Object, Array<Object>) — The field values to start the query after.
Returns
  • (Query) — New query with start_after called on it.
Raises
  • (ArgumentError)
Examples

Starting a query after a document reference id

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.order(firestore.document_id)
                  .start_after(nyc_doc_id)

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

Starting a query after a document reference object

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"
nyc_doc_id = "NYC"
nyc_ref = cities_col.doc nyc_doc_id

# Create a query
query = cities_col.order(firestore.document_id)
                  .start_after(nyc_ref)

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

Starting a query after multiple explicit values

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(:population, :desc)
                  .order(:name)
                  .start_after(1000000, "New York City")

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

Starting a query after a DocumentSnapshot

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Create a query
query = cities_col.order(:population, :desc)
                  .order(:name)
                  .start_after(nyc_snap)

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

#start_at

def start_at(*values) -> Query

Starts query results at a set of field values. The field values can be specified explicitly as arguments, or can be specified implicitly by providing a DocumentSnapshot object instead. The result set will include the document specified by values.

If the current query already has specified start_at or start_after, this will overwrite it.

The values are associated with the field paths that have been provided to order, and must match the same sort order. An ArgumentError will be raised if more explicit values are given than are present in order.

Parameter
  • values (DocumentSnapshot, Object, Array<Object>) — The field values to start the query at.
Returns
  • (Query) — New query with start_at called on it.
Raises
  • (ArgumentError)
Examples

Starting a query at a document reference id

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

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

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

Starting a query at a document reference object

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"
nyc_doc_id = "NYC"
nyc_ref = cities_col.doc nyc_doc_id

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

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

Starting a query at multiple explicit values

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(:population, :desc)
                  .order(:name)
                  .start_at(1000000, "New York City")

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

Starting a query at a DocumentSnapshot

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Get a document snapshot
nyc_snap = firestore.doc("cities/NYC").get

# Create a query
query = cities_col.order(:population, :desc)
                  .order(:name)
                  .start_at(nyc_snap)

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

#to_json

def to_json(options = nil) -> String

Serializes the instance to a JSON text string. See also Query.from_json.

Returns
  • (String) — A JSON text string.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).select(:population)

json = query.to_json

new_query = Google::Cloud::Firestore::Query.from_json json, firestore

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

#where

def where(filter) -> Query
def where(field, operator, value) -> Query

Adds filter to the where clause

@param filter [::Google::Cloud::Firestore::Filter]

Overloads 
def where(filter) -> Query
Pass Firestore::Filter to where via field_or_filter argument. 
def where(field, operator, value) -> Query
Pass arguments to where via positional arguments.
Parameters
  • 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
  • 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
Returns
  • (Query) — New query with where called on it.
Examples 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a query
query = cities_col.where(:population, :>=, 1000000)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end
 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

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

# Create a filter
filter = Filter.create(:population, :>=, 1000000)

# Add filter to where clause
query = query.where filter

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