--- title: "Combine keys with nested values in Connector builder | Supermetrics" 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" } } ] ```