/ 
Neo4j-Driver-0.50
River stage one • 1 direct dependent • 2 total dependents
/ Neo4j::Driver::Result

NAME

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

VERSION

version 0.50

SYNOPSIS

$result = $session->run( ... );

# Stream result records
while ( $record = $result->fetch ) {
  ...
}

# List result records
@records = $result->list;
$records = $result->list;  # array ref
$record_count = $result->size;

# Shortcut for results with a single record only
$record = $result->single;

@field_keys = $result->keys;
$summary = $result->consume;

# For error checking, call any method on the result to ensure
# the statement has executed before leaving the try block
try {
  $result = $transaction->run( ... );
  $result->has_next;
}
catch ($e) { ... }

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.

Result streams 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.

Some result handlers may automatically detach a result stream immediately when the result is made available by the server. Such result streams are valid indefinitely. In driver version 0.xx, this happens for all HTTP results. This behaviour is subject to change in future versions and shouldn't be relied upon.

To obtain a query result, call "run" in Neo4j::Driver::Transaction.

Until version 0.18, this module was named StatementResult.

METHODS

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

consume

$summary = $result->consume;

Return the Neo4j::Driver::ResultSummary.

Calling this method fully exhausts the result and invalidates the result stream, discarding any remaining records. If you want to access records after retrieving the summary, you should use list() before consume() to buffer all records into memory.

fetch

while ($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 ($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

@keys = $result->keys;

Retrieve the column names (field keys) of the records this result contains. In scalar context, return the number of columns.

list

@records = $result->list;
$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.

peek

$record = $result->peek;

Obtain the next Record from this result without actually navigating to it and consuming it. The record is left in the internal stream buffer for further processing. If there is no next record, return undef.

single

$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

$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

$result_summary = $result->summary;

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

This method is discouraged. It may be deprecated and removed in a future version. Please use consume() instead.

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

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

SEE ALSO

AUTHOR

Arne Johannessen (AJNN)

COPYRIGHT AND LICENSE

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

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or (at your option) the same terms as the Perl 5 programming language system itself.