# The graph

One graph per estate: what each database means (entities, measures, relationships, lineage) and what runs it (instance class, storage, cost, usage, freshness).

## One graph, two kinds of facts

Datapace keeps one graph per estate. Every node is either a fact about **meaning** or a fact about **infrastructure**, and the two sit next to each other.

Meaning facts describe the data in your experts' terms:

- **Entities.** The things the business talks about: a customer, an order, a shipment, an account. An entity resolves to one or more tables, across one or more databases.
- **Measures.** The numbers people ask for, with their definition: which column, which filter, which grain.
- **Relationships.** How entities connect, whether or not a foreign key exists in the schema.
- **Semantics.** What a column means, what its values mean, which columns hold personal data.
- **Lineage.** Where a value comes from and where it goes: the tables, views, jobs, exports, and dashboards that produce and consume it.

Infrastructure facts describe what runs each database:

- **Instance class and storage.** What the database runs on and how much it holds.
- **Cost.** What it costs to run, from the provider's own figures.
- **Performance.** Workload signals: the queries that run, how often, how long.
- **Usage and freshness.** Which tables are read and written, and when they last changed.

## Why one graph

Teams usually keep these facts in different tools: a catalog for meaning, a monitoring tool for performance, a cloud bill for cost, a wiki for the rest. Each one describes its slice, none of them agrees with the others, and none of them is the place a change gets decided.

Putting both kinds of fact on one graph is what lets the routine work surface with its evidence. A dead table reveals a dead job; a dead job frees an oversized instance; a slow query points at the entity whose definition it serves. Catalogs describe. Datapace governs.

## What a node carries

An illustrative entity, as its facts read once confirmed:

```yaml
entity: Customer
source: sales.customers            # Postgres, sales, since 2016
grain: one row per billing account
state: validated                   # accepted by the data lead
confidence: 0.94                   # the inference score, kept for the record
measures:
  active_customers: count where status = 'active'
relationships:
  - places: Order                  # customers.id = orders.customer_id
pii:
  email: confirmed
  notes: to review
lineage:
  feeds: [finance.customer_export, bi.customers_dashboard]
```

Values here are illustrative. What matters is the shape: the meaning in the experts' words, the state and the score on the record, the personal-data flags on the columns, and the lineage to what consumes the entity.

## What the graph is used for

- **Documentation.** The graph is the documentation: current, confirmed, and in the team's own terms. See [infer and confirm](/docs/concepts/infer-and-confirm).
- **The agents' work.** Every proposal is drafted on the graph and cites it as evidence. See [agents](/docs/concepts/agents).
- **Governed context.** Copilots, BI, and MCP clients read the confirmed graph, not the raw database. See [governed context](/docs/concepts/governed-context).
- **Migration.** A source system's graph is the map a mapping starts from. See [migration mapping](/docs/guides/migration-mapping).

## What the graph is not

The graph is not a copy of your data. It holds metadata, definitions, signals, and structure, in the scope agreed with your team. It is not a second catalog to keep in sync either: it is the one place the team confirms, and the one place everything else reads from.