{
  "id": "e7fc46ce09e05836de309ca5",
  "source": "solid:signals",
  "type": "github-document",
  "title": "query",
  "content": "---\ntitle: query\nuse_cases: \u003e-\n  api calls, data fetching, caching, deduplication, preloading routes,\n  preventing waterfalls, ssr\ntags:\n  - query\n  - cache\n  - data-fetching\n  - deduplication\n  - preload\n  - ssr\n  - api\nversion: '1.0'\ndescription: \u003e-\n  Cache and deduplicate API calls with query. Prevent waterfalls, enable\n  preloading, and manage server-side rendering efficiently.\n---\n\nThe `query` function wraps an asynchronous function (the fetcher) and returns a query.\n\nThe primary purpose of a query is to prevent redundant data fetching.\nWhen a query is called, a key is generated from its name and arguments.\nThis key is used to internally cache the result of the fetcher.\nIf a query with the same key is called, the cached result is used in these scenarios:\n\n- **For preloading:**\n  After a route's data is preloaded, a subsequent call to the same query within a 5-second window uses the preloaded data.\n- **For active subscriptions:**\n  When a query is actively being used by a component (e.g., via [`createAsync`](/solid-router/reference/data-apis/create-async)), its data is reused without expiration.\n- **On native history navigation:**\n  When navigating with the browser's back or forward buttons, the data is reused instead of being re-fetched.\n- **For server-side deduplication:**\n  Within a single server-side rendering (SSR) request, repeated calls to the same query reuse the same value.\n- **During client hydration:**\n  If SSR has provided data for a key, that data is used immediately on the client without a new network request.\n\n## Import\n\n```tsx\nimport { query } from \"@solidjs/router\";\n```\n\n## Type\n\n```tsx\nfunction query\u003cT extends (...args: any) =\u003e any\u003e(\n  fn: T,\n  name: string\n): CachedFunction\u003cT\u003e;\n```\n\n## Parameters\n\n### `fetcher`\n\n- **Type:** `T extends (...args: any) =\u003e any`\n- **Required:** Yes\n\nAn asynchronous function that handles the logic for fetching data.\nAll arguments passed to this function must be JSON-serializable.\n\n### `name`\n\n- **Type:** `string`\n- **Required:** Yes\n\nA string used as a namespace for the query.\nSolid Router combines this with the query's arguments to generate a unique key for deduplication.\n\n## Return value\n\n`query` returns a new function with the same call signature as the fetcher.\nThis returned function has the following properties attached to it:\n\n### `key`\n\nThe base key for the query, derived from its name.\n\n### `keyFor`\n\nA function that takes the same arguments as the fetcher and returns a string representing a specific key for that set of arguments.\n\n## Example\n\n### Basic usage\n\n```tsx\nimport { query } from \"@solidjs/router\";\n\nconst getUserProfileQuery = query(async (userId: string) =\u003e {\n\tconst response = await fetch(\n\t\t`https://api.example.com/users/${encodeURIComponent(userId)}`\n\t);\n\tconst json = await response.json();\n\n\tif (!response.ok) {\n\t\tthrow new Error(json?.message ?? \"Failed to load user profile.\");\n\t}\n\n\treturn json;\n}, \"userProfile\");\n```",
  "url": "https://github.com/solidjs/solid-docs/blob/HEAD/src/routes/solid-router/reference/data-apis/query.mdx",
  "metadata": {
    "path": "src/routes/solid-router/reference/data-apis/query.mdx",
    "repo": "solidjs/solid-docs",
    "repo_url": "https://github.com/solidjs/solid-docs.git",
    "size": 2941,
    "source_type": "github"
  },
  "hash": "aed4f5d73bc595ec3ebb1137f25896b3a2c4804d4f5720ae7e757d304c928cf9",
  "timestamp": "2026-02-23T11:43:00.192721508+01:00"
}