Data and reporting
Reporting data needs a freshness contract
A useful data-freshness contract states what business period a report covers, when each required source should arrive, and what the report will do if a source is late. A page refresh time alone cannot establish that the underlying business data is current or complete.
The practical issue
A useful data-freshness contract states what business period a report covers, when each required source should arrive, and what the report will do if a source is late. A page refresh time alone cannot establish that the underlying business data is current or complete.
Imagine a distributor reviewing an illustrative morning fulfillment report. Order data has arrived, but the warehouse feed is still on the previous operating day. The dashboard opens normally and its charts calculate correctly. Yet a comparison of orders and shipments can give the wrong operational impression because the two sides describe different periods.
The familiar approach and its limit
Teams often add a single “last updated” label or rerun the dashboard on a schedule. Both can be useful, but the label needs a defined meaning. It might refer to the page loading, a transformation finishing, or one record arriving. Those events are different from all required data being available through a business cutoff.
A recent record also does not prove that an entire load arrived. One successful location can make a shared table look current while another location is missing. Treat freshness and completeness as separate checks, then decide which checks the report needs for its intended use.
Define the clocks before choosing the threshold
Start with three times: when the business event occurred, when it entered the reporting system, and when the report was produced. Keep their time zones clear. If an overnight business day crosses midnight, state the cutoff rather than assuming a calendar date tells the whole story.
dbt's source documentation shows how named sources can carry lineage, tests and freshness information. It also describes freshness thresholds and source-specific configuration. These are useful building blocks, whether a team uses dbt or implements an equivalent check elsewhere. They still need an operational definition of “ready.”
For the distributor, readiness could mean that every required warehouse has supplied its agreed batch through the previous operating-day cutoff. That is a proposed contract for this example, not a universal threshold. A planning report and a live dispatch screen can reasonably require different timeliness.
Make source coverage visible
Keep a small reporting status record for each required source or business partition. Record the expected coverage window, last accepted batch, completeness result, validation result and responsible team. Show the limiting source when a combined report is delayed.
For example, the report might say “Orders complete through the agreed cutoff; one warehouse shipment batch is pending.” Avoid replacing this with a reassuring green badge based only on the dashboard refresh. If a source has no events during a quiet period, use a completion signal or other agreed evidence rather than guessing that silence means failure.
Late corrections need a policy too. Decide whether historical values are restated, when affected periods are rebuilt, and how users will recognize a revision. Otherwise two people can export the same named reporting period and receive different totals without an explanation.
Decide what users can do with stale data
There are several reasonable behaviors: show the last complete snapshot with a warning, suppress only the affected metric, or block an automated downstream decision. Select the behavior according to the consequence of being wrong. Do not quietly substitute zero for missing data.
A warning should name the affected period and owner, and give the next expected check when known. Keep an outage message distinct from an ordinary scheduled delay. If an exception is approved for a particular decision, record its scope rather than removing the warning for everyone.
Test the contract against a missing source
Before release, withhold one expected batch in a test environment. Verify that the report identifies the missing coverage, follows its agreed fallback and recovers when the batch arrives. Repeat with an incomplete batch and a late correction. Measure whether users can understand the state without asking an analyst to interpret it.
Quarro can help align reporting pipelines, status displays and operational ownership around this contract. Start with the report used for the next real decision, then document the data conditions that make its answer trustworthy. For metric definitions themselves, see [the services-dashboard guide](/blog/professional-services-backlog-dashboard-definitions/).