Skip to main content
View source

RocketRide Graph

View as Markdown

A RocketRide graph database node for natural-language Cypher queries against the Apache AGE graph in the signed-in tenant's managed database. Pick it over rocketride_sql when relationships and traversals are the data model.

What it does​

The node accepts questions, asks its required LLM to generate read-only Cypher, translates it to Apache AGE SQL, and returns rows as a table, text, or answer. It also exposes graph discovery and query functions to an agent. Use it for graph labels, relationships, and multi-hop traversal; use rocketride_sql for relational SQL or rocketride_vector for embedding-backed document retrieval.

Connections​

ConnectionRequiredDescription
llmyesProduces Cypher from a natural-language question.

Lanes​

Lane inLane outDescription
questionstableReturns an executed graph-query result as a Markdown table.
questionstextReturns the graph-query result as text.
questionsanswersReturns the graph-query result on the answers lane.

As a tool​

The inherited graph functions are registered under the bare names below; this node defines no configurable server-name prefix. Inputs are JSON objects.

FunctionDescription
get_dataConverts required natural-language question to a safe read-only Cypher query and returns rows; limit is optional.
get_schemaReturns the discovered labels, sampled node properties, and relationships.
get_queryConverts required natural-language question to read-only Cypher without executing it; limit is optional.
executeRuns required raw Cypher query when direct execution is enabled; optional params binds $name values (for example {"rows": [...]} for UNWIND $rows), which need no escaping and do not count toward the 10,000-character query limit (params JSON is capped at 8 MiB). The statement may also be sent as sql, the key client.database.query uses; session_id and row_mode 'array' are refused, because graph nodes have no transactions and return row objects. If the result has more rows than the execute row limit, the call fails and nothing is saved. Remove repeated keys first, on both AGE versions: on 1.5.0, UNWIND $rows ... MERGE creates duplicates when rows repeat a key; on 1.6.0, rows that repeat a key keep only one write.
dialectReturns {"dialect": "age"}.

get_data defaults to the shared read limit, then clamps the requested limit to the configured Max read rows ceiling. A successful result contains {valid, rows, query, row_limit, truncated}. Generation, validation, or execution failure returns {valid: false, error, query, rows: []}; a non-graph question may instead carry an LLM answer with valid: false.

get_query returns {query, valid: true} only after its safe-query checks. execute bypasses the read-only gate but still passes Cypher through the AGE translation and resource limits; it raises if direct execution is disabled or the input is invalid, and otherwise returns {rows, affected_rows}.

The translator also guards AGE gaps that would otherwise return wrong data without an error, with rules for the AGE version the database reports (1.5.0 or 1.6.0; any other version gets the 1.5.0 rules). An empty-list test such as x IN [] is rewritten to false, its standard Cypher value.

After a MERGE, SET, REMOVE and DELETE are checked. AGE 1.5.0 applies them only to the first node or edge a MERGE creates in a statement, so they are rejected unless they change a variable bound before that MERGE, or the node of a single-node MERGE that starts the query; for a bulk upsert, run the MERGE, then the SET as a separate execute call, for example UNWIND $rows AS row MATCH (n:Item {id: row.id}) SET n.name = row.name. AGE 1.6.0 applies them to every entity a MERGE creates, so the one-call form UNWIND $rows AS row MERGE (n:Item {id: row.id}) SET n.name = row.name works. It is still rejected when one MERGE-created entity would be written from several rows, for example a node with a fixed key such as {name: 'acme'} that every row reaches, because AGE keeps only one of those writes.

On both versions, keep keys unique within one call: when two rows reach the same node or edge, AGE keeps only one of their writes. Properties written inside the MERGE pattern are stored, but MERGE matches on them: with different values it creates a second node or edge.

Configuration​

The single built-in profile supplies the default graph name. RocketRide provisions a per-tenant database for its managed database nodes, and this node resolves it from the signed-in RocketRide identity instead of a host, user, password, or database name you enter. Start with the defaults, then tune the graph context and read limits around the size and shape of the graph your LLM must query.

Graph name and graph description​

Graph name defaults to rocketride and must name an existing AGE graph; startup fails instead of creating a missing graph. Graph description is empty by default and becomes LLM context, so describe labels, relationship meaning, and domain vocabulary when those are not obvious from reflected schema. Change the graph name when the tenant database contains multiple AGE graphs; update the description with it so generated Cypher targets the right model.

Validation attempts and read rows​

