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

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

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.

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.

Always date-filter observations

cargowise_xml_observations is large by design. Always add a date window (and usually a path or label filter).

Missing from shipments ≠ missing from Analytics

If a value is not a curated column, look in discovery before assuming it was never stored.