Map states and examples - CloudFlow - Alibaba Cloud Documentation Center

This topic describes Map states and provides related examples.

Overview

A Map state is used to traverse a parameter of the array type in the input and execute the Processor states in parallel for all elements in the array. A Map state is similar to the foreach statement in programming languages. However, the iterations in Map are executed in parallel.

When a Map state is executed, the Processor states of all elements in the input parameter are concurrently executed. By default, a map[string]any output that contains the results of all branches is returned after all branches are executed. Then, the system uses the output constructor to further process the results.

Note

Up to 100 Processor states can be concurrently executed in a Map state. The maximum number of Processor states that can be concurrently executed varies based on the I/O size.

The following table describes the attributes that a Map state contains.

Attribute	Type	Required	Description	Example
Name	string	Yes	The name of the state.	my-state-name
Description	string	No	The description of the state.	describe it here
Type	string	Yes	The type of the state.	Map
InputConstructor	map[string]any	No	The input constructor.	See Inputs and outputs.
ItemsPath	string	Yes	The expression that is used to extract the input array.	See the ItemsPath section of this topic.
Processor	ItemProcessor	Yes	The iteration processor.	See the ItemProcessor section of this topic.
OutputConstructor	map[string]any	No	The output constructor.	See the State OutputConstructor section of the "Inputs and outputs" topic.
Next	string	No	The next state that is executed after the current state is complete. If the value of the End attribute is true, you do not need to specify this attribute.	my-next-state
End	bool	No	Specifies whether to end the current scope.	true
Retry	Retry	No	The information about the retry policy.	See Error handling.
Catch	Catch	No	The information about the catch policy.	See Error handling.
MaxConcuccency	int	No	The concurrency configuration.	40
ItemConstructor	map[string]any	No	The child input constructor.	See the ItemConstructor section of this topic.

ItemsPath

If a value in the JSON array format is returned after an ItemsPath expression is executed, the return value can be iterated. Then, all elements in the iterated value are passed to ItemProcessor for processing. You can use the $Context and $Input expression variables, as shown in the following example:

$Input.FieldA

ItemProcessor

Attribute	Type	Required	Description	Example
States	array	Yes	The array of states that are contained in the flow.	For more information, see the Example 1 section of this topic.
StartAt	string	Yes	The state from which the execution of the flow starts.	my start task

ItemConstructor

The syntax is similar to the syntax of the input and output constructors. The $Item reserved word is added.

  - Type: Map
    Name: MapReduce
    ItemsPath: $Input.formap
    ItemConstructor:
      origItem.$: $Item
      outterFieldA.$: $Input.fieldA
      staticValue: 123qwe

The $Item reserved word represents the elements that are iterated each time. The $Input reserved word represents the context of the expression, which is the input of MapReduce.

If multiple configurations exist, the configurations are executed in the following order: InputConstructor, ItemsPath, and ItemConstructor.

Examples

Example 1

The following sample flow defines a Map state. The MapProcessor contains a Pass state.

Type: StateMachine
Name: my-wkfl
SpecVersion: v1
StartAt: Map1
States:
  - Type: Map
    Name: Map1
    End: true
    InputConstructor:
      FieldA: 
        - a : b
        - c : d
        - e : f
    ItemsPath: $Input.FieldA
    Processor:
      StartAt: Pass1
      States:
        - Type: Pass
          Name: Pass1
          End: true

The following sample code provides an example of the input construction result of the flow.

{
    "FieldA": [
        {
            "a": "b"
        },
        {
            "c": "d"
        },
        {
            "e": "f"
        }
    ]
}

For a Map, the system merges the outputs of all iteration processors. By default, the Items keyword is used as the key and the merged result is used as the value. The following sample code provides an example of the output of Map1. This is also the final output after the flow is executed.

{
    "Items": [
        {
            "a": "b"
        },
        {
            "c": "d"
        },
        {
            "e": "f"
        }
    ]
}

Example 2 is more complex.

Example 2

Type: Workflow
Name: my-wkfl
Description: test workflow definition
SpecVersion: V3
StartAt: MapReduce
States:
  - Type: Map
    Name: MapReduce
    ItemsPath: $Input.formap
    ItemConstructor:
      origItem.$: $Item
      outterFieldA.$: $Input.fieldA
      staticValue: 123qwe
    ItemBatcher:
      MaxItemsPerBatch: 2
      BatchInput: 
        apd: tt
    End: true
    Processor:
      StartAt: Succeed
      States:
        - Type: Succeed
          Name: Succeed

The input:

{
    "fieldA": {
        "orig-fieldA-1": 1,
        "orig-fieldA-2": "qwe1"
    },
    "formap": [
        {
            "k0": "v"
        },
        {
            "k1": "v"
        },
        {
            "k2": "v"
        },
        {
            "k3": "v"
        },
        {
            "k4": "v"
        }
    ]
}

The items in the input are batched, and each batch contains two items. A dataset named apd is appended to each batch.

The input of each batch is constructed in advance, including the origItem, outterFieldA, and staticValue attributes.

The output:

{
    "Items": [
        {
            "origItem": {
                "BatchInput": {
                    "apd": "tt"
                },
                "Items": [
                    {
                        "k0": "v"
                    },
                    {
                        "k1": "v"
                    }
                ]
            },
            "outterFieldA": {
                "orig-fieldA-1": 1,
                "orig-fieldA-2": "qwe1"
            },
            "staticValue": "123qwe"
        },
        {
            "origItem": {
                "BatchInput": {
                    "apd": "tt"
                },
                "Items": [
                    {
                        "k2": "v"
                    },
                    {
                        "k3": "v"
                    }
                ]
            },
            "outterFieldA": {
                "orig-fieldA-1": 1,
                "orig-fieldA-2": "qwe1"
            },
            "staticValue": "123qwe"
        },
        {
            "origItem": {
                "BatchInput": {
                    "apd": "tt"
                },
                "Items": [
                    {
                        "k4": "v"
                    }
                ]
            },
            "outterFieldA": {
                "orig-fieldA-1": 1,
                "orig-fieldA-2": "qwe1"
            },
            "staticValue": "123qwe"
        }
    ]
}