# How Time Distribution Size Checks Work

Source: https://userguide.qualytics.io/data-quality-checks/time-distribution-size/deep-dive/how-it-works/

## Definition

*Asserts that the number of records in each time segment of a date field falls within a range.*

## Overview

The Time Distribution Size rule buckets the rows of a container by a date or timestamp field, one bucket per **Interval** (yearly, monthly, weekly, daily, or hourly), and counts the rows in each. Every bucket must hold between **Min Count** and **Max Count** records, inclusive.

Where a row-count rule watches the container as a whole, this one watches its shape over time. A table can hold exactly the number of rows you expect while a whole day is missing and the next one is doubled, and only a per-segment view makes that visible.

Typical use cases:

- Detect a day or hour where the load produced far fewer records than usual.
- Catch a segment that was ingested twice and now holds double the rows.
- Confirm a backfill produced a plausible volume for every period it covered.

## Field Scope

**Single:** The rule evaluates one field per check: the date or timestamp used to place each row into a time segment. It accepts `Timestamp` and `Date` fields.

**Accepted Types**

| Type | Supported |
| --- | --- |
| `Timestamp` | Yes |
| `Date` | Yes |

## Anomaly Types

| Type | Supported |
| --- | --- |
| Record Flag inconsistencies at the row level | Not supported |
| Shape Flag inconsistencies in the overall patterns and distributions of a field | Supported |

## Evaluation Flow

Every Time Distribution Size check follows the same four-step evaluation flow:

1. **Apply the filter clause.** If the check has a `filter` set, only rows matching the filter expression are considered. Filtered-out rows are not counted into any segment.
2. **Group the rows into time segments.** Each row is placed into a segment according to its value in the evaluated field and the chosen **Interval**. Rows with no date go into no segment.
3. **Count the records in each segment.** The platform counts how many rows landed in every segment the data produced.
4. **Compare each count against the range.** A segment passes when its count is between **Min Count** and **Max Count**, inclusive. Any segment outside that range produces a Shape Anomaly, which reports the failing segments together.

## Only Segments the Data Produces Are Evaluated

Segments come from the values in the field. If no row carries a date in a given day, that day produces no segment, so it is not evaluated and cannot fail the count range.

This is the rule's most important limitation: it catches a day that arrived **short**, not a day that did not arrive at all. To detect an entirely absent period, pair it with a [Freshness](https://userguide.qualytics.io/data-quality-checks/freshness/introduction/) check, which watches how recent the newest record is.

## Both Bounds Are Inclusive

A segment holding exactly **Min Count** records passes, and so does one holding exactly **Max Count**. The range is closed at both ends, so set the bounds to the counts you are willing to accept rather than to the first count you would reject.

## The Interval Decides What the Check Can See

A daily interval on a table with a few rows per day produces noisy segments where normal variation looks like a failure. A yearly interval on the same table hides a missing week inside a total that still looks right.

Pick the interval at which the data has a rhythm you can state: the level where you could confidently say "a normal one of these holds between X and Y records".

## The Filter Reshapes the Segments

The filter runs before the grouping, so filtered-out rows never reach a segment and the counts reflect only the rows that remain. Scoping a check to one region turns it into a per-region distribution check, which is often useful and occasionally surprising if the range was sized for the whole table.

## Coverage Does Not Change the Outcome

The form shows a **Coverage** slider because it is part of the shared check form, but Time Distribution Size evaluates segment counts rather than individual rows. There is no per-row pass rate for a threshold to relax, so the setting does not affect whether the check passes.

## The Filter Clause

The filter clause is a SQL `WHERE` expression applied **before** the evaluation. Filtered-out rows are ignored entirely.

When a filter is set, the Shape Anomaly message names it at the end of its first sentence, as `(applied to records where <expression>)`.

## See Also

- **Anomaly Reporting**

  The Shape Anomaly the check produces, what the percentage counts, and how the failing segments are reported.

  [Anomaly Reporting](https://userguide.qualytics.io/data-quality-checks/time-distribution-size/deep-dive/anomaly-reporting/)
- **Examples**

  Three production scenarios with sample data, the resulting anomaly message, and the SQL equivalent of what the check evaluates.

  [Examples](https://userguide.qualytics.io/data-quality-checks/time-distribution-size/deep-dive/examples/)
- **Best Practices**

  Guidelines for picking the interval, sizing the range, and handling seasonality.

  [Best Practices](https://userguide.qualytics.io/data-quality-checks/time-distribution-size/deep-dive/best-practices/)
- **Permissions**

  The team permission each action needs: view, create, edit, archive, restore, and delete.

  [Permissions](https://userguide.qualytics.io/data-quality-checks/time-distribution-size/deep-dive/permissions/)

*Last updated: October 12, 2026.*
