NAME

Neo4j::Driver::StatementResult - Result of running a Cypher statement (a stream of records)

VERSION

version 0.14

SYNOPSIS

 use Neo4j::Driver;
 my $session = Neo4j::Driver->new->basic_auth(...)->session;
 
 # stream result records
 my $result = $session->run('MATCH (a:Actor) RETURN a.name, a.born');
 while ( my $record = $result->fetch ) {
   ...
 }
 
 # list result records
 my $result = $session->run('MATCH (m:Movie) RETURN m.name, m.year');
 my $record_count = $result->size;
 my @records = $result->list;
 
 # shortcut for results with a single record only
 my $query = 'MATCH (m:Movie) WHERE id(m) = {id} RETURN m.name';
 my $name = $session->run($query, id => 12)->single->get('m.name');

DESCRIPTION

The result of running a Cypher statement, conceptually a stream of records. The result stream can be navigated through using fetch() to consume records one at a time, or be consumed in its entirety using list() to get an array of all records.

Result streams typically are initially attached to the active session. As records are retrieved from the stream, they may be buffered locally in the driver. Once all data on the result stream has been retrieved from the server and buffered locally, the stream becomes detached.

Results received over HTTP always contain the complete list of records, which is kept buffered in the driver. HTTP result streams are thus immediately detached and valid indefinitely.

Result streams received on Bolt are valid until the next statement is run on the same session or (if the result was retrieved within an explicit transaction) until the transaction is closed, whichever comes first. When a result stream has become invalid before it was detached, calling any methods in this class may fail.

METHODS

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

fetch

 while (my $record = $result->fetch) {
   ...
 }

Navigate to and retrieve the next Record in this result.

When a record is fetched, that record is removed from the result stream. Once all records have been fetched, the result stream is exhausted and fetch() returns undef.

has_next

 while (my $record = $result->fetch) {
   print $record->get('field');
   print ', ' if $result->has_next;
 }

Whether the next call to fetch() will return a record.

Calling this method may change the internal stream buffer and detach the result, but will never exhaust it.

keys

 my @keys = $result->keys;

Retrieve the column names of the records this result contains.

list

 my @records = $result->list;
 my $records = $result->list;  # arrayref

Return the entire list of all Records that remain in the result stream. Calling this method exhausts the result stream.

The list is internally buffered by this class. Calling this method multiple times returns the buffered list.

This method returns an array reference if called in scalar context.

single

 my $name = $session->run('... LIMIT 1')->single->get('name');

Return the single Record left in the result stream, failing if there is not exactly one record left. Calling this method exhausts the result stream.

The returned record is internally buffered by this class. Calling this method multiple times returns the buffered record.

size

 my $record_count = $result->size;

Return the count of records that calling list() would yield.

Calling this method exhausts the result stream and buffers all records for use by list().

summary

 my $result_summary = $result->summary;

Return a Neo4j::Driver::ResultSummary object. Calling this method detaches the result stream, but does not exhaust it.

As a special case, Records returned by the single method also have a summary method that works the same way.

 my $record = $transaction->run('...')->single;
 my $result_summary = $record->summary;

EXPERIMENTAL FEATURES

Neo4j::Driver::StatementResult 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 scalar context

 my $keys = $result->keys;  # arrayref

The keys() method returns an array reference if called in scalar context.

Control result stream attachment

 my $buffered = $result->attached;  # boolean
 my $count = $result->detach;  # number of records fetched

If necessary, detach() can force the entire result stream to be buffered locally, so that it will be available to fetch() indefinitely, irrespective of other statements run on the same session. Essentially, the outcome is the same as calling list(), except that fetch() can continue to be used because the result is not exhausted.

Most of the official drivers do not offer these methods. Their usefulness is doubtful. They may be removed in future versions.

Discarding the result stream

 $result->consume;

Discarding the entire result may be useful as a cheap way to signal to the Bolt networking layer that any resources held by the result may be released. The actual result records are silently discarded without any effort to buffer the results. Calling this method exhausts the result stream.

As a side effect, discarding the result yields a summary of it.

 my $result_summary = $result->consume;

All of the official drivers offer this method, but it doesn't appear to be necessary here, since Neo4j::Bolt::ResultStream reliably calls neo4j_close_results() in its DESTROY() method. It may be removed in future versions.

Look ahead in the result stream

 say "Next record: ", $result->peek->get(...) if $result->has_next;

Using peek(), it is possible to retrieve the same record the next call to fetch() would retrieve without actually navigating to it. This may change the internal stream buffer and detach the result, but will never exhaust it.

SEE ALSO

Neo4j::Driver, Neo4j::Driver::Record, Neo4j::Driver::ResultSummary, Neo4j Java Driver, Neo4j Python Driver, Neo4j JavaScript Driver, Neo4j .NET Driver

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