The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Neo4j-Driver-0.49
River stage one • 1 direct dependent • 2 total dependents
4 ++
/ Neo4j::Driver::Types

NAME

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

VERSION

version 0.49

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

  • hash ref { ... } – Neo4j maps

  • array ref [ ... ] – Neo4j lists

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

The properties() method of node and relationship objects currently makes a new defensive copy of the properties hash each time it's called. Version 1.xx of the driver will change this to give a reference to the internal hash instead, providing a significant performance increase. Until then, you might consider caching the hash ref locally.

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 the latest released version of Neo4j::Bolt (0.4203 at time of this writing):

  • Neo4j 5 element IDs are not yet supported (perlbolt#50).

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

  • With Neo4j::Bolt version 0.01, the value of node or relationship properties named _end, _node, _labels, _relationship, _start, or _type may not be returned correctly. Note that support for all Neo4j::Bolt versions earlier than 0.4201 will be phased out entirely soon.

  • builtin::true and builtin::false are not yet supported in query parameters. Use \1 and \0 or JSON::PP::Boolean instead.

  • Byte arrays are not yet supported as query parameters. Byte arrays are coded as unblessed strings in Bolt results.

  • Temporal and spatial values are not yet supported (perlbolt#36).

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 are not supported as query parameters.

  • Temporal and spatial values are not supported as query parameters.

  • 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 not supported as query parameters. Byte arrays are coded as lists of integers in JSON results.

  • Temporal and spatial values are not supported as query parameters.

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

  • The value of node or relationship properties named _meta may not be returned correctly.

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