diff --git a/doc/caching.md b/doc/caching.md index f16aa600..c502f1a0 100644 --- a/doc/caching.md +++ b/doc/caching.md @@ -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) +$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.