Monthly Statement Numbers Mismatch: Reconciling Dashboard Snapshots with Live Queries

When monthly statement numbers do not align with dashboard snapshots or live queries, it requires a systematic investigation. The key is to generate each statement from an immutable, versioned data snapshot, rather than relying on live data that can change between runs. This approach ensures repeatable explanations rather than accidental visual agreement.

To properly evaluate the situation, one must compare various factors such as the cutoff, filters, timezone settings, metric definitions, and revision tokens. These details need to be recorded in a manifest for the statement, including the snapshot identifier, source watermark, metric version, period boundaries, and timezone information.

A common mistake is executing the reporting query again whenever someone opens a statement. This turns a historical artifact into a moving target, as late corrections, timezone boundaries, mutable dimensions, and newly arrived events can alter the answer between runs. Instead, the reporting query should only be executed once to create the statement.

One must also inspect data freshness, ensuring that the snapshot includes a watermark or equivalent revision token that indicates which source changes it encompasses. The live query may see later inserts and corrections, while a dashboard backed by a materialized aggregate may lag behind. Comparing only the visible date range can hide these distinctions, so all relevant information should be included in the statement manifest.

Another trap is the potential drift in metric definitions. For example, "net_revenue" might mean gross revenue minus refunds in one path, while another path excludes tax or applies currency conversion on a different date. A versioned metric contract shared by snapshot creation, dashboard inspection, and statement rendering is the right repair in this case.

Lastly, multiplicity in joins can lead to duplicate monetary facts before aggregation. Careful checks on row counts and stable fact identifiers at each join boundary are necessary to ensure accuracy. By treating statement generation as a small data build with separate stages for resolving the closed period, applying a named metric contract, emitting typed statement rows, consuming those rows without querying operational tables, and storing the PDF alongside a manifest and data digest, one can maintain accurate and reliable monthly statements.