# Transformation helpers in \$1util.transform
**Note**
We now primarily support the APPSYNC\$1JS runtime and its documentation. Please consider using the APPSYNC\$1JS runtime and its guides [here](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html).
`$util.transform` contains helper methods that make it easier to perform complex operations against data sources, such as Amazon DynamoDB filter operations.
## Transformation helpers
### Transformation helpers utils list
****`$util.transform.toDynamoDBFilterExpression(Map) : Map`****
Converts an input string to a filter expression for use with DynamoDB.
```
Input:
$util.transform.toDynamoDBFilterExpression({
"title":{
"contains":"Hello World"
}
})
Output:
{
"expression" : "contains(#title, :title_contains)"
"expressionNames" : {
"#title" : "title",
},
"expressionValues" : {
":title_contains" : { "S" : "Hello World" }
},
}
```
****`$util.transform.toElasticsearchQueryDSL(Map) : Map`****
Converts the given input into its equivalent OpenSearch Query DSL expression, returning it as a JSON string.
```
Input:
$util.transform.toElasticsearchQueryDSL({
"upvotes":{
"ne":15,
"range":[
10,
20
]
},
"title":{
"eq":"hihihi",
"wildcard":"h*i"
}
})
Output:
{
"bool":{
"must":[
{
"bool":{
"must":[
{
"bool":{
"must_not":{
"term":{
"upvotes":15
}
}
}
},
{
"range":{
"upvotes":{
"gte":10,
"lte":20
}
}
}
]
}
},
{
"bool":{
"must":[
{
"term":{
"title":"hihihi"
}
},
{
"wildcard":{
"title":"h*i"
}
}
]
}
}
]
}
}
```
The default operator is assumed to be AND.
## Transformation helpers subscription filters
### Transformation helpers subscription filters utils list
****`$util.transform.toSubscriptionFilter(Map) : Map`****
Converts a `Map` input object to a `SubscriptionFilter` expression object. The `$util.transform.toSubscriptionFilter` method is used as an input to the `$extensions.setSubscriptionFilter()` extension. For more information, see [Extensions](https://docs.aws.amazon.com/appsync/latest/devguide/extensions).
****`$util.transform.toSubscriptionFilter(Map, List) : Map`****
Converts a `Map` input object to a `SubscriptionFilter` expression object. The `$util.transform.toSubscriptionFilter` method is used as an input to the `$extensions.setSubscriptionFilter()` extension. For more information, see [Extensions](https://docs.aws.amazon.com/appsync/latest/devguide/extensions).
The first argument is the `Map` input object that's converted to the `SubscriptionFilter` expression object. The second argument is a `List` of field names that are ignored in the first `Map` input object while constructing the `SubscriptionFilter` expression object.
****`$util.transform.toSubscriptionFilter(Map, List, Map) : Map`****
Converts a `Map` input object to a `SubscriptionFilter` expression object. The `$util.transform.toSubscriptionFilter` method is used as an input to the `$extensions.setSubscriptionFilter()` extension. For more information, see [Extensions](https://docs.aws.amazon.com/appsync/latest/devguide/extensions).
The first argument is the `Map` input object that's converted to the `SubscriptionFilter` expression object, the second argument is a `List` of field names that will be ignored in the first `Map` input object, and the third argument is a `Map` input object of strict rules that's included while constructing the `SubscriptionFilter` expression object. These strict rules are included in the `SubscriptionFilter` expression object in such a way that at least one of the rules will be satisfied to pass the subscription filter.
## Subscription filter arguments
The following table explains the how the arguments of the following utilities are defined:
+ `$util.transform.toSubscriptionFilter(Map) : Map`
+ `$util.transform.toSubscriptionFilter(Map, List) : Map`
+ `$util.transform.toSubscriptionFilter(Map, List, Map) : Map`
------
#### [ Argument 1: Map ]
Argument 1 is a `Map` object with the following key values:
+ field names
+ "and"
+ "or"
For field names as keys, the conditions on these fields' entries are in the form of `"operator" : "value"`.
The following example shows how entries can be added to the `Map`:
```
"field_name" : {
"operator1" : value
}
## We can have multiple conditions for the same field_name:
"field_name" : {
"operator1" : value
"operator2" : value
.
.
.
}
```
When a field has two or more conditions on it, all of these conditions are considered to use the OR operation.
The input `Map` can also have "and" and "or" as keys, implying that all entries within these should be joined using AND or OR logic depending on the key. The key values "and" and "or" expect an array of conditions.
```
"and" : [
{
"field_name1" : {
"operator1" : value
}
},
{
"field_name2" : {
"operator1" : value
}
},
.
.
].
```
Note that you can nest "and" and "or". That is, you can have nested "and"/"or" within another "and"/"or" block. However, this doesn't work for simple fields.
```
"and" : [
{
"field_name1" : {
"operator" : value
}
},
{
"or" : [
{
"field_name2" : {
"operator" : value
}
},
{
"field_name3" : {
"operator" : value
}
}
].
```
The following example shows an input of *argument 1* using `$util.transform.toSubscriptionFilter(Map) : Map`.
**Input(s)**
Argument 1: Map:
```
{
"percentageUp": {
"lte": 50,
"gte": 20
},
"and": [
{
"title": {
"ne": "Book1"
}
},
{
"downvotes": {
"gt": 2000
}
}
],
"or": [
{
"author": {
"eq": "Admin"
}
},
{
"isPublished": {
"eq": false
}
}
]
}
```
**Output**
The result is a `Map` object:
```
{
"filterGroup": [
{
"filters": [
{
"fieldName": "percentageUp",
"operator": "lte",
"value": 50
},
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 2000
},
{
"fieldName": "author",
"operator": "eq",
"value": "Admin"
}
]
},
{
"filters": [
{
"fieldName": "percentageUp",
"operator": "lte",
"value": 50
},
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 2000
},
{
"fieldName": "isPublished",
"operator": "eq",
"value": false
}
]
},
{
"filters": [
{
"fieldName": "percentageUp",
"operator": "gte",
"value": 20
},
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 2000
},
{
"fieldName": "author",
"operator": "eq",
"value": "Admin"
}
]
},
{
"filters": [
{
"fieldName": "percentageUp",
"operator": "gte",
"value": 20
},
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 2000
},
{
"fieldName": "isPublished",
"operator": "eq",
"value": false
}
]
}
]
}
```
------
#### [ Argument 2: List ]
Argument 2 contains a `List` of field names that shouldn't be considered in the input `Map` (argument 1) while constructing the `SubscriptionFilter` expression object. The `List` can also be empty.
The following example shows the inputs of argument 1 and argument 2 using `$util.transform.toSubscriptionFilter(Map, List) : Map`.
**Input(s)**
Argument 1: Map:
```
{
"percentageUp": {
"lte": 50,
"gte": 20
},
"and": [
{
"title": {
"ne": "Book1"
}
},
{
"downvotes": {
"gt": 20
}
}
],
"or": [
{
"author": {
"eq": "Admin"
}
},
{
"isPublished": {
"eq": false
}
}
]
}
```
Argument 2: List:
```
["percentageUp", "author"]
```
**Output**
The result is a `Map` object:
```
{
"filterGroup": [
{
"filters": [
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 20
},
{
"fieldName": "isPublished",
"operator": "eq",
"value": false
}
]
}
]
}
```
------
#### [ Argument 3: Map ]
Argument 3 is a `Map` object that has field names as key values (cannot have "and" or "or"). For field names as keys, the conditions on these fields are entries in the form of `"operator" : "value"`. Unlike argument 1, argument 3 cannot have multiple conditions in the same key. In addition, argument 3 doesn't have an "and" or "or" clause, so there's no nesting involved either.
Argument 3 represents a list of strict rules, which are added to the `SubscriptionFilter` expression object so that **at least one** of these conditions is met to pass the filter.
```
{
"fieldname1": {
"operator": value
},
"fieldname2": {
"operator": value
}
}
.
.
.
```
The following example shows the inputs of *argument 1*, *argument 2*, and *argument 3* using `$util.transform.toSubscriptionFilter(Map, List, Map) : Map`.
**Input(s)**
Argument 1: Map:
```
{
"percentageUp": {
"lte": 50,
"gte": 20
},
"and": [
{
"title": {
"ne": "Book1"
}
},
{
"downvotes": {
"lt": 20
}
}
],
"or": [
{
"author": {
"eq": "Admin"
}
},
{
"isPublished": {
"eq": false
}
}
]
}
```
Argument 2: List:
```
["percentageUp", "author"]
```
Argument 3: Map:
```
{
"upvotes": {
"gte": 250
},
"author": {
"eq": "Person1"
}
}
```
**Output**
The result is a `Map` object:
```
{
"filterGroup": [
{
"filters": [
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 20
},
{
"fieldName": "isPublished",
"operator": "eq",
"value": false
},
{
"fieldName": "upvotes",
"operator": "gte",
"value": 250
}
]
},
{
"filters": [
{
"fieldName": "title",
"operator": "ne",
"value": "Book1"
},
{
"fieldName": "downvotes",
"operator": "gt",
"value": 20
},
{
"fieldName": "isPublished",
"operator": "eq",
"value": false
},
{
"fieldName": "author",
"operator": "eq",
"value": "Person1"
}
]
}
]
}
```
------