The Neo4j Java Driver provides you with three APIs for consuming results:
-
Synchronous API
-
Async API
-
Reactive API
The Three APIs
The most common and straightforward method of consuming results is with the synchronous API.
When using session.run(), tx.run(), or one of the two transaction functions, the query will return a Result object that you can process incrementally and then return the results of that processing.
For the asynchronous and reactive APIs you need to use different entry-points and API methods and helpers like a reactive framework. In return you get more efficient resource usage in the database, middleware and client by using the non-synchronous APIs.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/AsyncApi.java[tag=sync]Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/AsyncApi.java[tag=async]Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/AsyncApi.java[tag=reactive]The Result
The Result object, contains the records received by the Driver along with a set of additional meta data about the query execution and results.
An individual row of results is referred to as a Record, and can be accessed from the result various ways, as Iterator<Record> and via the stream(), the list() or single() methods.
A Record refers to the keyed set of values specified in the RETURN portion of the statement.
If no RETURN values are specified, the query will not return any results, and record results will be empty or throw an error in the case of single().
Additional meta data about the result and query is accessible from Result too (see below).
Records
You can access the records returned by the query through several means.
A Result is an Iterator<Record> there are stream() and list() accessors for streaming and materialization/conversion.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/Results.java[tag=records]Key or Index
You can either access a value within the record by using the alias as specified in theRETURN portion of the Cypher statement or by specifying the column index (not recommended).
The available keys can be accessed through res.keys().Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/Results.java[tag=record]Result Summary
The meta data ResultSummary accessed from Result.consume() include
-
statistics on how many nodes and relationships were created, updated, or deleted as a result of the query,
-
the query type
-
database and server info
-
query plan with and without profile
-
notifications
You can find more detail in the API docs for ResultSummary
For example, to get information about how long the query took to complete, you can use the following property:
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/Results.java[tag=summary]Another interesting part of the summary is the SummaryCounters available via counters(), which has update counts about a write-statement’s execution.
You can check via counters.containsUpdates() if there were any updates.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/app-python/main/src/main/java/example/Results.java[tag=summary:counters]Check Your Understanding
1. What is the drawback of using the synchronous API to consume results?
-
❏ The synchronous API is only available to Enterprise customers.
-
✓ Results are only available once the Driver has received the final record.
-
❏ You can only use the synchronous API within a Read Transactions.
Hint
If you are not subscribing to the record stream, you will only be able to access the first record once the entire stream has finished.
Solution
Results are only available once the Driver has received the final record. This can provide a negative experience for users waiting for the results of a long running query.
Lesson Summary
You now have all the information required to send Cypher queries to Neo4j and consume the results.
Next, we will look at the Cypher Type System and some of the considerations that you need to make when working with values coming from Neo4j in your Java application.