--- title: "Append key adapter in Connector builder | Supermetrics" slug: "append-key" description: "Transform your data in Connector Builder 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.