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

# How Analytics works

> Long-term storage, curated tables, field discovery, and access rules.

Analytics is built for long-term storage and analytics visibility. Think of it as two layers in one schema. Both live under `reporting`. Both use the same login.

## Mental model

```text theme={null}
Long-term Analytics store (your organization)
        │
        ├── curated tables (shipments, versions, changes, …)
        │     stable shape for everyday reports and dashboards
        │
        └── field catalog + observations
              values available for discovery when not yet curated
        │
        ▼
Your login SELECT-only on reporting.*
```

You do not reconnect when new data lands. As long as your credential is active, visibility stays on the same views.

## Curated tables

Curated tables are the clean spreadsheet version of common business questions. The main one is `reporting.shipments`: job number, transport mode, origin, destination, weight, volume, and related history.

These columns stay stable on purpose. Power BI and recurring dashboards need a shape that does not change every time a new field appears.

When a field becomes important enough for everyday reports, it can be promoted into a curated table — after the source data actually supplies it.

Read [Query curated data](/analytics/curated-data) for everyday SQL.

## Field discovery

Not every useful value is a curated column yet. Discovery keeps those values available as **rows** under `reporting`, instead of endlessly widening `shipments`.

| View                                   | What it is                                                              |
| -------------------------------------- | ----------------------------------------------------------------------- |
| `reporting.cargowise_xml_fields`       | Catalog of field names and paths already observed for your organization |
| `reporting.cargowise_xml_observations` | The actual values for those fields                                      |

The everyday loop:

1. List fields in `cargowise_xml_fields`.
2. Query matching values in `cargowise_xml_observations` with a date window.

Read [Discover fields](/analytics/discover-fields) for the exact queries.

## Access rules

Your reporting login can only read. It cannot:

* write to the database
* see another organization's data
* query anything outside `reporting`

## Rules worth remembering

<AccordionGroup>
  <Accordion title="Job number vs shipment key">
    Use `job_number` in business-facing filters and exports — that is the job people recognize. Use
    `shipment_key` only for joins to history tables.
  </Accordion>

  <Accordion title="Reporting is a contract, not an API">
    Day-to-day visibility uses the Postgres login and the supported `reporting` views. Arbitrary
    read-only SQL over those views is fine.
  </Accordion>

  <Accordion title="Always date-filter observations">
    `cargowise_xml_observations` is large by design. Always add a date window (and usually a path or
    label filter).
  </Accordion>

  <Accordion title="Missing from shipments ≠ missing from Analytics">
    If a value is not a curated column, look in discovery before assuming it was never stored.
  </Accordion>
</AccordionGroup>