NAME

Neo4j::Driver::Transaction - Logical container for an atomic unit of work

VERSION

version 0.12

SYNOPSIS

 use Neo4j::Driver;
 my $session = Neo4j::Driver->new->basic_auth(...)->session;
 
 # Commit
 my $tx = $session->begin_transaction;
 my $node_id = $tx->run(
   'CREATE (p:Person) RETURN id(p)'
 )->single->get;
 $tx->run(
   'MATCH (p) WHERE id(p) = {id} SET p.name = {name}',
   {id => $node_id, name => 'Douglas'}
 );
 $tx->commit;
 
 # Rollback
 my $tx = $session->begin_transaction;
 my $tx->run('CREATE (a:Universal:Answer {value:42})');
 $tx->rollback;

DESCRIPTION

Logical container for an atomic unit of work that is either committed in its entirety or is rolled back on failure. A driver Transaction object corresponds to a server transaction.

This driver currently only supports blocking transactions that are executed non-lazily. In other words, each call to the run method immediately initiates an HTTP request to the Neo4j server that runs the given statement and waits for the result. The run method does not return until either the statement result has been fully received or an error is triggered.

Transactions are often wrapped in a try (or eval) block to ensure that commit and rollback occur correctly. Note that the server will automatically roll back the transaction if any database errors occur while executing statements.

 use Try::Tiny;
 try {
   $result = $tx->run($query, \%parameters);
   $tx->commit;
 }
 catch {
   say "Database error: $_";
   say "Transaction closed by server." if ! $tx->is_open;
 };

After commit or rollback, the transaction is automatically closed by the server and can no longer be used. The is_open method can be used to determine the server-side transaction status.

METHODS

Neo4j::Driver::Transaction implements the following methods.

commit

 $transaction->commit;

Commits the transaction and returns the result.

After committing the transaction is closed and can no longer be used.

is_open

 my $bool = $transaction->is_open;

Detect whether this transaction is still open, which means commit or rollback did not happen.

Note that this method does not request the transaction status from the Neo4j server. Instead, it uses the status information the server provided along with its previous response, which may be outdated. In particular, a transaction can timeout on the server due to inactivity, in which case it may in fact be closed even though this method returns a true value. The Neo4j server default dbms.transaction_timeout is 60 seconds.

rollback

 $transaction->rollback;

Rollbacks the transaction.

After rolling back the transaction is closed and can no longer be used.

run

 my $result = $transaction->run($query, %params);

Run a statement and return the StatementResult. This method takes an optional set of parameters that will be injected into the Cypher statement by Neo4j. Using parameters is highly encouraged: It helps avoid dangerous Cypher injection attacks and improves database performance as Neo4j can re-use query plans more often.

Parameters are given as Perl hashref. Alternatively, they may be given as a hash / balanced list.

 # all of these are semantically equal
 my $result = $transaction->run('...', {key => 'value'});
 my $result = $transaction->run('...',  key => 'value' );
 my %hash = (key => 'value');
 my $result = $transaction->run('...', \%hash);
 my $result = $transaction->run('...',  %hash);

The Neo4j values true, false and null may be given as \1, \0 and undef, respectively, as specified for the JSON module used by this class to encode the request sent to the Neo4j server. To force numeric values, an arithmetic operation should be carried out, such as adding zero (e. g. number => 0 + $value). String values may be forced by concatenating the empty string (string => '' . $value).

Running empty queries is supported. Such queries establish a connection with the Neo4j server, which returns a result with zero records. This feature may be used to reset the transaction timeout or test the connection to the server.

 my $result = $transaction->run;

Queries are usually strings, but may also be REST::Neo4p::Query or Neo4j::Cypher::Abstract objects. Such objects are automatically converted to strings before they are sent to the Neo4j server.

 $transaction->run( REST::Neo4p::Query->new('RETURN 42') );
 $transaction->run( Neo4j::Cypher::Abstract->new->return(42) );

EXPERIMENTAL FEATURES

Neo4j::Driver::Transaction implements the following experimental features. These are subject to unannounced modification or removal in future versions. Expect your code to break if you depend upon these features.

Calling in list context

 my @records = $transaction->run('...');
 my @results = $transaction->run([...]);

The run method tries to Do What You Mean if called in list context.

Execute multiple statements at once

 my $statements = [
   [ 'RETURN 42' ],
   [ 'RETURN {value}', value => 'forty-two' ],
 ];
 my $results = $transaction->run($statements);
 foreach my $result ( @$results ) {
   say $result->single->get;
 }

The Neo4j HTTP API supports executing multiple statements within a single HTTP request. This driver exposes this feature to the client.

This feature is likely to be removed from this driver in favour of lazy execution, similar to the official Neo4j drivers.

Obtain query statistics

 my $transaction = $session->begin_transaction;
 $transaction->{return_stats} = 1;
 my $result = $transaction->run('...');
 my $stats = $result->summary->counters;

The Neo4j server supports requesting query statistics. This driver exposes this feature to the client and will continue to do so, but the interface is not yet finalised.

Return results in graph format

 my $transaction = $session->begin_transaction;
 $transaction->{return_graph} = 1;
 my $records = $transaction->run('...')->list;
 for $record ( @$records ) {
   my $graph_data = $record->{graph};
   ...
 }

The Neo4j HTTP API supports a "graph" results data format. This driver exposes this feature to the client and will continue to do so, but the interface is not yet finalised.

SEE ALSO

Neo4j::Driver, Neo4j::Driver::StatementResult, Neo4j Java Driver, Neo4j JavaScript Driver, Neo4j .NET Driver, Neo4j Python Driver, Neo4j Transactional Cypher HTTP API

AUTHOR

Arne Johannessen <ajnn@cpan.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm Neo4j::Driver

perl -MCPAN -e shell
install Neo4j::Driver