> Documentation index: https://firebase.google.com/docs/firestore/llms.txt

## Description

Filters the documents from the previous stage, returning only the documents
where the condition evaluates to `true`.

## Examples

### Web

```javascript
let results;

results = await execute(db.pipeline().collection("books")
  .where(field("rating").equal(5))
  .where(field("published").lessThan(1900))
);

results = await execute(db.pipeline().collection("books")
  .where(and(field("rating").equal(5), field("published").lessThan(1900)))
);
```

##### Swift

```swift
var results: Pipeline.Snapshot

results = try await db.pipeline().collection("books")
  .where(Field("rating").equal(5))
  .where(Field("published").lessThan(1900))
  .execute()

results = try await db.pipeline().collection("books")
  .where(Field("rating").equal(5) && Field("published").lessThan(1900))
  .execute()
```

### Kotlin

```kotlin
var results: Task<Pipeline.Snapshot>

results = db.pipeline().collection("books")
    .where(field("rating").equal(5))
    .where(field("published").lessThan(1900))
    .execute()

results = db.pipeline().collection("books")
    .where(Expression.and(field("rating").equal(5),
      field("published").lessThan(1900)))
    .execute()
```

### Java

```java
Task<Pipeline.Snapshot> results;

results = db.pipeline().collection("books")
    .where(field("rating").equal(5))
    .where(field("published").lessThan(1900))
    .execute();

results = db.pipeline().collection("books")
    .where(Expression.and(
        field("rating").equal(5),
        field("published").lessThan(1900)
    ))
    .execute();
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import And, Field

results = (
    client.pipeline()
    .collection("books")
    .where(Field.of("rating").equal(5))
    .where(Field.of("published").less_than(1900))
    .execute()
)

results = (
    client.pipeline()
    .collection("books")
    .where(And(Field.of("rating").equal(5), Field.of("published").less_than(1900)))
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot results1 =
    firestore
        .pipeline()
        .collection("books")
        .where(field("rating").equal(5))
        .where(field("published").lessThan(1900))
        .execute()
        .get();

Pipeline.Snapshot results2 =
    firestore
        .pipeline()
        .collection("books")
        .where(and(field("rating").equal(5), field("published").lessThan(1900)))
        .execute()
        .get();
```

##### Go

```go
results1, err := client.Pipeline().
	Collection("books").
	Where(firestore.FieldOf("rating").Equal(5)).
	Where(firestore.FieldOf("published").LessThan(1900)).
	Execute(ctx).Results().GetAll()
if err != nil {
	fmt.Fprintf(w, "GetAll failed: %v", err)
	return err
}

results2, err := client.Pipeline().
	Collection("books").
	Where(firestore.And(
		firestore.FieldOf("rating").Equal(5),
		firestore.FieldOf("published").LessThan(1900),
	)).
	Execute(ctx).Results().GetAll()
if err != nil {
	fmt.Fprintf(w, "GetAll failed: %v", err)
	return err
}
```

## Behavior

### Chained versus Nested Filters

Multiple `where(...)` stages can be chained together, which is logically
equivalent to combining the filter conditions within a single `where(...)` stage
using an `and(...)` expression. Both approaches produce the same execution plan
and have no impact on query execution or performance.

For example, chaining multiple `where(...)` stages:

### Node.js

```javascript
const cities = await db.pipeline()
  .collection("/cities")
  .where(field("location.country").equals("USA"))
  .where(field("population").greaterThan(500000))
  .execute();
```

is equivalent to using a single `where(...)` stage with a compound `and(...)`:

### Node.js

```javascript
const cities = await db.pipeline()
  .collection("/cities")
  .where(
    field("location.country").equals("USA")
      .and(field("population").greaterThan(500000)))
  .execute();
```

However, filtering based on a logical `or(...)` of conditions cannot be split
across multiple stages and must be done in a single `where(...)` stage:

### Node.js

```javascript
const cities = await db.pipeline()
  .collection("/cities")
  .where(
    field("location.state").equals("NY")
      .or(field("location.state").equals("CA")))
  .execute();
```

### Complex Expressions

The filter condition can contain complex filter conditions containing deeply
nested expressions and logical operators. For example:

### Node.js

```javascript
const cities = await db.pipeline()
  .collection("/cities")
  .where(
    field("name").like("San%")
    .or(
      field("location.state").charLength().greaterThan(7)
      .and(field("location.country").equals("USA"))))
```

filters `/cities` based on a regular expression, or if the city is in the `USA`
with a long enough state name. Any expression can be given as the condition, but
will only match those which evaluate to `true`.

### Stage Ordering

The order of stages is important as it can change the query evaluation order.
For example the query:

### Node.js

```javascript
const cities = await db.pipeline()
  .collection("/cities")
  .limit(10)
  .where(field("location.country").equals("USA"))
  .execute();
```

will only filter on `location.country` for a (potentially random) set of 10
documents as the prior [`limit(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/limit.md.txt) stage is restricting
the documents that are ever provided to the `where(...)` stage. Given this, the
rule of thumb is to put the `where(...)` stages as early in the query as
possible.

**`HAVING`-Like Functionality:**

The `where(...)` stage can come after any stage that changes the schema of the
documents, like [`select(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/select.md.txt) or
[`aggregate(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/aggregate.md.txt) and will refer to the fields
produced from those stages. Importantly for
[`aggregate(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/aggregate.md.txt), a following `where(...)` clause
that refers to the accumulated fields acts like a `HAVING` clause in a typical
SQL system. For example:

### Node.js

```javascript
const cities = await db.pipeline()
  .collection("/cities")
  .aggregate({
    accumulators: [field("population").sum().as("total_population")],
    groups: ["location.state"]
  })
  .where(field("total_population").greaterThan(10000000))
```

allows returning the states which have cities over a total population size.