/ 
Neo4j-Driver-1.02
River stage one • 1 direct dependent • 2 total dependents
/ Neo4j::Driver::Types

NAME

Neo4j::Driver::Types - Type mapping from Neo4j to Perl and vice versa

VERSION

version 1.02

MAPPING

Neo4j values can have a variety of types, and mapping these types onto Perl types and vice versa isn't always straight-forward. Neo4j::Driver is designed to use the Neo4j::Types system as far as possible.

When this driver returns values from queries, Neo4j types are represented by the Perl types shown in the following list.

Structural values
Temporal and spatial values
Simple property values
Constructed values

  • array ref [ ... ] – Neo4j lists

  • hash ref { ... } – Neo4j maps

Null values

  • undef

Byte arrays

In principle, you can also use values of these Perl types as query parameters, and they will be correctly recognised by Neo4j. However, Neo4j doesn't accept structural values (nodes / relationships) as query parameters. See below for further limitations that depend on the network protocol.

Perl "distinguished" core boolean values (builtin::true and builtin::false) are only available starting with Perl v5.36. On older Perls, JSON::PP::true and JSON::PP::false are used instead. These are blessed objects overloaded to evaluate correctly in boolean context. Additionally, \1 and \0 are accepted as literal booleans in query parameters.

USAGE NOTES

Element IDs and legacy numeric IDs

Neo4j is in the process of replacing legacy numeric IDs with element IDs. On Neo4j 5 and newer, numeric IDs may not be reliably available and methods like id() may issue a warning in the deprecated category. Use element_id() on Neo4j 5 instead.

Representation of nodes and relationships

Node and relationship objects are not in a one-to-one relation with nodes and relationships in a Neo4j graph. If the same Neo4j entity is fetched multiple times, then multiple distinct objects will be created by the driver. If your intention is to verify that e. g. two node objects in Perl describe the same node in the Neo4j database, you need to compare their element IDs.

Perl number / string coercions

A Perl scalar may internally be represented as a number or a string (see "Scalar values" in perldata). Perl usually auto-converts one into the other based on the context in which the scalar is used. However, Perl cannot know the context of a Neo4j query parameter, because queries are just opaque strings to Perl. Most often your scalars will already have the correct internal flavour. A typical example for a situation in which this is not the case are numbers parsed out of strings using regular expressions. If necessary, you can force conversion of such values into the correct type by using JSON::Types or with simple unary coercions like this:

$number =  0 + $scalar;
$string = '' . $scalar;
Properties hash reference

Since driver version 1.02, the properties() method of node and relationship objects returns a reference to the internal hash. This makes properties() the preferred way to retrieve a single property, as it's both faster and clearer than get().

$value = $node->properties->{key};

# Chaining get() is a potentially confusing anti-pattern
$value = $record->get('field')->get('key');  # avoid this!

BUGS AND LIMITATIONS

Bolt networking

For connecting to a Neo4j server using the Bolt protocol, this driver will by default use Neo4j::Bolt. The following bugs and limitations related to types are known for Bolt:

  • Query parameters containing an empty list or empty map will be converted to a Cypher null value (perlbolt#19).

  • Neo4j ZONED DATETIME values defined by time zone name rather than just by offset are not supported (libneo4j-omni#5).

  • The use of builtin::true, builtin::false, byte arrays, spatial values, and temporal values requires a recent enough Neo4j::Bolt version (0.5000 or later).

Jolt networking

For connecting to a Neo4j server (version 4.2 and later) using the HTTP or HTTPS protocol, this driver will by default use its built-in Jolt networking. The following bugs and limitations related to types are known for Jolt in this version of Neo4j::Driver:

  • Byte arrays, spatial values, and temporal values cannot be used as query parameters. This is due to a limitation in the Neo4j server.

  • The use of builtin::true and builtin::false in query parameters requires recent enough JSON module versions (Cpanel::JSON::XS 4.38 / JSON::PP 4.11).

JSON networking

For connecting to a Neo4j server earlier than version 4.2 using the HTTP or HTTPS protocol, Neo4j::Driver will by default use its built-in JSON networking. The following bugs and limitations related to types are known for JSON:

  • Byte arrays are coded as lists of integers in JSON results.

  • Byte arrays, spatial values, and temporal values cannot be used as query parameters. This is due to a limitation in the Neo4j server.

  • The use of builtin::true and builtin::false in query parameters requires recent enough JSON module versions (Cpanel::JSON::XS 4.38 / JSON::PP 4.11).

  • Fields in records containing maps, lists, or temporal values may be returned with incorrect type or meta data due to a bug in the Neo4j server (neo4j#12306).

  • The labels of nodes and type of relationships that are returned as part of a Neo4j path are unavailable, because that information is not provided by the Neo4j server (neo4j#12613).

SEE ALSO

AUTHOR

Arne Johannessen (AJNN)

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016-2024 by Arne Johannessen.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or (at your option) the same terms as the Perl 5 programming language system itself.