Can queries be read without subscribing to realtime updates
#Opt out of realtime updates
snow peak
midnight forgeBOT
Hi @snow peak. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Yes, you can read queries without subscribing to realtime updates in Convex. While the default behavior of query functions is to be reactive and provide realtime updates, you can opt out of this by calling queries imperatively rather than using the subscription-based hooks.
For example, in environments like Expo (or outside of React), you can use the Convex client directly to call a query once without setting up a subscription:
const convex = useConvex();
const result = await convex.query(...);
This approach will fetch the data once and will not subscribe to future updates, similar to the fetchQuery method in the Next.js SDK. This is useful if you want to avoid the overhead of realtime updates and just need a snapshot of the data at a specific moment in time. This method was confirmed as a solution in a support thread for users who do not want reactivity in their data fetching Discord support thread: Call query once (alternative to fetchQuery).
Additionally, if you use the HTTP API to call your functions, you also do not get automatic subscriptions or realtime updates Convex Overview – Client libraries.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
snow peak
@midnight forge what if I want it react query style with a stale time
midnight forgeBOT
Let me check the knowledge base for you again. One moment! :books:
If you want to use Convex in a "React Query style" with a stale time—meaning you want to cache query results and only refetch after a certain period, rather than subscribing to realtime updates—Convex's integration with TanStack Query (@convex-dev/react-query) is the closest fit.
However, Convex queries are always live and up-to-date by default. The concept of "stale time" (where data is considered fresh for a period and only refetched after it becomes stale) does not directly apply, because Convex pushes updates to the client as soon as data changes. The isStale property in TanStack Query will always be false with Convex, and refetch/retry options are ignored, since Convex manages its own reactivity and retry logic over WebSockets Differences from using fetch with TanStack Query.
That said, you can control how long a query subscription remains active after the last component using it unmounts by setting the gcTime option. The default is 5 minutes. This means the subscription (and its cached data) will be kept alive for that period, but it will still receive live updates from the server during that time. If you want to reduce resource usage, you can set a shorter gcTime Differences from using fetch with TanStack Query.
Summary:
Convex does not support a true "stale time" where data is considered fresh and not updated for a period. Instead, it always provides live data, but you can control how long the subscription (and its cache) is kept alive after unmounting with gcTime. If you need true stale caching (no live updates), you would need to implement a custom solution or use imperative query calls instead of the subscription-based hooks.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
snow peak
What if I use the convex.query with react query myself @midnight forge
midnight forgeBOT
Let me check the knowledge base for you again. One moment! :books:
If you use convex.query (the imperative, one-off query method) together with React Query (TanStack Query) yourself, you will get the classic React Query behavior: the query will be fetched once, and you can control caching, stale time, and refetching using React Query's options. This means you will not get realtime updates from Convex—your data will only update when you explicitly refetch or when React Query's cache invalidation logic triggers a refetch.
This approach is different from using the Convex TanStack Query adapter (convexQuery), which sets up a live subscription and always provides up-to-date data, ignoring staleTime and refetch options Differences from using fetch with TanStack Query.
So, if you want to opt out of realtime updates and use React Query's caching and stale time features, using convex.query as your query function in React Query is a valid approach. However, this is not the default or recommended pattern in Convex, and you will lose the benefits of Convex's realtime reactivity.