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

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

## 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`    | Raw JSON array of result rows. Best for scripting and automation. |

<Tip>
  Always pass `--json` when parsing output programmatically. Table formatting can vary across CLI versions, while the JSON schema is stable and easy to process with tools like `jq`.
</Tip>