Core concepts

These are the terms you'll see throughout the docs and the CLI. Read this once and the rest of the documentation reads faster. For a fuller alphabetical list, see the Glossary.

The state graph

The central idea. Instead of storing your state as a flat file, Stategraph stores it as a graph: every resource is a node, and every dependency between resources is an edge. Terraform already computes this graph to order its operations — Stategraph keeps it, so you can lock, query, and analyze against it.

Everything else below is something the graph makes possible.

State

A state is one Terraform state — the resources of a single root module — stored on the Server and identified by a UUID. A state has a human-readable name, belongs to a workspace, and is wired to a directory of configuration through a group. This is the rough equivalent of one S3 state file, but graph-shaped and server-managed.

Group and workspace

A group ties a configuration directory to its state. The mapping is recorded in a stategraph.json file in that directory (written for you on import), so the CLI knows which state a directory drives.

A workspace is the same concept as a Terraform workspace — a named variant of a configuration (for example default, staging, production). One group can contain several workspaces, each with its own state.

Tenant

A tenant is the top-level isolation boundary — typically an organization or team. Every state lives in exactly one tenant, and access, billing sources, and gap analysis are all scoped per tenant. Most CLI commands take a --tenant (or the STATEGRAPH_TENANT_ID environment variable).

Transaction

Every plan and apply is a transaction. It moves through a lifecycle — open, previewing, committing, then committed (or failed/aborted) — and the Server records it in a timeline you can inspect. Transactions are how Stategraph coordinates concurrent changes safely. See Transactions.

Resource-level locking

Because the state is a graph, Stategraph locks at the level of individual resources rather than the whole state. Two transactions that touch disjoint sets of resources can plan and apply at the same time; only genuinely overlapping changes are serialized, with conflicts detected at commit time. This is what makes Velocity parallel.

Resource and instance

A resource is a single resource block in your configuration (for example aws_instance.web). An instance is a concrete object that block produces — a block with count or for_each has several instances (aws_instance.web[0], aws_instance.web[1], …). Inventory queries and blast radius operate at the instance level.

Blast radius

The blast radius of a resource is its dependency cone — everything that could be affected if you change it. Stategraph computes it from the graph so you can assess impact before you apply. See Blast Radius.

Gap analysis

Gap analysis finds cloud resources that exist in your account but aren't managed by any Terraform state — drift in the other direction. It's how you discover what's running outside of code. See Gap Analysis.

Querying with SQL

Stategraph exposes your estate as a set of SQL-queryable tables (resources, instances, states, and more). You ask questions about your infrastructure the way you'd query a database. Start with stategraph sql schema to discover the tables, then stategraph query "...". See Query.

Cost

Stategraph estimates the cost of the resources in your states, attributes spend by tag/owner/provider, and can show a cost delta at plan time. With a FOCUS billing source connected, it also reconciles estimates against your actual cloud spend. See Cost Analysis.

Access and capabilities

Users and service accounts authenticate with API keys (access tokens). Tokens can be capability-scoped — granted only the specific rights they need (for example commit access to a single state) rather than blanket admin. See Authentication.