The node retries failed Cypher validation up to five times by default. Raise Max validation attempts for a complex schema where the returned validation error is likely to let the LLM repair its query, or lower it to fail faster. Max read rows defaults to 1,000 and is an owner-controlled cap for both the questions lane and get_data; increase it only when agents truly need larger result sets, since results beyond the cap are intentionally truncated.

Query timeout​

Query timeout (ms) defaults to 30,000 and is applied inside each query's transaction. Reduce it to protect an interactive pipeline from expensive traversals; increase it only for known queries that legitimately need more time. It works with the row cap: one limits execution time and the other limits returned data.

Allow direct query execution​

This setting is off by default. Turning it on permits raw Cypher through the execute tool and QuestionType.EXECUTE; those calls skip LLM translation and the safe read-only gate. They still use the AGE translator and its resource controls. Enable it only for trusted callers that require writes or raw Cypher.

Database​

Database picks which RocketRide cloud database the node uses. It defaults to Organization, so existing pipelines keep using the database they already had.

  • Organization: the database shared by everyone in the organization the pipeline runs in. Data from before this choice existed lives here.
  • Team: the database of the run's team. A run from the builder uses your current dev team and needs run rights (task.control) on it; a deployed pipeline uses the team it is billed to.
  • Personal: your own database in this organization. It works only when you are the person running the pipeline: builder runs, store apps you run, and pipelines you deploy for yourself (@me). A pipeline deployed for a team has no person behind it, so it fails at start with an error that says so. Organization admins can reach members' personal databases, and that access is logged.

Each choice is a separate database. Switching does not move or copy data, and a database you have not used yet is created empty on the first run that needs it. Every database, new ones included, comes with a graph named rocketride, so the default Graph name works in each.

A pipeline exposed through a public link (a chat, dropper, webhook, Discord or Telegram source) runs as you, so visitors' requests use your team or personal database, not their own.

Access is checked when the run starts. If the run may not use the chosen database, it does not start, and the error says which database and why. A self-hosted engine supports only Organization; Team and Personal fail at start because they need RocketRide cloud. Access is approved for the whole run, not each node: every node in a run can reach every database the run was approved for.

Limitations​

This node runs on the RocketRide engine host and does not support remote execution. The engine host must have access to the signed-in RocketRide identity used to resolve the tenant DSN; on a server without a RocketRide cloud database (for example, a local or self-hosted engine with no database broker) the task fails at start with a message that says so; use a connection-configured node such as graph_neo4j or graph_falkordb there. On RocketRide Cloud, missing broker configuration is a server configuration error: contact the server operator to restore it and retry. The tenant database must already have Apache AGE installed and contain the configured graph. Read paths are intentionally read-only; raw execution remains disabled until explicitly enabled.

Notes​

Translation and schema discovery​

Apache AGE cannot execute bare Cypher. Every query path is translated, and the safe path runs in a server-side read-only transaction with a semantic firewall, the base Cypher safety check, and a transaction-local statement timeout. Schema reflection is best effort: it lists AGE labels, samples node properties, and samples relationship endpoints; an individual reflection failure warns and returns partial rather than blocking all schema output.

Schema​

FieldTypeDescriptionDefault
rocketridegraph.allow_executebooleanAllow direct query execution
Permit QuestionType.EXECUTE callers to run raw Cypher without LLM translation or read-only safety checks. Resource limits still apply. Leave OFF unless a trusted application explicitly needs to issue Cypher directly.
false
rocketridegraph.db_descriptionstringGraph description
What is this graph used for? Describe its content and purpose, this helps the LLM generate more accurate queries.
""
rocketridegraph.graphstringGraph name
Name of the AGE graph to query in your RocketRide cloud database
"rocketride"
rocketridegraph.max_attemptsintegerMax validation attempts
Maximum number of times to re-ask the LLM if validation rejects the generated Cypher
5
rocketridegraph.max_rowsintegerMax read rows
Row ceiling for read queries on the questions lane and get_data tool
1000
rocketridegraph.profilestring"default"
rocketridegraph.query_timeout_msintegerQuery timeout (ms)
Per-query statement timeout applied inside each query's transaction
30000
rocketridegraph.scopestringDatabase
Organization (default): shared by everyone in the organization. Team: the run's team (your current dev team, or the team a deploy is billed to). Personal: your own, for runs you start yourself. Each is a separate database: switching doesn't move data, and a new one starts empty.
"org"
rocketridegraph.targetstringTeam or user
Another team's or user's database (admins only). Leave empty to use your own team's or your own
""

Dependencies​

  • psycopg2-binary ==2.9.12