falkordb-ts

falkordb is a FalkorDB client for Node.js.

Upgrading from v6? Version 7 has breaking changes; see the migration guide.

Installation

Start a falkordb via docker:

docker run -p 6379:6379 -it falkordb/falkordb:latest

To install node falkordb, simply:

npm install falkordb

Usage

Basic Example

import { FalkorDB } from 'falkordb';

const db = await FalkorDB.connect({
    host: 'localhost',
    port: 6379,
    username: 'myUsername',
    password: 'myPassword'
})

console.log('Connected to FalkorDB')

const graph = db.selectGraph('myGraph')

await graph.query(`CREATE (:Rider {name:'Valentino Rossi'})-[:rides]->(:Team {name:'Yamaha'}),
        (:Rider {name:'Dani Pedrosa'})-[:rides]->(:Team {name:'Honda'}),
        (:Rider {name:'Andrea Dovizioso'})-[:rides]->(:Team {name:'Ducati'})`)

const result = await graph.query(`MATCH (r:Rider)-[:rides]->(t:Team) 
                            WHERE t.name = $name RETURN r.name`, 
                            {params: {name: 'Yamaha'}})
                            
console.log(result.data)    // [{ 'r.name': 'Valentino Rossi' }]
console.log(result.headers) // ['r.name']
console.log(result.stats)   // { nodesCreated: 0, ..., cachedExecution: false, queryInternalExecutionTime: 0.31 }

console.log(await db.list())
console.log(await db.info())

db.close()

To learn more about Cypher query language check: https://docs.falkordb.com/cypher/

Query Parameters

Parameter values can be a string, a finite number, a bigint, a boolean, null, an array, a typed array (e.g. a Float32Array vector, sent as a list) or a plain object (sent as a map). Names that are not plain identifiers, such as my-key or @type, work too: quote them in the query, e.g. $`my-key`. An empty name, or one containing the ` character, throws a TypeError, since FalkorDB cannot represent it.

await graph.query('RETURN $`my-key`, $vec', {params: {'my-key': 1, vec: new Float32Array([0.1, 0.2])}})

A plain object is an object literal or one made with Object.create(null). Any other object, such as a class instance, Date, Map or Set, throws a TypeError, as do undefined and NaN; convert such values first:

await graph.query('CREATE (:User $props)', {params: {props: {...user, createdAt: user.createdAt.toISOString()}}})

A bigint is sent exactly. Integers in query results are returned as a number by default, so values beyond Number.MAX_SAFE_INTEGER come back rounded; see Large Integers to read them exactly.

Large Integers

To read every integer in query results exactly, connect with integers: 'bigint'. Integer values then come back as a bigint, including small ones; node and edge ids stay a number.

const db = await FalkorDB.connect({ socket: { host: 'localhost', port: 6379 }, integers: 'bigint' })
const { data } = await db.selectGraph('g').query('RETURN 9007199254740993 AS n')
console.log(data) // [{ n: 9007199254740993n }]

JSON.stringify throws on a bigint, so convert such values before serializing them.

Query Replies

graph.query, graph.roQuery and the index helpers (such as graph.createNodeRangeIndex) resolve to { headers?, data?, stats }: headers and data are present when the query returns columns, and stats always holds the server's statistics as numbers (a counter the server did not report is 0).

const { stats } = await graph.query(`CREATE (:Rider {name:'Jorge Lorenzo'})`)

console.log(stats.nodesCreated)               // 1
console.log(stats.queryInternalExecutionTime) // milliseconds, e.g. 0.42
console.log(stats.cachedExecution)            // false

Version 7 removed the raw metadata lines (such as "Nodes created: 1") from these replies; read the matching stats field instead.

Connection Options

host and port are the shorthand for a plain TCP connection and default to localhost:6379. You can also pass a connection URL:

const db = await FalkorDB.connect({ url: 'falkor://localhost:6379' })

For anything beyond host and port — TLS, connection timeouts, keep-alive — use socket, which is passed to the underlying node-redis client:

const db = await FalkorDB.connect({
    socket: {
        host: 'localhost',
        port: 6379,
        tls: true,
        connectTimeout: 5000
    }
})

url sets the connection address, so it overrides the top-level host and port. Other socket settings such as TLS and timeouts still apply alongside it. When both are given, socket.host and socket.port take precedence over the top-level host and port.

.stubs()

Lists the graphs that are currently offloaded to disk ("stubs"). db.list() already includes offloaded graphs, so stubs() is how you tell which of the listed graphs are not loaded in memory.

GRAPH.STUBS is provided by the FalkorDB Enterprise graph-offloading module, so on deployments without that module the call rejects with an "unknown command" error — treat that as "offloading is not supported here".

On a cluster the replies of all master nodes are combined. If only some masters fail, the partial result is returned and the failures are logged; the call rejects only when every master fails.

const offloaded = await db.stubs();

.close()

Forcibly close a client's connection to FalkorDB immediately. Calling close will not send further pending commands to the Redis server, or wait for or parse outstanding responses.

await client.close();

Contributing

For information on how to release a new version to npm, see RELEASE.md.

License

This repository is licensed under the "MIT" license. See LICENSE.