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

# CargoWise model

> Understand the canonical current-state model used for advanced CargoWise consultation.

The `cargowise` schema turns source evidence into current business records and explicit
relationships.

Use [Reporting](/analytics/reporting) for normal reports, Power BI, exports, and reusable SQL. Use
`cargowise` when a complex consultation needs a root, detail, or relationship that reporting does
not expose.

## When to use CargoWise

The schema includes consols, bookings, operational shipment details, documents, air waybill data,
and other structures outside the smaller reporting contract.

<Warning>
  Direct CargoWise queries must select the active generation and preserve each table's grain and
  ownership rules. Internal table shapes can change as projection support grows.
</Warning>

## Business records

The schema has four roots: shipments, consols, bookings, and one-off quotes. Detail tables can
belong to one supported root. Bridge tables keep relationships proven by CargoWise data.

The model does not create relationships from matching names, dates, routes, or amounts.

## Generations

| Status     | Meaning                                                                     |
| ---------- | --------------------------------------------------------------------------- |
| `building` | A historical rebuild is writing a separate generation                       |
| `ready`    | The generation finished and passed the required checks                      |
| `active`   | Reporting reads this generation. Only one can be active for an organization |
| `retired`  | A previous generation was replaced after a safe switch                      |
| `failed`   | The generation failed and does not become the source for normal reports     |

## Unknown data

Unknown XML evidence remains in `source_data`. Scalar values can still appear through
`reporting.source_fields`. Structured data stays in the source layer until the CargoWise and
reporting contracts support it.

Next, read [Reporting](/analytics/reporting) for the smaller model used by normal reports.