> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query the graph with SQL and Cypher

> Run SQL against your organization's relational data and Cypher against the production knowledge graph. Both commands support --json for scripting.

You can query two Tolmo data stores from the command line. `tolmo sql` reads your organization's relational data, such as findings. Row-level security limits each query to your organization. `tolmo cypher` traverses the [knowledge graph](https://docs.tolmo.com/knowledge-graph/overview.md). The graph contains your production resources and the relationships between them.

Use SQL for tabular questions and Cypher for "what connects to what". Both commands support `--json`. Use the global `--org` flag with either command to select an organization.

## SQL queries

`tolmo sql` runs a query against your organization's relational database and prints a table by default.

```bash theme={null}
# Return a scalar value to verify connectivity
tolmo sql "SELECT 1"

# Machine-readable output for scripting
tolmo sql --json "SELECT 1"
```

Pass `--json` to get raw JSON, for example to pipe into `jq`.

### Query findings at a past time

```bash theme={null}
tolmo sql --as-of 2026-09-01 "SELECT id, title, severity, status FROM findings LIMIT 20"
```

`--as-of` accepts a date or timestamp. Values without a timezone use UTC. It reconstructs findings at that instant; other tables remain current. See [Time machine](https://docs.tolmo.com/knowledge-graph/time-machine.md).

## Cypher (graph) queries

The `tolmo cypher` command executes a Cypher query against the infrastructure graph database. The graph represents your cloud environment as a network of nodes (resources) and edges (relationships between them), giving you a powerful way to understand how infrastructure components connect.

```bash theme={null}
# Count nodes by label
tolmo cypher "MATCH (n) RETURN labels(n), count(*)"

# Return a sample of raw nodes as JSON
tolmo cypher --json "MATCH (n) RETURN n LIMIT 5"
```

### Record why you're running a query

Pass `--intent` with one sentence stating the goal the query serves. Tolmo attaches it to the request trace in APM and to the security audit log of rejected queries, so a burst of automated queries has an attributable purpose. It never changes the query or its results.

```bash theme={null}
tolmo cypher --intent "triaging exposed EC2 with IAM roles" "MATCH (i:Exposed {resourceType: 'EC2Instance'})-[h:GRAPH_EDGE {type:'HAS_ROLE'}]->(r:GraphNode) RETURN i.resourceKey, r.resourceKey"
```

> [!NOTE]
>
> Agents and scripts must set `--intent` on every query. Skip it only for a one-off query you type yourself. When you call the [Cypher endpoint](https://docs.tolmo.com/api-reference/cypher/run-a-cypher-query.md) directly, send the same text in the `intent` field of the request body.

## Graph data model

Every resource in the infrastructure graph is stored as a **`GraphNode`**, and every relationship between resources is stored as a **`GRAPH_EDGE`**.

| Element | Key properties | Description |
| - | - | - |
| `GraphNode` | `resourceType`, `resourceKey` | Represents a single infrastructure resource (e.g. an S3 bucket, an IAM role, a GitHub repository). |
| `GRAPH_EDGE` | `type` | A directed relationship between two nodes (e.g. `HAS_ROLE`, `OWNS`, `CONNECTS_TO`). |

Both nodes and edges carry **temporal tracking fields**:

| Field | Type | Description |
| - | - | - |
| `firstSeenAt` | epoch milliseconds | When the crawler first discovered this resource or relationship. |
| `lastSeenAt` | epoch milliseconds | The most recent time the crawler confirmed it still exists. |

You can use these fields to write time-aware queries:

```bash theme={null}
# Resources added in the last 7 days
tolmo cypher "MATCH (n:GraphNode) WHERE n.firstSeenAt >= (timestamp() - 7*24*60*60*1000) RETURN n.resourceType, n.resourceKey ORDER BY n.firstSeenAt DESC"

# Stale resources not seen in the last 48 hours
tolmo cypher "MATCH (n:GraphNode) WHERE n.lastSeenAt < (timestamp() - 48*60*60*1000) RETURN n.resourceType, n.resourceKey LIMIT 50"

# New relationships discovered in the last 24 hours
tolmo cypher "MATCH ()-[r:GRAPH_EDGE]->() WHERE r.firstSeenAt >= (timestamp() - 24*60*60*1000) RETURN r.type, count(r) AS cnt ORDER BY cnt DESC"
```

## Recipes

Start from these queries and adapt them. Each one is read-only.

### Assets that appeared this week

New resources are where new risk usually comes from. List everything the crawlers first observed in the last seven days, grouped by type:

```bash theme={null}
tolmo cypher --intent "review assets first seen this week" \
  "MATCH (n:GraphNode) WHERE n.firstSeenAt >= (timestamp() - 7*24*60*60*1000) RETURN n.resourceType, count(*) AS added ORDER BY added DESC"
```

### Relationships that changed today

```bash theme={null}
tolmo cypher --intent "review relationships first seen today" \
  "MATCH (a:GraphNode)-[r:GRAPH_EDGE]->(b:GraphNode) WHERE r.firstSeenAt >= (timestamp() - 24*60*60*1000) RETURN a.resourceKey, r.type, b.resourceKey LIMIT 100"
```

### Open high-severity findings

```bash theme={null}
tolmo sql "SELECT id, title, severity, status FROM findings WHERE severity IN ('critical', 'high') AND status = 'open' LIMIT 50"
```

### Findings at the start of the month

```bash theme={null}
tolmo sql --as-of 2026-11-01 "SELECT severity, count(*) FROM findings GROUP BY severity"
```

See [Time machine](https://docs.tolmo.com/knowledge-graph/time-machine.md) for how historical queries behave.

## Output formats

Both `sql` and `cypher` support two output modes:

| Mode | Flag | Description |
| - | - | - |
| Table | *(default)* | Human-readable, column-aligned output. Best for interactive use. |
| JSON | `--json` | JSON object containing `rows`, `fields`, and `metadata`. Best for scripting and automation. |

> [!TIP]
>
> Always pass `--json` when parsing output programmatically. Table formatting can vary across CLI versions, and JSON gives you structured fields to process with tools like `jq`: `tolmo sql --json "SELECT 1" | jq '.rows[]'`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.