Map - Amazon Step Functions
Map State ExampleMap State Example with ParametersMap State Input and Output Processing
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 the Iterator field can transition to a state within it.

If any iteration fails, entire Map state fails, and all iterations are terminated.

MaxConcurrency (Optional)

The MaxConcurrencyfield’s value is an integer that provides an upper bound on how many invocations of the Iterator may run in parallel. For instance, a MaxConcurrency value of 10 will limit your Map 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.

To achieve a higher number of concurrency, consider using nested state machines that cascade Map states. For example, to achieve a concurrency of 1024 you could build a state machine that contains a Map state that iterates 32 times, then nest that state machine into the Map state of a higher level state machine that iterates 32 times.

The default value is 0, which places no quota on parallelism and iterations are invoked as concurrently as possible.

A MaxConcurrency value of 1 invokes the Iterator 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.

Note

If you define Retriers for the Map state, the retry policy applies to all the Map state iterations instead of only the failed iterations. For example, if your Map state contains three iterations out of which one fails, and you've defined the Retry field for the Map state, the retry policy applies to all the Map state iterations instead of only the failed iteration.

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 Amazon 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 the ItemsPath field, which selects where in the input to find the array to be used for iterations. If not specified, the value of ItemsPath is $, and the Iterator section expects that the array is the only input. If you specify the ItemsPath field, its value must be a Reference Path, which is applied to the effective input (after InputPath is applied) and it 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.

Tip

To deploy an example of a workflow that uses a Map state to your Amazon Web Services account, see Module 5 - Choice State and Map State of The Amazon Step Functions Workshop.