GraphQL with DynamoDB: AppSync, Apollo and Amplify Gen 2

DynamoDB does not expose a GraphQL endpoint itself: use AWS AppSync resolvers, an Apollo Server application, or Amplify Gen 2 to put a GraphQL API in front of it. AppSync manages the API service, Apollo gives you control of the server, and Amplify generates and manages an AppSync-backed data layer from TypeScript. In every approach, design DynamoDB keys around the operations your API must support.

Choose AppSync, Apollo or Amplify

These options overlap: Amplify Data uses AppSync, and an Apollo client can call an AppSync GraphQL API when configured with compatible authentication and transport. Apollo Server is the backend server, not a requirement for using Apollo Client.

Set up DynamoDB with AppSync GraphQL

1. Create the table and API

For the standalone AppSync and Apollo examples, create a table named Articles with a string partition key id. These are alternative API implementations over that table:

aws dynamodb create-table \
  --table-name Articles \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST
aws dynamodb create-table \
  --table-name Articles \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

In AppSync, create a GraphQL API, configure authentication, and add the existing table as a DynamoDB data source. Grant the AppSync service role only the table operations used by its resolvers. An API key can support a deliberately public demonstration, but it is not user identity or per-user authorization. Use IAM, Cognito user pools, OIDC or a Lambda authorizer as appropriate for the application.

2. Define a schema that matches your table

This schema keeps the examples consistent. id is the DynamoDB key; publications is a list attribute. The list operation is paginated, and counters and list updates are explicit mutations:

type Article {
  id: ID!
  title: String!
  views: Int
  publications: [String!]
}

type ArticlePage {
  items: [Article!]!
  nextToken: String
}

type Query {
  getArticle(id: ID!): Article
  listArticles(limit: Int, nextToken: String): ArticlePage!
  batchGetArticles(ids: [ID!]!): [Article]
}

type Mutation {
  createArticle(id: ID!, title: String!): Article!
  incrementViews(id: ID!): Article
  appendPublication(id: ID!, publication: String!): Article
}
type Article {
  id: ID!
  title: String!
  views: Int
  publications: [String!]
}

type ArticlePage {
  items: [Article!]!
  nextToken: String
}

type Query {
  getArticle(id: ID!): Article
  listArticles(limit: Int, nextToken: String): ArticlePage!
  batchGetArticles(ids: [ID!]!): [Article]
}

type Mutation {
  createArticle(id: ID!, title: String!): Article!
  incrementViews(id: ID!): Article
  appendPublication(id: ID!, publication: String!): Article
}

Defining a field does not implement its database behavior. Attach a resolver to each operation you expose. A GraphQL selection set controls the API response fields; it does not automatically reduce DynamoDB read capacity.

3. Attach JavaScript resolvers

Choose the APPSYNC_JS runtime and the Articles data source. A resolver for Query.getArticle is:

import { util } from "@aws-appsync/utils";
import { get } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return get({ key: { id: ctx.args.id } });
}

export function response(ctx) {
  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
  return ctx.result;
}
import { util } from "@aws-appsync/utils";
import { get } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return get({ key: { id: ctx.args.id } });
}

export function response(ctx) {
  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
  return ctx.result;
}

For Mutation.createArticle, use a conditional put to avoid overwriting an existing ID:

import { util } from "@aws-appsync/utils";
import { put } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return put({
    key: { id: ctx.args.id },
    item: { title: ctx.args.title, views: 0, publications: [] },
    condition: { id: { attributeExists: false } },
  });
}

export function response(ctx) {
  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
  return ctx.result;
}
import { util } from "@aws-appsync/utils";
import { put } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return put({
    key: { id: ctx.args.id },
    item: { title: ctx.args.title, views: 0, publications: [] },
    condition: { id: { attributeExists: false } },
  });
}

export function response(ctx) {
  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
  return ctx.result;
}

These resolvers run in AppSync's JavaScript runtime, not Node.js. They produce DynamoDB requests through AppSync's built-in helpers; they do not create an AWS SDK client. Use the AppSync DynamoDB modules for supported operations and runtime behavior. Add item-level authorization before exposing them to users who should not access every article.

