Skip to content

docs: document AppSync per-item cache eviction (evictFromApiCache) #720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sid88in merged 1 commit into from
Jun 1, 2026
Merged

docs: document AppSync per-item cache eviction (evictFromApiCache) #720

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions doc/caching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,50 @@ appSync:

See [Resolver caching](resolvers.md#caching)

## Evicting items from the cache

To evict a single entry from the cache (rather than flushing everything), use AppSync's [`evictFromApiCache`](https://docs.aws.amazon.com/appsync/latest/devguide/extensions.html) extension from within a resolver. This is a runtime feature of AppSync, so there is nothing special to configure in this plugin: just call it from the mapping template or JavaScript code of the resolver, and it is passed through to AppSync as-is.

A few things to keep in mind (see the [AppSync docs](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html) for the details):

- It only works in **mutation** resolvers, not queries.
- The target entry is identified by the type name, field name, and a map of caching keys. The keys must match — in the same order — the `keys` of the cached resolver you want to evict.

For example, given a cached query resolver:

```yaml
appSync:
resolvers:
Query.getNote:
dataSource: notes
caching:
ttl: 60
keys:
- '$context.arguments.id'
```

You can evict its cached entry from a mutation resolver. With a VTL response template:

```vtl
#set($keys = {})
$util.qr($keys.put("context.arguments.id", $ctx.args.id))
$extensions.evictFromApiCache("Query", "getNote", $keys)
Comment on lines +56 to +58

@coderabbitai coderabbitai Bot Jun 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

AWS AppSync evictFromApiCache key name format - should the key map use the exact string from the resolver's caching keys configuration including dollar sign prefix?

💡 Result:

When using the evictFromApiCache extension in AWS AppSync, the keys in your mapping object must exactly match the strings defined in your resolver's cachingKeys configuration [1][2][3]. If your cachingKeys configuration includes the dollar sign prefix (e.g., "$context.arguments.id"), you must include that exact string as the key in the mapping object provided to the evictFromApiCache function [2][3]. Key requirements for successful cache eviction include: 1. Exact Match: The map keys must match the configuration exactly, including the dollar sign [2][3]. 2. Order: If you are using multiple caching keys, the entries must be added to the mapping object in the same order they are defined in the resolver's cachingKeys list [1][3][4]. 3. Mapping: Each value in your mapping object should be the actual value you wish to use to identify the specific cache entry (e.g., the specific ID or username) [1][3]. For example, if your caching configuration is: cachingKeys: ['$context.arguments.id'] Your eviction call should look like this: extensions.evictFromApiCache('Query', 'getNote', { '$context.arguments.id': ctx.args.id });

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail
# Show the relevant section around the reported lines
nl -ba doc/caching.md | sed -n '35,70p'

Repository: sid88in/serverless-appsync-plugin

Length of output: 120

🏁 Script executed:

#!/bin/bash
set -euo pipefail
awk 'NR>=35 && NR<=70 {printf "%d:%s\n", NR, $0}' doc/caching.md

Repository: sid88in/serverless-appsync-plugin

Length of output: 1258

Fix cache eviction key mapping to exactly match caching.keys (include the $ prefix).

doc/caching.md defines the caching key as '$context.arguments.id' (line 50), but the VTL eviction example uses "context.arguments.id" (line 57), and the JS example similarly uses 'context.arguments.id' (line 69). AppSync eviction keys must match the resolver’s cachingKeys strings exactly (including $), so the examples should use "$context.arguments.id" / '$context.arguments.id'.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@doc/caching.md` around lines 56 - 58, The VTL and JS eviction examples use
"context.arguments.id" but must include the leading $ to match caching.keys
exactly; update the VTL snippet that sets $keys (and any usage of $util.qr or
$extensions.evictFromApiCache) to use "$context.arguments.id" as the key name,
and likewise update the JS example to use '$context.arguments.id' so the
eviction keys exactly match the resolver cachingKeys strings.

$util.toJson($ctx.result)
```

Or with a JavaScript resolver:

```js
import { extensions } from '@aws-appsync/utils';

export function response(ctx) {
extensions.evictFromApiCache('Query', 'getNote', {
'context.arguments.id': ctx.args.id,
});
return ctx.result;
}
```

## Flushing the cache

You can use the [flush-cache command](commands.md#flush-cache) to easily flush the cache.
Loading