Combine keys with nested values

A variant of combine_keys_with_values for cases where the pairing should be merged into an existing row instead of replacing the row entirely. Use this when each row has fields you want to keep alongside the newly paired key/value object.

Field	Type	Required	Description
`keysPath`	string	Yes	JSONPath to the array of header names.
`dataPath`	string	Yes	JSONPath to the rows that should receive the merged result.
`valuesPath`	string	Yes	JSONPath, relative to each row, to the array of values being paired with the keys.
`valuesDestinationPath`	string	Yes	JSONPath, relative to each row, where the paired object is written. Equal to `valuesPath` replaces the original array; differs from it to add the result under a new key.

The examples below use the same input — a results array where each row has a metrics array of values, paired with a query.metrics array of names that explains what each position means:

{
  "results": [
    {
      "date": "2025-08-25",
      "metrics": [
        1,
        16
      ]
    },
    {
      "date": "2025-08-27",
      "metrics": [
        1,
        1
      ]
    }
  ],
  "query": {
    "metrics": [
      "visitors",
      "events"
    ]
  }
}

Replacing the original array

Set valuesDestinationPath equal to valuesPath to replace the original values array on each row with the keyed object in place.

After the adapter runs, the metrics array becomes a keyed object on each row:

{
  "results": [
    {
      "date": "2025-08-25",
      "metrics": {
        "visitors": 1,
        "events": 16
      }
    },
    {
      "date": "2025-08-27",
      "metrics": {
        "visitors": 1,
        "events": 1
      }
    }
  ]
}

Configuration:

"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.results.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "combine_keys_with_nested_values",
        "config": {
          "keysPath": "$.query.metrics",
          "dataPath": "$.results",
          "valuesPath": "$.metrics",
          "valuesDestinationPath": "$.metrics"
        }
      }
    ]
  }
}

Below you can find example field definitions that read from the transformed structure:

[
  {
    "id": "date",
    "label": "Date",
    "dataType": "string.time.date",
    "value": {
      "source": "jsonPath",
      "value": "$.date"
    }
  },
  {
    "id": "visitors",
    "label": "Visitors",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.metrics.visitors"
    }
  },
  {
    "id": "events",
    "label": "Events",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.metrics.events"
    }
  }
]

Adding the paired object under a new key

Set valuesDestinationPath to a different path than valuesPath to keep the original values array intact and add the keyed object as a new field on each row.

After the adapter runs, the original metrics array is preserved and a new metrics_named object is added:

{
  "results": [
    {
      "date": "2025-08-25",
      "metrics": [
        1,
        16
      ],
      "metrics_named": {
        "visitors": 1,
        "events": 16
      }
    },
    {
      "date": "2025-08-27",
      "metrics": [
        1,
        1
      ],
      "metrics_named": {
        "visitors": 1,
        "events": 1
      }
    }
  ]
}

Configuration:

"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.results.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "combine_keys_with_nested_values",
        "config": {
          "keysPath": "$.query.metrics",
          "dataPath": "$.results",
          "valuesPath": "$.metrics",
          "valuesDestinationPath": "$.metrics_named"
        }
      }
    ]
  }
}

Below you can find example field definitions that read from the transformed structure:

[
  {
    "id": "date",
    "label": "Date",
    "dataType": "string.time.date",
    "value": {
      "source": "jsonPath",
      "value": "$.date"
    }
  },
  {
    "id": "visitors",
    "label": "Visitors",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.metrics_named.visitors"
    }
  },
  {
    "id": "events",
    "label": "Events",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.metrics_named.events"
    }
  }
]

Documentation Index

Combine keys with nested values

Replacing the original array

Adding the paired object under a new key