$extensions.evictFromApiCache(String, String, Object) : Object $extensions.setSubscriptionFilter(filterJsonObject)$extensions.setSubscriptionInvalidationFilter(filterJsonObject)$extensions.invalidateSubscriptions(invalidationJsonObject)

Extensions

Warning

We're slowly phasing out our doc support for VTL in favor of APPSYNC_JS. Please consider using the APPSYNC_JS runtime and its guides here.

$extensions contains a set of methods to make additional actions within your resolvers.

$extensions.evictFromApiCache(String, String, Object) : Object

Evicts an item from the AWS AppSync server-side cache. The first argument is the type name. The second argument is the field name. The third argument is an object containing key-value pair items that specify the caching key value. You must put the items in the object in the same order as the caching keys in the cached resolver's cachingKey.

Note

This utility works only for mutations, not queries.

$extensions.setSubscriptionFilter(filterJsonObject)

Defines enhanced subscription filters. Each subscription notification event is evaluated against provided subscription filters and delivers notifications to clients if all filters evaluate to true. The argument is filterJsonObject as described in the following.

Note

You can use this extension method only in the response mapping templates of a subscription resolver.

$extensions.setSubscriptionInvalidationFilter(filterJsonObject)

Defines subscription invalidation filters. Subscription filters are evaluated against the invalidation payload, then invalidate a given subscription if the filters evaluate to true. The argument is filterJsonObject as described in the following.

Note

You can use this extension method only in the response mapping templates of a subscription resolver.

Argument: filterJsonObject

The JSON object defines either subscription or invalidation filters. It's an array of filters in a filterGroup. Each filter is a collection of individual filters.


{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                }
           ]
           
        },
        {
           "filters" : [
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

Each filter has three attributes:

fieldName – The GraphQL schema field.
operator – The operator type.
value – The values to compare to the subscription notification fieldName value.

The following is an example assignment of these attributes:


{
 "fieldName" : "severity",
 "operator" : "le",
 "value" : $context.result.severity
}

Field: fieldName

The string type fieldName refers to a field defined in the GraphQL schema that matches the fieldName in the subscription notification payload. When a match is found, the value of the GraphQL schema field is compared to the value of the subscription notification filter. In the following example, the fieldName filter matches the service field defined in a given GraphQL type. If the notification payload contains a service field with a value equivalent to AWS AppSync, the filter evaluates to true:


{
 "fieldName" : "service",
 "operator" : "eq",
 "value" : "AWS AppSync"
}

Field: value

The value can be a different type based on the operator:

A single number or Boolean
- String examples: "test", "service"
- Number examples: 1, 2, 45.75
- Boolean examples: true, false
Pairs of numbers or strings
- String pair example: ["test1","test2"], ["start","end"]
- Number pair example: [1,4], [67,89], [12.45, 95.45]
Arrays of numbers or strings
- String array example: ["test1","test2","test3","test4","test5"]
- Number array example: [1,2,3,4,5], [12.11,46.13,45.09,12.54,13.89]

Field: operator

A case-sensitive string with the following possible values:

Operator	Description	Possible value types
eq	Equal	integer, float, string, Boolean
ne	Not equal	integer, float, string, Boolean
le	Less than or equal	integer, float, string
lt	Less than	integer, float, string
ge	Greater than or equal	integer, float, string
gt	Greater than	integer, float, string
contains	Checks for a subsequence or value in the set.	integer, float, string
notContains	Checks for the absence of a subsequence or absence of a value in the set.	integer, float, string
beginsWith	Checks for a prefix.	string
in	Checks for matching elements that are in the list.	Array of integer, float, or string
notIn	Checks for matching elements that aren't in the list.	Array of integer, float, or string
between	Between two values	integer, float, string
containsAny	Contains common elements	integer, float, string

The following table describes how each operator is used in the subscription notification.

eq (equal)

The eq operator evaluates to true if the subscription notification field value matches and is strictly equal to the filter's value. In the following example, the filter evaluates to true if the subscription notification has a service field with the value equivalent to AWS AppSync.

Possible value types: integer, float, string, Boolean


{
 "fieldName" : "service",
 "operator" : "eq",
 "value" : "AWS AppSync"
}

ne (not equal)

The ne operator evaluates to true if the subscription notification field value is different from the filter's value. In the following example, the filter evaluates to true if the subscription notification has a service field with a value different from AWS AppSync.

Possible value types: integer, float, string, Boolean


{
 "fieldName" : "service",
 "operator" : "ne",
 "value" : "AWS AppSync"
}

le (less or equal)

The le operator evaluates to true if the subscription notification field value is less than or equal to the filter's value. In the following example, the filter evaluates to true if the subscription notification has a size field with a value less than or equal to 5.