# Source: https://docs.convex.dev/database/reading-data/filters.md

# Filtering

The [`filter`](/api/interfaces/server.Query.md#filter) method allows you to restrict the documents that your document query returns. This method takes a filter constructed by [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md) and will only select documents that match.

The examples below demonstrate some of the common uses of `filter`. You can see the full list of available filtering methods [in the reference docs](/api/interfaces/server.FilterBuilder.md).

If you need to filter to documents containing some keywords, use a [search query](/search/text-search.md).

Use indexes instead

Filters effectively loop over your table looking for documents that match. This can be slow or cause your function to hit a [limit](/production/state/limits.md) when your table has thousands of rows. For faster more database efficient queries use [indexes instead](/database/reading-data/indexes/.md).

### Equality conditions[​](#equality-conditions "Direct link to Equality conditions")

This document query finds documents in the `users` table where `doc.name === "Alex"`:

```
// Get all users named "Alex".
const usersNamedAlex = await ctx.db
  .query("users")
  .filter((q) => q.eq(q.field("name"), "Alex"))
  .collect();
```

Here `q` is the [`FilterBuilder`](/api/interfaces/server.FilterBuilder.md) utility object. It contains methods for all of our supported filter operators.

This filter will run on all documents in the table. For each document, `q.field("name")` evaluates to the `name` property. Then `q.eq` checks if this property is equal to `"Alex"`.

If your query references a field that is missing from a given document then that field will be considered to have the value `undefined`.

### Comparisons[​](#comparisons "Direct link to Comparisons")

Filters can also be used to compare fields against values. This document query finds documents where `doc.age >= 18`:

```
// Get all users with an age of 18 or higher.
const adults = await ctx.db
  .query("users")
  .filter((q) => q.gte(q.field("age"), 18))
  .collect();
```

Here the `q.gte` operator checks if the first argument (`doc.age`) is greater than or equal to the second (`18`).

Here's the full list of comparisons:

| Operator      | Equivalent TypeScript |
| ------------- | --------------------- |
| `q.eq(l, r)`  | `l === r`             |
| `q.neq(l, r)` | `l !== r`             |
| `q.lt(l, r)`  | `l < r`               |
| `q.lte(l, r)` | `l <= r`              |
| `q.gt(l, r)`  | `l > r`               |
| `q.gte(l, r)` | `l >= r`              |

### Arithmetic[​](#arithmetic "Direct link to Arithmetic")

You can also include basic arithmetic in your queries. This document query finds documents in the `carpets` table where `doc.height * doc.width > 100`:

```
// Get all carpets that have an area of over 100.
const largeCarpets = await ctx.db
  .query("carpets")
  .filter((q) => q.gt(q.mul(q.field("height"), q.field("width")), 100))
  .collect();
```

Here's the full list of arithmetic operators:

| Operator      | Equivalent TypeScript |
| ------------- | --------------------- |
| `q.add(l, r)` | `l + r`               |
| `q.sub(l, r)` | `l - r`               |
| `q.mul(l, r)` | `l * r`               |
| `q.div(l, r)` | `l / r`               |
| `q.mod(l, r)` | `l % r`               |
| `q.neg(x)`    | `-x`                  |

### Combining operators[​](#combining-operators "Direct link to Combining operators")

You can construct more complex filters using methods like `q.and`, `q.or`, and `q.not`. This document query finds documents where `doc.name === "Alex" && doc.age >= 18`:

```
// Get all users named "Alex" whose age is at least 18.
const adultAlexes = await ctx.db
  .query("users")
  .filter((q) =>
    q.and(q.eq(q.field("name"), "Alex"), q.gte(q.field("age"), 18)),
  )
  .collect();
```

Here is a query that finds all users where `doc.name === "Alex" || doc.name === "Emma"`:

```
// Get all users named "Alex" or "Emma".
const usersNamedAlexOrEmma = await ctx.db
  .query("users")
  .filter((q) =>
    q.or(q.eq(q.field("name"), "Alex"), q.eq(q.field("name"), "Emma")),
  )
  .collect();
```

## Advanced filtering techniques[​](#advanced-filtering-techniques "Direct link to Advanced filtering techniques")

Sometimes the filter syntax is is not expressive enough. For example you may want to collect all posts that have a tag. Your schema for the posts looks like this:

```
export default defineSchema({
  posts: defineTable({
    body: v.string(),
    tags: v.array(v.string()),
  }),
});
```

One way to solve is by applying the filter on the result of the `collect()` call. This is just filtering a JavaScript array:

```
export const postsWithTag = query({
  args: { tag: v.string() },
  handler: async (ctx, args) => {
    const allPosts = await ctx.db.query("posts").collect();
    return allPosts.filter((post) => post.tags.includes(args.tag));
  },
});
```

But this requires reading the whole table first. If you want to just get the first result that matches, reading the whole table could be very inefficient. Instead you may want to use the JavaScript [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) syntax to loop through the table one document at a time:

```
export const firstPostWithTag = query({
  args: { tag: v.string() },
  handler: (ctx, args) => {
    for await (const post of db.query("posts")) {
      if (post.tags.includes(args.tag)) {
        return post;
      }
    }
  },
});
```

This works because Convex queries are [JavaScript iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).

Even with this optimization you are still just looping over the table to find the first post that matches and may hit your function limits. Using indexes is still the way to go. You can read a [detailed discussion of how to handle tags with indexes](https://stack.convex.dev/complex-filters-in-convex#optimize-with-indexes).

## Querying performance and limits[​](#querying-performance-and-limits "Direct link to Querying performance and limits")

Most of the example document queries above can lead to a *full table scan*. That is, for the document query to return the requested results, it might need to walk over every single document in the table.

Take this simple example:

```
const tasks = await ctx.db.query("tasks").take(5);
```

This document query will not scan more than 5 documents.

On the other hand, this document query:

```
const tasks = await ctx.db
  .query("tasks")
  .filter((q) => q.eq(q.field("isCompleted"), true))
  .first();
```

might need to walk over every single document in the `"tasks"` table just to find the first one with `isCompleted: true`.

If a table has more than a few thousand documents, you should use [indexes](/database/reading-data/indexes/.md) to improve your document query performance. Otherwise, you may run into our enforced limits, detailed in [Read/write limit errors](/functions/error-handling/.md#readwrite-limit-errors).

For information on other limits, see [Limits](/production/state/limits.md).