# graph_arango

A RocketRide graph database node that translates questions into validated AQL for ArangoDB; choose it for an ArangoDB multi-model database rather than a Cypher graph service.

## About ArangoDB

ArangoDB is a database designed to work with document and graph data. It supports AQL for querying documents, edges, graphs, and search views through one database interface.

## What it does

The node reflects collections, named graphs, and ArangoSearch views, then uses its required LLM connection to build read-only AQL from a question. It can run in a pipeline or as an agent tool. Generated AQL is checked with `EXPLAIN`, which rejects plans containing data-modification nodes; choose it over `graph_falkordb` when the data is in ArangoDB and AQL is the target query language.

## Connections

| Connection | Required | Description |
|---|---|---|
| `llm` | yes | LLM used to craft AQL from a question. |

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `questions` | `table` | Emits a Markdown table result. |
| `questions` | `text` | Emits a text result. |
| `questions` | `answers` | Emits the answer result. |

## As a tool

The registered tool names are the bare method names `get_data`, `get_schema`, and `get_aql`; an agent catalog namespaces them by the pipeline component id, not by the services.json `prefix`.

| Function | Description |
|---|---|
| `get_data` | Requires a non-empty `question`; optional `limit` is clamped. Returns rows, executed AQL, and the applied row limit, or an `error` with empty rows. |
| `get_schema` | Accepts an optional `collection` filter and returns the database, collections, graphs, and views. An unknown collection returns `error`. |
| `get_aql` | Requires a non-empty `question`; returns a validated read-only AQL query and `valid: true`, or `error`/`answer` with `valid: false`. |

## Configuration

Configure the endpoint, database, credentials, and an accurate database description before using natural-language queries. The description and reflected schema are provided to the LLM, so improve it when generated AQL targets the wrong collections or relationships.

### Database description and validation attempts

`db_description` gives the LLM domain context. Start with a concise explanation of the collections and relationships, then add detail if retries produce invalid AQL. `max_attempts` defaults to five and controls re-generation after `EXPLAIN` rejects a query; raise it for a difficult schema only if the connected LLM needs more repair attempts.

### Result limits and direct execution

`max_execute_rows` caps raw `QuestionType.EXECUTE` results; a query above the cap fails rather than streaming unbounded rows. `allow_execute` is false by default. Enable it only for a trusted caller, because that path runs raw AQL without LLM translation or the normal read-only gate.

## Authentication

The default `userpass` method uses `user` and `password`; a blank user falls back to `root`. The `token` method passes the configured bearer/JWT token to the ArangoDB client. Startup verifies the configured database and performs a `RETURN 1` probe, so connection and permission failures surface before processing questions.

## Limitations

The node declares `noremote`, so it is intended for a deployment that can directly reach its ArangoDB endpoint. Normal natural-language and tool queries are read-only; direct execution is a separate trusted-caller option and must be explicitly enabled.

## Notes

### Pipeline question types

`QuestionType.DIALECT` emits `{"dialect": "arango"}` on `answers`. `QuestionType.EXECUTE` is rejected with a warning until `allow_execute` is enabled; when enabled, it may report `affected_rows` for writes that return no rows.

## Upstream docs

- [ArangoDB documentation](https://docs.arangodb.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `arangodb.allow_execute` | `boolean` | **Allow direct query execution**<br/>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**<br/>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**<br/>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**<br/>HTTP(S) endpoint for the ArangoDB server. Use http://host:8529 for self-host/Docker, or https://<id>.arangodb.cloud:8529 for ArangoGraph cloud (TLS). | `"http://localhost:8529"` |
| `arangodb.max_attempts` | `integer` | **Max validation attempts**<br/>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**<br/>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**<br/>Password to authenticate with the ArangoDB instance. |  |
| `arangodb.profile` | `string` |  | `"default"` |
| `arangodb.token` | `string` | **Bearer token**<br/>JWT bearer token for token-based authentication (e.g. ArangoGraph cloud). |  |
| `arangodb.user` | `string` | **User**<br/>Username to authenticate with ArangoDB. Defaults to 'root'. | `"root"` |

## Dependencies

- `python-arango`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/graph_arango)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->