MetricsHub
MetricsHub Community Connectors 1.0.24
-
Home
- Connector Developer Guide Computes 27
json2Csv (Compute)
When To Use
Use json2Csv to turn a raw JSON payload — typically the body of an http[1] source — into the tabular form that mapping and other computes expect. Point entryKey at the JSON array (or object) holding the entries, and list in properties the values to extract from each entry: the compute emits one row per entry, one column per property.
This is almost always the first compute in an HTTP source pipeline: parse the payload into a table immediately, then filter and reshape with regular table computes.
Syntax
sources:
switches:
type: http
method: get
path: /api/v1/inventory/switches
resultContent: body
computes:
- type: json2Csv
entryKey: /switches
properties: /id;/name;/operationalStatus
separator: ;
Properties
| Property | Required | Default | Description |
|---|---|---|---|
type |
Yes | None | json2Csv. |
entryKey |
No | None | JSON pointer to the node containing the entries to convert. Point at an array (/switches, /Members) to get one row per element; use / to treat the whole document as a single entry. Always set it explicitly. |
properties |
Yes | None | Semicolon-separated list of JSON pointers, each resolved relative to one entry (/id;/name;/operationalStatus). Nested values use full pointer paths, including array indexes (/Links/Storage[0]/@odata.id). The list order defines the column order. |
separator |
No | ; |
Column separator of the generated rows. Keep the default ; so the output matches the engine table serialization. |
parsingMode |
No | tree |
How the JSON document is read: tree loads the whole document in memory, events reads it as a stream and keeps only one entry at a time. The rows are the same. See Large Payloads. |
json2Csv prepends one extra column identifying the JSON entry each row was built from (its path in the document). Your first property therefore lands in column 2: reference it as $2 in mapping and in subsequent computes.
You may encounter two shorthand styles in examples: property pointers written without the leading / (properties: id;name;status), which resolve against each entry's top level, and array traversal expressed inside the property itself (properties: Members[*].@odata.id). Prefer the canonical form used by real connectors: entryKey pointing at the array, plus one leading-slash pointer per column (entryKey: /Members with properties: /@odata.id).
Table Transformation Example
Input (JSON body)
{
"switches": [
{ "id": "sw-01", "name": "edge-01", "operationalStatus": "ok" },
{ "id": "sw-02", "name": "core-01", "operationalStatus": "degraded" }
]
}
Result
| Entry (col 1) | id (col 2) | name (col 3) | operationalStatus (col 4) |
|---|---|---|---|
| /switches[0] | sw-01 | edge-01 | ok |
| /switches[1] | sw-02 | core-01 | degraded |
Equivalent serialized output:
/switches[0];sw-01;edge-01;ok
/switches[1];sw-02;core-01;degraded
Large Payloads
With the default parsingMode: tree, json2Csv builds a map of every node of the document before it writes the rows. This takes about 20 times the size of the payload in memory, even when only a few values are read per entry.
For a REST API that returns large lists (thousands of objects, several MB), set parsingMode: events:
computes:
- type: json2Csv
entryKey: /items
properties: /metadata/name;/metadata/namespace;/status/phase
separator: ;
parsingMode: events
The document is then read as a stream of JSON events:
- Only one element of the array at the start of
entryKey(/itemsabove) is flattened at a time. - The nodes that neither
entryKeynorpropertiescan reach are skipped.
Memory stays close to the size of the payload and the conversion is faster. The rows are the same as with tree, in the same order.
Some documents cannot be read this way and are processed as with tree, with the same memory usage:
- the payload is an array,
entryKeyis/, or the first element ofentryKeyis*or contains an index (/items[0]/...); - a property refers to a node above the array element, for example
../kindwithentryKey: /items(../../metadata/namewithentryKey: /items/status/conditionsstays inside the element and is fine); - an object of an element has a duplicate key.
parsingMode is available from MetricsHub Community 3.9.08. Earlier versions ignore it and read the document as a tree, so the connector still works.
Recommended Pattern
- Set
resultContent: bodyon the HTTP source and putjson2Csvfirst in itscomputespipeline. - Point
entryKeyat the array of records and keep every property pointer relative to a single record. - Account for the leading entry column: the first property is
$2, not$1. - Add
parsingMode: eventswhen the payload can be large (a list of all the objects of a kind). - Quote the
propertiesvalue when a pointer contains YAML-sensitive characters such as[0](for exampleproperties: "/@odata.id;/Links/Storage[0]/@odata.id").
Common Mistakes
- Off-by-one column references in
mappingor later computes because the leading entry column was forgotten. - Writing property pointers relative to the document root instead of relative to one entry under
entryKey. - Separating
propertieswith commas: the list is semicolon-separated. - Leaving
entryKeypointing at a single object when the payload nests the records one level deeper, which yields a single mostly-empty row instead of one row per record.
Community Examples
- Redfish[2]
computes:
- type: json2csv
entryKey: /Members
properties: /@odata.id;
separator: ;
Redfish still uses the legacy lowercase alias json2csv. Use the canonical json2Csv casing in new connectors (see Legacy and Compatibility[3]).
- [1] ../sources/http.html
- [2] https://github.com/metricshub/community-connectors/blob/main/src/main/connector/hardware/Redfish/Redfish.yaml
- [3] ../legacy-and-compatibility.html