4. Test a mutation and query

Run these as separate operations in the AppSync query editor with an authorized identity:

mutation CreateArticle {
  createArticle(id: "article-001", title: "DynamoDB and GraphQL") {
    id
    title
    views
  }
}
mutation CreateArticle {
  createArticle(id: "article-001", title: "DynamoDB and GraphQL") {
    id
    title
    views
  }
}

query ReadArticle {
  getArticle(id: "article-001") {
    id
    title
    publications
  }
}
query ReadArticle {
  getArticle(id: "article-001") {
    id
    title
    publications
  }
}

Verify the item in DynamoDB and test a duplicate create. Check both authorization failures and DynamoDB conditional errors; a request returning HTTP success can still contain GraphQL errors.

Set up DynamoDB with Apollo Server

Apollo Server runs your resolvers in your own application process. Use the current @apollo/server package rather than the old apollo-server v2 package. Follow Apollo's setup documentation for supported Node.js and GraphQL versions.

Configure credentials and dependencies

Use AWS IAM Identity Center or an assumed role for local development. On AWS, attach an execution role to the compute service. Do not create an administrator access key just to run a GraphQL tutorial. This example needs GetItem, PutItem and Scan on Articles.

In a new example project, install the dependencies and enable ESM:

npm init -y
npm pkg set type=module
npm install @apollo/server graphql @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm init -y
npm pkg set type=module
npm install @apollo/server graphql @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Save this as server.js. It implements a small subset of the earlier schema, including explicit pagination for the demonstration list operation:

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient, GetCommand, PutCommand, ScanCommand,
} from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TableName = process.env.ARTICLES_TABLE ?? "Articles";

const typeDefs = `#graphql
  type Article { id: ID!, title: String!, views: Int, publications: [String!] }
  type ArticlePage { items: [Article!]!, nextToken: String }
  type Query {
    getArticle(id: ID!): Article
    listArticles(limit: Int, nextToken: String): ArticlePage!
  }
  type Mutation { createArticle(id: ID!, title: String!): Article! }
`;

const resolvers = {
  Query: {
    getArticle: async (_, { id }) => {
      const result = await ddb.send(new GetCommand({ TableName, Key: { id } }));
      return result.Item ?? null;
    },
    listArticles: async (_, { limit = 20, nextToken }) => {
      if (limit < 1 || limit > 100) throw new Error("limit must be between 1 and 100");
      let ExclusiveStartKey;
      if (nextToken) {
        const key = JSON.parse(Buffer.from(nextToken, "base64url").toString("utf8"));
        if (typeof key.id !== "string" || key.id.length === 0) {
          throw new Error("Invalid cursor");
        }
        ExclusiveStartKey = { id: key.id };
      }
      const result = await ddb.send(new ScanCommand({
        TableName, Limit: limit, ExclusiveStartKey,
      }));
      return {
        items: result.Items ?? [],
        nextToken: result.LastEvaluatedKey
          ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString("base64url")
          : null,
      };
    },
  },
  Mutation: {
    createArticle: async (_, { id, title }) => {
      const Item = { id, title, views: 0, publications: [] };
      await ddb.send(new PutCommand({
        TableName, Item, ConditionExpression: "attribute_not_exists(id)",
      }));
      return Item;
    },
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
  listen: { host: "127.0.0.1", port: 4000 },
});
console.log(`Local GraphQL API: ${url}`);
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient, GetCommand, PutCommand, ScanCommand,
} from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TableName = process.env.ARTICLES_TABLE ?? "Articles";

const typeDefs = `#graphql
  type Article { id: ID!, title: String!, views: Int, publications: [String!] }
  type ArticlePage { items: [Article!]!, nextToken: String }
  type Query {
    getArticle(id: ID!): Article
    listArticles(limit: Int, nextToken: String): ArticlePage!
  }
  type Mutation { createArticle(id: ID!, title: String!): Article! }
`;

