# tool_falkordb A RocketRide tool node that exposes a FalkorDB graph database to an AI agent. > **Experimental.** This node is marked experimental and its surface may change. ## What it does Lets an agent query a [FalkorDB](https://www.falkordb.com) graph database with Cypher. The agent can run queries, list the graphs on the server, and inspect a graph's schema (labels, relationship types, and property keys) to discover the data model before querying. Queries are **read-only by default**: they run through `GRAPH.RO_QUERY`, so the FalkorDB server itself rejects any write clause (`CREATE`/`MERGE`/`SET`/`DELETE`), the restriction is enforced server-side, not by client-side parsing. Turn on **Allow Writes** to let the agent mutate the graph. Values always travel as Cypher parameters (`$name`), which FalkorDB treats strictly as data and never as query text. Node, edge, and path results are serialized to plain JSON-safe objects, and result sets are capped at **Max Rows** with a `truncated` flag so a broad query cannot flood the agent's context. --- ## Configuration | Field | Type | Description | |---|---|---| | `host` | string | Default `localhost`. FalkorDB host, e.g. `localhost` or `your-instance.falkordb.cloud`. | | `port` | integer | Default 6379 (1–65535). FalkorDB port (Redis protocol). | | `username` | string | Default empty. Username, e.g. `default` for FalkorDB Cloud. Leave empty for no auth. | | `password` | string | Default empty. Password for the FalkorDB instance. Leave empty for no auth. | | `tls` | boolean | Default false. Connect with TLS (for FalkorDB Cloud TLS endpoints). | | `graph` | string | Default `agent`. Graph queried when the agent does not pass one explicitly. | | `allow_writes` | boolean | Default false. Permit `CREATE`/`MERGE`/`SET`/`DELETE`. When off, queries run via `GRAPH.RO_QUERY` and the server rejects write clauses. | | `max_rows` | integer | Default 250 (1–25000). Upper cap on rows returned to the agent per query. | | `query_timeout_ms` | integer | Default 30000 (100–600000). Server-side timeout for a single query. | --- ## Available tools | Tool | Description | |---|---| | `query` | Run a Cypher query against a graph and return rows. | | `list_graphs` | List the graph names that exist on this FalkorDB instance. | | `get_schema` | Return a graph's node labels, relationship types, and property keys. | ### query | Parameter | Required | Description | |---|---|---| | `cypher` | yes | Cypher query. Reference values as `$name` placeholders, never inline data into the query string. | | `params` | no | Object of values for the `$name` placeholders (injection-safe). | | `graph` | no | Graph to query. Defaults to the graph configured on the node. | Returns `columns`, `rows` (nodes/edges serialized to objects, capped at `max_rows`), `row_count`, and `truncated`. When writes are enabled and a query mutates the graph, non-zero write counters are returned under `stats`. On failure it returns `error` with empty `rows`/`columns`, `row_count: 0`, and `truncated: false`. ### list_graphs No parameters. Returns `graphs` (or `error` on failure). ### get_schema | Parameter | Required | Description | |---|---|---| | `graph` | no | Graph to inspect. Defaults to the graph configured on the node. | Returns `labels`, `relationship_types`, and `property_keys` (or `error` on failure). Useful when a query returns unexpected results or the agent needs to discover the data model. --- ## Read-only by default With `allow_writes` off (the default), `query` runs every statement through `GRAPH.RO_QUERY`. FalkorDB rejects write clauses at the server, so the agent cannot create, merge, set, or delete no matter what Cypher it sends. Set `allow_writes: true` to switch `query` to the read/write `GRAPH.QUERY` path; write counters then surface under `stats`. `get_schema` always uses the read-only path. --- ## Local quickstart ```bash docker run -p 6379:6379 -it --rm falkordb/falkordb:latest ``` Point the node at `localhost:6379` and ask the agent to `MATCH` away, or to `CREATE` with **Allow Writes** turned on. --- ## Running the tests ```bash # Unit tests (mocked FalkorDB client — no server or network needed) pytest nodes/test/test_tool_falkordb.py -v ``` --- ## Schema | Field | Type | Description | Default | |---|---|---|---| | `tool_falkordb.allow_writes` | `boolean` | **Allow Writes**
Permit CREATE/MERGE/SET/DELETE. When off, queries run via GRAPH.RO_QUERY and the server rejects write clauses. | `false` | | `tool_falkordb.graph` | `string` | **Default Graph**
Graph queried when the agent does not pass one explicitly. | `"agent"` | | `tool_falkordb.host` | `string` | **Host**
FalkorDB host, e.g. localhost or your-instance.falkordb.cloud. | `"localhost"` | | `tool_falkordb.max_rows` | `integer` | **Max Rows**
Upper cap on rows returned to the agent per query. | `250` | | `tool_falkordb.password` | `string` | **Password**
Password for the FalkorDB instance. Leave empty for no auth. | `""` | | `tool_falkordb.port` | `integer` | **Port**
FalkorDB port (Redis protocol). | `6379` | | `tool_falkordb.query_timeout_ms` | `integer` | **Query Timeout (ms)**
Server-side timeout for a single query. | `30000` | | `tool_falkordb.tls` | `boolean` | **TLS**
Connect with TLS (FalkorDB Cloud TLS endpoints). | `false` | | `tool_falkordb.username` | `string` | **Username**
Username, e.g. "default" for FalkorDB Cloud. Leave empty for no auth. | `""` | ## Dependencies - `falkordb` `>=1.6,<2` - `redis` `>=7.1,<8` ## Source [ View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_falkordb)