<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
-->

# Apollo – Queries

> Source: [https://www.apollographql.com/docs/react/data/queries/](https://www.apollographql.com/docs/react/data/queries/)
> Retrieved: 2025-11-19T07:02:41.913342Z

[ Docs  ](/docs)

[ ](/docs)

Search Apollo content (Cmd+K or /)

[Launch GraphOS Studio ](https://studio.apollographql.com/signup?referrer=docs)

[ Home Home ](/docs/)[ Schema Design Schema Design ](/docs/graphos/schema-design)[ Connectors Connectors ](/docs/graphos/connectors)[ GraphOS Platform GraphOS Platform ](/docs/graphos/platform)[ Routing Routing ](/docs/graphos/routing)[ Resources Resources ](/docs/graphos/resources)

Apollo Client (Web) Apollo Client (Web)

[Rover CLI](https://www.apollographql.com/docs/rover)[IDE Support](https://www.apollographql.com/docs/ide-support)[Apollo Client (Web)](https://www.apollographql.com/docs/react)[Apollo iOS](https://www.apollographql.com/docs/ios)[Apollo Kotlin](https://www.apollographql.com/docs/kotlin)[Apollo Server](https://www.apollographql.com/docs/apollo-server)[Apollo MCP Server](https://www.apollographql.com/docs/apollo-mcp-server)[Apollo Operator](https://www.apollographql.com/docs/apollo-operator)

Apollo Client (Web) - v4 (latest)

[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)

### Core concepts

[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directives](https://www.apollographql.com/docs/react/data/directives)[Error handling](https://www.apollographql.com/docs/react/data/error-handling)[Persisted queries](https://www.apollographql.com/docs/react/data/persisted-queries)[Document transforms](https://www.apollographql.com/docs/react/data/document-transforms)[Deferring response data](https://www.apollographql.com/docs/react/data/defer)[Best practices](https://www.apollographql.com/docs/react/data/operation-best-practices)

### Caching

[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.com/docs/react/caching/memory-management)[Advanced topics](https://www.apollographql.com/docs/react/caching/advanced-topics)

### Pagination

[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)

### Local State

[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)

### Development & Testing

[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client-schema-mocking)[Reducing bundle size](https://www.apollographql.com/docs/react/development-testing/reducing-bundle-size)

### Performance

[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)

### Integrations

[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)

### Networking

[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)

### API Reference

### Core

[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)

### Errors

[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/react/api/errors/ServerParseError)[UnconventionalError](https://www.apollographql.com/docs/react/api/errors/UnconventionalError)

### React

[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](https://www.apollographql.com/docs/react/api/react/useApolloClient)[useReactiveVar](https://www.apollographql.com/docs/react/api/react/useReactiveVar)[useSuspenseQuery](https://www.apollographql.com/docs/react/api/react/useSuspenseQuery)[useBackgroundQuery](https://www.apollographql.com/docs/react/api/react/useBackgroundQuery)[useReadQuery](https://www.apollographql.com/docs/react/api/react/useReadQuery)[useLoadableQuery](https://www.apollographql.com/docs/react/api/react/useLoadableQuery)[useQueryRefHandlers](https://www.apollographql.com/docs/react/api/react/useQueryRefHandlers)[skipToken](https://www.apollographql.com/docs/react/api/react/skipToken)[createQueryPreloader](https://www.apollographql.com/docs/react/api/react/preloading)[MockProvider](https://www.apollographql.com/docs/react/api/react/testing)[SSR](https://www.apollographql.com/docs/react/api/react/ssr)

### Apollo Link

[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch)[ClientAwarenessLink](https://www.apollographql.com/docs/react/api/link/apollo-link-client-awareness)[ErrorLink](https://www.apollographql.com/docs/react/api/link/apollo-link-error)[GraphQLWsLink](https://www.apollographql.com/docs/react/api/link/apollo-link-subscriptions)[HttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-http)[PersistedQueryLink](https://www.apollographql.com/docs/react/api/link/apollo-link-persisted-queries)[RemoveTypenameFromVariablesLink](https://www.apollographql.com/docs/react/api/link/apollo-link-remove-typename)[RetryLink](https://www.apollographql.com/docs/react/api/link/apollo-link-retry)[SchemaLink](https://www.apollographql.com/docs/react/api/link/apollo-link-schema)[SetContextLink](https://www.apollographql.com/docs/react/api/link/apollo-link-context)[WebSocketLink (deprecated)](https://www.apollographql.com/docs/react/api/link/apollo-link-ws)[Community links](https://www.apollographql.com/docs/react/api/link/community-links)

[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)

Navigation controls

## Schema Design

[Overview](https://www.apollographql.com/docs/graphos/schema-design)

### Federated Schemas

[Overview](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/federation)[Schema Types](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/schema-types)[Schema Composition](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/composition)[Sharing Types (Value Types)](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/sharing-types)

### Federation Reference

[Federation Changelog](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/versions)[Federation Directives](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives)[Composition Rules](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/composition-rules)

### Subgraph Reference

[Federation Subgraphs Specification](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-spec)[Subgraph Specific Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-specific-fields)[Compatible Subgraph Libraries](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/compatible-subgraphs)

### Development and Tooling

[Query Plans](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/query-plans)[Composition Hints](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/hints)[Errors](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/errors)

### From Federation 1 to 2

[Upgrade Guide](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/moving-to-federation-2)[Federation 2 Backwards Compatibility](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/backward-compatibility)

### Entities

[Introduction](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/intro)

### Entity Essentials

[Entity Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/contribute-fields)[Advanced Keys](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/define-keys)[Entity Interfaces](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/interfaces)

### Entity Guides

[Entity Best Practices](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/best-practices)[Migrate Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/migrate-fields)[Resolve Another Subgraph's Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields)[Enforce Ownership](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/enforce-ownership)[Use Contexts](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/use-contexts)

### Schema Design Guides

### Schema Design Principles

[Demand Oriented Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/demand-oriented-schema-design)[Naming Conventions](https://www.apollographql.com/docs/graphos/schema-design/guides/naming-conventions)[Namespacing](https://www.apollographql.com/docs/graphos/schema-design/guides/namespacing-by-separation-of-concerns)

### Server-Driven UI

[Basics](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/basics)[Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/schema-design)[Client Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/client-design)

### Data Handling Techniques

[Handling the N+1 Problem](https://www.apollographql.com/docs/graphos/schema-design/guides/handling-n-plus-one)[Nullability](https://www.apollographql.com/docs/graphos/schema-design/guides/nullability)[Interfaces](https://www.apollographql.com/docs/graphos/schema-design/guides/interfaces)[Response Type Pattern](https://www.apollographql.com/docs/graphos/schema-design/guides/response-type-pattern)[Errors as Data](https://www.apollographql.com/docs/graphos/schema-design/guides/errors-as-data-explained)[Aggregating Data](https://www.apollographql.com/docs/graphos/schema-design/guides/aggregating-data-across-subgraphs)[Graph Identities](https://www.apollographql.com/docs/graphos/schema-design/guides/graph-identities)

### Schema Development and Evolution

[Mocking to Unblock Development](https://www.apollographql.com/docs/graphos/schema-design/guides/mocking)[Deprecations](https://www.apollographql.com/docs/graphos/schema-design/guides/deprecations)[Distributed Orchestration](https://www.apollographql.com/docs/graphos/schema-design/guides/distributed-orchestration)[Migrating from a Monolith](https://www.apollographql.com/docs/graphos/schema-design/guides/from-monolith)[Migrating from Schema Stitching](https://www.apollographql.com/docs/graphos/schema-design/guides/migrating-from-stitching)

## Connectors

[Overview](https://www.apollographql.com/docs/graphos/connectors)[Why use Connectors?](https://www.apollographql.com/docs/graphos/connectors/why-connectors)

### Getting Started

[Quickstart](https://www.apollographql.com/docs/graphos/connectors/getting-started)[API Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/requirements)[Version Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/version-requirements)

### Connectors Library

[Overview](https://www.apollographql.com/docs/graphos/connectors/library)

### Prebuilt Connectors

[Anthropic](https://www.apollographql.com/docs/graphos/connectors/library/anthropic)[Open AI](https://www.apollographql.com/docs/graphos/connectors/library/openai)[AWS DynamoDB](https://www.apollographql.com/docs/graphos/connectors/library/aws-dynamodb)[AWS Lambda](https://www.apollographql.com/docs/graphos/connectors/library/aws-lambda)[Strapi](https://www.apollographql.com/docs/graphos/connectors/library/strapi)[Stripe](https://www.apollographql.com/docs/graphos/connectors/library/stripe)[OData](https://www.apollographql.com/docs/graphos/connectors/library/odata)

### Development and Tooling

[Overview](https://www.apollographql.com/docs/graphos/connectors/tooling)[IDE Extensions](https://www.apollographql.com/docs/graphos/connectors/tooling/ide-extensions)[Using Rover](https://www.apollographql.com/docs/graphos/connectors/tooling/rover)[CLI Tools](https://www.apollographql.com/docs/graphos/connectors/tooling/cli-tools)[Mapping Playground](https://www.apollographql.com/docs/graphos/connectors/tooling/mapping-playground)

### Making Requests

[Overview](https://www.apollographql.com/docs/graphos/connectors/requests)[Request URLs](https://www.apollographql.com/docs/graphos/connectors/requests/url)[Request Headers](https://www.apollographql.com/docs/graphos/connectors/requests/headers)[Request Bodies](https://www.apollographql.com/docs/graphos/connectors/requests/body)[Batch Requests](https://www.apollographql.com/docs/graphos/connectors/requests/batching)[gRPC over JSON](https://www.apollographql.com/docs/graphos/connectors/requests/grpc-json-bridge)

### Handling Responses

[Overview](https://www.apollographql.com/docs/graphos/connectors/responses)[Mapping Response Fields](https://www.apollographql.com/docs/graphos/connectors/responses/fields)[Error Handling](https://www.apollographql.com/docs/graphos/connectors/responses/error-handling)

### Working with Entities

[Overview](https://www.apollographql.com/docs/graphos/connectors/entities)[Common Patterns](https://www.apollographql.com/docs/graphos/connectors/entities/patterns)[Working Across Subgraphs](https://www.apollographql.com/docs/graphos/connectors/entities/across-subgraphs)

### Mapping Language

[Overview](https://www.apollographql.com/docs/graphos/connectors/mapping)[Handling Arrays](https://www.apollographql.com/docs/graphos/connectors/mapping/arrays)[Mapping Enums](https://www.apollographql.com/docs/graphos/connectors/mapping/enums)[Using Literal Values](https://www.apollographql.com/docs/graphos/connectors/mapping/literals)[Variable Reference](https://www.apollographql.com/docs/graphos/connectors/mapping/variables)[Method Reference](https://www.apollographql.com/docs/graphos/connectors/mapping/methods)

### Deployment

[Overview](https://www.apollographql.com/docs/graphos/connectors/deployment)[Configuration](https://www.apollographql.com/docs/graphos/connectors/deployment/configuration)

### Deployment Configurations

[Overriding Base URLs](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-base-urls)[Overriding Headers](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-headers)

### Security Configurations

[Overview](https://www.apollographql.com/docs/graphos/connectors/security)[Authentication](https://www.apollographql.com/docs/graphos/connectors/security/auth)[Request Limits](https://www.apollographql.com/docs/graphos/connectors/security/request-limits)[TLS](https://www.apollographql.com/docs/graphos/connectors/security/tls)

### Performance Configurations

[Overview](https://www.apollographql.com/docs/graphos/connectors/performance)[Traffic Shaping](https://www.apollographql.com/docs/graphos/connectors/performance/traffic-shaping)

### Observability

[Overview](https://www.apollographql.com/docs/graphos/connectors/observability)[Telemetry Configurations](https://www.apollographql.com/docs/graphos/connectors/observability/telemetry)

### Testing

[Testing Framework](https://www.apollographql.com/docs/graphos/connectors/testing)

### Connectors Reference

[Changelog](https://www.apollographql.com/docs/graphos/connectors/reference/changelog)[Directives](https://www.apollographql.com/docs/graphos/connectors/reference/directives)[Limitations](https://www.apollographql.com/docs/graphos/connectors/reference/limitations)

[Troubleshooting](https://www.apollographql.com/docs/graphos/connectors/troubleshooting)

## GraphOS Platform

[Overview](https://www.apollographql.com/docs/graphos/platform)[Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox)

### Schema Management

[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management)

### Schema Delivery

### Publishing

[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing)[Publish with Rover](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/rover)[Publish with the Platform API](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/platform-api)[Guide: Publish with GitHub Actions](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/guide-github)

[Launches](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/launch)[Graph Artifacts](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/graph-artifacts)

### Contracts

[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/overview)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/create)[Usage Patterns](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/usage-patterns)[Reference](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/reference)

### Schema Checks

[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/checks)[Run Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/run)[Custom Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/custom)[Checks Configuration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/configure)[GitHub Integration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/github-integration)[Checks Reference](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/reference)

### Schema Linting

[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/linting)[Linter Rules](https://www.apollographql.com/docs/graphos/platform/schema-management/linting/rules)

### Schema Proposals

[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals)[Configure](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/configure)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/create)[Review](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/review)[Implement](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/implement)

### Explorer IDE

[Overview](https://www.apollographql.com/docs/graphos/platform/explorer)[Connect and Authenticate](https://www.apollographql.com/docs/graphos/platform/explorer/connect)[Operation Collections](https://www.apollographql.com/docs/graphos/platform/explorer/operation-collections)[Subscription Support](https://www.apollographql.com/docs/graphos/platform/explorer/subscription-support)[Embed](https://www.apollographql.com/docs/graphos/platform/explorer/embed)[Scripting](https://www.apollographql.com/docs/graphos/platform/explorer/scripting)[Additional Features](https://www.apollographql.com/docs/graphos/platform/explorer/additional-features)

### Graph Security

[Overview](https://www.apollographql.com/docs/graphos/platform/security/overview)[Persisted Queries](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries)

### Metrics and Insights

[Overview](https://www.apollographql.com/docs/graphos/platform/insights)

### Metrics Collection and Forwarding

[Sending Metrics to GraphOS](https://www.apollographql.com/docs/graphos/platform/insights/sending-operation-metrics)[Operation Signatures](https://www.apollographql.com/docs/graphos/platform/insights/operation-signatures)[Datadog Forwarding](https://www.apollographql.com/docs/graphos/platform/insights/datadog-forwarding)

### Insights and Analysis

[Operation Metrics](https://www.apollographql.com/docs/graphos/platform/insights/operation-metrics)[Field Usage](https://www.apollographql.com/docs/graphos/platform/insights/field-usage)[Error Diagnostics](https://www.apollographql.com/docs/graphos/platform/insights/errors)[Subgraph Metrics](https://www.apollographql.com/docs/graphos/platform/insights/subgraphs)[Segmenting by Client](https://www.apollographql.com/docs/graphos/platform/insights/client-segmentation)

### Notifications and Alerts

[Overview](https://www.apollographql.com/docs/graphos/platform/insights/notifications)[Daily Reports](https://www.apollographql.com/docs/graphos/platform/insights/notifications/daily-reports)[Schema Changes](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-changes)[Schema Proposals](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-proposals)[Performance Alerts](https://www.apollographql.com/docs/graphos/platform/insights/notifications/performance-alerts)[Build Status](https://www.apollographql.com/docs/graphos/platform/insights/notifications/build-status)

### Access Management

[Organizations](https://www.apollographql.com/docs/graphos/platform/access-management/org)[API Keys](https://www.apollographql.com/docs/graphos/platform/access-management/api-keys)[Members, Roles, and Permissions](https://www.apollographql.com/docs/graphos/platform/access-management/member-roles)[Audit Logs](https://www.apollographql.com/docs/graphos/platform/access-management/audit-log)

### SSO

[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/sso/overview)[Multi-Organization](https://www.apollographql.com/docs/graphos/platform/access-management/sso/multi-organization)

### SAML

[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-microsoft-entra-id)[Generic SAML Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-integration-guide)

### OIDC

[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-microsoft-entra-id)[Generic OIDC Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-integration-guide)

### SCIM

[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/scim)[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/scim/okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/scim/microsoft-entra-id)

### Graph Management

[Using Variants](https://www.apollographql.com/docs/graphos/platform/graph-management/variants)[Adding Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/add-subgraphs)[Managing Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/manage-subgraphs)[Updating Graph Components](https://www.apollographql.com/docs/graphos/platform/graph-management/updates)[Transferring Graphs](https://www.apollographql.com/docs/graphos/platform/graph-management/transfers)

### Production Readiness

[Production Readiness Checklist](https://www.apollographql.com/docs/graphos/platform/production-readiness/checklist)

### Testing and Load Management

[Overload Protection](https://www.apollographql.com/docs/graphos/platform/production-readiness/overload-protection)[Load Testing](https://www.apollographql.com/docs/graphos/platform/production-readiness/load-testing)[Testing with Federation](https://www.apollographql.com/docs/graphos/platform/production-readiness/testing-with-apollo-federation)

### Environment and Deployment

[Environment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/environment-best-practices)[Schema Change Management](https://www.apollographql.com/docs/graphos/platform/production-readiness/change-management)[Updating Client Schema](https://www.apollographql.com/docs/graphos/platform/production-readiness/updating-client-schema)[Deployment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/deployment-best-practices)

[Platform Limits](https://www.apollographql.com/docs/graphos/platform/platform-limits)[GraphOS Platform API](https://www.apollographql.com/docs/graphos/platform/platform-api)[GraphOS MCP Tools](https://www.apollographql.com/docs/graphos/platform/graphos-mcp-tools)

## Routing

Apollo Router - v2 (latest)

[Overview](https://www.apollographql.com/docs/graphos/routing)[Get Started](https://www.apollographql.com/docs/graphos/routing/get-started)[Request Lifecycle](https://www.apollographql.com/docs/graphos/routing/request-lifecycle)

### Configuration

[Overview](https://www.apollographql.com/docs/graphos/routing/configuration/overview)[Environment Variable Reference](https://www.apollographql.com/docs/graphos/routing/configuration/envvars)[CLI Reference](https://www.apollographql.com/docs/graphos/routing/configuration/cli)[YAML Reference](https://www.apollographql.com/docs/graphos/routing/configuration/yaml)

### Features

### Security

[Overview](https://www.apollographql.com/docs/graphos/routing/security)[Persisted Queries](https://www.apollographql.com/docs/graphos/routing/security/persisted-queries)[Authorization](https://www.apollographql.com/docs/graphos/routing/security/authorization)

### Authentication

[JWT Authentication](https://www.apollographql.com/docs/graphos/routing/security/jwt)[Router Authentication](https://www.apollographql.com/docs/graphos/routing/security/router-authentication)[Subgraph Authentication](https://www.apollographql.com/docs/graphos/routing/security/subgraph-authentication)

[CORS](https://www.apollographql.com/docs/graphos/routing/security/cors)[CSRF Prevention](https://www.apollographql.com/docs/graphos/routing/security/csrf)[TLS](https://www.apollographql.com/docs/graphos/routing/security/tls)[Request Limits](https://www.apollographql.com/docs/graphos/routing/security/request-limits)[Demand Control](https://www.apollographql.com/docs/graphos/routing/security/demand-control)

### Observability

### Studio Insights

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/graphos)[Operation Metrics Reporting](https://www.apollographql.com/docs/graphos/routing/observability/graphos/graphos-reporting)[Federated Trace Data](https://www.apollographql.com/docs/graphos/routing/observability/graphos/federated-trace-data)

### Router Telemetry (OTEL)

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel)

### Telemetry Data

### Metrics

[Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/instruments)[Standard Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-instruments)

[Events](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/events)

### Traces

[Spans](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/spans)[Standard Attributes](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-attributes)

[Conditions](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/conditions)[Selectors](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/selectors)

### Usage Guides

### Subgraph Observability

[Subgraph Error Inclusion](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/subgraph-error-inclusion)[Debugging Subgraph Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-subgraph-requests)[Instrumenting Subgraphs](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/subgraph-instrumentation)

### Client Observability

[Debugging Client Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-client-requests)[Client ID Enforcement](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/client-id-enforcement)

### Telemetry Exporters

### Metrics Exporters

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/otlp)

### Log Exporters

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/overview)[Stdout](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/stdout)

### Trace Exporters

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/otlp)

### APM Guides

### Datadog

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog)

### Connecting to Datadog

[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog)[OpenTelemetry Collector](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/otel-collector)

### Datadog Agent

[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-traces)

[Router Instrumentation](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/router-instrumentation)[Dashboard Template](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/observing-and-monitoring/dashboard-template)

### New Relic

[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-traces)

### Prometheus

[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/prometheus-metrics)[Trace Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/otel-traces-to-prometheus)

### Zipkin

[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/zipkin/zipkin-traces)

### Jaeger

[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/jaeger/jaeger-traces)

### Dynatrace

[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-traces)

### Performance and Scaling

[Overview](https://www.apollographql.com/docs/graphos/routing/performance)

### Response Caching

[Overview](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/overview)[Quickstart](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/quickstart)[Invalidation](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/invalidation)[Customization](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/customization)[Observability](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/observability)[FAQ](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/faq)

[Traffic Shaping](https://www.apollographql.com/docs/graphos/routing/performance/traffic-shaping)[Query Batching](https://www.apollographql.com/docs/graphos/routing/performance/query-batching)

### Client Features

[APQ](https://www.apollographql.com/docs/graphos/routing/operations/apq)[HTTP Header Propagation](https://www.apollographql.com/docs/graphos/routing/header-propagation)[@defer](https://www.apollographql.com/docs/graphos/routing/operations/defer)

### GraphQL Subscriptions

[Overview](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/overview)[Configuration](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/configuration)[Callback Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/callback-protocol)[Multipart Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol)[Enable with API Gateway](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/api-gateway)

[File Upload](https://www.apollographql.com/docs/graphos/routing/operations/file-upload)

### Query Planning

[Native Query Planner](https://www.apollographql.com/docs/graphos/routing/query-planning/native-query-planner)[Best Practices](https://www.apollographql.com/docs/graphos/routing/query-planning/query-planning-best-practices)[Caching](https://www.apollographql.com/docs/graphos/routing/query-planning/caching)

### Customization

[Overview](https://www.apollographql.com/docs/graphos/routing/customization/overview)

### Coprocessors

[Coprocessor Configuration](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor)[Coprocessor Reference](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor/reference)

### Rhai Scripts

[Rhai Configuration](https://www.apollographql.com/docs/graphos/routing/customization/rhai)[Rhai API Reference](https://www.apollographql.com/docs/graphos/routing/customization/rhai/reference)

### Custom Builds

[Building a Binary](https://www.apollographql.com/docs/graphos/routing/customization/custom-binary)[Rust Plugins](https://www.apollographql.com/docs/graphos/routing/customization/native-plugins)

### Deployment

[Overview](https://www.apollographql.com/docs/graphos/routing/self-hosted)

### Docker

[Docker with the Apollo Runtime Container](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker)[Docker with Apollo Router](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker-router-only)

### Kubernetes

[Quickstart](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/quickstart)[Deploying with Extensibility](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/extensibility)[Enabling Metrics](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/metrics)[Other Considerations](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/other-considerations)

### AWS

[AWS ECS](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/aws)

### Azure

[Azure Container Apps](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/azure)

### GCP

[Google Cloud Run](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/gcp)

### Managed Hosting

[Railway](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/railway)[Render](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/render)

### Apollo Cloud Routing

[Overview](https://www.apollographql.com/docs/graphos/routing/cloud)[Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/configuration)[Secure Subgraphs](https://www.apollographql.com/docs/graphos/routing/cloud/secure-subgraphs)[Subscriptions](https://www.apollographql.com/docs/graphos/routing/cloud/subscriptions)[Serverless](https://www.apollographql.com/docs/graphos/routing/cloud/serverless)

### Dedicated

[Overview](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated)[Quickstart](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated-quickstart)[Custom Domains](https://www.apollographql.com/docs/graphos/routing/cloud/custom-domains)[Throughput Guide](https://www.apollographql.com/docs/graphos/routing/cloud/throughput-guide)[Migrate to Dedicated](https://www.apollographql.com/docs/graphos/routing/cloud/migrate-to-dedicated)

### AWS Lattice

[Lattice Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-configuration)[Lattice Management](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-management)[Lattice Troubleshooting](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-troubleshooting)

### Tools

[Router Resource Estimator](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-estimator)[Health Checks](https://www.apollographql.com/docs/graphos/routing/self-hosted/health-checks)[Resource Management](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-management)

### Releases

[Changelogs](https://www.apollographql.com/docs/graphos/routing/changelog)[What's New in Router v2](https://www.apollographql.com/docs/graphos/routing/about-v2)[Upgrade from Router v1](https://www.apollographql.com/docs/graphos/routing/upgrade/from-router-v1)[Migrate from Gateway](https://www.apollographql.com/docs/graphos/routing/migration/from-gateway)[API Gateway Comparison](https://www.apollographql.com/docs/graphos/routing/router-api-gateway-comparison)

### GraphOS Integration

[GraphOS Plan License](https://www.apollographql.com/docs/graphos/routing/license)[GraphOS Plan Features](https://www.apollographql.com/docs/graphos/routing/graphos-features)[Apollo Uplink](https://www.apollographql.com/docs/graphos/routing/uplink)

### Reference

[Federation Version Support](https://www.apollographql.com/docs/graphos/routing/federation-version-support)[Errors](https://www.apollographql.com/docs/graphos/routing/errors)

## Resources

[Overview](https://www.apollographql.com/docs/graphos/resources)[Changelogs](https://www.apollographql.com/docs/graphos/resources/changelog)[Glossary](https://www.apollographql.com/docs/graphos/resources/glossary)[Examples](https://www.apollographql.com/docs/graphos/resources/solutions)

### Release Policies

[Apollo Feature Launch Stages](https://www.apollographql.com/docs/graphos/resources/feature-launch-stages)[GraphOS Router Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/router-release-lifecycle)[Apollo Client Library Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/client-library-release-lifecycle)

### Architecture

[Reference Architecture](https://www.apollographql.com/docs/graphos/resources/architecture)

### Supergraph Architecture Framework

[Overview](https://www.apollographql.com/docs/graphos/resources/saf)[Operational Excellence](https://www.apollographql.com/docs/graphos/resources/saf/operational-excellence)[Security](https://www.apollographql.com/docs/graphos/resources/saf/security)[Reliability](https://www.apollographql.com/docs/graphos/resources/saf/reliability)[Performance](https://www.apollographql.com/docs/graphos/resources/saf/performance)[Developer Experience](https://www.apollographql.com/docs/graphos/resources/saf/developer-experience)

### GraphQL Adoption Guides

[GraphQL Adoption Patterns](https://www.apollographql.com/docs/graphos/resources/guides/graphql-adoption-patterns)[Using GraphQL for Abstraction](https://www.apollographql.com/docs/graphos/resources/guides/using-graphql-for-abstraction)[Supergraph Stewardship](https://www.apollographql.com/docs/graphos/resources/guides/supergraph-stewardship)

## Rover CLI

[Overview](https://www.apollographql.com/docs/rover)[Install](https://www.apollographql.com/docs/rover/getting-started)[Configure](https://www.apollographql.com/docs/rover/configuring)[Proxy Configuration](https://www.apollographql.com/docs/rover/proxy)[CI/CD](https://www.apollographql.com/docs/rover/ci-cd)[Conventions](https://www.apollographql.com/docs/rover/conventions)[Privacy and Data Collection](https://www.apollographql.com/docs/rover/privacy)[Contributing](https://www.apollographql.com/docs/rover/contributing)[Error Codes](https://www.apollographql.com/docs/rover/errors)

### Commands

[api-key](https://www.apollographql.com/docs/rover/commands/api-key)[cloud](https://www.apollographql.com/docs/rover/commands/cloud)[config](https://www.apollographql.com/docs/rover/commands/config)[connector](https://www.apollographql.com/docs/rover/commands/connectors)[contract](https://www.apollographql.com/docs/rover/commands/contracts)[dev](https://www.apollographql.com/docs/rover/commands/dev)[explain](https://www.apollographql.com/docs/rover/commands/explain)[graph](https://www.apollographql.com/docs/rover/commands/graphs)[init](https://www.apollographql.com/docs/rover/commands/init)[license](https://www.apollographql.com/docs/rover/commands/license)[persisted-queries](https://www.apollographql.com/docs/rover/commands/persisted-queries)[readme](https://www.apollographql.com/docs/rover/commands/readmes)[subgraph](https://www.apollographql.com/docs/rover/commands/subgraphs)[supergraph](https://www.apollographql.com/docs/rover/commands/supergraphs)[template](https://www.apollographql.com/docs/rover/commands/template)

### The Apollo CLI (deprecated)

[Installation](https://www.apollographql.com/docs/rover/apollo-cli)[Validating Client Operations](https://www.apollographql.com/docs/rover/validating-client-operations)[Moving to Rover](https://www.apollographql.com/docs/rover/migration)

## IDE Support

### IDE Support

[Overview](https://www.apollographql.com/docs/ide-support)[Visual Studio Code](https://www.apollographql.com/docs/ide-support/vs-code)[JetBrains IDEs](https://www.apollographql.com/docs/ide-support/jetbrains)[Vim/NeoVim](https://www.apollographql.com/docs/ide-support/vim)

## Apollo Client (Web)

Apollo Client (Web) - v4 (latest)

[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)

### Core concepts

[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directives](https://www.apollographql.com/docs/react/data/directives)[Error handling](https://www.apollographql.com/docs/react/data/error-handling)[Persisted queries](https://www.apollographql.com/docs/react/data/persisted-queries)[Document transforms](https://www.apollographql.com/docs/react/data/document-transforms)[Deferring response data](https://www.apollographql.com/docs/react/data/defer)[Best practices](https://www.apollographql.com/docs/react/data/operation-best-practices)

### Caching

[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.com/docs/react/caching/memory-management)[Advanced topics](https://www.apollographql.com/docs/react/caching/advanced-topics)

### Pagination

[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)

### Local State

[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)

### Development & Testing

[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client-schema-mocking)[Reducing bundle size](https://www.apollographql.com/docs/react/development-testing/reducing-bundle-size)

### Performance

[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)

### Integrations

[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)

### Networking

[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)

### API Reference

### Core

[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)

### Errors

[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/react/api/errors/ServerParseError)[UnconventionalError](https://www.apollographql.com/docs/react/api/errors/UnconventionalError)

### React

[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](https://www.apollographql.com/docs/react/api/react/useApolloClient)[useReactiveVar](https://www.apollographql.com/docs/react/api/react/useReactiveVar)[useSuspenseQuery](https://www.apollographql.com/docs/react/api/react/useSuspenseQuery)[useBackgroundQuery](https://www.apollographql.com/docs/react/api/react/useBackgroundQuery)[useReadQuery](https://www.apollographql.com/docs/react/api/react/useReadQuery)[useLoadableQuery](https://www.apollographql.com/docs/react/api/react/useLoadableQuery)[useQueryRefHandlers](https://www.apollographql.com/docs/react/api/react/useQueryRefHandlers)[skipToken](https://www.apollographql.com/docs/react/api/react/skipToken)[createQueryPreloader](https://www.apollographql.com/docs/react/api/react/preloading)[MockProvider](https://www.apollographql.com/docs/react/api/react/testing)[SSR](https://www.apollographql.com/docs/react/api/react/ssr)

### Apollo Link

[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch)[ClientAwarenessLink](https://www.apollographql.com/docs/react/api/link/apollo-link-client-awareness)[ErrorLink](https://www.apollographql.com/docs/react/api/link/apollo-link-error)[GraphQLWsLink](https://www.apollographql.com/docs/react/api/link/apollo-link-subscriptions)[HttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-http)[PersistedQueryLink](https://www.apollographql.com/docs/react/api/link/apollo-link-persisted-queries)[RemoveTypenameFromVariablesLink](https://www.apollographql.com/docs/react/api/link/apollo-link-remove-typename)[RetryLink](https://www.apollographql.com/docs/react/api/link/apollo-link-retry)[SchemaLink](https://www.apollographql.com/docs/react/api/link/apollo-link-schema)[SetContextLink](https://www.apollographql.com/docs/react/api/link/apollo-link-context)[WebSocketLink (deprecated)](https://www.apollographql.com/docs/react/api/link/apollo-link-ws)[Community links](https://www.apollographql.com/docs/react/api/link/community-links)

[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)

## Apollo iOS

Apollo iOS - v2 (latest)

[Introduction](https://www.apollographql.com/docs/ios)[Get Started](https://www.apollographql.com/docs/ios/get-started)

### Project Configuration

[Introduction](https://www.apollographql.com/docs/ios/project-configuration/intro)[1\. Project Modularization](https://www.apollographql.com/docs/ios/project-configuration/modularization)[2\. Schema Types](https://www.apollographql.com/docs/ios/project-configuration/schema-types)[3\. Operation Models](https://www.apollographql.com/docs/ios/project-configuration/operation-models)[SDK components](https://www.apollographql.com/docs/ios/project-configuration/sdk-components)

### Migration Guides

[v2.0](https://www.apollographql.com/docs/ios/migrations/2.0)

### Tutorial

[Code Generation](https://www.apollographql.com/docs/ios/tutorial/codegen-getting-started)

### Build a project with Apollo

[Introduction](https://www.apollographql.com/docs/ios/tutorial/tutorial-introduction)[1\. Configure your project](https://www.apollographql.com/docs/ios/tutorial/tutorial-configure-project)[2\. Add the GraphQL schema](https://www.apollographql.com/docs/ios/tutorial/tutorial-add-graphql-schema)[3\. Write your first query](https://www.apollographql.com/docs/ios/tutorial/tutorial-write-your-first-query)[4\. Running code generation](https://www.apollographql.com/docs/ios/tutorial/tutorial-running-code-generation)[5\. Execute your first query](https://www.apollographql.com/docs/ios/tutorial/tutorial-execute-first-query)[6\. Connect your queries to your UI](https://www.apollographql.com/docs/ios/tutorial/tutorial-connect-queries-to-ui)[7\. Add more info to the list](https://www.apollographql.com/docs/ios/tutorial/tutorial-add-more-info-to-list)[8\. Paginate results](https://www.apollographql.com/docs/ios/tutorial/tutorial-paginate-results)[9\. Complete the details view](https://www.apollographql.com/docs/ios/tutorial/tutorial-complete-details-view)[10\. Write your first mutation](https://www.apollographql.com/docs/ios/tutorial/tutorial-first-mutation)[11\. Authenticate your operations](https://www.apollographql.com/docs/ios/tutorial/tutorial-authenticate-operations)[12\. Define additional mutations](https://www.apollographql.com/docs/ios/tutorial/tutorial-define-additional-mutations)

[API Reference](https://www.apollographql.com/docs/ios/docc/documentation)

### Code Generation

[Introduction](https://www.apollographql.com/docs/ios/code-generation/introduction)[The Codegen CLI](https://www.apollographql.com/docs/ios/code-generation/codegen-cli)[Configuration](https://www.apollographql.com/docs/ios/code-generation/codegen-configuration)[Downloading a Schema](https://www.apollographql.com/docs/ios/code-generation/downloading-schema)[Running Code Generation in Swift Code](https://www.apollographql.com/docs/ios/code-generation/run-codegen-in-swift-code)[Code Generation Troubleshooting](https://www.apollographql.com/docs/ios/troubleshooting/codegen-troubleshooting)

### Fetching

[Fetching Data](https://www.apollographql.com/docs/ios/fetching/fetching-data)

### Operations

[Queries](https://www.apollographql.com/docs/ios/fetching/queries)[Mutations](https://www.apollographql.com/docs/ios/fetching/mutations)[Subscriptions](https://www.apollographql.com/docs/ios/fetching/subscriptions)[Fragments](https://www.apollographql.com/docs/ios/fetching/fragments)

[Operation Arguments](https://www.apollographql.com/docs/ios/fetching/operation-arguments)[Error Handling](https://www.apollographql.com/docs/ios/fetching/error-handling)[Type Conditions](https://www.apollographql.com/docs/ios/fetching/type-conditions)[Custom Scalars](https://www.apollographql.com/docs/ios/custom-scalars)[Persisted Queries](https://www.apollographql.com/docs/ios/fetching/persisted-queries)[@defer support](https://www.apollographql.com/docs/ios/fetching/defer)

### Caching

[Introduction](https://www.apollographql.com/docs/ios/caching/introduction)[Setup](https://www.apollographql.com/docs/ios/caching/cache-setup)[Direct Cache Access](https://www.apollographql.com/docs/ios/caching/cache-transactions)[Custom Cache Keys](https://www.apollographql.com/docs/ios/caching/cache-key-resolution)[Programmatic Cache Keys](https://www.apollographql.com/docs/ios/caching/programmatic-cache-keys)

### Networking

[Creating a Client](https://www.apollographql.com/docs/ios/networking/client-creation)

### Pagination

[Introduction](https://www.apollographql.com/docs/ios/pagination/introduction)[Using Custom Response Models](https://www.apollographql.com/docs/ios/pagination/custom-types)[Directional Pagination](https://www.apollographql.com/docs/ios/pagination/directional-pagers)[Multi-query Pagination](https://www.apollographql.com/docs/ios/pagination/multi-query)

### Development & Testing

[Test Mocks](https://www.apollographql.com/docs/ios/testing/test-mocks)[Including Apollo as an XCFramework](https://www.apollographql.com/docs/ios/development/using-xcframework)

### Advanced

[File Uploads](https://www.apollographql.com/docs/ios/advanced/file-uploads)[Request Chain Customization](https://www.apollographql.com/docs/ios/advanced/request-chain)[Client Directives](https://www.apollographql.com/docs/ios/client-directives)

## Apollo Kotlin

Apollo Kotlin - v4 (latest)

[Get Started](https://www.apollographql.com/docs/kotlin)[Migrating to v4](https://www.apollographql.com/docs/kotlin/migration/4.0)[Modules](https://www.apollographql.com/docs/kotlin/essentials/modules)[Evolution policy](https://www.apollographql.com/docs/kotlin/essentials/evolution)[Tutorial](https://www.apollographql.com/tutorials/apollo-kotlin-android-part1)[Kdoc](https://apollographql.github.io/apollo-kotlin/kdoc/older/4.2.0/)[Changelog](https://github.com/apollographql/apollo-kotlin/blob/main/CHANGELOG.md)

### Configuration

[Gradle plugin configuration](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration)[Gradle plugin recipes](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes)[Multi Modules](https://www.apollographql.com/docs/kotlin/advanced/multi-modules)[File types](https://www.apollographql.com/docs/kotlin/essentials/file-types)[Client Awareness](https://www.apollographql.com/docs/kotlin/advanced/client-awareness)

### Fetching

[Queries](https://www.apollographql.com/docs/kotlin/essentials/queries)[Mutations](https://www.apollographql.com/docs/kotlin/essentials/mutations)[Subscriptions](https://www.apollographql.com/docs/kotlin/essentials/subscriptions)[GraphQL variables](https://www.apollographql.com/docs/kotlin/advanced/operation-variables)[Error handling](https://www.apollographql.com/docs/kotlin/essentials/errors)[Custom scalars](https://www.apollographql.com/docs/kotlin/essentials/custom-scalars)[Fragments](https://www.apollographql.com/docs/kotlin/essentials/fragments)[@defer support](https://www.apollographql.com/docs/kotlin/fetching/defer)[Persisted queries](https://www.apollographql.com/docs/kotlin/advanced/persisted-queries)

### Caching

[Introduction](https://www.apollographql.com/docs/kotlin/caching/introduction)[Normalized caches](https://www.apollographql.com/docs/kotlin/caching/normalized-cache)[Declarative cache IDs](https://www.apollographql.com/docs/kotlin/caching/declarative-ids)[Programmatic cache IDs](https://www.apollographql.com/docs/kotlin/caching/programmatic-ids)[Watching cached data](https://www.apollographql.com/docs/kotlin/caching/query-watchers)[ApolloStore](https://www.apollographql.com/docs/kotlin/caching/store)[HTTP cache](https://www.apollographql.com/docs/kotlin/caching/http-cache)[Troubleshooting](https://www.apollographql.com/docs/kotlin/caching/troubleshooting)

### Networking

[Interceptors](https://www.apollographql.com/docs/kotlin/advanced/interceptors-http)[Custom HTTP clients](https://www.apollographql.com/docs/kotlin/advanced/http-engine)[Using the models without apollo-runtime](https://www.apollographql.com/docs/kotlin/advanced/no-runtime)[Authentication](https://www.apollographql.com/docs/kotlin/advanced/authentication)[WebSocket errors](https://www.apollographql.com/docs/kotlin/advanced/websocket-errors)[Batching operations](https://www.apollographql.com/docs/kotlin/advanced/query-batching)

### Development & Testing

[Testing overview](https://www.apollographql.com/docs/kotlin/testing/overview)[Mocking HTTP responses](https://www.apollographql.com/docs/kotlin/testing/mocking-http-responses)[Mocking GraphQL responses](https://www.apollographql.com/docs/kotlin/testing/mocking-graphql-responses)[Data builders](https://www.apollographql.com/docs/kotlin/testing/data-builders)[Android Studio plugin](https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin)[Apollo Debug Server](https://www.apollographql.com/docs/kotlin/testing/apollo-debug-server)

### Advanced

[Uploading files](https://www.apollographql.com/docs/kotlin/advanced/upload)[Monitoring the network state](https://www.apollographql.com/docs/kotlin/advanced/network-connectivity)[Handling nullability](https://www.apollographql.com/docs/kotlin/advanced/nullability)[Experimental WebSockets](https://www.apollographql.com/docs/kotlin/advanced/experimental-websockets)[Using aliases](https://www.apollographql.com/docs/kotlin/advanced/using-aliases)[Using Java](https://www.apollographql.com/docs/kotlin/advanced/java)[Apollo AST](https://www.apollographql.com/docs/kotlin/advanced/apollo-ast)[Compiler plugins](https://www.apollographql.com/docs/kotlin/advanced/compiler-plugins)[JS Interoperability](https://www.apollographql.com/docs/kotlin/advanced/js-interop)[Response based codegen](https://www.apollographql.com/docs/kotlin/advanced/response-based)[Apollo Kotlin galaxy](https://www.apollographql.com/docs/kotlin/advanced/galaxy)

## Apollo Server

Apollo Server - v4âv5 (latest)

[Introduction](https://www.apollographql.com/docs/apollo-server)[Get started](https://www.apollographql.com/docs/apollo-server/getting-started)

### New in v4 and v5

[Migrating from Apollo Server 4](https://www.apollographql.com/docs/apollo-server/migration)[Migrating from Apollo Server 3](https://www.apollographql.com/docs/apollo-server/migration-from-v3)[Previous versions](https://www.apollographql.com/docs/apollo-server/previous-versions)[Changelog](https://github.com/apollographql/apollo-server/blob/main/packages/server/CHANGELOG.md)

### Defining a Schema

[Schema basics](https://www.apollographql.com/docs/apollo-server/schema/schema)[Unions and interfaces](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces)[Custom scalars](https://www.apollographql.com/docs/apollo-server/schema/custom-scalars)[Directives](https://www.apollographql.com/docs/apollo-server/schema/directives)

### Resolving Operations

[Resolvers](https://www.apollographql.com/docs/apollo-server/data/resolvers)[Sharing context](https://www.apollographql.com/docs/apollo-server/data/context)[Error handling](https://www.apollographql.com/docs/apollo-server/data/errors)[Subscriptions](https://www.apollographql.com/docs/apollo-server/data/subscriptions)

### Fetching Data

[Overview](https://www.apollographql.com/docs/apollo-server/data/fetching-data)[REST APIs](https://www.apollographql.com/docs/apollo-server/data/fetching-rest)

### Web Frameworks

[Integrations](https://www.apollographql.com/docs/apollo-server/integrations/integration-index)[Building integrations](https://www.apollographql.com/docs/apollo-server/integrations/building-integrations)[MERN stack tutorial](https://www.apollographql.com/docs/apollo-server/integrations/mern)

### Development Workflow

[Build and run queries](https://www.apollographql.com/docs/apollo-server/workflow/build-run-queries)[Request format](https://www.apollographql.com/docs/apollo-server/workflow/requests)[Generating TS types](https://www.apollographql.com/docs/apollo-server/workflow/generate-types)[Mocking](https://www.apollographql.com/docs/apollo-server/testing/mocking)[Integration testing](https://www.apollographql.com/docs/apollo-server/testing/testing)[Apollo Studio Explorer](https://www.apollographql.com/docs/studio/explorer/)

### Performance

[Caching](https://www.apollographql.com/docs/apollo-server/performance/caching)[Cache backends](https://www.apollographql.com/docs/apollo-server/performance/cache-backends)[Response Cache Eviction](https://www.apollographql.com/docs/apollo-server/performance/response-cache-eviction)[Automatic persisted queries](https://www.apollographql.com/docs/apollo-server/performance/apq)

### Security

[Auth](https://www.apollographql.com/docs/apollo-server/security/authentication)[CORS](https://www.apollographql.com/docs/apollo-server/security/cors)[Terminating SSL](https://www.apollographql.com/docs/apollo-server/security/terminating-ssl)[Proxy configuration](https://www.apollographql.com/docs/apollo-server/security/proxy-configuration)

### Deployment

[Lambda](https://www.apollographql.com/docs/apollo-server/deployment/lambda)[Heroku](https://www.apollographql.com/docs/apollo-server/deployment/heroku)

### Monitoring

[Metrics and logging](https://www.apollographql.com/docs/apollo-server/monitoring/metrics)[Health checks](https://www.apollographql.com/docs/apollo-server/monitoring/health-checks)

### API Reference

[ApolloServer](https://www.apollographql.com/docs/apollo-server/api/apollo-server)[startStandaloneServer](https://www.apollographql.com/docs/apollo-server/api/standalone)[expressMiddleware](https://www.apollographql.com/docs/apollo-server/api/express-middleware)

### Plugins

[Overview](https://www.apollographql.com/docs/apollo-server/builtin-plugins)

### Built-in

[Usage reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting)[Schema reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/schema-reporting)[Inline trace](https://www.apollographql.com/docs/apollo-server/api/plugin/inline-trace)[Drain HTTP server](https://www.apollographql.com/docs/apollo-server/api/plugin/drain-http-server)[Cache control](https://www.apollographql.com/docs/apollo-server/api/plugin/cache-control)[Landing pages](https://www.apollographql.com/docs/apollo-server/api/plugin/landing-pages)[Federated subscriptions](https://www.apollographql.com/docs/apollo-server/api/plugin/subscription-callback)

### Custom

[Creating plugins](https://www.apollographql.com/docs/apollo-server/integrations/plugins)[Event reference](https://www.apollographql.com/docs/apollo-server/integrations/plugins-event-reference)

### Using with Federation

### As a subgraph

[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup)[@apollo/subgraph reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-subgraph)

### As a gateway

[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-gateway-setup)[Gateway performance](https://www.apollographql.com/docs/apollo-server/using-federation/gateway-performance)[@apollo/gateway reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-gateway)

## Apollo MCP Server

Apollo MCP Server - v1 (latest)

[Overview](https://www.apollographql.com/docs/apollo-mcp-server)[Quickstart](https://www.apollographql.com/docs/apollo-mcp-server/quickstart)[Define tools](https://www.apollographql.com/docs/apollo-mcp-server/define-tools)

### Configuration

[YAML Config Reference](https://www.apollographql.com/docs/apollo-mcp-server/config-file)[Custom Scalars](https://www.apollographql.com/docs/apollo-mcp-server/custom-scalars)

[Run the MCP Server](https://www.apollographql.com/docs/apollo-mcp-server/run)[Debugging](https://www.apollographql.com/docs/apollo-mcp-server/debugging)

### Deployment

[Overview](https://www.apollographql.com/docs/apollo-mcp-server/deploy)[Health Checks](https://www.apollographql.com/docs/apollo-mcp-server/health-checks)[CORS](https://www.apollographql.com/docs/apollo-mcp-server/cors)

[Authorization](https://www.apollographql.com/docs/apollo-mcp-server/auth)[Telemetry](https://www.apollographql.com/docs/apollo-mcp-server/telemetry)[Best Practices](https://www.apollographql.com/docs/apollo-mcp-server/best-practices)[Licensing](https://www.apollographql.com/docs/apollo-mcp-server/licensing)[Limitations](https://www.apollographql.com/docs/apollo-mcp-server/limitations)

### Guides

[Authorization with Auth0](https://www.apollographql.com/docs/apollo-mcp-server/guides/auth-auth0)

## Apollo Operator

[Overview](https://www.apollographql.com/docs/apollo-operator)

### Getting Started

[Install Operator](https://www.apollographql.com/docs/apollo-operator/get-started/install-operator)[Add Subgraphs](https://www.apollographql.com/docs/apollo-operator/get-started/add-subgraphs)[Deploy Supergraphs](https://www.apollographql.com/docs/apollo-operator/get-started/deploy-supergraph)

### Kubernetes Resources

### Supergraph

[Overview](https://www.apollographql.com/docs/apollo-operator/resources/supergraph)[Autoscaling your Supergraphs](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/autoscalers)[Supergraph podTemplate](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/pod_template)[Supergraph networking](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/networking)

[SupergraphSchema](https://www.apollographql.com/docs/apollo-operator/resources/supergraphschema)[SupergraphSet](https://www.apollographql.com/docs/apollo-operator/resources/supergraphset)[Subgraph](https://www.apollographql.com/docs/apollo-operator/resources/subgraph)

### Workflows

[Overview](https://www.apollographql.com/docs/apollo-operator/workflows)[Single Cluster Setup](https://www.apollographql.com/docs/apollo-operator/workflows/single-cluster)[Multi-Cluster & Hybrid Setup](https://www.apollographql.com/docs/apollo-operator/workflows/multi-cluster)[Deploy Only](https://www.apollographql.com/docs/apollo-operator/workflows/deploy-only)

### Configuration

[Overview](https://www.apollographql.com/docs/apollo-operator/configuration)[Telemetry](https://www.apollographql.com/docs/apollo-operator/configuration/telemetry)[Controllers](https://www.apollographql.com/docs/apollo-operator/configuration/controllers)[OCI](https://www.apollographql.com/docs/apollo-operator/configuration/oci)[Private Registries](https://www.apollographql.com/docs/apollo-operator/configuration/private-registries)

[Security Best Practices](https://www.apollographql.com/docs/apollo-operator/security-best-practices)

[Apollo Client (Web)](react)

## 

On this page

Copy as MD

  * Prerequisites 

  * Executing a query 

  * Caching query results 

  * Updating cached query results 

  * Polling 

  * Refetching 

  * Inspecting loading states 

  * Inspecting error states 

  * Fetching in response to user interaction 

  * Re-rendering with new options 

  * Working with variables 

  * Using the promise returned from the execution function 

  * Setting a fetch policy 

  * nextFetchPolicy 

  * Supported fetch policies 

  * Skipping queries with skipToken 

  * useQuery API 

  * Options 

  * Result 

  * Next steps 




[ Home ](/docs/)

/ [ Apollo Client (Web) ](/docs/react)

/ [ Core concepts ](/docs/react/data/queries)

[ Apollo Client (Web) ](/docs/react)

#  Queries 

Fetch data with the useQuery hook

Ask AI a question about this page

Ask with ChatGPT

Ask with ClaudeAsk with ChatGPT

* * *

This article shows how to fetch GraphQL data in React with the `useQuery` hook and attach the result to your UI. You'll also learn how Apollo Client simplifies data management code by tracking error and loading states for you.

**note**

This article shows how to use Apollo Client in a React application that doesn't make use of React's "Suspense" features. For modern React applications built around Suspense, suspense-enabled data fetching hooks are described in Apollo Client's [Suspense docs](https://www.apollographql.com/docs/react/data/suspense/).

## Prerequisites

**note**

If your application is built using TypeScript, we recommend reading the [TypeScript guide](https://www.apollographql.com/docs/react/development-testing/static-typing) to learn how to use TypeScript with Apollo Client.

This article assumes you're familiar with building basic GraphQL queries. If you need a refresher, we recommend [this guide](http://graphql.org/learn/queries/). You can also build example queries against Apollo's [full-stack tutorial server](https://apollo-fullstack-tutorial.herokuapp.com/graphql).

This article also assumes that you've already set up Apollo Client and have wrapped your React app in an `ApolloProvider` component. For more information, see the [getting started guide](https://www.apollographql.com/docs/react/get-started/).

> To follow along with the examples below, open up our [starter project](https://codesandbox.io/s/queries-example-app-start-nvp9z) and [sample GraphQL server](https://codesandbox.io/s/queries-example-app-server-71z1g) on CodeSandbox. You can view the completed version of the app [here](https://codesandbox.io/s/queries-example-app-final-nrlnl).

## Executing a query

The `useQuery` [React hook](https://react.dev/reference/react) is the primary API for executing queries in a non-suspenseful Apollo application (for information about using Apollo Client with suspenseful React, see [Suspense](https://www.apollographql.com/docs/react/data/suspense)). To run a query within a React component, call `useQuery` and pass it a GraphQL document. When your component renders, `useQuery` returns an object from Apollo Client that contains `loading`, `error`, `dataState` and `data` properties you can use to render your UI.

Let's look at an example. First, we'll create a GraphQL query named `GET_DOGS`. Remember to wrap query strings in the `gql` function to parse them into query documents:

JavaScript

index.js

copy
    
    
    1import { gql } from "@apollo/client";
    2import { useQuery } from "@apollo/client/react";
    3
    4const GET_DOGS = gql`
    5  query GetDogs {
    6    dogs {
    7      id
    8      breed
    9    }
    10  }
    11`;

Next, we'll create a component named `Dogs`. Inside it, we'll pass our `GET_DOGS` query to the `useQuery` hook:

JavaScript

index.js

copy
    
    
    1function Dogs({ onDogSelected }) {
    2  const { loading, error, data } = useQuery(GET_DOGS);
    3
    4  if (loading) return "Loading...";
    5  if (error) return `Error! ${error.message}`;
    6
    7  return (
    8    <select name="dog" onChange={onDogSelected}>
    9      {data.dogs.map((dog) => (
    10        <option key={dog.id} value={dog.breed}>
    11          {dog.breed}
    12        </option>
    13      ))}
    14    </select>
    15  );
    16}

As our query executes and the values of `loading`, `error`, and `data` change, the `Dogs` component can intelligently render different UI elements according to the query's state:

  * As long as `loading` is `true` (indicating the query is still in flight), the component presents a `Loading...` notice.

  * When loading is `false` and there is no `error`, the query has completed. The component renders a dropdown menu that's populated with the list of dog breeds returned by the server.




When the user selects a dog breed from the populated dropdown, the selection is sent to the parent component via the provided `onDogSelected` function.

**note**

If you are using TypeScript, `data` is typed as `unknown` when the query type is unknown. Accessing fields on `data` results in a TypeScript error. See the [TypeScript with Apollo Client](https://www.apollographql.com/docs/react/development-testing/static-typing) guide to learn how to add types for your queries.

In the next step, we'll associate the dropdown with a more sophisticated query that uses GraphQL variables.

## Caching query results

Whenever Apollo Client fetches query results from your server, it automatically **caches** those results locally. This makes later executions of that same query extremely fast.

To see this caching in action, let's build a new component called `DogPhoto`. `DogPhoto` accepts a prop called `breed` that reflects the current value of the dropdown menu in our `Dogs` component:

JavaScript

index.js

copy
    
    
    1const GET_DOG_PHOTO = gql`
    2  query Dog($breed: String!) {
    3    dog(breed: $breed) {
    4      id
    5      displayImage
    6    }
    7  }
    8`;
    9
    10function DogPhoto({ breed }) {
    11  const { loading, error, data } = useQuery(GET_DOG_PHOTO, {
    12    variables: { breed },
    13  });
    14
    15  if (loading) return null;
    16  if (error) return `Error! ${error}`;
    17
    18  return (
    19    <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
    20  );
    21}

Notice that we're providing a configuration option (`variables`) to the `useQuery` hook this time. The `variables` option is an object that contains all of the variables we want to pass to our GraphQL query. In this case, we want to pass the currently selected `breed` from the dropdown.

Select `bulldog` from the dropdown to see its photo appear. Then switch to another breed, and then switch _back_ to `bulldog`. You'll notice that the bulldog photo loads instantly the second time around. This is the cache at work!

Next, let's learn some techniques for ensuring that our cached data is fresh.

## Updating cached query results

Sometimes, you want to make sure that your query's cached data is up to date with your _server's_ data. Apollo Client supports two strategies for this: **polling** and **refetching**.

### Polling

Polling provides near-real-time synchronization with your server by executing your query periodically at a specified interval. To enable polling for a query, pass a `pollInterval` configuration option to the `useQuery` hook with an interval in milliseconds:

JavaScript

index.js

copy
    
    
    1function DogPhoto({ breed }) {
    2  const { loading, error, data } = useQuery(GET_DOG_PHOTO, {
    3    variables: { breed },
    4    pollInterval: 500,
    5  });
    6
    7  if (loading) return null;
    8  if (error) return `Error! ${error}`;
    9
    10  return (
    11    <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
    12  );
    13}

By setting `pollInterval` to 500, we fetch the current breed's image from the server every 0.5 seconds. Note that if you set `pollInterval` to `0`, the query does **not** poll.

> You can also start and stop polling dynamically with the [`startPolling` and `stopPolling` functions](https://www.apollographql.com/docs/react/data/queries#startpolling) that are returned by the `useQuery` hook. When using these functions, set the `pollInterval` configuration option as a parameter of the `startPolling` function.

### Refetching

Refetching enables you to refresh query results in response to a particular user action, as opposed to using a fixed interval.

Let's add a button to our `DogPhoto` component that calls our query's `refetch` function whenever it's clicked.

You can optionally provide a new `variables` object to the `refetch` function. If you don't provide a `variables` object, the query uses the same `variables` object that it used in its previous execution.

JavaScript

index.js

copy
    
    
    1function DogPhoto({ breed }) {
    2  const { loading, error, data, refetch } = useQuery(GET_DOG_PHOTO, {
    3    variables: { breed },
    4  });
    5
    6  if (loading) return null;
    7  if (error) return `Error! ${error}`;
    8
    9  return (
    10    <div>
    11      <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
    12      <button onClick={() => refetch()}>Refetch new breed!</button>
    13    </div>
    14  );
    15}

Click the button and notice that the UI updates with a new dog photo. Refetching is an excellent way to guarantee fresh data, but it introduces some complexity with loading state. In the next section, we'll cover strategies for handling complex loading and error state.

#### Providing new variables to `refetch`

You call `refetch` with a new set of variables like so:

JavaScript

copy
    
    
    1<button
    2  onClick={() =>
    3    refetch({
    4      breed: "dalmatian", // Always refetches a dalmatian instead of original breed
    5    })
    6  }
    7>
    8  Refetch!
    9</button>;

If you provide new values for _some_ of your original query's variables but not _all_ of them, `refetch` uses each omitted variable's original value.

## Inspecting loading states

We've already seen that the `useQuery` hook exposes our query's current loading state. This is helpful when a query first loads, but what happens to our loading state when we're refetching or polling?

Let's return to our refetching example from the previous section. If you click the refetch button, you'll see that the component re-renders while we're refetching the photo.

The `useQuery` hook's result object provides fine-grained information about the status of the query via the `networkStatus` property. This allows us to indicate to the user that we're refetching the photo:

JavaScript

index.js

copy
    
    
    1import { NetworkStatus } from "@apollo/client";
    2
    3function DogPhoto({ breed }) {
    4  const { loading, error, data, refetch, networkStatus } = useQuery(
    5    GET_DOG_PHOTO,
    6    {
    7      variables: { breed },
    8    }
    9  );
    10
    11  if (networkStatus === NetworkStatus.refetch) return "Refetching!";
    12  if (loading) return null;
    13  if (error) return `Error! ${error}`;
    14
    15  return (
    16    <div>
    17      <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
    18      <button onClick={() => refetch()}>Refetch!</button>
    19    </div>
    20  );
    21}

The value of `loading` also updates accordingly. Even if you don't use the more fine-grained information provided by the `networkStatus` property, the `loading` property indicates that the refetch is in progress.

The `networkStatus` property is a `NetworkStatus` enum that represents different loading states. Refetch is represented by `NetworkStatus.refetch`. There are additional values for e.g. polling and pagination. For a full list of all the possible loading states, check out [this table](https://www.apollographql.com/docs/react/api/core/ObservableQuery#networkstatus).

**note**

If you want to disable automatic re-rendering when the network status changes, set `notifyOnNetworkStatusChange` to `false` either in individual queries or globally via `defaultOptions`:

JavaScript

copy
    
    
    1const client = new ApolloClient({
    2  // ... other options
    3  defaultOptions: {
    4    watchQuery: {
    5      notifyOnNetworkStatusChange: false,
    6    },
    7  },
    8});

> To view a complete version of the app we just built, check out the CodeSandbox [here](https://codesandbox.io/s/queries-example-app-final-nrlnl).

## Inspecting error states

You can customize your query error handling by providing the `errorPolicy` configuration option to the `useQuery` hook. The default value is `none`, which tells Apollo Client to treat all GraphQL errors as runtime errors. In this case, Apollo Client discards any query response data returned by the server and sets the `error` property in the `useQuery` result object.

If you set `errorPolicy` to `all`, `useQuery` does _not_ discard query response data, allowing you to render partial results.

For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).

## Fetching in response to user interaction

When React renders a component that calls `useQuery`, Apollo Client automatically executes the corresponding query. But what if you want to execute a query in response to a user interaction, such as a user clicking a button?

The [`useLazyQuery`](https://www.apollographql.com/docs/react/api/react/useLazyQuery) hook is for manually executing queries. Unlike `useQuery`, when you use `useLazyQuery`, it doesn't immediately execute its associated query. Instead, it returns an execution function that you call whenever you need to execute the query.

Here's an example:

JavaScript

index.js

copy
    
    
    1import React from "react";
    2import { useLazyQuery } from "@apollo/client/react";
    3
    4function GetDogsOnClick() {
    5  const [getDogs, { loading, error, data }] = useLazyQuery(GET_DOGS);
    6
    7  if (loading) return <p>Loading ...</p>;
    8  if (error) return `Error! ${error.message}`;
    9
    10  return (
    11    <div>
    12      {data?.dogs.map((dog) => (
    13        <Dog key={dog.id} dog={dog} />
    14      ))}
    15      <button onClick={() => getDogs()}>Load dogs</button>
    16    </div>
    17  );
    18}

The first item in `useLazyQuery`'s return tuple is the execution function, and the second item is an object that contains information about the executed query, such as the `loading`, `error`, `data`, and `dataState` properties.

### Re-rendering with new options

Unlike `useQuery`, options provided to `useLazyQuery` that change on re-renders do not automatically execute the query. Instead, `useLazyQuery` waits to execute the query with the updated options until you call the execution function again.

The following is an example that changes the fetch policy depending on whether the user is online or offline:

TypeScript

copy
    
    
    1function GetDogs({ isOnline }) {
    2  const [getDogs, { loading, data }] = useLazyQuery(GET_DOGS, {
    3    fetchPolicy: isOnline ? "network-only" : "cache-only",
    4  });
    5
    6  if (loading) return <p>Loading ...</p>;
    7
    8  return (
    9    <div>
    10      {data && <Dogs data={data.dogs} />}
    11      <button onClick={() => getDogs()}>Get dogs</button>
    12    </div>
    13  );
    14}

**note**

The changed options are immediately applied to the underlying `ObservableQuery` (accessible by the `observable` property) even though the query isn't executed. Inspecting the options on the `observable` returns the updated options. This means the updated options are used for other APIs (such as `refetch`), even before you call the execution function again.

### Working with variables

You provide `variables` to the execution function when executing the query.

The following example gets a specific dog's photo when you click the **Get photo** button:

JavaScript

copy
    
    
    1function DogPhoto() {
    2  const [getDogPhoto, { loading, error, data }] = useLazyQuery(GET_DOG_PHOTO);
    3
    4  if (loading) return <p>Loading ...</p>;
    5  if (error) return `Error! ${error.message}`;
    6
    7  return (
    8    <div>
    9      {data?.dog && <img src={data.dog.displayImage} />}
    10      <button onClick={() => getDogPhoto({ variables: { name: "Lucky" } })}>
    11        Get photo
    12      </button>
    13    </div>
    14  );
    15}

**note**

When using TypeScript, the `variables` option is required if the query provided to `useLazyQuery` contains required variables. If the options argument isn't provided to the execution function, or the `variables` option is missing required variables, TypeScript raises an error.

#### Changing variables

You change variables by calling the execution function with updated variables.

The following example gets the selected dog's photo when you click the **Get photo** button.

JavaScript

copy
    
    
    1function DogPhoto() {
    2  const [selectedDog, setSelectedDog] = useState(null);
    3  const [getDogPhoto, { loading, error, data }] = useLazyQuery(GET_DOG_PHOTO);
    4
    5  if (loading) return <p>Loading ...</p>;
    6  if (error) return `Error! ${error.message}`;
    7
    8  return (
    9    <div>
    10      <DogSelect
    11        onChange={(dogName) => setSelectedDog(dogName)}
    12        value={selectedDog}
    13      />
    14      {data?.dog && <img src={data.dog.displayImage} />}
    15      {selectedDog && (
    16        <button
    17          onClick={() => getDogPhoto({ variables: { name: selectedDog } })}
    18        >
    19          Get photo
    20        </button>
    21      )}
    22    </div>
    23  );
    24}

If you need to reference the currently executed query's variables, use the `variables` property returned by `useLazyQuery`. The `variables` property contains the value of the variables from the last execution of the query.

**tip**

The `variables` property is empty until you call the execution function for the first time. Use the `called` property returned by `useLazyQuery` to determine if you've called the execution function at least once.

JavaScript

copy
    
    
    1function DogPhoto() {
    2  const [getDogPhoto, { called, variables }] = useLazyQuery(GET_DOG_PHOTO);
    3
    4  return (
    5    <div>
    6      {/* ... */}
    7      <button onClick={() => getDogPhoto({ variables: { name: selectedDog } })}>
    8        Get photo
    9      </button>
    10
    11      {called && <span>Last fetched: {variables.name}</span>}
    12    </div>
    13  );
    14}

### Using the promise returned from the execution function

The execution function returns a promise that resolves with the query result:

JavaScript

copy
    
    
    1function GetDogs() {
    2  const [getDogs, { data, loading, error }] = useLazyQuery(GET_DOGS);
    3
    4  const handleClick = async () => {
    5    const { data } = await getDogs();
    6
    7    // Do something with `data`
    8  };
    9
    10  return (
    11    <div>
    12      {/* ... */}
    13      <button onClick={handleClick}>Get dogs</button>
    14    </div>
    15  );
    16}

The result returned from the promise is useful when you need to execute side-effects using the data returned by the query.

**tip**

Use the `data`, `error`, and other properties returned by `useLazyQuery` to sync the query state with your component. Avoid using your own state setters from React's `useState` hook with data resolved from the promise. This ensures your component stays up-to-date with cache changes as they occur throughout your application.  
  
In cases where you don't need to keep your component in sync with query state, use `client.query()` directly because it won't unnecessarily render your component for data that you don't use.Using `useLazyQuery` in these situations is an antipattern.

Example

TypeScript

copy
    
    
    1import { useApolloClient } from "@apollo/client/react";
    2
    3function GetDogs() {
    4  const client = useApolloClient();
    5
    6  const handleClick = async () => {
    7    const { data } = await client.query({ query: GET_DOGS });
    8
    9    // Do something with `data`
    10  };
    11
    12  return <button onClick={handleClick}>Get dogs</button>;
    13}

#### Handling errors

The promise resolves or rejects depending on the configured [`errorPolicy`](https://www.apollographql.com/docs/react/data/error-handling#setting-an-error-policy). For a more comprehensive guide on working with errors, read the [Error handling documentation](https://www.apollographql.com/docs/react/data/error-handling).

##### `errorPolicy: "none"`

The promise rejects with the error that caused the query to fail.

TypeScript

copy
    
    
    1const handleClick = async () => {
    2  try {
    3    const { data } = await getDogs();
    4  } catch (error) {
    5    if (CombinedGraphQLErrors.is(error)) {
    6      // handle GraphQL errors
    7    }
    8
    9    // Handle other error types
    10    console.log(error.message);
    11  }
    12};

**note**

Errors always cause the promise to reject. The `error` property is never set when the promise resolves.

##### `errorPolicy: "all"`

The promise resolves with an object that includes the error and any partial data returned by the query. Read the partial data on the `data` property and the error that caused the query to fail on the `error` property.

TypeScript

copy
    
    
    1const handleClick = async () => {
    2  const { data, error } = await getDogs();
    3
    4  if (CombinedGraphQLErrors.is(error)) {
    5    // handle GraphQL errors returned by the query
    6  }
    7};

**note**

The `data` property might be `undefined` instead of containing partial data. This typically occurs when a [network error](https://www.apollographql.com/docs/react/data/error-handling#network-errors) causes the query to fail, because the error isn't associated with GraphQL execution.

##### `errorPolicy: "ignore"`

The promise resolves with an object that includes any partial data returned by the query. Errors are discarded.

TypeScript

copy
    
    
    1const handleClick = async () => {
    2  const { data } = await getDogs();
    3
    4  if (data !== undefined) {
    5    // Do something with the returned data
    6  }
    7};

**tip**

`data` might be `undefined` if a [network error](https://www.apollographql.com/docs/react/data/error-handling#network-errors) occurs. Check if `data` is `undefined` before you use it, in case an error occurs during query execution.

#### Retaining query results

Apollo Client aborts in-flight queries executed by `useLazyQuery` when the component unmounts or when you start another query by calling the execution function. This causes the promise to reject. In some cases, you might find this behavior undesirable and prefer to let the query run to completion.

**note**

Apollo Client ensures the rejected promise doesn't throw an unhandled rejection error when you don't add a rejection handler to the promise. However, this means that aborted errors are silent and might go unnoticed. If you want to be notified when the request is aborted, provide a rejection handler for the promise.

The promise returned by the execution function includes a `.retain()` method. When you call it, it ensures the query continues running even if the component unmounts or you start a new query before the previous one finishes.

JavaScript

copy
    
    
    1function GetDogs() {
    2  const [getDogs] = useLazyQuery(GET_DOGS);
    3
    4  const handleClick = async () => {
    5    const promise = getDogs();
    6
    7    // Retain the query even if component unmounts
    8    promise.retain();
    9
    10    const { data } = await promise;
    11
    12    // Do something with data
    13  };
    14
    15  return <button onClick={handleClick}>Get dogs</button>;
    16}

The `retain()` method returns the original promise, so you can shorten the previous example to a single line:

TypeScript

copy
    
    
    1const { data } = await getDogs().retain();

For a complete list of supported options and result properties, see the [`useLazyQuery` API reference](https://www.apollographql.com/docs/react/api/react/useLazyQuery).

## Setting a fetch policy

By default, the `useQuery` hook checks the Apollo Client cache to see if all the data you requested is already available. If all of the data _is_ available in the cache, `useQuery` returns that data and _doesn't_ query your GraphQL server. This `cache-first` policy is Apollo Client's default **fetch policy**.

You specify a fetch policy using the `fetchPolicy` option. For example, we can instruct `useQuery` to bypass the cache and fetch from the network by setting the `fetchPolicy` option to `network-only`:

JavaScript

copy
    
    
    1const { loading, error, data } = useQuery(GET_DOGS, {
    2  fetchPolicy: "network-only", // Doesn't check cache before making a network request
    3});

### `nextFetchPolicy`

You can _also_ specify a query's `nextFetchPolicy`. When provided, `fetchPolicy` is used for the query's _first_ execution, and `nextFetchPolicy` is used to determine how the query responds to future cache updates:

JavaScript

copy
    
    
    1const { loading, error, data } = useQuery(GET_DOGS, {
    2  fetchPolicy: "network-only", // Used for first execution
    3  nextFetchPolicy: "cache-first", // Used for subsequent executions
    4});

For example, this is helpful if you want a query to always make an initial network request, but you're comfortable reading from the cache after that.

#### `nextFetchPolicy` functions

If you want to apply a single `nextFetchPolicy` by default, because you find yourself manually providing `nextFetchPolicy` for most of your queries, you can configure `defaultOptions.watchQuery.nextFetchPolicy` when creating your `ApolloClient` instance:

JavaScript

copy
    
    
    1new ApolloClient({
    2  link,
    3  client,
    4  defaultOptions: {
    5    watchQuery: {
    6      nextFetchPolicy: "cache-only",
    7    },
    8  },
    9});

This configuration applies to all `client.watchQuery` calls and `useQuery` calls that do not otherwise configure `nextFetchPolicy`.

If you want more control over how `nextFetchPolicy` behaves, you can provide a function instead of a `WatchQueryFetchPolicy` string:

JavaScript

copy
    
    
    1new ApolloClient({
    2  link,
    3  client,
    4  defaultOptions: {
    5    watchQuery: {
    6      nextFetchPolicy(currentFetchPolicy) {
    7        if (
    8          currentFetchPolicy === "network-only" ||
    9          currentFetchPolicy === "cache-and-network"
    10        ) {
    11          // Demote the network policies (except "no-cache") to "cache-first"
    12          // after the first request.
    13          return "cache-first";
    14        }
    15        // Leave all other fetch policies unchanged.
    16        return currentFetchPolicy;
    17      },
    18    },
    19  },
    20});

This `nextFetchPolicy` function will be called after each request, and uses the `currentFetchPolicy` parameter to decide how to modify the fetch policy.

In addition to being called after each request, your `nextFetchPolicy` function will also be called when variables change, which by default resets the `fetchPolicy` to its initial value, which is often important to trigger a fresh network request for queries that started out with `cache-and-network` or `network-only` fetch policies.

To intercept and handle the `variables-changed` case yourself, you can use the `NextFetchPolicyContext` object passed as the second argument to your `nextFetchPolicy` function:

JavaScript

copy
    
    
    1new ApolloClient({
    2  link,
    3  client,
    4  defaultOptions: {
    5    watchQuery: {
    6      nextFetchPolicy(
    7        currentFetchPolicy,
    8        {
    9          // Either "after-fetch" or "variables-changed", indicating why the
    10          // nextFetchPolicy function was invoked.
    11          reason,
    12          // The rest of the options (currentFetchPolicy === options.fetchPolicy).
    13          options,
    14          // The original value of options.fetchPolicy, before nextFetchPolicy was
    15          // applied for the first time.
    16          initialFetchPolicy,
    17          // The ObservableQuery associated with this client.watchQuery call.
    18          observable,
    19        }
    20      ) {
    21        // When variables change, the default behavior is to reset
    22        // options.fetchPolicy to context.initialFetchPolicy. If you omit this logic,
    23        // your nextFetchPolicy function can override this default behavior to
    24        // prevent options.fetchPolicy from changing in this case.
    25        if (reason === "variables-changed") {
    26          return initialFetchPolicy;
    27        }
    28
    29        if (
    30          currentFetchPolicy === "network-only" ||
    31          currentFetchPolicy === "cache-and-network"
    32        ) {
    33          // Demote the network policies (except "no-cache") to "cache-first"
    34          // after the first request.
    35          return "cache-first";
    36        }
    37
    38        // Leave all other fetch policies unchanged.
    39        return currentFetchPolicy;
    40      },
    41    },
    42  },
    43});

In order to debug these `nextFetchPolicy` transitions, it can be useful to add `console.log` or `debugger` statements to the function body, to see when and why the function is called.

### Supported fetch policies

Name | Description  
---|---  
  
###### `cache-first`

(default)| Apollo Client first executes the query against the cache. If _all_ requested data is present in the cache, that data is returned. Otherwise, Apollo Client executes the query against your GraphQL server and returns that data after caching it.Prioritizes minimizing the number of network requests sent by your application.This is the default fetch policy.  
  
###### `cache-only`

| Apollo Client executes the query _only_ against the cache. It never queries your server in this case.When the cache does not contain data for all requested fields, a `cache-only` query returns `data: undefined` with `dataState: "empty"` and a `networkStatus` of `NetworkStatus.ready`.  
  
###### `cache-and-network`

| Apollo Client executes the full query against both the cache _and_ your GraphQL server. The query automatically updates if the result of the server-side query modifies cached fields.Provides a fast response while also helping to keep cached data consistent with server data.  
  
###### `network-only`

| Apollo Client executes the full query against your GraphQL server, _without_ first checking the cache. The query's result _is_ stored in the cache. After the first result is received, external cache updates will be reflected by this query.Prioritizes consistency with server data, but can't provide a near-instantaneous response when cached data is available.  
  
###### `no-cache`

| Similar to `network-only`, except the query's result _is not_ stored in the cache and external cache updates are completely ignored.  
  
###### `standby`

| Uses the same logic as `cache-first`, except this query does _not_ automatically update when underlying field values change. You can still _manually_ update this query with `refetch` and `updateQueries`.`standby` queries return `networkStatus: NetworkStatus.ready` even before subscription, providing immediate feedback to your UI.  
  
## Skipping queries with `skipToken`Requires â¥ 4.0.4

`skipToken` provides a type-safe mechanism to skip query execution. When you pass `skipToken` to `useQuery` instead of the options object, the hook will not execute the query and keeps the last `data` available. It is typically used conditionally to start query execution when the input data is available.

JavaScript

Recommended usage of skipToken with useQuery

copy
    
    
    1import { skipToken, useQuery } from "@apollo/client/react";
    2
    3const { data } = useQuery(query, id ? { variables: { id } } : skipToken);

Imagine this common scenario: You want to skip your query if a certain required variable is not set. You might be tempted to write something like this:

TypeScript

copy
    
    
    1const { data } = useQuery(query, {
    2  variables: { id },
    3  skip: !id,
    4});

But in that case, TypeScript will complain:

Text

copy
    
    
    1Type 'number | undefined' is not assignable to type 'number'.
    2      Type 'undefined' is not assignable to type 'number'.ts(2769)

To get around that, you have to tell TypeScript to ignore the fact that `id` could be `undefined`:

TypeScript

copy
    
    
    1const { data } = useQuery(query, {
    2  variables: { id: id! },
    3  skip: !id,
    4});

Alternatively, you could also use some obscure default value:

TypeScript

copy
    
    
    1const { data } = useQuery(query, {
    2  variables: { id: id || 0 },
    3  skip: !id,
    4});

Both of these solutions hide a potential bug. If your `skip` logic becomes more complex, you might accidentally introduce a bug that causes your query to execute, even when `id` is still `undefined`. In that case, TypeScript cannot warn you about it.

Instead we recommend using `skipToken`. It provides type safety without the need for an obscure default value:

TypeScript

copy
    
    
    1const { data } = useQuery(query, id ? { variables: { id } } : skipToken);

Here it becomes apparent for TypeScript that there is a direct connection between skipping and the `variables` option - and it will work without unsafe workarounds.

## `useQuery` API

Supported options and result fields for the `useQuery` hook are listed below.

Most calls to `useQuery` can omit the majority of these options, but it's useful to know they exist. To learn about the `useQuery` hook API in more detail with usage examples, see the [API reference](https://www.apollographql.com/docs/react/api/react/hooks/#usequery).

### Options

The `useQuery` hook accepts the following options:

Operation options

###### [`client` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-client)

`ApolloClient`

The instance of `ApolloClient` to use to execute the query.

By default, the instance that's passed down via context is used, but you can provide a different instance here.

###### [`errorPolicy` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-errorpolicy)

`ErrorPolicy`

Specifies how the query handles a response that returns both GraphQL errors and partial results.

For details, see [GraphQL error policies](https://www.apollographql.com/docs/react/data/error-handling/#graphql-error-policies).

The default value is `none`, meaning that the query result includes error details but not partial results.

###### [`skip` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-skip)

`boolean`

If true, the query is not executed.

The default value is `false`.

###### [`variables` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-variables)

`TVariables`

An object containing all of the GraphQL variables your query requires to execute.

Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.

Networking options

###### [`context` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-context)

`DefaultContext`

If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.

###### [`notifyOnNetworkStatusChange` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-notifyonnetworkstatuschange)

`boolean`

If `true`, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.

The default value is `true`.

###### [`pollInterval` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-pollinterval)

`number`

Specifies the interval (in milliseconds) at which the query polls for updated results.

The default value is `0` (no polling).

###### [`skipPollAttempt` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-skippollattempt)

`() => boolean`

A callback function that's called whenever a refetch attempt occurs while polling. If the function returns `true`, the refetch is skipped and not reattempted until the next poll interval.

###### [`ssr` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-ssr)

`boolean`

Pass `false` to skip executing the query during [server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering/).

Caching options

###### [`fetchPolicy` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-fetchpolicy)

`WatchQueryFetchPolicy`

Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).

For details, see [Setting a fetch policy](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy).

The default value is `cache-first`.

###### [`initialFetchPolicy` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-initialfetchpolicy)

`WatchQueryFetchPolicy`

Defaults to the initial value of options.fetchPolicy, but can be explicitly configured to specify the WatchQueryFetchPolicy to revert back to whenever variables change (unless nextFetchPolicy intervenes).

###### [`nextFetchPolicy` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-nextfetchpolicy)

`WatchQueryFetchPolicy | ((this: ApolloClient.WatchQueryOptions<TData, TVariables>, currentFetchPolicy: WatchQueryFetchPolicy, context: InternalTypes.NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy)`

Specifies the `FetchPolicy` to be used after this query has completed.

###### [`refetchWritePolicy` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-refetchwritepolicy)

`RefetchWritePolicy`

Specifies whether a `NetworkStatus.refetch` operation should merge incoming field data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with Apollo Client 3.x.

###### [`returnPartialData` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryhookoptions-interface-returnpartialdata)

`boolean`

If `true`, the query can return partial results from the cache if the cache doesn't contain results for all queried fields.

The default value is `false`.

### Result

After being called, the `useQuery` hook returns a result object with the following properties. This object contains your query result, plus some helpful functions for refetching, dynamic polling, and pagination.

Operation data

###### [`data` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-data)

`DataValue.Complete<TData> | DataValue.Streaming<TData> | DataValue.Partial<TData> | undefined`

An object containing the result of your GraphQL query after it completes.

This value might be `undefined` if a query results in one or more errors (depending on the query's `errorPolicy`).

###### [`dataState`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-datastate)

`"complete" | "streaming" | "partial" | "empty"`

Describes the completeness of `data`.

  * `empty`: No data could be fulfilled from the cache or the result is incomplete. `data` is `undefined`.

  * `partial`: Some data could be fulfilled from the cache but `data` is incomplete. This is only possible when `returnPartialData` is `true`.

  * `streaming`: `data` is incomplete as a result of a deferred query and the result is still streaming in.

  * `complete`: `data` is a fully satisfied query result fulfilled either from the cache or network.




###### [`error` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-error)

`ErrorLike`

A single ErrorLike object describing the error that occurred during the latest query execution.

For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).

###### [`previousData` _(optional)_](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-previousdata)

`MaybeMasked<TData>`

An object containing the result from the most recent _previous_ execution of this query.

This value is `undefined` if this is the query's first execution.

###### [`variables`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-variables)

`TReturnVariables`

An object containing the variables that were provided for the query.

Network info

###### [`client`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-client)

`ApolloClient`

The instance of Apollo Client that executed the query. Can be useful for manually executing followup queries or writing data to the cache.

###### [`loading`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-loading)

`boolean`

If `true`, the query is still in flight.

###### [`networkStatus`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-networkstatus)

`NetworkStatus`

A number indicating the current network state of the query's associated request. [See possible values.](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/core/networkStatus.ts#L4)

Used in conjunction with the [`notifyOnNetworkStatusChange`](https://www.apollographql.com/docs#notifyonnetworkstatuschange) option.

Helper functions

###### [`fetchMore`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-fetchmore)

`<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: ObservableQuery.FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars>) => Promise<ApolloClient.QueryResult<MaybeMasked<TFetchData>>>`

A function that helps you fetch the next set of results for a [paginated list field](https://www.apollographql.com/docs/react/pagination/core-api/).

###### [`refetch`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-refetch)

`(variables?: Partial<TVariables>) => Promise<ApolloClient.QueryResult<MaybeMasked<TData>>>`

A function that enables you to re-execute the query, optionally passing in new `variables`.

To guarantee that the refetch performs a network request, its `fetchPolicy` is set to `network-only` (unless the original query's `fetchPolicy` is `no-cache` or `cache-and-network`, which also guarantee a network request).

See also [Refetching](https://www.apollographql.com/docs/react/data/queries/#refetching).

Returns a `ResultPromise` with an additional `.retain()` method. Calling `.retain()` keeps the network operation running even if the `ObservableQuery` no longer requires the result.

###### [`startPolling`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-startpolling)

`(pollInterval: number) => void`

A function that instructs the query to begin re-executing at a specified interval (in milliseconds).

###### [`stopPolling`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-stoppolling)

`() => void`

A function that instructs the query to stop polling after a previous call to `startPolling`.

###### [`subscribeToMore`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-subscribetomore)

`SubscribeToMoreFunction<TData, TVariables>`

A function that enables you to execute a [subscription](https://www.apollographql.com/docs/react/data/subscriptions/), usually to subscribe to specific fields that were included in the query.

This function returns _another_ function that you can call to terminate the subscription.

###### [`updateQuery`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-updatequery)

`(mapFn: UpdateQueryMapFn<TData, TVariables>) => void`

A function that enables you to update the query's cached result without executing a followup GraphQL operation.

See [using updateQuery and updateFragment](https://www.apollographql.com/docs/react/caching/cache-interaction/#using-updatequery-and-updatefragment) for additional information.

Other

###### [`observable`](https://www.apollographql.com/docs/react/data/queries#queryresult-interface-observable)

`ObservableQuery<TData, TVariables>`

A reference to the internal `ObservableQuery` used by the hook.

## Next steps

Now that you understand how to fetch data with the `useQuery` hook, [learn how to _update_ your data with the `useMutation` hook!](https://www.apollographql.com/docs/react/data/mutations/)

After that, learn about some other handy Apollo Client features:

  * [Local state management](https://www.apollographql.com/docs/react/local-state/local-state-management/): Learn how to query local data.

  * [Pagination](https://www.apollographql.com/docs/react/pagination/overview): Learn how to fetch data incrementally from list fields.




[PreviousGet started with Apollo Client](/docs/react/get-started)

[NextSuspense](/docs/react/data/suspense)

Give FeedbackFeedback

[ Edit on GitHub ](https://github.com/apollographql/apollo-client/blob/main/./docs/source/data/queries.mdx) [ Ask Community ](https://community.apollographql.com/)

[ ](https://www.apollographql.com)

(C) 2025 Apollo Graph Inc., d/b/a Apollo GraphQL. 

[ Privacy Policy ](https://www.apollographql.com/privacy-policy)

## Company

  * [ About Apollo ](https://www.apollographql.com/about-us)
  * [ Careers ](https://www.apollographql.com/careers)
  * [ Partners ](https://www.apollographql.com/partners)



## Resources

  * [ Blog ](https://blog.apollographql.com)
  * [ Tutorials ](https://www.apollographql.com/tutorials)
  * [ Content Library ](https://www.apollographql.com/resources)



## Get in touch

  * [ Contact Sales ](https://www.apollographql.com/contact-sales)
  * [ Contact Support ](https://www.apollographql.com/support)
