# json_util

A module for loading JSON from a local file or remote address. If the JSON that
is being loaded is an array, then this module loads it as a stream of values,
and if it is a map, the module loads it as a single value.

| Trait               | Value      |
| ------------------- | ---------- |
| **Module type**     | util       |
| **Implementation**  | Python     |
| **Parallelism**     | sequential |

## Functions

### `from_json_list()`

Converts a JSON string representation of a list into an actual list object.

> **Info**
>
> Prefer the C++ [`convert.from_json_list`](https://memgraph.com/docs/advanced-algorithms/available-algorithms/convert#from_json_list),
> which is what `apoc.convert.fromJsonList` maps to. This Python version can
> produce slightly different output.

#### Input:

- `json_str: string` ➡ The JSON string representation of a list that needs to be converted.

#### Output:

- `List[Any]` ➡ The converted list object from the JSON string.

#### Usage:

Use the following query to convert a JSON string to a list:

```cypher
RETURN json_util.from_json_list('[1, 2, 3, "hello", true]') AS result;
```

Results:

```plaintext
+---------------------------------------------------------+
| result                                                   |
+---------------------------------------------------------+
| [1, 2, 3, "hello", true]                               |
+---------------------------------------------------------+
```

### `to_json()`

Converts any value to its JSON string representation.

> **Info**
>
> Prefer the C++ [`convert.to_json`](https://memgraph.com/docs/advanced-algorithms/available-algorithms/convert#to_json),
> which is what `apoc.convert.toJson` maps to. This Python version can produce
> slightly different output.

#### Input:

- `value: Any` ➡ The value that needs to be converted to JSON string format.

#### Output:

- `string` ➡ The JSON string representation of the input value.

#### Usage:

Use the following query to convert a value to JSON string:

```cypher
RETURN json_util.to_json([1, 2, 3, "hello", true]) AS result;
```

Results:

```plaintext
+---------------------------------------------------------+
| result                                                   |
+---------------------------------------------------------+
| "[1, 2, 3, \"hello\", true]"                           |
+---------------------------------------------------------+
```

## Procedures

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.
- `path: string` ➡ Path to the JSON that needs to be loaded.

#### Output:

- `objects: List[object]` ➡ The list of JSON objects from the file that is being loaded.

#### Usage:

Use the following query to load data from a local JSON file:

```cypher
CALL json_util.load_from_path(path) 
YIELD objects
RETURN objects;
```

### `load_from_url()`

The procedure loads data from a JSON file at a specified URL.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.
- `url: string` ➡ URL to the JSON that needs to be loaded.

#### Output:

- `objects: List[object]` ➡ A list of JSON objects from the file that is being loaded.

#### Usage:

Use the following query to load data from a JSON file at a specified URL:

```cypher
CALL json_util.load_from_url(url) 
YIELD objects
RETURN objects;
```

### `load_from_str()`

The procedure loads data from a JSON string.

#### Input:

- `json_str: string` ➡ JSON string that needs to be loaded.

#### Output:

- `objects: List[object]` ➡ A list of JSON objects from the string that is being loaded.

#### Usage:

Use the following query to load data from a JSON string:

```cypher
CALL json_util.load_from_str(json_str) 
YIELD objects
RETURN objects;
```

## Examples

### Load JSON from path

### Input file

The `data.json` file is located in the `load-data` directory with the following
content:

```json
{
	"first_name": "Jessica",
	"last_name": "Rabbit",
	"pets": [
		"dog",
		"cat",
		"bird"
	]
}
```

### Import data

Run the query to load the data from the file:

```cypher
CALL json_util.load_from_path("load-data/data.json") 
YIELD objects
UNWIND objects AS o
RETURN o.first_name AS name, o.last_name AS surname;
```

Results:

```plaintext
+------------------+-------------------+
| name             | surname           |
+------------------+-------------------+
| Jessica          | Rabbit            |
+------------------+-------------------+
```

### Load JSON from URL

### Input file

The `data.json` file is located at `"https://download.memgraph.com/asset/mage/data.json"` with the following
content:

```json
{
	"first_name": "James",
	"last_name": "Bond",
	"pets": [
		"dog",
		"cat",
		"fish"
	]
}
```

### Import data

Run the query to load the data from the file at the URL:

```cypher
CALL json_util.load_from_url("https://download.memgraph.com/asset/mage/data.json") 
YIELD objects
UNWIND objects AS o
RETURN o.first_name AS name, o.last_name AS surname;
```

Results:

```plaintext
+------------------+-------------------+
| name             | surname           |
+------------------+-------------------+
| James            | Bond              |
+------------------+-------------------+
```

### Load JSON from string

### Input string

The JSON string is `{"first_name": "James", "last_name": "Bond"}`.

### Import data

Directly parse the JSON string:

```cypher
CALL json_util.load_from_str('{"first_name": "James", "last_name": "Bond"}')
YIELD objects
UNWIND objects AS o
RETURN o.first_name AS name, o.last_name AS surname;
```

Results:

```plaintext
+------------------+-------------------+
| name             | surname           |
+------------------+-------------------+
| James            | Bond              |
+------------------+-------------------+
```