Skipping “what is GraphQL” — this chapter covers the concepts that matter once AppSync is resolving real production schemas against real data sources.

Every field, not every query, has its own resolver

The unit of resolution in AppSync isn’t the query as a whole — it’s the individual field. A single GraphQL query requesting a user and their list of orders, each order’s line items, and each line item’s product details, potentially invokes a distinct resolver for every one of those nested fields, each independently mapped to whatever data source actually serves that data (DynamoDB for the user, a Lambda function for orders, an HTTP data source for product details from a separate service). This field-level granularity is what makes GraphQL’s core promise — one API surface, many backends — actually work, but it’s also the direct cause of the N+1 problem covered in Chapter Two: naive field-level resolution for a list of nested objects can trigger one data source call per item unless deliberately batched.

Resolvers are a pipeline, not a single function — Before, individual, and After stages

A pipeline resolver in AppSync consists of a “before” mapping template, one or more discrete “functions” executed in sequence (each with its own request/response mapping against a specific data source), and an “after” mapping template that assembles the final field response. This pipeline architecture is what enables a single field’s resolution to involve multiple sequential data source calls with shared context passed between them — for example, checking an authorization condition against one data source before proceeding to fetch the actual data from another, all within resolving one field.

VTL and JavaScript resolvers are two distinct execution runtimes for the same resolver concept

AppSync resolvers can be written in Apache Velocity Template Language (VTL, the original resolver mechanism) or in JavaScript (the newer, generally preferred runtime for new development) — both accomplish the same job of transforming a GraphQL request into a data source request and transforming the data source response back into a GraphQL response, but they execute in different runtimes with different debugging ergonomics, different utility function libraries available, and different levels of expressiveness for complex logic. Teams standardizing on JavaScript resolvers for new work while maintaining legacy VTL resolvers is a common, and entirely supported, mixed-runtime state.

Subscriptions are not “the client polling” — they’re a distinct, persistent delivery mechanism triggered by mutations

A GraphQL subscription in AppSync isn’t the client repeatedly asking “anything new?” — it’s a persistent connection (over WebSockets, or MQTT for certain client configurations) that AppSync proactively pushes data through the moment a matching mutation resolves. The connection between “a mutation just happened” and “subscribed clients receive an update” is established explicitly at the schema level, by configuring which mutations trigger which subscriptions — this is a deliberate wiring decision, not an automatic behavior that happens for every mutation by default.

graph TB
    subgraph Pipeline["Pipeline Resolver for One Field"]
        BEFORE[Before Mapping Template] --> F1[Function 1
Data Source A]
        F1 --> F2[Function 2
Data Source B]
        F2 --> AFTER[After Mapping Template]
        AFTER --> RESULT[Final Field Response]
    end
    subgraph Subscription["Subscription Delivery"]
        MUT[Mutation Resolves] --> TRIGGER{Wired to a
subscription field?}
        TRIGGER -->|Yes| PUSH[AppSync pushes update
over persistent connection]
        PUSH --> CLIENTS[All matching
subscribed clients]
    end
        

What actually happens, mechanically, between a GraphQL query arriving and a fully assembled response being returned.

Query parsing, validation, and execution planning happen before any resolver runs

Before any data fetching begins, AppSync parses the incoming GraphQL document, validates it against the registered schema (rejecting malformed queries or references to nonexistent fields immediately), and builds an execution plan that identifies every field requiring resolution and the dependency order between them (a field can’t resolve until its parent object’s relevant data is available). This planning phase is why a syntactically invalid query fails fast with a clear error, without ever touching a single data source — validation and execution are genuinely separate internal stages.

The N+1 problem and how BatchInvoke actually solves it internally

When resolving a list field (say, “orders” returning 50 items) followed by a nested field on each item (each order’s “customer”), a naive resolver implementation calls the customer data source once per order — 50 separate calls for what’s logically one batch operation. AppSync’s BatchInvoke mechanism for Lambda data sources solves this by collecting all the individual field-resolution requests for that batch into a single Lambda invocation carrying an array of requests, letting the Lambda function’s own logic perform one batched lookup (e.g., a single DynamoDB BatchGetItem) and return an array of results mapped back to each original request — this is functionally analogous to the DataLoader pattern from the broader GraphQL ecosystem, but implemented as a first-class AppSync/Lambda data source feature rather than a client-side library.

Subscription fan-out: how one mutation reaches potentially millions of connected clients

