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]]
type: 3 * var * float64

or a file name:

!echo "[[1.1, 2.2, 3.3], [], [4.4, 5.5]]" > /tmp/awkward-example-1.json
[[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"}')
{x: 1,
 y: [1, 2],
 z: 'hello'}
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]]))

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

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.)


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.