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.

Documentation Index

Append key

When each key references a single object

When each key references an array of objects

When the response contains non-object values