When a mutation triggers a subscription, AppSync’s internal pub/sub infrastructure identifies every currently-connected client subscribed to that specific subscription field (filtered further by any subscription-time arguments the client specified) and pushes the resolved payload to each one over their existing persistent connection. This fan-out is handled by AppSync’s own managed real-time messaging infrastructure — the mutation resolver itself doesn’t loop through connected clients or manage delivery directly; it simply returns its result, and the subscription delivery is a separate, automatically-triggered process layered on top.

Caching operates at the resolver level, with configurable TTL and per-resolver granularity

AppSync’s caching layer, when enabled, can cache resolver responses (full response caching or per-resolver caching) with a configurable time-to-live, keyed by the resolved arguments and, optionally, the identity of the calling user for per-user cache isolation — this is a request-time optimization layered on top of the resolver pipeline itself, meaning a cache hit skips resolver execution and data source calls entirely for that specific field-and-arguments combination until the TTL expires or the cache entry is explicitly invalidated.

sequenceDiagram
    participant C as Client
    participant AS as AppSync Engine
    participant Cache as Resolver Cache
    participant L as Lambda Data Source (BatchInvoke)
    participant Sub as Subscription Fan-Out

    C->>AS: GraphQL Query (list + nested field)
    AS->>AS: Parse, validate, build execution plan
    AS->>Cache: Check cache for resolver + args
    alt Cache miss
        AS->>L: Batched request for all list items' nested field
        L-->>AS: Batched response, mapped back per item
        AS->>Cache: Store result with TTL
    end
    AS-->>C: Assembled GraphQL response

    Note over C,Sub: Separately, elsewhere:
    C->>AS: Mutation
    AS->>Sub: Mutation resolved, check subscription wiring
    Sub->>Sub: Identify all matching connected clients
    Sub-->>C: Push real-time update to each
        

Tracing a request from arrival through resolution, and a subscription connection through its own separate lifecycle.

The request lifecycle: parse, authorize, resolve, respond

A request moves through parsing/validation (Chapter Two), then authorization (checked against the configured auth mode — API key, IAM, Amazon Cognito user pools, OpenID Connect, or Lambda custom authorization — potentially at both the operation level and, for finer-grained control, the individual field level via @aws_auth directives), then resolver pipeline execution per field, and finally response assembly. A field-level authorization failure doesn’t necessarily fail the entire query — depending on how nullability is defined in the schema, a single unauthorized field can resolve to null while sibling fields the caller is authorized for still return successfully.

Subscription connection lifecycle is independent of any single query or mutation’s lifecycle

A subscription connection is established once (via a WebSocket handshake carrying its own authorization), then persists — independently of any individual mutation lifecycle — until the client disconnects, the connection times out due to inactivity, or the server-side connection is terminated for operational reasons. This means a subscription’s authorization is checked at connection/subscribe time, not re-validated on every single pushed message, which has real implications for scenarios where a user’s permissions change mid-connection: the existing subscription may continue delivering updates based on the authorization state at subscribe time until the connection is naturally re-established.

Conflict detection and resolution lifecycle for offline-capable clients

For applications built with client-side offline support (commonly via AWS Amplify’s DataStore), local mutations queued while offline are synced once connectivity resumes, and AppSync’s conflict detection (based on a version number tracked per record) identifies when a client’s mutation is based on stale data that’s since changed server-side — at which point a configured conflict resolution strategy (server wins by default, or a custom Lambda-based resolution function) determines the final state, rather than simply overwriting server data blindly with whatever the offline client queued.

AppSync’s scaling story is largely automatic, but resolver design and subscription fan-out patterns determine real-world performance.

BatchInvoke and DynamoDB BatchGetItem resolvers are the primary levers against N+1 latency

Beyond Lambda’s BatchInvoke (Chapter Two), AppSync’s native DynamoDB resolvers support BatchGetItem operations directly at the mapping-template level for list-of-references patterns, avoiding the need for a Lambda function at all in many common batched-lookup scenarios. Choosing between a native batched DynamoDB resolver and a Lambda-based BatchInvoke resolver is a genuine architectural decision — native resolvers avoid Lambda’s own cold-start and invocation overhead entirely, while Lambda-based resolvers offer more flexibility for complex batching logic that a mapping template alone can’t express.

Subscription fan-out scale is bounded primarily by concurrent connection count, not message volume alone

AppSync’s real-time infrastructure is designed to fan out a single mutation’s result to a very large number of concurrently subscribed clients, but the practical scaling consideration for advanced teams is connection count and connection churn (rapid connect/disconnect cycles, as from a mobile app backgrounding/foregrounding frequently) rather than raw message throughput — architectures with extremely high connection churn benefit from client-side reconnection backoff strategies to avoid unnecessary connection thrashing against the service.

