Package org.neo4j.graphdb

Interface Result

All Superinterfaces:
AutoCloseable, Iterator<Map<String,Object>>, Resource, ResourceIterator<Map<String,Object>>
public interface Result extends ResourceIterator<Map<String,Object>>
Represents the result of executing a query.

The result is comprised of a number of rows, potentially computed lazily, with this result object being an iterator over those rows. Each row is represented as a Map<String, Object>, the keys in this map are the names of the columns in the row, as specified by the return clause of the query, and the values of the map is the corresponding computed value of the expression in the return clause. Each row will thus have the same set of keys, and these keys can be retrieved using the columns-method.

To ensure that any resource, including transactions bound to the query, are properly freed, the result must either be fully exhausted, by means of the iterator protocol, or the result has to be explicitly closed, by invoking the close-method.

Idiomatic use of the Result object would look like this: 


 try ( Result result = graphDatabase.execute( query, parameters ) )
 {
     while ( result.hasNext() )
     {
         Map<String, Object> row = result.next();
         for ( String key : result.columns() )
         {
             System.out.printf( "%s = %s%n", key, row.get( key ) );
         }
     }
 }
If the result consists of only a single column, or if only one of the columns is of interest, a projection can be extracted using columnAs(String). This produces a new iterator over the values of the named column. It should be noted that this iterator consumes the rows of the result in the same way as invoking next() on this object would, and that the close-method on either iterator has the same effect. It is thus safe to either close the projected column iterator, or this iterator, or both if all rows have not been consumed.

In addition to the iteration methods on this interface, close(), and the column projection method, there are two methods for getting a string representation of the result that also consumes the entire result if invoked. resultAsString() returns a single string representation of all (remaining) rows in the result, and writeAsStringTo(PrintWriter) does the same, but streams the result to the provided PrintWriter instead, without allocating large string objects.

The methods that do not consume any rows from the result, or in other ways alter the state of the result are safe to invoke at any time, even after the result has been closed or fully exhausted. These methods are:

Not all queries produce an actual result, and some queries that do might yield an empty result set. In order to distinguish between these cases the QueryExecutionType of this result can be queried.

  • Method Details

    • getQueryExecutionType

      QueryExecutionType getQueryExecutionType()
      Indicates what kind of query execution produced this result.
      Returns:
      an object that indicates what kind of query was executed to produce this result.

    • columns

      List<String> columns()
      The exact names used to represent each column in the result set.
      Returns:
      List of the column names.

    • columnAs

      <T> ResourceIterator<T> columnAs(String name)
      Returns an iterator with the result objects from a single column of the result set. This method is best used for single column results.

      To ensure that any resources, including transactions bound to it, are properly closed, the iterator must either be fully exhausted, or the close() method must be called.

      As an example, if we are only interested in a column n that contains node values, we can extract it like this: 

      
     try ( ResourceIterator<Node> nodes = result.columnAs( "n" ) )
     {
         while ( nodes.hasNext() )
         {
             Node node = nodes.next();
             // Do some work with the 'node' instance.
         }
     }
      Type Parameters:
      T - desired type cast for the result objects
      Parameters:
      name - exact name of the column, as it appeared in the original query
      Returns:
      an iterator of the result objects, possibly empty
      Throws:
      ClassCastException - when the result object can not be cast to the requested type
      NotFoundException - when the column name does not appear in the original query

    • hasNext

      boolean hasNext()
      Denotes there being more rows available in this result. These rows must either be consumed, by invoking next(), or the result has to be closed.
      Returns:
      true if there is more rows available in this result, false otherwise.

    • next

      Map<String,Object> next()
      Returns the next row in this result.
      Returns:
      the next row in this result.

    • close

      void close()
      Closes the result, freeing up any resources held by the result.

      This is an idempotent operation, invoking it multiple times has the same effect as invoking it exactly once. It is thus safe (and even encouraged, for style and simplicity) to invoke this method even after consuming all rows in the result through the next-method.

      Specified by:
      close in interface Resource
      Specified by:
      close in interface ResourceIterator<Map<String,Object>>

    • getQueryStatistics

      QueryStatistics getQueryStatistics()
      Statistics about the effects of the query.
      Returns:
      statistics about the effects of the query.

    • getExecutionPlanDescription

      ExecutionPlanDescription getExecutionPlanDescription()
      Returns a description of the query plan used to produce this result.

      Retrieving a description of the execution plan that was executed is always possible, regardless of whether the query requested a plan or not. For implementing a client with the ability to present the plan to the user, it is useful to be able to tell if the query requested a description of the plan or not. For these purposes the QueryExecutionType.requestedExecutionPlanDescription()-method is used.

      Being able to invoke this method, regardless of whether the user requested the plan or not is useful for purposes of debugging queries in applications.

      Returns:
      a description of the query plan used to produce this result.

    • resultAsString

      String resultAsString()
      Provides a textual representation of the query result.

      The execution result represented by this object will be consumed in its entirety after this method is called. Calling any of the other iterating methods on it should not be expected to return any results.

      Returns:
      the execution result formatted as a string

    • writeAsStringTo

      void writeAsStringTo(PrintWriter writer)
      Provides a textual representation of the query result to the provided PrintWriter.

      The execution result represented by this object will be consumed in its entirety after this method is called. Calling any of the other iterating methods on it should not be expected to return any results.

      Parameters:
      writer - the PrintWriter to receive the textual representation of the query result.

    • remove

      void remove()
      Removing rows from the result is not supported.

    • getNotifications

      Iterable<Notification> getNotifications()
      Provides notifications about the query producing this result.

      Notifications can be warnings about problematic queries or other valuable information that can be presented in a client.

      Returns:
      an iterable of all notifications created when running the query.

    • accept

      <VisitationException extends Exception> void accept(Result.ResultVisitor<VisitationException> visitor) throws VisitationException
      Visits all rows in this Result by iterating over them.

      This is an alternative to using the iterator form of Result. Using the visitor is better from a object creation perspective.

      Type Parameters:
      VisitationException - the type of the exception that might get thrown
      Parameters:
      visitor - the ResultVisitor instance that will see the results of the visit.
      Throws:
      VisitationException - if the visit(ResultRow) method of Result.ResultVisitor throws such an exception.