---
title: "Match values by keys"
slug: "match-values-by-keys"
description: "Learn how the match values by keys adapter pivots a keys array and a values map into one row per key, with each metric as a column."
updated: 2026-06-04T07:44:13Z
published: 2026-06-04T07:44:13Z
canonical: "docs.supermetrics.com/match-values-by-keys"
---

> ## 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.

# Match values by keys

Some APIs return data split between two parallel structures: an array of keys (typically dates) and a values map where each metric's measurements are indexed by those same keys. The `match_values_by_keys` adapter pivots that shape into one row per key, with each metric becoming a column. Missing intersections are filled with `null`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keysPath` | string | Yes | JSONPath to the array of key values (these become the values of the new key field on each output row). |
| `valuesPath` | string | Yes | JSONPath to the value maps that are indexed by the same values found at `keysPath`. |
| `dataDestinationPath` | string | Yes | JSONPath where the resulting rows are written. |
| `keyName` | string | Yes | The name of the field that holds each key on the output rows. |

Below you can find a before/after example. The original response separates the date axis from the per-metric values:

```
{
  "data": {
    "series": [
      "2010-05-29",
      "2010-05-30",
      "2010-05-31"
    ],
    "values": {
      "account-page": {
        "2010-05-30": 1
      },
      "splash features": {
        "2010-05-29": 6,
        "2010-05-30": 4,
        "2010-05-31": 5
      }
    }
  }
}
```

After the adapter runs, each date becomes a row with metrics as columns:

```
{
  "data": [
    {
      "date": "2010-05-29",
      "account-page": null,
      "splash features": 6
    },
    {
      "date": "2010-05-30",
      "account-page": 1,
      "splash features": 4
    },
    {
      "date": "2010-05-31",
      "account-page": null,
      "splash features": 5
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "match_values_by_keys",
        "config": {
          "keysPath": "$.series.*",
          "valuesPath": "$.values.*",
          "dataDestinationPath": "$.data",
          "keyName": "date"
        }
      }
    ]
  }
}
```

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": "account_page",
    "label": "Account page",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.account-page"
    }
  },
  {
    "id": "splash_features",
    "label": "Splash features",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$['splash features']"
    }
  }
]
```