where()
Mission
The .where() modifier adds filtering conditions to restrict query results based on field values.
The Payoff
By completing this module, you will understand how to build single comparisons, chain filters together, and structure valid array queries.
Estimated Time: 4 minutesModules: 4 Concepts
Signature: .where(field: string, operator: Operator, value: unknown)
Target document property
Specify the database field path string you want to filter.
Choose comparison operator
Provide a valid operator string like '=', '>', or 'contains'.
Pass query argument
Input the matching value constraints.
Interactive Code Snippet
typescript
const activeUsers = await sdk.collection("users") .where("status", "=", "active") .get();| Operator | Description | Example Value |
|---|---|---|
| = | Matches exact values | "active" |
| != | Matches values not equal to input | "guest" |
| > | Greater than comparison | 100 |
| < | Less than comparison | 50 |
| >= | Greater than or equal to | 10 |
| <= | Less than or equal to | 5 |
| in | Matches any item inside the target array | ["admin", "guest"] |
| contains | Matches substring values (string fields only) | "gaming" |
Chain query builder hooks
Call .where() sequentially on the returned builder instance.
Observe backend execution
Note that multiple conditions are evaluated using logical implicit AND operations.
Interactive Code Snippet
typescript
// Combined implicitly using logical ANDconst products = await sdk.collection("products") .where("category", "=", "kitchen") .where("price", "<", 50) .where("stock", ">", 0) .get();Validation Rule
The `in` operator requires its `value` argument to be an array/list. If any other type is supplied, the SDK halts execution and raises a value exception immediately.
Supply an array list parameter
Ensure that values supplied for 'in' operators are structured as list arrays.
Avoid validation errors
Passing non-array parameters immediately throws a client-side SDK error.
Interactive Code Snippet
typescript
const targetedUsers = await sdk.collection("users") .where("role", "in", ["admin", "moderator"]) // Value must be array .get();