Query Results
How to work with data returned from queries.
QueryResult structure#
Every db.query() and db.mutate() returns a result with:
interface QueryResult {
columns: string[] // Column names in result order
rows: TypedRow[] // Result rows with typed access
rowCount: number // Number of rows
computeMs: number // Execution time in milliseconds
gqlstatus(): string // ISO GQL status: "00000" = data, "02000" = no data
}Accessing values#
By column name (recommended)#
const result = db.query("MATCH (n:Person) RETURN n.name, n.age")
for (const row of result.rows) {
const name = row.get('name') // string
const age = row.get('age') // number (automatically typed)
console.log(name, age)
}Column names match the query's RETURN clause. For RETURN n.name, the column is n.name — but the SDK also indexes the short form name, so both work:
row.get('n.name') // works
row.get('name') // also works (short form)As a full object#
const obj = row.toObject()
// { 'n.name': 'Alice', 'n.age': 30, 'n.active': true }Iterate all rows#
const result = db.query("MATCH (n:Person) RETURN n.name, n.age")
const people = result.rows.map(row => row.toObject())
// [{ 'n.name': 'Alice', 'n.age': 30 }, { 'n.name': 'Bob', 'n.age': 35 }]Automatic type coercion#
The SDK automatically parses raw string values into their correct TypeScript types:
| Raw Value | TypeScript Type | Returned As |
|---|---|---|
'Alice' | string | 'Alice' |
'30' | number | 30 |
'3.14' | number | 3.14 |
'true' | boolean | true |
'false' | boolean | false |
'' or 'null' | null | null |
MutationResult#
db.mutate() returns a MutationResult which extends QueryResult with mutation statistics:
interface MutationResult extends QueryResult {
nodesCreated: number
nodesDeleted: number
relationshipsCreated: number
relationshipsDeleted: number
propertiesSet: number
}Checking empty results#
const result = db.query("MATCH (n:Missing) RETURN n")
if (result.rowCount === 0) {
console.log('No results found')
}ISO GQL status codes#
gqlstatus() returns the ISO/IEC 39075 GQL status for the result:
const result = db.query("MATCH (n:Person) WHERE n.age > 100 RETURN n.name")
result.gqlstatus() // "02000" — query succeeded, no matching rows
// vs.
const result2 = db.query("MATCH (n:Person) RETURN n.name")
result2.gqlstatus() // "00000" — rows were returned| Code | Meaning |
|---|---|
"00000" | Success with data — at least one row returned |
"02000" | No data — query executed correctly but matched nothing |
Timing#
const result = db.query("CALL algo.pageRank()")
console.log(`PageRank computed in ${result.computeMs.toFixed(1)}ms`)See Also#
- Parameters — always use
$paramsplaceholders for world model queries - TypeScript API Reference — full method signatures and return types
- Error Handling — what
db.query()throws and when
Try it
Open ↗⌘↵ to run
Loading engine…