---
title: "Append key"
slug: "append-key"
description: "Transform your data with the append_key adapter, converting keys into rows and managing object types for seamless integration and analysis."
updated: 2026-06-04T07:43:51Z
published: 2026-06-04T07:43:51Z
canonical: "docs.supermetrics.com/append-key"
---

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

# Append key

The `append_key` adapter takes an object at `dataPath` whose keys are values you want available on each row (typically dates), and converts it into an array of rows where each key becomes a field named by `keyName`. Use `dataType` to indicate whether each key references a single object or an array of objects.

| Field | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `dataPath` | string | – | Yes | JSONPath to the keyed object. Use `$` when the whole response is the keyed object. |
| `keyName` | string | – | Yes | The name of the new field that will hold the original key's value on each row. |
| `dataType` | string | `object` | No | `object` when each key references a single object, or `array_of_objects` when each key references an array. |
| `skipNonArrayValues` | boolean | `false` | No | When `true`, keys whose values are neither objects nor arrays of objects are ignored. The default raises an error if such keys are present. |

## When each key references a single object

The simplest case: each key (here, a date) references a single object whose properties become fields on the resulting row. Use `dataType: "object"` (this is also the default).

The original response is keyed by date:

```
{
  "2022-11-27": {
    "nb_uniq_visitors": 1203,
    "nb_users": 28
  },
  "2022-11-28": {
    "nb_uniq_visitors": 1029,
    "nb_users": 60
  }
}
```

After the adapter runs, each date becomes a row with `date` as a field:

```
[
  {
    "nb_uniq_visitors": 1203,
    "nb_users": 28,
    "date": "2022-11-27"
  },
  {
    "nb_uniq_visitors": 1029,
    "nb_users": 60,
    "date": "2022-11-28"
  }
]
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "append_key",
        "config": {
          "dataPath": "$",
          "keyName": "date",
          "dataType": "object"
        }
      }
    ]
  }
}
```

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": "nb_uniq_visitors",
    "label": "Unique visitors",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.nb_uniq_visitors"
    }
  },
  {
    "id": "nb_users",
    "label": "Users",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.nb_users"
    }
  }
]
```

## When each key references an array of objects

When each key references an array of objects, the adapter emits one row per array entry, copying the key onto each. Use `dataType: "array_of_objects"`.

The original response is keyed by date, with multiple per-device entries per date:

```
{
  "2023-01-01": [
    {
      "label": "Desktop",
      "visits": 540
    },
    {
      "label": "Mobile",
      "visits": 980
    }
  ],
  "2023-01-03": [
    {
      "label": "Desktop",
      "visits": 612
    },
    {
      "label": "Mobile",
      "visits": 1104
    }
  ]
}
```

After the adapter runs, each array entry becomes its own row with the date attached:

```
[
  {
    "label": "Desktop",
    "visits": 540,
    "date": "2023-01-01"
  },
  {
    "label": "Mobile",
    "visits": 980,
    "date": "2023-01-01"
  },
  {
    "label": "Desktop",
    "visits": 612,
    "date": "2023-01-03"
  },
  {
    "label": "Mobile",
    "visits": 1104,
    "date": "2023-01-03"
  }
]
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "append_key",
        "config": {
          "dataPath": "$",
          "keyName": "date",
          "dataType": "array_of_objects"
        }
      }
    ]
  }
}
```

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": "label",
    "label": "Device",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.label"
    }
  },
  {
    "id": "visits",
    "label": "Visits",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.visits"
    }
  }
]
```

## When the response contains non-object values

Some APIs include metadata keys (such as `has_more`, pagination cursors, or counts) alongside the date-keyed data. By default the adapter raises an error if it encounters keys whose values are neither objects nor arrays of objects. Setting `skipNonArrayValues: true` tells the adapter to skip those keys instead.

The original response includes `has_more` and `non_relevant_prop` alongside the date-keyed arrays:

```
{
  "has_more": false,
  "2023-01-01": [
    {
      "label": "Desktop",
      "visits": 540
    },
    {
      "label": "Mobile",
      "visits": 980
    }
  ],
  "non_relevant_prop": 123,
  "2023-01-03": [
    {
      "label": "Desktop",
      "visits": 612
    },
    {
      "label": "Mobile",
      "visits": 1104
    }
  ]
}
```

After the adapter runs, the date-keyed arrays become rows and the non-object values are ignored:

```
[
  {
    "label": "Desktop",
    "visits": 540,
    "date": "2023-01-01"
  },
  {
    "label": "Mobile",
    "visits": 980,
    "date": "2023-01-01"
  },
  {
    "label": "Desktop",
    "visits": 612,
    "date": "2023-01-03"
  },
  {
    "label": "Mobile",
    "visits": 1104,
    "date": "2023-01-03"
  }
]
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "append_key",
        "config": {
          "dataPath": "$",
          "keyName": "date",
          "dataType": "array_of_objects",
          "skipNonArrayValues": true
        }
      }
    ]
  }
}
```

Field paths are the same as in the previous scenario.