const resolvers = {
  Query: {
    getArticle: async (_, { id }) => {
      const result = await ddb.send(new GetCommand({ TableName, Key: { id } }));
      return result.Item ?? null;
    },
    listArticles: async (_, { limit = 20, nextToken }) => {
      if (limit < 1 || limit > 100) throw new Error("limit must be between 1 and 100");
      let ExclusiveStartKey;
      if (nextToken) {
        const key = JSON.parse(Buffer.from(nextToken, "base64url").toString("utf8"));
        if (typeof key.id !== "string" || key.id.length === 0) {
          throw new Error("Invalid cursor");
        }
        ExclusiveStartKey = { id: key.id };
      }
      const result = await ddb.send(new ScanCommand({
        TableName, Limit: limit, ExclusiveStartKey,
      }));
      return {
        items: result.Items ?? [],
        nextToken: result.LastEvaluatedKey
          ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString("base64url")
          : null,
      };
    },
  },
  Mutation: {
    createArticle: async (_, { id, title }) => {
      const Item = { id, title, views: 0, publications: [] };
      await ddb.send(new PutCommand({
        TableName, Item, ConditionExpression: "attribute_not_exists(id)",
      }));
      return Item;
    },
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
  listen: { host: "127.0.0.1", port: 4000 },
});
console.log(`Local GraphQL API: ${url}`);

Run it with an authorized local profile and a Region:

AWS_PROFILE=development AWS_REGION=us-east-1 node server.js
AWS_PROFILE=development AWS_REGION=us-east-1 node server.js

This local example intentionally has no application authentication. Before hosting it, authenticate requests, authorize each operation and tenant, validate input sizes, limit query complexity and configure error reporting. SDK credentials belong on the server, never in a browser bundle.

The list resolver uses Scan to preserve a simple all-articles demonstration. It is not the right production access pattern for every request: model an author, tenant or publication key and use Query for those lists. The cursor is encoded, not encrypted or signed. Treat it as untrusted input, and bind production cursors to the authorized query scope.

Use Amplify Gen 2 for a generated data API

Amplify Gen 2 defines the backend in TypeScript. The old amplify import storage and amplify push workflow belongs to Gen 1. Gen 1 entered maintenance on May 1, 2026 and is scheduled to reach end of life on May 1, 2027, according to the maintainers' notice.

In an initialized Gen 2 project with Amplify Auth configured, define amplify/data/resource.ts:

import { type ClientSchema, a, defineData } from "@aws-amplify/backend";

const schema = a.schema({
  Article: a.model({
    title: a.string().required(),
    views: a.integer(),
    publications: a.string().array(),
  }).authorization((allow) => [allow.owner()]),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: { defaultAuthorizationMode: "userPool" },
});
import { type ClientSchema, a, defineData } from "@aws-amplify/backend";

const schema = a.schema({
  Article: a.model({
    title: a.string().required(),
    views: a.integer(),
    publications: a.string().array(),
  }).authorization((allow) => [allow.owner()]),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: { defaultAuthorizationMode: "userPool" },
});

Register the resources in amplify/backend.ts:

import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource";
import { data } from "./data/resource";

defineBackend({ auth, data });
import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource";
import { data } from "./data/resource";

defineBackend({ auth, data });

Use npx ampx sandbox for the development environment. This provisions AWS resources; it is not merely an offline GraphQL emulator. Configure the frontend using the generated outputs and create a typed client after the user signs in:

import { Amplify } from "aws-amplify";
import { generateClient } from "aws-amplify/data";
import outputs from "./amplify_outputs.json";
import type { Schema } from "./amplify/data/resource";

Amplify.configure(outputs);
const client = generateClient<Schema>();

const { data, errors } = await client.models.Article.create({
  title: "DynamoDB and GraphQL",
  views: 0,
  publications: [],
});
if (errors) console.error(errors);
else console.log(data);
import { Amplify } from "aws-amplify";
import { generateClient } from "aws-amplify/data";
import outputs from "./amplify_outputs.json";
import type { Schema } from "./amplify/data/resource";

Amplify.configure(outputs);
const client = generateClient<Schema>();

