docs: explain how to reason about dimension anomaly tests

[joostboon]

Adds a conceptual guide for dimension_anomalies — the test with the most configuration nuance and the sparsest docs. Written to be sendable to a team member who needs to understand the test, not just look up a parameter.

Behaviour was verified against the macros in dbt-data-reliability, because two of the three areas below have answers that are non-obvious from the reference pages.

What it covers

Multiple dimensions produce one composite series per observed combination, not one series per column. Columns are concatenated with ; (NULLs rendered as the literal NULL), so [country, device_os] monitors US; ios, US; android, … Series count multiplies, and combinations are individually noisier than either column alone. Also documented: the dimension list — including its order — is part of the metric identity, so editing or reordering it orphans the collected history and restarts the training set.

detection_delay is not needed to avoid partial buckets. Only complete time buckets are ever evaluated: the newest bucket is the last one whose end falls at or before the invocation time. With daily buckets and a 02:00 run, the newest scored bucket is yesterday 00:00→today 00:00, and today's partial data is never scored. A delay exists for data arriving after its bucket closed. It also snaps to bucket boundaries — a 4-hour delay on a 02:00 run costs a full day, same as asking for one. The case where a delay genuinely is needed: the detection boundary comes from the dbt invocation time (UTC) while buckets align to midnight in the timestamp_column's own frame, so a local-time column can be scored before it is complete.

Training/detection overlap is self-masking, not just imprecise. The expected range at each bucket is a cumulative window over that series up to and including that bucket. With a multi-bucket detection_period, Monday's anomaly joins the training data used to judge Tuesday, widening the range Wednesday is measured against — a sustained incident hides its own tail, giving one alert then silence that reads like recovery. Hence the flat recommendation: detection_period longer than one bucket ⇒ set exclude_detection_period_from_training: true.

Also covered: dimension value lifecycle (previously-seen values get an explicit 0 for empty buckets, which is what makes disappearance detectable; never-seen values get no backfill, so a new value cannot alert on first appearance), the seasonality interaction, the no-timestamp_column mode, and how to read a failure (the failure count is anomalous bucket/value pairs, while stored results deliberately include each affected value's full series for graph context).

Files

• data-tests/anomaly-detection-tests/understanding-dimension-anomalies.mdx — new page
• data-tests/anomaly-detection-tests/dimension-anomalies.mdx — series-per-value note and a card link to the guide
• data-tests/anomaly-detection-configuration/dimensions.mdx — multi-dimension behaviour
• data-tests/anomaly-detection-configuration/detection-delay.mdx — complete buckets, boundary snapping, how to choose
• data-tests/anomaly-detection-configuration/exclude_detection_period_from_training.mdx — why the overlap happens
• docs.json — nav entry

The reference pages repeat the guidance inline rather than only linking out, since skills.md asks for pages to be self-contained enough for Kapa to answer from a single page.

Checks

JSON parses, every internal link and nav target resolves to a real file, MDX tags and fences balanced. mintlify dev was not run — the CLI is not installed locally, so a preview check before merge would be worthwhile.

Note for a follow-up

docs/skills.md instructs git checkout -b docs/<feature-name>, which git cannot push while a branch named docs exists (directory file conflict). Hence the flat branch name here. Worth fixing in the guide separately.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 353e774a-9607-4abb-a51b-e2c3daebfaf3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}