How to convert to/from JSON
Contents
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.