Understanding Tanstack Query Keys

In React Query, the Query Key is a unique identifier that represents a specific query. They not only help you identify the query, but they also play a critical role in caching data. At a high level, the Query Key is an array and can simply contain a single string or be more complex and contain nested objects. This identifier is used to manage the cache, track the status of queries, and enable efficient updates to the UI when data changes. This blog will give an understanding of that functionality and best practices on how to do that effectively so you can get React Query up and running in your project.

Caching

To understand the role Query Keys play and how to use them you have to understand that the Query Cache is an object. In this object, the keys are your Query Keys that have been serialized and the value is the data returned from your query. Because of this, your keys will need to be unique to that specific query otherwise when React Query finds an entry for that key, it will use the value rather than use the query function to return the data.

Invalidating

In React Query, when you invalidate a query the Query Function refetches and updates the data associated with a particular query. When data in the underlying source changes, you can use the queryClient.invalidateQueries method to mark a specific query or set of queries as stale. This triggers a refetch the next time the invalidated query is accessed.

For instance, if a user updates an item in a to-do list, the corresponding query fetching that list can be invalidated using this method:

queryClient.invalidateQueries(queryKey);

By invalidating queries strategically, you ensure that the UI reflects the most up-to-date data without the need for a manual refresh. React Query's caching system then handles the refetch efficiently, maintaining a seamless and performant user experience.

Structure

Structure your keys as an array from most generic to most specific, with as much detail as you see fit. Be sure to include any variables your function depends on. Consider breaking apart the URL with the information in each slash being a new element in the array.

/posts > ["posts"]
/posts/1 > ["posts", post.id]
/posts?authorId=1 > ["posts", {authorId: 1}]
/posts/2/comments > ["posts", post.id, "comments"]

With this structure, you can invalidate everything related to posts with ["posts"] and any specific post.id.

Dynamic

One of the strengths of React Query is its ability to handle dynamic data fetching. Query keys can include dynamic parameters, allowing you to easily fetch data based on user input or other changing conditions.

const userId = getCurrentUserId(); // dynamic user ID const userQueryKey = ['user', userId];

In this example, the query key includes a dynamic userId obtained at runtime, allowing you to fetch data for a specific user dynamically.