Skip to main content

Map@1

Node Map@1 is used to transform JSON data by mapping multiple arrays into a list of objects, effectively pivoting the data from a wide format to a long format. This node is particularly useful when you have JSON data organized with multiple arrays representing different attributes and you want to consolidate them into a single array of objects where each object represents a combined set of values at each index.

Adapter Prerequisites​

  • General availability: All adapters support this node type.

Node Configuration​

For fields path, targetPath, targetValueWriteMode, and targetValueKind, see Overview.

transformations:
  - type: Map@1
    path: $.data                          # The JSON path to the data containing arrays to map
    targetPath: $.mappedData              # Path where the mapped data should be stored in the payload
    targetValueKind: Simple               # The target value kind; 'Simple' for standard JSON types
    targetValueWriteMode: Overwrite       # The target value write mode; 'Overwrite' to set the value
    selectPaths:                          # List of JSON paths to the arrays within 'data' to map
      - $.timestamps                      # Path to the array of timestamps
      - $.values.temperature              # Path to the array of temperature values
      - $.values.humidity                 # Path to the array of humidity values

Configuration Properties​

  • selectPaths (IEnumerable<string>): A list of JSON paths to the arrays within the data that you want to map into objects. Each path should point to an array in the JSON structure.

  • path (string): The JSON path to the parent data object containing the arrays specified in selectPaths. This is where the node will look for the arrays to map.

  • targetPath (string): The JSON path where the resulting array of mapped objects will be stored in the payload.

  • targetValueKind (ValueKind): Specifies the kind of value to write at the targetPath. For this node, it should be set to 'Simple'.

  • targetValueWriteMode (WriteMode): Specifies how to write the value at the targetPath. Options are 'Overwrite', 'Append', etc. Typically, you would use 'Overwrite' for this node.

Usage Example​

Assume you have the following JSON payload:

{
  "data": {
    "timestamps": ["2023-01-01T00:00:00Z", "2023-01-01T01:00:00Z"],
    "values": {
      "temperature": [20.5, 21.0],
      "humidity": [30, 35]
    }
  }
}

You can use the Map@1 node to transform this data into an array of objects where each object contains a timestamp, temperature, and humidity value:

transformations:
  - type: Map@1
    path: $.data
    targetPath: $.mappedData
    targetValueKind: Simple
    targetValueWriteMode: Overwrite
    selectPaths:
      - $.timestamps
      - $.values.temperature
      - $.values.humidity

After the transformation, the payload will include:

{
  "mappedData": [
    {
      "timestamps": "2023-01-01T00:00:00Z",
      "values": {
        "temperature": 20.5,
        "humidity": 30
      }
    },
    {
      "timestamps": "2023-01-01T01:00:00Z",
      "values": {
        "temperature": 21.0,
        "humidity": 35
      }
    }
  ]
}

Notes​

  • Array Lengths: The node will process arrays up to the length of the longest array among the specified selectPaths. If some arrays are shorter, their values will not be included in entries beyond their length.

  • Non-array Paths: If a path in selectPaths does not point to an array, the node will issue a warning and skip that path.

  • Nested Objects: The node preserves the structure of nested objects in the paths specified. For example, if a path points to $.values.temperature, the resulting objects will include values.temperature as the key.

  • Data Alignment: It assumes that the arrays are aligned by index; that is, the first elements of each array correspond to each other.

Configuration Properties Details​

selectPaths​

  • Type: IEnumerable<string>
  • Description: A list of JSON paths to the arrays within the data that you want to map. Each path should point to an array in the JSON structure.

path​

  • Type: string
  • Description: The JSON path to the parent data object containing the arrays specified in selectPaths. This is the context where the node will look for the arrays to map.

targetPath​

  • Type: string
  • Description: The JSON path where the resulting array of mapped objects will be stored in the payload.

targetValueKind​

  • Type: ValueKind
  • Default: Simple
  • Description: Specifies the kind of value to write at the targetPath. For this node, it should be set to 'Simple' to denote standard JSON types.

targetValueWriteMode​

  • Type: WriteMode
  • Default: Overwrite
  • Description: Specifies how to write the value at the targetPath. Options include 'Overwrite' to replace any existing value at the path or 'Append' to add to an existing array.
  • Flatten@1: Flattens nested JSON structures into a flat key-value pair format.

By configuring and using the Map@1 node, you can effectively restructure your JSON data from a wide format with multiple arrays into a long format with a list of objects, each representing a combined set of values from the arrays. This transformation is particularly useful when preparing data for processes that require records in a unified object format.