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

NAME

Neo4j::Driver::Deprecations - Explains features that have been deprecated, but not yet removed

VERSION

version 0.26

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

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.

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 custom net modules 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 is 1. Setting this to 0 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 of die_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 blessing 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::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 as undef.

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 the get() 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

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 or HTTP/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 deprecated protocol() 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 renamed Result.

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() in scalar(). This will always get you a Neo4j::Driver::Result. In the next major version of the driver, wrapping the call in scalar() 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.

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 still RETURN 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 custom net module to disable Jolt, then try to access the result's raw meta data. For caveats, see "USE OF INTERNAL APIS" in Neo4j::Driver::Net.

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 methods nodes() and relationships() are plural, implying the return of a list. This was inconsistent. Additionally, the path() method led to awkward expressions such as $path->path, which are needlessly difficult to comprehend.

This experimental feature was added in version 0.13 and deprecated in 0.18. It will be removed in 1.00.

Use elements() instead.

 $array = [ $path->elements ];

AUTHOR

Arne Johannessen <ajnn@cpan.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)