---
title: "Combine keys with nested values"
slug: "combine-keys-with-nested-values"
description: "Learn how the combine keys with nested values adapter pairs keys with values and merges the result into each row, keeping existing fields."
updated: 2026-06-04T07:44:24Z
published: 2026-06-04T07:44:24Z
canonical: "docs.supermetrics.com/combine-keys-with-nested-values"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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"
    }
  }
]
```