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
import pathlib

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]]")

[[1.1, 2.2, 3.3],
 [],
 [4.4, 5.5]]
-----------------
backend: cpu
nbytes: 72 B
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(pathlib.Path("/tmp/awkward-example-1.json"))

[[1.1, 2.2, 3.3],
 [],
 [4.4, 5.5]]
-----------------
backend: cpu
nbytes: 72 B
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"}')

{x: 1,
 y: [1, 2],
 z: 'hello'}
------------
backend: cpu
nbytes: 61 B
type: {
    x: int64,
    y: var * int64,
    z: string
}

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.