Processing Results

The Promise API

The most common method of consuming results is with the Promise API.

When using session.run(), tx.run(), or one of the two transaction functions, the query will return a Promise.

Once the query has finished with all results results streamed to the Driver, the method resolves with a Result object.

try {
  const res = await session.executeRead(tx =>
    tx.run(
      'MATCH (p:Person) RETURN p.name AS name LIMIT 10'
    )
  )

  const names = res.records.map(row => {
    return row.get('name')
  })

  // `names` is an array of strings
  console.log(names)
}
catch (e) {
  // There was a problem with the
  // database connection or the query
  console.log(e)
}
finally {
  await session.close()
}

session.executeRead(tx => tx.run(
  'MATCH (p:Person) RETURN p.name AS name LIMIT 10')
)
  .then(res => {
    return res.records.map(row => {
      return row.get('name')
    })
  })
  .then(names => {
    // `names` is an array of strings
    console.log(names)
  })
  .catch(e => {
    // There was a problem with the
    // database connection or the query
    console.log(e)
  })
  // Finally, close the session
  .finally(() => session.close())

The Result

The Result object, defined as res in the examples above, contains the total number of records received by the Driver along with a set of additional meta data about the query.

An individual row of results is referred to as a record, and can be accessed by the res.records array. 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 as a result res.records will be an empty array.

The meta data included in the Result include statistics on how many nodes and relationships were created, updated, or deleted as a result of the query.

const names = res.records.map(row => {
  return row.get('name')
})

for (const record in res.records) {
  console.log(record.get('name'))
}

// Time in milliseconds before receiving the first result
console.log(res.summary.resultAvailableAfter) // 10

// Time in milliseconds once the final result was consumed
console.log(res.summary.resultConsumedAfter) // 30

console.log(res.summary.counters.updates())

/*
{
  nodesCreated: 10,
  nodesDeleted: 0,
  relationshipsCreated: 5,
  relationshipsDeleted: 0,
  propertiesSet: 20,
  labelsAdded: 10,
  labelsRemoved: 0,
  indexesAdded: 0,
  indexesRemoved: 0,
  constraintsAdded: 0,
  constraintsRemoved: 0
}
*/

The Streaming API

The drawback to the Promise API method of consuming results, is that the Promise will only resolve after all results have been received by the Driver.

There may be occasions where you have more complex, or slower-running queries in your application but wish to update a front-end application as results become available. For example, many Flight search websites have complex queries that take up to a minute to complete, but simple, more expensive flights may be available immediately.

In this case, you can use the subscribe() method to consume results as they become available. This method can be used when calling session.run() or tx.run() within a transaction function.

You can use this method with websockets, or a similar technology to update the front-end application with new results as they are made available.

The subscribe() method accepts one argument, an object of callbacks:

// Run a Cypher statement, reading the result in a streaming manner as records arrive:
session
  .run('MERGE (alice:Person {name : $nameParam}) RETURN alice.name AS name', {
    nameParam: 'Alice'
  })
  .subscribe({
    onKeys: keys => {
      console.log(keys) // ['name]
    },
    onNext: record => {
      console.log(record.get('name')) // 'Alice'
    },
    onCompleted: (summary) => {
      // `summary` holds the same information as `res.summary`

      // Close the Session
      session.close()
    },
    onError: error => {
      console.log(error)
    }
  })

const res = await rxSession
  .executeWrite(txc =>
    txc
      .run('MERGE (p:Person) RETURN p.name AS name LIMIT 10')
      .records()
      .pipe(
        map(record => record.get('name'))
      )
  )

Check Your Understanding