NAME

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

VERSION

version 0.14

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.

Statements may be run lazily. Most of the time, you will not notice this, because the driver automatically waits for statements to complete at specific points to fulfill its contracts. If you require execution of a statement to have completed, you need to use the result, for example by calling one of the methods fetch(), list() or summary().

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);

When used as parameters, Perl values are converted to Neo4j types as shown in the following example:

 my $parameters = {
   number =>  0 + $scalar,
   string => '' . $scalar,
   true   => \1,
   false  => \0,
   null   => undef,
   list   => [ ],
   map    => { },
 };

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 using unary coercions as shown in the example above.

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.

Disable obtaining query statistics

 my $transaction = $session->begin_transaction;
 $transaction->{return_stats} = 0;
 my $result = $transaction->run('...');

Since version 0.13, this driver requests query statistics from the Neo4j server by default. When using HTTP, this behaviour can be disabled. Doing so might provide a very minor performance increase.

The ability to disable the statistics may be removed in future.

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