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.
- json (String) — A JSON text string serialized using #to_json.
- client (Google::Cloud::Firestore::Client) — A connected client instance.
- (Query) — A new query equal to the original query used to create the JSON text string.
- (ArgumentError)
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.
- (AggregateQuery) — New empty aggregate query.
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
.
- values (DocumentSnapshot, Object, Array<Object>) — The field values to end the query at.
-
(Query) — New query with
end_at
called on it.
- (ArgumentError)
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
.
- values (DocumentSnapshot, Object, Array<Object>) — The field values to end the query before.
-
(Query) — New query with
end_before
called on it.
- (ArgumentError)
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
#get
def get(read_time: nil) { |document| ... } -> Enumerator<DocumentSnapshot>
Retrieves document snapshots for the query.
- 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>) — A list of document snapshots.
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.
- num (Integer) — The maximum number of results to return.
-
(Query) — New query with
limit
called on it.
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.
- num (Integer) — The maximum number of results to return.
-
(Query) — New query with
limit_to_last
called on it.
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
Listen to this query for changes.
- (callback) — The block for accessing the query snapshot.
- snapshot (QuerySnapshot) — A query snapshot.
- (QueryListener) — The ongoing listen operation on the query.
- (ArgumentError)
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.
- num (Integer) — The number of results to skip.
-
(Query) — New query with
offset
called on it.
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
Listen to this query for changes.
- (callback) — The block for accessing the query snapshot.
- snapshot (QuerySnapshot) — A query snapshot.
- (QueryListener) — The ongoing listen operation on the query.
- (ArgumentError)
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
Specifies an "order by" clause on a field.
-
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 considereddescending
. Default isascending
. Optional.
-
(Query) — New query with
order
called on it.
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
Specifies an "order by" clause on a field.
-
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 considereddescending
. Default isascending
. Optional.
-
(Query) — New query with
order
called on it.
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>
Retrieves document snapshots for the query.
- 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>) — A list of document snapshots.
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.
-
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.
-
(Query) — New query with
select
called on it.
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
.
- values (DocumentSnapshot, Object, Array<Object>) — The field values to start the query after.
-
(Query) — New query with
start_after
called on it.
- (ArgumentError)
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
.
- values (DocumentSnapshot, Object, Array<Object>) — The field values to start the query at.
-
(Query) — New query with
start_at
called on it.
- (ArgumentError)
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.
- (String) — A JSON text string.
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]
def where(filter) -> Query
where
via field_or_filter argument.
def where(field, operator, value) -> Query
where
via positional arguments.
-
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
-
(Query) — New query with
where
called on it.
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