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 Detail

      • 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.
        Specified by:
        hasNext in interface Iterator<Map<String,Object>>
        Returns:
        true if there is more rows available in this result, false otherwise.
      • 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 AutoCloseable
        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.
      • 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 extends Exception
        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.
        VisitationException extends Exception

Copyright © 2002–2017 The Neo4j Graph Database Project. All rights reserved.