snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/react/guides/query-functions.md

@@ -0,0 +1,119 @@
+---
+id: query-functions
+title: Query Functions
+---
+
+A query function can be literally any function that **returns a promise**. The promise that is returned should either **resolve the data** or **throw an error**.
+
+On success, the resolved value may be anything **except `undefined`**. Queries that resolve to `undefined` will be [treated as failed](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-react-query-4#undefined-is-an-illegal-cache-value-for-successful-queries). To store "nothing" as a successful result in the query cache, resolve `null` instead.
+
+All of the following are valid query function configurations:
+
+[//]: # 'Example'
+
+```tsx
+useQuery({ queryKey: ['todos'], queryFn: fetchAllTodos })
+useQuery({ queryKey: ['todos', todoId], queryFn: () => fetchTodoById(todoId) })
+useQuery({
+  queryKey: ['todos', todoId],
+  queryFn: async () => {
+    const data = await fetchTodoById(todoId)
+    return data
+  },
+})
+useQuery({
+  queryKey: ['todos', todoId],
+  queryFn: ({ queryKey }) => fetchTodoById(queryKey[1]),
+})
+```
+
+[//]: # 'Example'
+
+## Handling and Throwing Errors
+
+For TanStack Query to determine a query has errored, the query function **must throw** or return a **rejected Promise**. Any error that is thrown in the query function will be persisted on the `error` state of the query.
+
+[//]: # 'Example2'
+
+```tsx
+const { error } = useQuery({
+  queryKey: ['todos', todoId],
+  queryFn: async () => {
+    if (somethingGoesWrong) {
+      throw new Error('Oh no!')
+    }
+    if (somethingElseGoesWrong) {
+      return Promise.reject(new Error('Oh no!'))
+    }
+
+    return data
+  },
+})
+```
+
+[//]: # 'Example2'
+
+## Usage with `fetch` and other clients that do not throw by default
+
+While most utilities like `axios` or `graphql-request` automatically throw errors for unsuccessful HTTP calls, some utilities like `fetch` do not throw errors by default. If that's the case, you'll need to throw them on your own. Here is a simple way to do that with the popular `fetch` API:
+
+[//]: # 'Example3'
+
+```tsx
+useQuery({
+  queryKey: ['todos', todoId],
+  queryFn: async () => {
+    const response = await fetch('/todos/' + todoId)
+    if (!response.ok) {
+      throw new Error('Network response was not ok')
+    }
+    return response.json()
+  },
+})
+```
+
+[//]: # 'Example3'
+
+## Query Function Variables
+
+Query keys are not just for uniquely identifying the data you are fetching, but are also conveniently passed into your query function as part of the QueryFunctionContext. While not always necessary, this makes it possible to extract your query functions if needed:
+
+[//]: # 'Example4'
+
+```tsx
+function Todos({ status, page }) {
+  const result = useQuery({
+    queryKey: ['todos', { status, page }],
+    queryFn: fetchTodoList,
+  })
+}
+
+// Access the key, status and page variables in your query function!
+function fetchTodoList({ queryKey }) {
+  const [_key, { status, page }] = queryKey
+  return new Promise()
+}
+```
+
+[//]: # 'Example4'
+
+### QueryFunctionContext
+
+The `QueryFunctionContext` is the object passed to each query function. It consists of:
+
+- `queryKey: QueryKey`: [Query Keys](./query-keys.md)
+- `client: QueryClient`: [QueryClient](../reference/classes/QueryClient.md)
+- `signal?: AbortSignal`
+  - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance provided by TanStack Query
+  - Can be used for [Query Cancellation](./query-cancellation.md)
+- `meta: Record<string, unknown> | undefined`
+  - an optional field you can fill with additional information about your query
+
+Additionally, [Infinite Queries](./infinite-queries.md) get the following options passed:
+
+- `pageParam: TPageParam`
+  - the page parameter used to fetch the current page
+- `direction: 'forward' | 'backward'`
+  - **deprecated**
+  - the direction of the current page fetch
+  - To get access to the direction of the current page fetch, please add a direction to `pageParam` from `getNextPageParam` and `getPreviousPageParam`.