const { data, errors } = await client.models.Article.create({
  title: "DynamoDB and GraphQL",
  views: 0,
  publications: [],
});
if (errors) console.error(errors);
else console.log(data);

Adjust imports to your frontend's directory layout. Owner authorization makes this a per-user model; it does not make every article public. Amplify creates its own table and generated operations, so this model is an alternative to the manually managed Articles schema above. Follow Amplify Data setup for initialization and deployment.

Connect an existing DynamoDB table

For an existing table, use a custom data source rather than assuming a.model() adopts it. In amplify/backend.ts, replace the bare backend declaration with:

import { defineBackend } from "@aws-amplify/backend";
import { Table } from "aws-cdk-lib/aws-dynamodb";
import { auth } from "./auth/resource";
import { data } from "./data/resource";

const backend = defineBackend({ auth, data });
const existing = Table.fromTableName(
  backend.data.stack, "ExistingArticles", "Articles"
);
backend.data.addDynamoDbDataSource("ExistingArticlesSource", existing);
import { defineBackend } from "@aws-amplify/backend";
import { Table } from "aws-cdk-lib/aws-dynamodb";
import { auth } from "./auth/resource";
import { data } from "./data/resource";

const backend = defineBackend({ auth, data });
const existing = Table.fromTableName(
  backend.data.stack, "ExistingArticles", "Articles"
);
backend.data.addDynamoDbDataSource("ExistingArticlesSource", existing);

Define these entries in amplify/data/resource.ts and include ...existingOperations inside its a.schema({ ... }) object:

const existingOperations = {
  ExistingArticle: a.customType({
    id: a.id().required(),
    title: a.string().required(),
  }),
  getExistingArticle: a.query()
    .arguments({ id: a.id().required() })
    .returns(a.ref("ExistingArticle"))
    .authorization((allow) => [allow.authenticated()])
    .handler(a.handler.custom({
      dataSource: "ExistingArticlesSource",
      entry: "./get-existing-article.js",
    })),
};
const existingOperations = {
  ExistingArticle: a.customType({
    id: a.id().required(),
    title: a.string().required(),
  }),
  getExistingArticle: a.query()
    .arguments({ id: a.id().required() })
    .returns(a.ref("ExistingArticle"))
    .authorization((allow) => [allow.authenticated()])
    .handler(a.handler.custom({
      dataSource: "ExistingArticlesSource",
      entry: "./get-existing-article.js",
    })),
};

Put the earlier AppSync getArticle JavaScript resolver in amplify/data/get-existing-article.js. Authenticated access allows every signed-in caller of this operation to request a known ID; add tenant or ownership checks if that is too broad. Importing the table does not infer its authorization model or convert its items into generated Amplify models. The external DynamoDB data-source guide covers custom operation wiring.

Common GraphQL and DynamoDB operations

The following examples use the manually defined AppSync schema. GraphQL has no universal _inc, append() or SQL-style where syntax; those names only work if a particular schema and resolver implement them.

Increment a counter

Attach this request function to incrementViews, with the same error-checking response function used above:

import { update, operations } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return update({
    key: { id: ctx.args.id },
    update: { views: operations.increment(1) },
    condition: { id: { attributeExists: true } },
  });
}
import { update, operations } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return update({
    key: { id: ctx.args.id },
    update: { views: operations.increment(1) },
    condition: { id: { attributeExists: true } },
  });
}

mutation CountView {
  incrementViews(id: "article-001") { id views }
}
mutation CountView {
  incrementViews(id: "article-001") { id views }
}

This is an atomic numeric update, not an auto-incrementing primary key. Retrying the mutation can increment again; use an idempotency mechanism if each logical event must count once.

Batch get items

A schema field such as batchGetArticles(ids: [ID!]!) needs a BatchGetItem resolver. The request names the physical table and converts each ID into a key. Handle missing items and unprocessed keys explicitly; a partial batch is not proof every requested item was absent or returned. AWS provides the AppSync batch-get request and response format.

query ReadSeveralArticles {
  batchGetArticles(ids: ["article-001", "article-002"]) { id title }
}
query ReadSeveralArticles {
  batchGetArticles(ids: ["article-001", "article-002"]) { id title }
}

