|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: "Introducing Realtime queries: Server-side event filtering for subscriptions" |
| 4 | +description: Pass SDK queries when subscribing to realtime channels to automatically filter events server-side, so your callbacks only receive the updates you care about. |
| 5 | +date: 2026-02-16 |
| 6 | +cover: /images/blog/announcing-realtime-queries/cover.png |
| 7 | +timeToRead: 4 |
| 8 | +author: jake-barnby |
| 9 | +category: announcement |
| 10 | +featured: false |
| 11 | +--- |
| 12 | + |
| 13 | +If you've built realtime features with Appwrite, you've likely written filtering logic inside your subscription callbacks: checking payload fields, comparing values, and discarding events you don't need. While this works, it adds boilerplate to your client code and means you're still receiving and processing every event on the channel, even the ones you'll throw away. |
| 14 | + |
| 15 | +To make realtime subscriptions more precise, Appwrite now supports **Realtime queries**: pass SDK queries when subscribing to automatically filter events server-side. |
| 16 | + |
| 17 | +# Filter at the source, not in your callback |
| 18 | + |
| 19 | +Realtime queries let you pass SDK queries as a parameter when subscribing to a channel. Events are filtered on the server based on your queries, so your callback only fires when the payload matches your conditions. |
| 20 | + |
| 21 | +This means less client-side filtering logic, fewer unnecessary callback invocations, and a cleaner subscription model overall. |
| 22 | + |
| 23 | +# How it works |
| 24 | + |
| 25 | +Realtime queries use the same `Query` helpers you already use with Appwrite's database and other services. Pass an array of queries when subscribing, and only events matching those conditions will trigger your callback. |
| 26 | + |
| 27 | +```javascript |
| 28 | +import { Client, Realtime, Channel, Query } from "appwrite"; |
| 29 | + |
| 30 | +const client = new Client() |
| 31 | + .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') |
| 32 | + .setProject('<PROJECT_ID>'); |
| 33 | + |
| 34 | +const realtime = new Realtime(client); |
| 35 | + |
| 36 | +// Subscribe to all updates on the channel |
| 37 | +const allVotes = await realtime.subscribe( |
| 38 | + Channel.tablesdb('<DATABASE_ID>').table('<TABLE_ID>').row(), |
| 39 | + response => { |
| 40 | + console.log(response.payload); |
| 41 | + } |
| 42 | +); |
| 43 | + |
| 44 | +// Subscribe only to updates where person equals 'person1' |
| 45 | +const person1Votes = await realtime.subscribe( |
| 46 | + Channel.tablesdb('<DATABASE_ID>').table('<TABLE_ID>').row(), |
| 47 | + response => { |
| 48 | + console.log(response.payload); |
| 49 | + }, |
| 50 | + [Query.equal('person', ['person1'])] |
| 51 | +); |
| 52 | + |
| 53 | +// Subscribe only to updates where person is not 'person1' |
| 54 | +const otherVotes = await realtime.subscribe( |
| 55 | + Channel.tablesdb('<DATABASE_ID>').table('<TABLE_ID>').row(), |
| 56 | + response => { |
| 57 | + console.log(response.payload); |
| 58 | + }, |
| 59 | + [Query.notEqual('person', 'person1')] |
| 60 | +); |
| 61 | +``` |
| 62 | + |
| 63 | +Without queries, the first subscription receives every event on the channel. With queries, the second and third subscriptions only receive events where the payload matches the specified conditions. No manual filtering required. |
| 64 | + |
| 65 | +# Supported queries |
| 66 | + |
| 67 | +Realtime queries support a subset of the full SDK query methods, focused on value comparison and logical composition: |
| 68 | + |
| 69 | +- **Comparison**: `Query.equal()`, `Query.notEqual()`, `Query.greaterThan()`, `Query.greaterThanEqual()`, `Query.lessThan()`, `Query.lessThanEqual()` |
| 70 | +- **Null checks**: `Query.isNull()`, `Query.isNotNull()` |
| 71 | +- **Logical**: `Query.and()`, `Query.or()` |
| 72 | + |
| 73 | +These cover the most common filtering patterns for realtime events. You can combine multiple queries to build precise conditions for your subscriptions. |
| 74 | + |
| 75 | +# Key benefits |
| 76 | + |
| 77 | +- **Server-side filtering**: Events are filtered before reaching your client, reducing unnecessary processing |
| 78 | +- **Consistent API**: Uses the same `Query` helpers from Appwrite's database APIs |
| 79 | +- **Cleaner code**: Eliminate manual filtering logic inside subscription callbacks |
| 80 | +- **Available across all platforms**: Supported in Web, Flutter, Apple, and Android client SDKs |
| 81 | + |
| 82 | +# More resources |
| 83 | + |
| 84 | +- [Read the Realtime queries documentation](/docs/apis/realtime#queries) |
| 85 | +- [Learn about Realtime channel helpers](/docs/apis/realtime#channel-helpers) |
| 86 | +- [View all available Realtime events](/docs/advanced/platform/events) |
0 commit comments