Resolver caching trades data freshness for reduced data-source load directly and measurably

Enabling per-resolver caching on frequently-read, infrequently-changed fields (reference/lookup data, for instance) can dramatically reduce data source load and latency for read-heavy workloads, but every cached field introduces a data-freshness window bounded by the TTL — advanced teams tune TTL per resolver based on how tolerant that specific field’s data is of staleness, rather than applying one blanket cache TTL uniformly across a schema with very different field volatility profiles.

AppSync’s own availability is managed, but downstream data source reliability is still your responsibility

AppSync itself runs as a managed, multi-AZ service with no availability configuration required on your part, but a resolver’s overall reliability is only as strong as its weakest data source — a Lambda-backed resolver calling a downstream third-party HTTP API inherits that API’s availability characteristics directly, and AppSync provides no automatic circuit-breaking or fallback logic for a struggling downstream dependency unless the resolver logic itself (typically in a Lambda function) is explicitly designed with timeouts, retries, and graceful degradation.

Subscription connection resilience requires deliberate client-side reconnection logic

A subscription’s persistent connection can drop for many reasons (network transitions, client app backgrounding, transient service-side events), and AppSync does not automatically preserve missed messages during a disconnected window for later delivery upon reconnection — clients must implement their own reconnection logic, and for applications where missing an update during a brief disconnection is unacceptable, a deliberate reconciliation step (re-querying current state upon reconnect, rather than assuming the subscription stream alone is a complete history) is required.

Partial failure in pipeline resolvers needs explicit handling, not implicit assumption

In a multi-function pipeline resolver, a failure partway through (function two of three fails after function one succeeded) doesn’t automatically roll back function one’s side effects if it had any — pipeline resolvers are not transactional by default. Resolver logic that performs a write in one function and a dependent write in a later function needs its own explicit compensating logic or idempotent design if partial pipeline failure is a real possibility, rather than assuming AppSync provides transactional guarantees across pipeline stages it does not actually provide.

graph LR
    A[Client subscribes] --> B[Connection established
auth checked at connect time]
    B --> C{Connection drops
network transition}
    C --> D[Missed messages during
disconnection window are NOT queued]
    D --> E[Client reconnects]
    E --> F{App assumes subscription
alone is complete history?}
    F -->|Yes - risky| G[Silently missing updates]
    F -->|No - reconciles| H[Re-queries current state
on reconnect, safe]
        

Multiple simultaneous authorization modes are supported, and mixing them deliberately is a real pattern

AppSync supports up to several authorization modes configured simultaneously on a single API (API key for public/demo access, Cognito user pools for authenticated end users, IAM for internal service-to-service calls, OIDC for third-party identity federation, and Lambda custom authorizers for fully bespoke logic), with individual fields able to specify which of the enabled modes they accept via @aws_auth directives — this allows, for example, a public read-only field to accept API key auth while a mutation field on the same schema requires Cognito-authenticated identity, all within one unified API.

Field-level authorization is where the real access-control granularity lives

Operation-level authorization alone is often too coarse for real applications — field-level @aws_auth directives, combined with resolver logic that checks the calling identity’s specific attributes (via $context.identity in VTL or the equivalent in JavaScript resolvers) against the requested data, is what implements genuine row-level or attribute-level access control, such as “a user can query their own order details but not another user’s.” Relying on operation-level auth alone for this kind of requirement is a common security gap.

IAM authorization for data sources is separate from API-facing client authorization

The authorization mode governing how a client calls the AppSync API (Cognito, API key, etc.) is entirely separate from the IAM role AppSync itself assumes to call its configured data sources (a DynamoDB table, a Lambda function) on the backend — a resolver’s data source IAM role should be scoped to the minimum actions and resources that specific data source integration needs, following the same least-privilege principle as any other AWS service-to-service permission, regardless of how permissive or restrictive the client-facing auth mode is.

API key auth is meant for temporary or low-security use cases, not production-scale authenticated access

API keys are simple to configure and useful for prototyping, public demo endpoints, or short-lived third-party integrations, but they carry no per-user identity, expire on a fixed schedule requiring manual or automated rotation, and provide no fine-grained access control beyond whatever field-level rules are applied uniformly to anyone holding the key — production applications with real user identity requirements should use Cognito, OIDC, or Lambda custom authorization instead.

