-
-
13 Jun 2022 21:56:15 UTC
- Distribution: Neo4j-Driver
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues
- Testers (370 / 1 / 1)
- Kwalitee
Bus factor: 2- 90.38% Coverage
- License: artistic_2
- Perl: v5.10.0
- Activity
24 month- Tools
- Download (104.5KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- NAME
- VERSION
- OVERVIEW
- Neo4j::Driver
- Neo4j::Driver::Net::HTTP::LWP
- Neo4j::Driver::Record
- Neo4j::Driver::Result
- Neo4j::Driver::ServerInfo
- Neo4j::Driver::Session
- Neo4j::Driver::StatementResult
- Neo4j::Driver::Transaction
- Neo4j::Driver::Type::Node, Neo4j::Driver::Type::Relationship
- Neo4j::Driver::Type::Path
- AUTHOR
- COPYRIGHT AND LICENSE
NAME
Neo4j::Driver::Deprecations - Explains features that have been deprecated, but not yet removed
VERSION
version 0.31
OVERVIEW
Deprecated features are removed from the pod documentation of the individual modules in this distribution in an attempt to keep those short and clear. This document describes all features that are deprecated, but still working for completeness' sake, briefly explains the reason for their deprecation, and suggests alternatives where possible.
The intention is that most deprecated features will be removed with the next major update to Neo4j::Driver. There is no schedule for the release of that update (version 1.00), but there is a decent chance that it will happen in the year 2022.
Neo4j::Driver
close()
Deprecated in version 0.14 and to be removed in 1.00. Originally added in 0.02 as an experimental feature.
$driver->close; # no-op
All resources opened by the Perl driver are closed automatically once they are no longer required. Explicit calls to
close()
are neither required nor useful.Config option
ca_file
Deprecated in version 0.15 and to be removed in 1.00. Originally added in 0.13 as an experimental feature.
$driver->config(ca_file => 'neo4j/certificates/neo4j.cert');
Specifies the location of a local copy of the server certificate for the then-experimental HTTPS self-signed certificate support. The driver config option
ca_file
corresponded toSSL_ca_file
in LWP::UserAgent and IO::Socket::SSL.This option was renamed
tls_ca
in version 0.15 to be more consistent with thetls
option, then later renamedtrust_ca
in version 0.27 to be more consistent with the Neo4j Driver API. See "trust_ca" in Neo4j::Driver.Custom networking modules
Deprecated in version 0.31 and to be removed in 1.00. Originally added in 0.21 as an experimental feature.
use Local::MyNetModule; $driver->config(net_module => 'Local::MyNetModule');
The module to be used for network communication may be specified using the
net_module
config option. The specified module must implement the API described in "EXTENSIONS" in Neo4j::Driver::Net. Your code mustuse
orrequire
the module it specifies here.The default value of
undef
will cause the driver to use its built-in modules. An empty string""
will do the same.# use the built-in networking modules $driver->config(net_module => undef); $driver->config(net_module => '');
Some versions of the driver also allow users to run its test suite against a custom net module.
TEST_NEO4J_NETMODULE=Local::MyNetModule prove
The
net_module
option provides decent flexibility for extending the driver. However, some interesting possible extensions have little to do with networking, and thenet_module
API itself lacks flexibility.Existing networking modules should be converted to HTTP network adapters. This is easily done with the the following two steps.
Rename your existing
sub new {}
constructor to (for example)sub _net_module_new {}
.Insert the following code into your module:
use parent 'Neo4j::Driver::Plugin'; sub new { bless [], shift; } sub register { my ($self, $manager) = @_; $manager->add_event_handler( http_adapter_factory => sub { my ($continue, $driver) = @_; __PACKAGE__->_net_module_new($driver); }, ); }
See "http_adapter_factory" in Neo4j::Driver::Plugin for details.
At that point, your code setting the
net_module
config option can simply be replaced by calls to "plugin" in Neo4j::Driver.# Deprecated config option: use Local::Foo; $driver->config( net_module => 'Local::Foo' ); # New plug-in interface: use Local::Foo; $driver->plugin( 'Local::Foo' );
Disable or enforce Jolt
Deprecated in version 0.30 and to be removed in 1.00. Originally added in 0.21 as an experimental feature.
$d->config(jolt => undef); # prefer Jolt (the default) $d->config(jolt => 0); # accept only JSON $d->config(jolt => 1); # accept only Jolt # Accept only Jolt and request ... $d->config(jolt => 'sparse'); # sparse Jolt mode + RFC 7464 $d->config(jolt => 'strict'); # strict Jolt mode + RFC 7464 $d->config(jolt => 'ndjson'); # newline delimited mode (non RFC)
Since driver version 0.24, the Jolt response format (JSON Bolt) is preferred for HTTP connections because the older REST-style JSON response format has several known issues and is much slower than Jolt.
This option is no longer useful. The driver will pick the fastest and most reliable format automatically (RFC 7464 sparse Jolt, if available). If you do need a specific response format, for example because you use driver internals to access the raw server response, you can use a plug-in to manipulate the HTTP
Accept
header according to your needs. See Neo4j::Driver::Net.Mutable auth credentials
Deprecated in version 0.15 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
$session1 = $driver->basic_auth('user1', 'password')->session; $session2 = $driver->basic_auth('user2', 'password')->session;
Early versions allowed modifying the driver object after session creation. This is not very useful in practice. The official Neo4j drivers are explicitly designed to be immutable.
Parameter syntax conversion using
cypher_filter
Config option
cypher_filter
deprecated in version 0.26 and to be removed in 1.00. Originally added in 0.14 as an experimental feature.$driver->config( cypher_filter => 'params' );
When this option is set, the driver automatically uses a regular expression to convert the old Cypher parameter syntax
{param}
supported by Neo4j versions 2 and 3 to the new syntax$param
supported by Neo4j versions 3 and 4.This option was meant to support more general filtering of Cypher statements at some point in the future. But plug-ins already make that very easy. Therefore the
cypher_filter
option won't be extended any further. However, the existing parameter syntax conversion is probably useful enough to stand on its own feet if given a more appropriate name.Instead of this option,
cypher_params
should be used; see "Parameter syntax conversion" in Neo4j::Driver.$driver->config( cypher_params => v2 );
Suppress exceptions
Deprecated in version 0.14 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
$driver = Neo4j::Driver->new; $driver->{die_on_error} = 0; $result = $driver->session->run('...');
The default value of the
die_on_error
attribute is1
. Setting this to0
causes the driver to no longer die on server errors.This is much less useful than it sounds. Not only is the Result structure not well-defined for such situations, but also the internal state of the Transaction object may be corrupted. For example, when a minor server error occurs on the first request (which would normally establish the connection), the expected
Location
header may be missing from the error message and the transaction may therefore be marked as closed, even though it still is open. The next request would then fail anyway, but with a misleading error message.Additionally, client errors (such as trying to call
single()
on a result with multiple result records) have always caused the driver to die in spite ofdie_on_error = 0
.Such inconsistent behaviour makes bugs harder to find and has no clear advantages. It is not present in the official drivers.
To suppress errors, wrap your calls in
try
/catch
blocks:use Feature::Compat::Try; my $result; try { $result = $session->run('MATCH (n:Test) RETURN m'); $result->has_next; # Wait for statement execution } catch ($e) { warn "Got a Neo4j error: $e" }
Type system customisation
Deprecated in version 0.25 and to be removed in 1.00. Originally added in 0.14 as an experimental feature.
$driver->config(cypher_types => { node => 'Local::Node', relationship => 'Local::Relationship', path => 'Local::Path', point => 'Local::Point', temporal => 'Local::Temporal', init => sub { my $object = shift; ... }, });
The package names used for
bless
ing objects in query results can be modified. This allows clients to add their own methods to such objects.Clients must make sure their custom type packages are subtypes of the base type packages that this module provides (e. g. with parent):
Clients may only use the documented API to access the data in the base type. As an exception, clients may store private data by calling the
_private()
method, which returns a hashref. Within that hashref, clients may make free use of any hash keys that begin with two underscores (__
). All other hash keys are reserved for use by Neo4j::Driver.The implementation of the custom type packages continues to be defined by the driver. In particular, it is the driver's choice what kind of reference to bless – hash, array, or scalar. This severely limits the freedom of the custom type packages.
Instead of the
cypher_types
option, users should consider a custom networking module that provides a custom result handler. This approach offers even more flexibility (albeit at the cost of some degree of convenience). See "Custom result handlers" in Neo4j::Driver::Net for details.Neo4j::Driver::Net::HTTP::LWP
agent
Deprecated in version 0.30 and currently planned to be removed in 1.00. Originally added in 0.21 as an experimental feature.
use parent 'Neo4j::Driver::Net::HTTP::LWP'; sub foo { my ($self) = @_; my $lwp_ua = $self->agent; ... }
Returns the LWP::UserAgent instance in use. Meant to facilitate subclassing. In version 0.30, this method was renamed
ua()
because LWP itself usesagent
for the User-Agent identification string and this was deemed a possible source of confusion.protocol
Deprecated in version 0.30 and currently planned to be removed in 1.00. Originally added in 0.21 as an experimental feature.
use parent 'Neo4j::Driver::Net::HTTP::LWP'; sub foo { my ($self) = @_; my $http_version = $self->protocol; ... }
Returns the HTTP version of the last response (typically
"HTTP/1.1"
). Since version 0.26, this method was no longer required for a net module and using it was discouraged.Neo4j::Driver::Record
Cypher type system
Direct access deprecated in version 0.13 and currently planned to be removed in 1.00. Originally added in 0.01.
$result = $session->run('MATCH (n:Person) RETURN (n)'); foreach my $node ( map { $_->get } $result->list ) { my $properties = $node; say $properties->{birthday}; }
Early versions of this driver returned nodes and relationships as unblessed hash references of their properties. Neo4j paths were returned as unblessed array references. This was a bug because this driver's goal always was to implement the Neo4j Driver API, which doesn't work this way. This bug made it impossible to distinguish between structural types and simple maps / lists. It also made it difficult to access metadata. See GitHub issues #2 and #8.
Proper blessed types for nodes, relationships and paths were added in version 0.13, and directly accessing their elements and properties using
->[]
or->{}
was deprecated at the same time. A deprecation warning was added in version 0.18. The current plan is to remove direct access in version 1.00.To obtain a hash reference of all properties of a node or relationship, use the
properties()
method:$result = $session->run('MATCH (n) RETURN (n)'); foreach my $node ( map { $_->get } $result->list ) { my $properties = $node->properties; say $properties->{birthday}; }
To obtain all nodes and relationships in a path as an alternating array, use the
elements()
method:$result = $session->run('MATCH p=(:Person)-[]->() RETURN (p)'); foreach my $path ( map { $_->get } $result->list ) { my $array = [ $path->elements ]; ... }
get_bool()
Deprecated in version 0.07 and to be removed in 1.00. Originally added in 0.02 as an experimental feature.
$bool = $session->run('RETURN false')->single->get_bool; $ref = ref $bool; # '' $undef = ! defined $bool; # 1
Get a boolean value from this record. Behaves exactly like
get()
, except that non-truthy boolean values are returned asundef
.In Perl, which doesn't have a native boolean type, JSON booleans are represented as a blessed scalar that uses overload to evaluate truthy or non-truthy as appropriate in Perl expressions. This almost always works perfectly fine. However, some conditions may not expect a non-truthy value to be blessed, which can result in wrong interpretation of query results. The
get_bool()
method was meant to ensure boolean results would evaluate correctly in such cases.If you do need an unblessed Perl scalar to express a boolean value, simply use
!!
to force evaluation in a boolean context.$val = $session->run('RETURN false')->single->get; $ref = ref $val; # 'JSON::PP::Boolean' $bool = !! $val;
Raw meta data access
Deprecated in version 0.18 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
$meta = $record->{meta};
Allows accessing the entity meta data that some versions of the Neo4j server provide. This meta data is not available reliably due to a known bug in the Neo4j server (#12306). If it is available, it can since version 0.13 be accessed via object methods. This raw access shouldn't be needed anymore and should no longer be relied upon.
stats()
Deprecated in version 0.07 and to be removed in 1.00. Originally added in 0.02 as an experimental feature.
Shortcut for "stats()" in Neo4j::Driver::Result (only for records obtained via "single" in Neo4j::Driver::Result).
Virtual columns
Deprecated in version 0.18 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
$size = $record->{column_keys}->count; $record->{column_keys}->add('new_field_key');
Access to the internal
{column_keys}
data structure allows adding new 'virtual' columns to the record's field key / index resolution used by theget()
method. The virtual columns can then be accessed just like regular columns.Rather than manipulating the driver's Neo4j statement result, users should make an in-memory copy of the results in a data structure under their own control.
Neo4j::Driver::Result
Control result stream attachment
Deprecated in version 0.30 and to be removed in 1.00. Originally added in 0.13 as an experimental feature.
$buffered = $result->attached; # boolean $count = $result->detach; # number of records fetched
detach()
forces the entire result stream to be buffered locally, so that it is available tofetch()
indefinitely, irrespective of other statements run on the same session. Essentially, the outcome is the same as callinglist()
, except thatfetch()
can continue to be used because the result is not exhausted.The utility of these methods could never be demonstrated. Clients are more likely to call
list()
instead. (To begin statement execution, callinghas_next()
is a potentially cheaper alternative.) Only one of the official Neo4j drivers has ever offered these methods, and even that one no longer does so in its latest version.stats()
Deprecated in version 0.07 and to be removed in 1.00. Originally added in 0.02 as an experimental feature.
$tx = $session->begin_transaction; $tx->{return_stats} = 1; $stats = $tx->run('...')->stats;
Return a hash ref. The hash ref contains query statistics if these were requested in advance. The hash ref may or may not be blessed.
In the Neo4j Driver API, query statistics are available from the Neo4j::Driver::ResultSummary instead, which is obtained using
summary()
.$stats = $session->run('...')->summary->counters;
Neo4j::Driver::ServerInfo
Protocol string
Deprecated in version 0.26 and to be removed in 1.00. Originally added in 0.19 as an experimental feature.
$protocol_string = $session->server->protocol;
Returns the protocol name and version number announced by the server. Similar to an agent string, this value is formed by the protocol name followed by a slash and the version number, usually two digits separated by a dot (for example:
Bolt/1.0
orHTTP/1.1
). If the protocol version is unknown, just the name is returned.Since Neo4j 4.3, the driver API has an official method for this purpose, "protocol_version" in Neo4j::Driver::ServerInfo. Therefore the experimental
protocol()
method is expendable. In the future, the behaviour of the deprecatedprotocol()
method can be approximated as follows:$protocol_string = $_ ? "Bolt/$_" : defined ? "Bolt" : "HTTP/1.1" for $session->server->protocol_version;
Neo4j::Driver::Session
Call run() in list context
Deprecated in version 0.26 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
@records = $session->run('...');
See Neo4j::Driver::Transaction below for details.
close()
Deprecated in version 0.14 and to be removed in 1.00. Originally added in 0.02 as an experimental feature.
$session->close; # no-op
All resources opened by the Perl driver are closed automatically once they are no longer required. Explicit calls to
close()
are neither required nor useful.Neo4j::Driver::StatementResult
Deprecated in version 0.19 and to be removed in 1.00. Originally added in 0.01.
$result = $session->run('...'); warn 'Unexpected type' unless $result->isa('Neo4j::Driver::StatementResult');
With version 4 of the official Neo4j drivers,
StatementResult
was renamedResult
.This driver deprecated any use of the Neo4j::Driver::StatementResult module name in version 0.19. Use Neo4j::Driver::Result instead.
Neo4j::Driver::Transaction
Call run() in list context
Deprecated in version 0.26 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
@records = $transaction->run('...');
The
run
method tries to Do What You Mean if called in list context. However, this may result in unexpected behaviour. For example, consider this code:$people = { jane => $tx->run('MATCH (n) WHERE n.name = "Jane" RETURN n'), john => $tx->run('MATCH (n) WHERE n.name = "John" RETURN n'), };
You might expect the result to be a hash with two Neo4j nodes as entry values. However, if no nodes match these queries, the list context will make
run()
return empty lists and you might end up with the hash{jane => 'john'}
instead. If one node matches and the other doesn't, the code may die.To avoid this issue, you can wrap every call to
run()
inscalar()
. This will always get you a Neo4j::Driver::Result. In the next major version of the driver, wrapping the call inscalar()
will no longer be necessary, because a Neo4j::Driver::Result will be returned in every context.To obtain a list of Neo4j::Driver::Record instances, simply use
list()
in list context:@records = $tx->run('...')->list;
Call run() with an array of multiple statements
Deprecated in version 0.25 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
$statements = [ [ 'RETURN 42' ], [ 'RETURN {value}', value => 'forty-two' ], ]; $results = $transaction->run($statements); foreach $result ( @$results ) { say $result->single->get; } # Call in list context (also deprecated): @results = $transaction->run($statements);
The Neo4j HTTP API supports executing multiple statements within a single HTTP request. This driver exposes this feature to the client by allowing a multi-dimensional array to be passed to
run()
. Unfortunately, the resulting API is confusing to use and implement and is therefore bug-prone.If you need this feature, you should consider using the private
_run_multiple()
method instead; see "Execute multiple statements at once" in Neo4j::Driver::Transaction.Disable obtaining query statistics
Deprecated in version 0.28 and now an internal API. Originally added in 0.02 / 0.13 as an experimental feature.
$transaction = $session->begin_transaction; $transaction->{return_stats} = 0; $result = $transaction->run('...');
The experimental
{return_stats}
feature for requesting query statistics from the Neo4j server was first added to the driver in version 0.02. Starting with version 0.13, stats are enabled by default. When using HTTP, this feature allowed disabling them. Doing so might provide a very minor performance increase.As of version 0.28, allowing stats to be disabled is considered to be a failed experiment. The performance impact is too minor to matter; on the other hand, the advantages of a common API between Bolt and HTTP connections are very clear. The driver currently uses
{return_stats} = 0
internally, so this feature will likely not be removed soon, but going forward, it will be treated as an internal API. There will be no deprecation warning. See "USE OF INTERNAL APIS" in Neo4j::Driver::Plugin.To disable query stats in future, use a plug-in to modify
includeStats
in the server request.Return results in graph format
Deprecated in version 0.28 and to be removed in 1.00. Originally added in 0.01 as an experimental feature.
$session = $driver->config( jolt => 0 )->session; $transaction = $session->begin_transaction; $transaction->{return_graph} = 1; $records = $transaction->run('...')->list; for $record ( @$records ) { $graph_data = $record->{graph}; ... }
The Neo4j HTTP JSON API supports a "graph" results data format. This feature is only available when Jolt is disabled, which is not recommended.
To request graph format in future, use a plug-in to disable Jolt and modify the
resultDataContents
in the server request. Note that$record->{graph}
is an internal API that may or may not be available in future versions. See "USE OF INTERNAL APIS" in Neo4j::Driver::Plugin.If there is demand for the graph format, equivalent functionality might be added to a future version of the driver itself. This would then also be available for Bolt and Jolt connections.
Neo4j::Driver::Type::Node, Neo4j::Driver::Type::Relationship
Deletion indicator
Deprecated in version 0.26 and to be removed in 1.00. Originally added in 0.13 as an experimental feature.
$node_definitely_deleted = $node->deleted; $node_definitely_exists = ! $node->deleted && defined $node->deleted; $node_status_unknown = ! defined $node->deleted; $reln_definitely_deleted = $relationship->deleted; ...
In some circumstances, Cypher statements using
DELETE
may stillRETURN
nodes or relationships that were deleted. To help avoid confusion in such cases, the server sometimes reports whether or not a node was deleted. If the deletion status of a node or relationship is unknown,undef
will be returned by this method.However, that information is not reliably available. In particular, it is only reported for HTTP connections using JSON responses (not for Bolt or Jolt). Additionally, some Neo4j server versions may not report it at all, and if reported, it may be affected by a known bug in the Neo4j server (#12306). Finally, the deletion indicator doesn't reflect whether or not a transaction was successful or rolled back.
Given the low availability and reliability of this indicator, consistency suggests to remove the
deleted()
method entirely. To obtain this indicator in the future, use a plug-in to disable Jolt, then try to access the result's raw meta data. For caveats, see "USE OF INTERNAL APIS" in Neo4j::Driver::Plugin.Neo4j::Driver::Type::Path
path()
Deprecated in version 0.18 and to be removed in 1.00. Originally added in 0.13 as an experimental feature.
$array = $path->path; $start_node = $array->[0];
Return the path as an array reference, alternating between nodes and relationships in path sequence order.
The word
path()
is singular, implying the return of a reference. The alternative methodsnodes()
andrelationships()
are plural, implying the return of a list. This was inconsistent. Additionally, thepath()
method led to awkward expressions such as$path->path
, which are needlessly difficult to comprehend.Use
elements()
instead.$array = [ $path->elements ];
AUTHOR
Arne Johannessen <ajnn@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2016-2022 by Arne Johannessen.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
Module Install Instructions
To install Neo4j::Driver, copy and paste the appropriate command in to your terminal.
cpanm Neo4j::Driver
perl -MCPAN -e shell install Neo4j::Driver
For more information on module installation, please visit the detailed CPAN module installation guide.