ArangoDB

View as Markdown

A RocketRide database and tool node that answers natural-language questions against an ArangoDB multi-model database by translating them to read-only AQL with a connected LLM.

What it does

Connects to ArangoDB over HTTP using the official python-arango driver and plays two roles. As a pipeline node, it receives natural-language questions on the questions lane, asks the connected LLM to generate an AQL query, executes it against the database, and emits results downstream on table, text, and answers. As a tool node, it exposes get_data, get_schema, and get_aql directly to an agent. Because ArangoDB is multi-model, the same node serves document retrieval, graph traversal, and ArangoSearch — designed for document and graph-based RAG workflows.

The schema is reflected once at pipeline start and included in every LLM prompt so AQL is generated against the real structure: user collections (classified as document or edge) with sampled fields and indexed fields, named graphs with their edge definitions (from → edge → to), and ArangoSearch views.

The node is read-only by design. Every generated query is validated with ArangoDB's EXPLAIN, and the resulting execution plan is inspected for data-modification nodes (InsertNode, UpdateNode, ReplaceNode, RemoveNode, UpsertNode) — this plan-level check is the authoritative read-only gate. A coarse keyword scan (INSERT, UPDATE, REPLACE, REMOVE, UPSERT; string literals and comments stripped) runs as a defence-in-depth backstop at execution time; because a write keyword can also be a collection or attribute name, on a match it defers to the same EXPLAIN-plan check before refusing, so a legitimate read is never blocked. Queries are bounded by a runtime limit, a per-query memory limit, and a maximum result-row cap. The only escape hatch is the opt-in QuestionType.EXECUTE path, gated by allow_execute, which is off by default.

Connections

Connection	Required	Description
`llm`	yes (min 1)	LLM used to generate AQL from natural language

Configuration

Lanes

Lane in	Lanes out	Description
`questions`	`table`, `text`, `answers`	Translate question to AQL, execute, emit results on each connected lane

For a normal question, results are emitted as a Markdown table on table and answers, and as plain text on text. If the LLM judges the question unrelated to the database, its text reply is forwarded in place of a query result.

Two special question types are handled on the questions lane:

QuestionType.DIALECT: emits {"dialect": "arango"} on the answers lane so SDK callers can detect they are talking to ArangoDB.
QuestionType.EXECUTE: treats the question text as raw AQL and runs it without LLM translation or the read-only safety check. Requires allow_execute: true; otherwise the request is silently rejected with a warning. Results are capped at max_execute_rows (the query fails if exceeded), and when a write returns no rows the emitted JSON reports affected_rows derived from the cursor statistics.

Available tools

When connected to an agent, the node exposes three functions namespaced under the node's prefix (e.g. arango.get_data):

Tool	Description
`get_data`	Accepts a natural-language description of the data you want, converts it to a safe read-only AQL query, executes it against the ArangoDB database, and returns the result rows. Works across documents and graphs. No schema lookup or AQL knowledge required.
`get_schema`	Returns the multi-model schema: collections (document and edge) with sampled fields, indexed fields, named graphs with edge definitions, and ArangoSearch views. Optional `collection` argument filters to a single collection. Intended for recovery when `get_data` fails or returns unexpected results.
`get_aql`	Translates a natural-language question to a read-only AQL query without executing it. Returns `{aql, valid: true}` on success, an `error` key if the generated AQL is unsafe, or an `answer` text reply when the question is not a database query. Use only when the caller explicitly needs to see the AQL.

AQL generation and validation

Each generated query goes through a validate-and-retry loop:

The LLM is prompted with the question, the reflected multi-model schema, the optional database description, and strict instructions: only read operations (FOR, FILTER, SORT, LIMIT, LET, COLLECT, RETURN, and graph traversals) are permitted, and a LIMIT clause must bound the query.
The generated AQL is validated with EXPLAIN against the live database. EXPLAIN both verifies syntax and yields the execution plan, which is inspected for data-modification nodes — this is the authoritative read-only gate, so a write query is rejected while a read that merely references a field or collection named like a write keyword is accepted. Any syntax error or modification rejection is fed back to the LLM together with the failing query, and the LLM retries up to max_attempts times (default 5, range 1-20).

As defence-in-depth, a coarse keyword scan (_is_aql_safe) also runs at execution time inside _run_query; because a write keyword can double as a collection or attribute name, on a match it defers to the same EXPLAIN-plan check before refusing — so an unsafe statement is still blocked even if a caller bypasses the generation path, while a legitimate read is not. Reads are additionally bounded by a 30-second runtime limit, a 1 GiB per-query memory limit, and the max_execute_rows result cap.

ArangoDB returns JSON-native documents, so result rows are emitted as-is with no special serialisation.

Authentication

Username and password

Set auth_method: userpass (the default), then provide user and password. A blank username falls back to root.

Bearer / JWT token

Set auth_method: token and provide token. The node passes it as a python-arango user token. Use this for token-based setups such as ArangoGraph cloud.

Connectivity and authentication are verified at pipeline start (verify=True plus an explicit RETURN 1 probe of the configured database), so a wrong database name or missing permissions fail fast rather than mid-pipeline. Self-host, Docker, and ArangoGraph cloud (HTTPS/TLS) endpoints are all supported via the endpoint field.

Schema

Field	Type	Description	Default
`arangodb.allow_execute`	`boolean`	Allow direct query execution Permit QuestionType.EXECUTE callers to run raw AQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue AQL directly.	`false`
`arangodb.auth_method`	`string`	Authentication	`"userpass"`
`arangodb.database`	`string`	Database name Name of the ArangoDB database to query. '_system' is the built-in default — point this at your application database.	`"_system"`
`arangodb.db_description`	`string`	Database description What is this database used for? Describe its collections, graphs and domain — this helps the LLM generate more accurate AQL queries.	`""`
`arangodb.endpoint`	`string`	Connection endpoint HTTP(S) endpoint for the ArangoDB server. Use http://host:8529 for self-host/Docker, or https://.arangodb.cloud:8529 for ArangoGraph cloud (TLS).	`"http://localhost:8529"`
`arangodb.max_attempts`	`integer`	Max validation attempts Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated AQL query	`5`
`arangodb.max_execute_rows`	`integer`	Max result rows Maximum number of rows returned by a query. Also caps the raw EXECUTE path; a query that exceeds it fails rather than streaming unbounded results.	`25000`
`arangodb.password`	`string`	Password Password to authenticate with the ArangoDB instance.
`arangodb.profile`	`string`		`"default"`
`arangodb.token`	`string`	Bearer token JWT bearer token for token-based authentication (e.g. ArangoGraph cloud).
`arangodb.user`	`string`	User Username to authenticate with ArangoDB. Defaults to 'root'.	`"root"`

Dependencies

python-arango

What it does​

Connections​

Configuration​

Lanes​

Available tools​

AQL generation and validation​

Authentication​

Username and password​

Bearer / JWT token​

Schema​

Dependencies​