Advanced patterns

This page covers four advanced topics: migrating React components from imperative DataStore calls to declarative Apollo hooks, composite and custom primary keys, GraphQL codegen for type-safe operations, and an honest accounting of DataStore features that have no direct Apollo Client equivalent.

Composite and custom primary keys

Amplify supports three identifier modes for models. Each mode changes how you query, update, and delete records -- and each requires different Apollo Client configuration.

The three identifier modes

Default (auto ID)

This is the default mode when you do not use @primaryKey on your model. AppSync auto-generates a UUID id field. No special migration is needed -- the standard CRUD patterns from the Migrate CRUD operations page apply directly.

Gen 1 schema:

# amplify/backend/api/<your-api>/schema.graphql
type Post @model @auth(rules: [{ allow: owner }]) {
  id: ID!
  title: String!
  content: String
  status: String
}

Custom single-field PK

When your model defines a custom primary key field, the id is no longer auto-generated. You must provide it explicitly in create mutations.

Gen 1 schema:

# amplify/backend/api/<your-api>/schema.graphql
type Product @model @auth(rules: [{ allow: owner }]) {
  id: ID! @primaryKey
  sku: String!
  name: String!
  price: Float
}

Apollo Client:

const { data } = await apolloClient.mutate({
  mutation: CREATE_PRODUCT,
  variables: {
    input: {
      id: 'PROD-001', // REQUIRED -- you must provide this
      sku: 'SKU-12345',
      name: 'Widget',
      price: 29.99,
    },
  },
});

Composite PK

This mode requires the most migration work. When a model uses @primaryKey with sortKeyFields, ALL primary key fields become required arguments.

Gen 1 schema:

type StoreBranch @model @auth(rules: [{ allow: owner }]) {
  tenantId: ID! @primaryKey(sortKeyFields: ["branchName"])
  branchName: String!
  address: String
  phone: String
}

Apollo Client queries and mutations:

// Query by composite key -- both fields as separate variables
const { data } = await apolloClient.query({
  query: GET_STORE_BRANCH,
  variables: { tenantId: 'tenant-123', branchName: 'Downtown' },
});

// Update -- ALL PK fields + _version required in input
await apolloClient.mutate({
  mutation: UPDATE_STORE_BRANCH,
  variables: {
    input: {
      tenantId: 'tenant-123',
      branchName: 'Downtown',
      address: '456 New St',
      _version: data.getStoreBranch._version,
    },
  },
});

Cache configuration for composite keys (typePolicies)

import { InMemoryCache } from '@apollo/client';

const cache = new InMemoryCache({
  typePolicies: {
    // Default models work automatically
    Post: { keyFields: ['id'] },
    // Composite key models NEED explicit keyFields
    StoreBranch: { keyFields: ['tenantId', 'branchName'] },
    // Custom single-field PK
    Product: { keyFields: ['sku'] },
  },
});

Warning signs that keyFields is missing: queries return stale data after mutations, Apollo DevTools shows duplicate entries, cache.readQuery returns null for records you know exist.

GraphQL codegen for type-safe operations

The CRUD examples in earlier pages use (post: any) casts. This section shows how to eliminate those.

Step 1: Generate GraphQL operations

amplify codegen

This generates TypeScript files in src/graphql/ containing your operations as string constants.

Step 2: Wrap with gql() and TypeScript types

Create a typed operations file that wraps the generated strings:

import { gql, TypedDocumentNode } from '@apollo/client';
import { getPost as getPostString, listPosts as listPostsString } from './queries';
import { createPost as createPostString, updatePost as updatePostString, deletePost as deletePostString } from './mutations';

export interface Post {
  id: string;
  title: string;
  content: string;
  status: string;
  rating: number;
  createdAt: string;
  updatedAt: string;
  _version: number;
  _deleted: boolean | null;
  _lastChangedAt: number;
}

export interface GetPostData { getPost: Post | null; }
export interface GetPostVars { id: string; }

export interface ListPostsData {
  listPosts: { items: Post[]; nextToken: string | null; };
}
export interface ListPostsVars {
  filter?: Record<string, unknown>;
  limit?: number;
  nextToken?: string;
}

export interface CreatePostData { createPost: Post; }
export interface CreatePostVars {
  input: { title: string; content: string; status?: string; rating?: number; };
}

export interface UpdatePostData { updatePost: Post; }
export interface UpdatePostVars {
  input: { id: string; _version: number; title?: string; content?: string; };
}

export interface DeletePostData { deletePost: Post; }
export interface DeletePostVars {
  input: { id: string; _version: number; };
}

export const GET_POST: TypedDocumentNode<GetPostData, GetPostVars> = gql(getPostString);
export const LIST_POSTS: TypedDocumentNode<ListPostsData, ListPostsVars> = gql(listPostsString);
export const CREATE_POST: TypedDocumentNode<CreatePostData, CreatePostVars> = gql(createPostString);
export const UPDATE_POST: TypedDocumentNode<UpdatePostData, UpdatePostVars> = gql(updatePostString);
export const DELETE_POST: TypedDocumentNode<DeletePostData, DeletePostVars> = gql(deletePostString);

Step 3: Use type-safe hooks

With TypedDocumentNode, Apollo hooks automatically infer data and variable types:

What is lost -- features with no direct equivalent

Hub events

DataStore dispatched 9 distinct events via Hub. Of the 9:

The 7 with no equivalent describe sync engine behavior, and Apollo Client does not have a sync engine.

Selective sync (syncExpressions)

DataStore's syncExpressions let you filter which records synced from server to local store. Apollo Client has no equivalent.

Lifecycle methods

Conflict handler configuration

This IS covered in the migration guide. Conflicts are handled server-side. Rating: Full (different location, same capability).

Summary

Practical guidance

If your app depends heavily on Hub events for UI state (showing sync progress indicators, outbox status badges), plan additional custom implementation work. For most apps migrating to Apollo Client, these features are not needed because there is no local sync to monitor. The loss is real but the impact is low.