convert

The convert module is a data transformation module that offers functions to convert various data structures into different formats, allowing operations like data type transformation and structural modifications for efficient data handling.

Functions in the collection are called inline.

Functions

str2object()

Converts a JSON string to an object representation. This function is useful for parsing JSON data and converting it into a usable object format.

Input:

• string: String ➡ The JSON string to be converted to an object.

Output:

• object: Any ➡ The resulting object representation of the JSON string.

Usage:

Use the following query to convert a JSON string to an object:

RETURN convert.str2object('{"name": "Alice", "age": 30, "city": "New York"}') AS result;

The output shows the parsed map:

{name: "Alice", age: 30, city: "New York"}

from_json_map()

Parses a JSON-object string into a map. An optional path selects a nested part of the document before conversion; the selected value must be a JSON object.

Input:

• map: String ➡ The JSON string to parse. A null value returns null.
• path: String (default "") ➡ An optional selector for a nested part of the document (see Path option).

Output:

• Map ➡ The parsed map. Returns null when the input is null, when the path does not resolve, or when the selected value is JSON null. An error is raised when the input (or selected value) is not a JSON object.

Usage:

RETURN convert.from_json_map('{"name": "GDS"}') AS result;

{name: "GDS"}

Select a nested object with path:

RETURN convert.from_json_map('{"a": 1, "b": {"c": 2, "d": [10, 20]}}', '$.b') AS result;

{c: 2, d: [10, 20]}

To read a single value out of the parsed map, index it with Cypher instead of using path:

RETURN convert.from_json_map('{"mode": "fast"}')['mode'] AS result;

"fast"

from_json_list()

Parses a JSON-array string into a list. An optional path selects a nested part of the document before conversion; the selected value must be a JSON array.

Input:

• list: String ➡ The JSON string to parse. A null value returns null.
• path: String (default "") ➡ An optional selector for a nested part of the document (see Path option).

Output:

• List ➡ The parsed list. Returns null when the input is null, when the path does not resolve, or when the selected value is JSON null. An error is raised when the input (or selected value) is not a JSON array.

Usage:

RETURN convert.from_json_list('[1, 2, 3]') AS result;

[1, 2, 3]

Select a nested array with path:

RETURN convert.from_json_list('{"a": [1, 2, 3]}', '$.a') AS result;

[1, 2, 3]

Path option

from_json_map() and from_json_list() accept an optional path that selects a nested part of the JSON document before conversion.

Steps chain left to right ($.b.e[0] selects 10), and a leading $ is optional (a.b is equivalent to $.a.b). Wildcards ($.e[*]), recursive descent ($..x), filter expressions and array slices are not supported and raise an error. A path that does not resolve, or that resolves to JSON null, returns null.

to_map()

Returns a map unchanged, or a node or relationship as its property map. Any other value — such as an integer, string or list — returns null.

Input:

• map: Any ➡ The value to convert.

Output:

• Map ➡ A map is returned unchanged, a node or relationship is returned as its property map, and null or any other value returns null.

Usage:

CREATE (n:Person {id: 4, name: 'z'})
RETURN convert.to_map(n) AS result;

{id: 4, name: "z"}

to_json()

Serializes a value into a JSON string.

Input:

• value: Any ➡ The value to serialize.

Output:

• String ➡ The JSON string representation of the value.

Scalars, lists and maps are serialized directly. Graph and spatial-temporal values use a structured form:

• Node ➡ {id, type: "node", labels, properties}; labels and properties are omitted when empty.
• Relationship ➡ {id, type: "relationship", label, start, end, properties}, where start and end are full node objects; properties is omitted when empty.
• Path ➡ a flat array [node, relationship, node, ...].
• Point ➡ {crs, x, y, z} for cartesian points, {crs, longitude, latitude, height} for geographic points.
• Temporal ➡ the canonical string form (for example "2020-01-02" for a date, an ISO-8601 period with a fixed six-digit fractional-second field for a duration, e.g. "P1DT2H3M4.500000S").

Object keys are serialized in alphabetical order, and the order of the labels array follows the node’s internal label IDs, so it is not guaranteed.

Null, boolean, numeric, string, list, map, node, relationship, path, point and temporal values are all supported. Serializing an enum value raises an error.

Usage:

RETURN convert.to_json({a: 1, b: 'x', c: [1, 2], d: null}) AS result;

{"a":1,"b":"x","c":[1,2],"d":null}

Serialize a node:

CREATE (n:Person:Human {name: 'Ana', age: 30})
RETURN convert.to_json(n) AS result;

{"id":"0","labels":["Person","Human"],"properties":{"age":30,"name":"Ana"},"type":"node"}