Field-level CloudWatch Logs are the primary debugging tool for resolver behavior

When enabled, AppSync’s field-level logging captures per-field request and response mapping detail, resolver execution time, and any errors at the individual field level — this granularity is what makes diagnosing “which specific nested field in a complex query is slow or failing” tractable, since aggregate API-level metrics alone can’t distinguish a slow top-level query from one specific slow nested field buried several levels deep in the response tree.

X-Ray tracing reveals the full resolver pipeline and downstream data source call chain

AWS X-Ray integration traces a request through its entire resolver pipeline, including each function stage in a pipeline resolver and calls out to Lambda, DynamoDB, or HTTP data sources — this is the tool that actually answers “where is the latency coming from” for a multi-stage pipeline resolver spanning several data sources, which aggregate latency metrics alone would blend together indistinguishably.

Subscription-specific metrics require their own dedicated monitoring lens

Beyond standard query/mutation metrics, mature AppSync observability tracks active subscription connection count, connection churn rate, and subscription message delivery latency separately from query/mutation resolver metrics — these are fundamentally different operational characteristics (long-lived connections vs. discrete request/response cycles) that a single unified dashboard treating all API activity identically will tend to obscure.

Data source diversity is the core integration story — one API, many backends

AppSync natively integrates DynamoDB, Lambda, RDS (via Aurora Data API), OpenSearch, HTTP endpoints (for calling any REST or other HTTP-based service), and EventBridge as data sources — a single schema can mix several of these across different fields, letting a GraphQL API front an existing microservices architecture without requiring every backend to be rewritten around GraphQL itself; the HTTP data source type specifically is what makes AppSync a viable API gateway layer in front of legacy or third-party REST services.

Merged APIs let independently-owned schemas compose into one unified endpoint

AppSync’s merged API capability allows multiple independently developed and deployed “source” GraphQL APIs (potentially owned by different teams) to be composed into a single “merged” API presenting one unified schema and endpoint to clients — this is the mechanism that supports a federated, team-owned-schema development model at organizational scale, similar in spirit to GraphQL federation patterns from the broader ecosystem, but implemented as a native AppSync feature.

Infrastructure-as-code patterns for schema, resolver, and data source management

Schemas, resolvers (including their mapping templates or JavaScript code), data sources, and authorization configuration are all managed via CloudFormation, Terraform, CDK, or the Amplify CLI/Gen 2 framework — advanced teams version-control resolver code alongside application code and deploy schema changes through the same CI/CD pipeline as the rest of the application, treating schema evolution with the same rigor (backward-compatibility checks, staged rollout) as any other production API contract change.

graph TD
    SCHEMA[AppSync GraphQL Schema] --> DDB[DynamoDB Data Source]
    SCHEMA --> LAMBDA[Lambda Data Source
with BatchInvoke]
    SCHEMA --> HTTP[HTTP Data Source
legacy REST services]
    SCHEMA --> RDS[Aurora Data API]
    SCHEMA --> EB[EventBridge Data Source]
    SRC1[Team A Source API] --> MERGE[Merged API]
    SRC2[Team B Source API] --> MERGE
    MERGE --> CLIENT[Single Unified
Client-Facing Endpoint]
        

Pattern: Batch by default for any list-then-nested-field pattern

Any resolver structure resembling “fetch a list, then resolve a per-item nested field” is designed with BatchInvoke (Lambda) or native BatchGetItem (DynamoDB) from the outset, rather than allowing an unbatched N+1 pattern to reach production and only fixing it once latency or cost problems surface.

Pattern: Explicit reconciliation on subscription reconnect

Client applications treat subscription reconnection as an explicit trigger to re-query current authoritative state, never assuming the subscription stream itself is a complete, gap-free history across any disconnection window.

Pattern: Field-level authorization as the default, not the exception

Every field returning user-specific or sensitive data includes an explicit identity check in its resolver logic, rather than relying on operation-level authorization alone to gate access to record-level data.

Anti-Pattern: Uniform cache TTL applied blindly across an entire schema

Applying one blanket cache TTL to every resolver, regardless of how frequently each field’s underlying data actually changes, either serves stale data on volatile fields or wastes caching benefit on fields that could safely tolerate a much longer TTL.

Anti-Pattern: Treating pipeline resolvers as transactional

Designing a multi-function pipeline resolver that performs sequential writes across stages, assuming a failure partway through automatically rolls back earlier stages’ effects, when AppSync provides no such transactional guarantee across pipeline functions by default.