> ## 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.

# Run SQL and Cypher Queries Against Your Infrastructure

> Run SQL queries against your org's relational data and Cypher queries against the infrastructure graph. Both commands support --json for scripting.

Tolmo lets you query two data stores — a relational database (via SQL) and a graph database (via Cypher) — directly from the command line. Use SQL for structured, tabular data about your organization and Cypher for traversing infrastructure relationships in the graph. Both commands support `--json` for machine-readable output and accept the global `--org` flag to target a specific organization.

## SQL queries

The `tolmo sql` command executes a SQL query against your organization's relational database and prints results as a formatted 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 receive raw JSON — useful when piping output to `jq` or another tool.

### 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/guides/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"
```

## 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.