DynamoDB batch get supports up to 100 items and a 16 MB response, and can return less. Deduplicate input keys and define how the API reports partial results. Do not silently return an empty list on a database error.

Query a string list

query ReadPublications {
  getArticle(id: "article-001") { id publications }
}
query ReadPublications {
  getArticle(id: "article-001") { id publications }
}

A list attribute can be returned as [String!]. Searching every article containing a publication is a different access pattern. Model an index or related items for that query instead of assuming GraphQL can turn arbitrary list membership into an efficient DynamoDB key lookup.

Append to a list

For appendPublication, attach this request function and the shared response function:

import { update, operations } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return update({
    key: { id: ctx.args.id },
    update: { publications: operations.append([ctx.args.publication]) },
    condition: { id: { attributeExists: true } },
  });
}
import { update, operations } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  return update({
    key: { id: ctx.args.id },
    update: { publications: operations.append([ctx.args.publication]) },
    condition: { id: { attributeExists: true } },
  });
}

mutation AddPublication {
  appendPublication(id: "article-001", publication: "Dynobase") {
    id
    publications
  }
}
mutation AddPublication {
  appendPublication(id: "article-001", publication: "Dynobase") {
    id
    publications
  }
}

The create resolver initializes the list. Appending does not deduplicate values, and repeated mutations can append twice. Choose a set or separate membership items if uniqueness is required.

Paginate with a cursor

Attach this resolver to the demonstration listArticles field. The limit cap is an application choice; for production keyed lists, use query with the same pagination pattern:

import { util } from "@aws-appsync/utils";
import { scan } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  const limit = ctx.args.limit ?? 20;
  if (limit < 1 || limit > 100) {
    util.error("limit must be between 1 and 100", "BadRequest");
  }
  return scan({ limit, nextToken: ctx.args.nextToken });
}

export function response(ctx) {
  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
  return { items: ctx.result.items, nextToken: ctx.result.nextToken };
}
import { util } from "@aws-appsync/utils";
import { scan } from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  const limit = ctx.args.limit ?? 20;
  if (limit < 1 || limit > 100) {
    util.error("limit must be between 1 and 100", "BadRequest");
  }
  return scan({ limit, nextToken: ctx.args.nextToken });
}

export function response(ctx) {
  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
  return { items: ctx.result.items, nextToken: ctx.result.nextToken };
}

query Page($nextToken: String) {
  listArticles(limit: 20, nextToken: $nextToken) {
    items { id title }
    nextToken
  }
}
query Page($nextToken: String) {
  listArticles(limit: 20, nextToken: $nextToken) {
    items { id title }
    nextToken
  }
}

Pass the returned token into the next request until it is absent. AppSync pagination tokens and the Apollo example's encoded keys are different formats and are not interchangeable. Filtering can produce an empty page with a continuation token. See DynamoDB pagination.

Access patterns, N+1 queries and real-time updates

Design each API field around a known database operation. A single-table design can place related entities together for one query, but it is not mandatory for every GraphQL application. Multiple tables or generated Amplify models can be appropriate. Use single-table design where it simplifies actual access patterns.

The N+1 problem occurs when a parent list causes an extra database call for every child. Batch or prefetch related records, and consider request-scoped loaders in Apollo. Avoid treating it as merely the opposite of over-fetching: one request can suffer from both. Returning fewer GraphQL fields does not automatically change the number or capacity cost of DynamoDB requests.

AppSync GraphQL subscriptions are triggered through configured mutations. An SDK write made directly to the table does not automatically publish a GraphQL subscription event. If external writes must notify clients, use a DynamoDB stream consumer that calls a suitable authorized mutation or an explicitly designed event-publishing path. Prevent that path from writing back and recursively triggering itself. See AppSync subscriptions.

Test authorization with two different users, paginate beyond one page, simulate conditional-write failures and verify duplicate mutation behavior. Monitor resolver errors and DynamoDB throttling alongside API latency. Successful schema deployment alone does not prove the data access or ownership rules are correct.