Map
The Map
state ("Type": "Map"
) can be used to run a set of steps
for each element of an input array. While the Parallel
state executes
multiple branches of steps using the same input, a Map
state will execute the
same steps for multiple entries of an array in the state input.
For an introduction to using a Map
state, see the Map State Tutorial.
In addition to the common state
fields, Map
states include these additional fields.
-
Iterator
(Required) -
The
Iterator
field’s value is an object that defines a state machine which will process each element of the array. -
ItemsPath
(Optional) -
The
ItemsPath
field’s value is a reference path identifying where in the effective input the array field is found. For more information, see ItemsPath.States within an
Iterator
field can only transition to each other, and no state outside theItemsPath
field can transition to a state within it.If any iteration fails, entire Map state fails, and all iterations are terminated.
-
MaxConcurrency
(Optional) -
The
MaxConcurrency
field’s value is an integer that provides an upper bound on how many invocations of the Iterator may run in parallel. For instance, aMaxConcurrency
value of 10 will limit yourMap
state to 10 concurrent iterations running at one time.Note Concurrent iterations may be limited. When this occurs, some iterations will not begin until previous iterations have completed. The likelihood of this occurring increases when your input array has more than 40 items.
The default value is
0
, which places no quota on parallelism and iterations are invoked as concurrently as possible.A
MaxConcurrency
value of1
invokes theIterator
once for each array element in the order of their appearance in the input, and will not start a new iteration until the previous has completed. -
ResultPath
(Optional) -
Specifies where (in the input) to place the output of the branches. The input is then filtered as specified by the
OutputPath
field (if present) before being used as the state's output. For more information, see Input and Output Processing. -
ResultSelector
(Optional) -
Pass a collection of key value pairs, where the values are static or selected from the result. For more information, see ResultSelector.
-
Retry
(Optional) -
An array of objects, called Retriers, that define a retry policy in case the state encounters runtime errors. For more information, see Examples using Retry and using Catch.
-
Catch
(Optional) -
An array of objects, called Catchers, that define a fallback state that is executed if the state encounters runtime errors and its retry policy is exhausted or isn't defined. For more information, see Fallback States.
Map State Example
Consider the following input data for a Map
state.
{
"ship-date": "2016-03-14T01:59:00Z",
"detail": {
"delivery-partner": "UQS",
"shipped": [
{ "prod": "R31", "dest-code": 9511, "quantity": 1344 },
{ "prod": "S39", "dest-code": 9511, "quantity": 40 },
{ "prod": "R31", "dest-code": 9833, "quantity": 12 },
{ "prod": "R40", "dest-code": 9860, "quantity": 887 },
{ "prod": "R40", "dest-code": 9511, "quantity": 1220 }
]
}
}
Given the previous input, the Map
state in the following example will
invoke a AWS Lambda function (ship-val
) once for each item of the array in
the shipped
field.
"Validate-All": {
"Type": "Map",
"InputPath": "$.detail",
"ItemsPath": "$.shipped",
"MaxConcurrency": 0,
"Iterator": {
"StartAt": "Validate",
"States": {
"Validate": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:ship-val",
"End": true
}
}
},
"ResultPath": "$.detail.shipped",
"End": true
}
Each iteration of the Map
state will send an item in the array (selected
with the ItemsPath field)
as input to the Lambda function. For instance, the input to one invocation of Lambda
would
be the following.
{
"prod": "R31",
"dest-code": 9511,
"quantity": 1344
}
When complete, the output of the Map
state is a JSON array where each
item is the output of an iteration (in this case, the output of the
ship-val
Lambda function).
Map State Example with Parameters
Suppose that the ship-val
Lambda function in the previous example also
needs information about the shipment's courier as well as the items in the array for
each iteration. You can include information from the input, along with information
specific to the current iteration of the map state. Note the Parameters
field in the following example.
"Validate-All": {
"Type": "Map",
"InputPath": "$.detail",
"ItemsPath": "$.shipped",
"MaxConcurrency": 0,
"ResultPath": "$.detail.shipped",
"Parameters": {
"parcel.$": "$$.Map.Item.Value",
"courier.$": "$.delivery-partner"
},
"Iterator": {
"StartAt": "Validate",
"States": {
"Validate": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:ship-val",
"End": true
}
}
},
"End": true
}
The Parameters
block replaces the input to the iterations with a JSON
node that contains both the current item data from the context object, and the courier information from the
delivery-partner
field from the Map
state input. The
following is an example of input to a single iteration, that is passed to an invocation
of the ship-val
Lambda function.
{
"parcel": {
"prod": "R31",
"dest-code": 9511,
"quantity": 1344
},
"courier": "UQS"
}
In the previous Map
state example, the ResultPath field produces
output the same as the input, but with the detail.shipped
field
overwritten by an array in which each element is the output of the
ship-val
Lambda function for each iteration.
For more information see the following.
Map State Input and Output Processing
For a map state, InputPath works as it does for other state types, selecting a subset of the input.
The input of a Map
state must include a JSON array, and it will run the
Iterator
section once for each item in the array. You specify where in
the input to find this array using the ItemsPath field. If not specified, the value of
ItemsPath
is $
, and the Iterator
section
expects that the array is the only input. A Map
state may also include an
ItemsPath field, whose
value must be a Reference
Path. The ItemsPath
field selects where in the input to find the
array to use for iterations. The Reference Path is applied to the effective input
(after
InputPath
is applied) and must identify a field whose value is a JSON
array.
The input to each iteration, by default, is a single element of the array field
identified by the ItemsPath
value, This may be overridden using the
Parameters
field.
When complete, the output of the Map
state is a JSON array, where each
item is the output of an iteration.
For more information, see the following.