How to convert to/from JSON¶

Any JSON data can be converted to Awkward Arrays and any Awkward Arrays can be converted to JSON. Awkward type information, such as the distinction between fixed-size and variable-length lists, is lost in the transformation to JSON, however.

import awkward as ak

From JSON to Awkward¶

The function for JSON → Awkward conversion is ak.from_json.

It can be given a JSON string:

ak.from_json("[[1.1, 2.2, 3.3], [], [4.4, 5.5]]")

<Array [[1.1, 2.2, 3.3], [], [4.4, 5.5]] type='3 * var * float64'>

or a file name:

!echo "[[1.1, 2.2, 3.3], [], [4.4, 5.5]]" > /tmp/awkward-example-1.json

ak.from_json("/tmp/awkward-example-1.json")

<Array [[1.1, 2.2, 3.3], [], [4.4, 5.5]] type='3 * var * float64'>

If the dataset contains a single JSON object, an ak.Record is returned, rather than an ak.Array.

ak.from_json('{"x": 1, "y": [1, 2], "z": "hello"}')

<Record {x: 1, y: [1, 2], z: 'hello'} type='{"x": int64, "y": var * int64, "z": ...'>

From Awkward to JSON¶

The function for Awkward → JSON conversion is ak.to_json.

With one argument, it returns a string.

ak.to_json(ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]]))

'[[1.1,2.2,3.3],[],[4.4,5.5]]'

But if a destination is given, it is taken to be a filename for output.

ak.to_json(ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]]), "/tmp/awkward-example-2.json")

!cat /tmp/awkward-example-2.json

[[1.1,2.2,3.3],[],[4.4,5.5]]

Conversion of different types¶

All of the rules that apply for Python objects in ak.from_iter and ak.to_list apply to ak.from_json and ak.to_json, replacing builtin Python types for JSON types. (One exception: JSON has no equivalent of a Python tuple.)

Performance¶

Since Awkward Array internally uses RapidJSON to simultaneously parse and convert the JSON string, ak.from_json and ak.to_json should always be faster and use less memory than ak.from_iter and ak.to_list. Don’t convert JSON strings into or out of Python objects for the sake of converting them as Python objects: use the JSON converters directly.