Consuming Results

Every time Cypher is executed, a BoltStatementResult is returned. This provides a handle to the result of the query, giving access to the records within it as well as the result metadata.

Each result consists of header metadata, zero or more Record objects and footer metadata (the summary). Results also contain a buffer that automatically stores unconsumed records when results are consumed out of order. A BoltStatementResult is attached to an active connection, through a Session, until all its content has been buffered or consumed.

class neo4j.BoltStatementResult
iter(result)
BoltStatementResult.session

The Session to which this result is attached, if any.

BoltStatementResult.attached()

Indicator for whether or not this result is still attached to an open Session.

BoltStatementResult.detach(sync=True)

Detach this result from its parent session by fetching the remainder of this result from the network into the buffer.

Returns:number of records fetched
BoltStatementResult.keys()

The keys for the records in this result.

Returns:tuple of key names
BoltStatementResult.records()

Generator for records obtained from this result.

Yields:iterable of Record objects
BoltStatementResult.summary()

Obtain the summary of this result, buffering any remaining records.

Returns:The ResultSummary for this result
BoltStatementResult.consume()

Consume the remainder of this result and return the summary.

Returns:The ResultSummary for this result
BoltStatementResult.single()

Obtain the next and only remaining record from this result.

A warning is generated if more than one record is available but the first of these is still returned.

Returns:the next Record or None if none remain
Warns:if more than one record is available
BoltStatementResult.peek()

Obtain the next record from this result without consuming it. This leaves the record in the buffer for further processing.

Returns:the next Record or None if none remain
BoltStatementResult.graph()

Return a Graph instance containing all the graph objects in the result. After calling this method, the result becomes detached, buffering all remaining records.

Returns:result graph
BoltStatementResult.value(item=0, default=None)

Return the remainder of the result as a list of values.

Parameters:
  • item – field to return for each remaining record
  • default – default value, used if the index of key is unavailable
Returns:

list of individual values

BoltStatementResult.values(*items)

Return the remainder of the result as a list of tuples.

Parameters:items – fields to return for each remaining record
Returns:list of value tuples
BoltStatementResult.data(*items)

Return the remainder of the result as a list of dictionaries.

Parameters:items – fields to return for each remaining record
Returns:list of dictionaries
class neo4j.Record

A Record is an immutable ordered collection of key-value pairs. It is generally closer to a namedtuple than to a OrderedDict inasmuch as iteration of the collection will yield values rather than keys.

Record(iterable)

Create a new record based on an dictionary-like iterable. This can be a dictionary itself, or may be a sequence of key-value pairs, each represented by a tuple.

record == other

Compare a record for equality with another value. The other value may be any Sequence or Mapping, or both. If comparing with a Sequence, the values are compared in order. If comparing with a Mapping, the values are compared based on their keys. If comparing with a value that exhibits both traits, both comparisons must be true for the values to be considered equal.

record != other

Compare a record for inequality with another value. See above for comparison rules.

hash(record)

Create a hash for this record. This will raise a TypeError if any values within the record are unhashable.

record[index]

Obtain a value from the record by index. This will raise an IndexError if the specified index is out of range.

record[i:j]

Derive a sub-record based on a start and end index. All keys and values within those bounds will be copied across in the same order as in the original record.

record[key]

Obtain a value from the record by key. This will raise a KeyError if the specified key does not exist.

Record.get(key, default=None)

Obtain a value from the record by key, returning a default value if the key does not exist.

Parameters:
  • key
  • default
Returns:

Record.value(key=0, default=None)

Obtain a single value from the record by index or key. If no index or key is specified, the first value is returned. If the specified item does not exist, the default value is returned.

Parameters:
  • key
  • default
Returns:

Record.index(key)

Return the index of the given item.

Parameters:key
Returns:
Record.keys()

Return the keys of the record.

Returns:list of key names
Record.values(*keys)

Return the values of the record, optionally filtering to include only certain values by index or key.

Parameters:keys – indexes or keys of the items to include; if none are provided, all values will be included
Returns:list of values
Record.items(*keys)

Return the fields of the record as a list of key and value tuples

Returns:
Record.data(*keys)

Return the keys and values of this record as a dictionary, optionally including only certain values by index or key. Keys provided in the items that are not in the record will be inserted with a value of None; indexes provided that are out of bounds will trigger an IndexError.

Parameters:keys – indexes or keys of the items to include; if none are provided, all values will be included
Returns:dictionary of values, keyed by field name
Raises:IndexError if an out-of-bounds index is specified

Summary Details

class neo4j.BoltStatementResultSummary(**metadata)

A summary of execution returned with a StatementResult object.

counters = None

A set of statistical information held in a Counters instance.

notifications = None

Notifications provide extra information for a user executing a statement. They can be warnings about problematic queries or other valuable information that can be presented in a client. Unlike failures or errors, notifications do not affect the execution of a statement.

parameters = None

Dictionary of parameters passed with the statement.

plan = None

A Plan instance

profile = None

A ProfiledPlan instance

protocol_version = None

The version of Bolt protocol over which this result was obtained.

result_available_after = None

The time it took for the server to have the result available.

result_consumed_after = None

The time it took for the server to consume the result.

server = None

The server on which this result was generated.

statement = None

The statement that was executed to produce this result.

statement_type = None

The type of statement ('r' = read-only, 'rw' = read/write).

class neo4j.SummaryCounters(statistics)

Set of statistics from a Cypher statement execution.

constraints_added = 0
constraints_removed = 0
indexes_added = 0
indexes_removed = 0
labels_added = 0
labels_removed = 0
nodes_created = 0
nodes_deleted = 0
properties_set = 0
relationships_created = 0
relationships_deleted = 0