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

3.2.0 (latest) 3.1.1 3.0.0 2.16.1 2.15.1 2.14.0 2.13.1 2.12.0 2.11.0 2.10.1 2.9.1 2.8.0 2.7.2 2.6.6 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

```ruby
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:

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_to_json_instance_ "Google::Cloud::Firestore::Query#to_json (method)").
**Parameters**

- **json** (String) --- A JSON text string serialized using [#to_json](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_to_json_instance_ "Google::Cloud::Firestore::Query#to_json (method)").
- **client** ([Google::Cloud::Firestore::Client](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Client)) --- A connected client instance.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- A new query equal to the original query used to create the JSON text string.
**Raises**

- (ArgumentError)
**Example**

```ruby
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**

- ([AggregateQuery](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-AggregateQuery)) --- New empty aggregate query.
**Example**

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot "Google::Cloud::Firestore::DocumentSnapshot (class)") 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.

<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot), Object, Array\<Object\>) --- The field values to end the query at.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `end_at` called on it.
**Raises**

- (ArgumentError)
**Examples**

Ending a query at a document reference id

```ruby
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

```ruby
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

```ruby
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

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot "Google::Cloud::Firestore::DocumentSnapshot (class)") 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.

<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot), Object, Array\<Object\>) --- The field values to end the query before.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `end_before` called on it.
**Raises**

- (ArgumentError)
**Examples**

Ending a query before a document reference id

```ruby
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

```ruby
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

```ruby
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

```ruby
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.


<br />

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**

- ([QueryExplainResult](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-QueryExplainResult))
**Examples**

Iterating over results multiple times

```ruby
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

```ruby
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

```ruby
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**

- [#run](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_run_instance_)
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**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- (Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- A list of document snapshots.
**Examples**

```ruby
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

```ruby
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.


<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `limit` called on it.
**Example**

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_order_instance_ "Google::Cloud::Firestore::Query#order (method)").)

<br />

Results for `limit_to_last` queries are only available once all documents
are received. Hence, `limit_to_last` queries cannot be streamed using
[#listen](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_listen_instance_ "Google::Cloud::Firestore::Query#listen (method)").
**Parameter**

- **num** (Integer) --- The maximum number of results to return.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `limit_to_last` called on it.
**Example**

```ruby
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**

- [#on_snapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_on_snapshot_instance_)
Listen to this query for changes.
**Yields**

- (callback) --- The block for accessing the query snapshot.
**Yield Parameter**

- **snapshot** ([QuerySnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-QuerySnapshot)) --- A query snapshot.
**Returns**

- ([QueryListener](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-QueryListener)) --- The ongoing listen operation on the query.
**Raises**

- (ArgumentError)
**Example**

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `offset` called on it.
**Example**

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_listen_instance_) Listen to this query for changes.
**Yields**

- (callback) --- The block for accessing the query snapshot.
**Yield Parameter**

- **snapshot** ([QuerySnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-QuerySnapshot)) --- A query snapshot.
**Returns**

- ([QueryListener](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-QueryListener)) --- The ongoing listen operation on the query.
**Raises**

- (ArgumentError)
**Example**

```ruby
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**

- [#order_by](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_order_by_instance_)
Specifies an "order by" clause on a field.
**Parameters**

- **field** ([FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath), String, Symbol) --- A field path to order results with.


  If a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `order` called on it.
**Examples**

```ruby
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:

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_order_instance_) Specifies an "order by" clause on a field.
**Parameters**

- **field** ([FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath), String, Symbol) --- A field path to order results with.


  If a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `order` called on it.
**Examples**

```ruby
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:

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_get_instance_) 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**

- **document** ([DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)) --- A document snapshot.
**Returns**

- (Enumerator\<[DocumentSnapshot](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot)\>) --- A list of document snapshots.
**Examples**

```ruby
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

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") object instead.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `select` called on it.
**Example**

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot "Google::Cloud::Firestore::DocumentSnapshot (class)") 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.

<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot), Object, Array\<Object\>) --- The field values to start the query after.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `start_after` called on it.
**Raises**

- (ArgumentError)
**Examples**

Starting a query after a document reference id

```ruby
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

```ruby
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

```ruby
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

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot "Google::Cloud::Firestore::DocumentSnapshot (class)") 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.

<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-DocumentSnapshot), Object, Array\<Object\>) --- The field values to start the query at.
**Returns**

- ([Query](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `start_at` called on it.
**Raises**

- (ArgumentError)
**Examples**

Starting a query at a document reference id

```ruby
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

```ruby
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

```ruby
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

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query#Google__Cloud__Firestore__Query_from_json_class_ "Google::Cloud::Firestore::Query.from_json (method)").
**Returns**

- (String) --- A JSON text string.
**Example**

```ruby
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


<br />

@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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath), String, Symbol) --- A field path to filter results with. If a [FieldPath](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-FieldPath "Google::Cloud::Firestore::FieldPath (class)") 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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-firestore/latest/Google-Cloud-Firestore-Query)) --- New query with `where` called on it.
**Examples**

```ruby
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
```

```ruby
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
```