> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementary-data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# dimension_anomalies

> [card] [Generate your anomaly test with Elementary AI](https://elementary-data.com/community)
>
> Let our Slack chatbot create the anomaly test you need.

`elementary.dimension_anomalies`

The test counts rows grouped by given `dimensions` (columns/expressions).

> [!NOTE]
>
> **BigQuery: nested STRUCT fields.** On BigQuery you can reference nested STRUCT leaf fields by their dotted path, for example `user.address.city`, wherever you name a column or dimension in this test. There is no need to flatten them into their own columns first, and the full dotted path is preserved in alerts.
>
> Fields under a `REPEATED` (array) ancestor are not supported.

This test practically monitors the frequency of values in the configured dimension over time, and alerts on unexpected changes in the distribution.
It is best to configure it on low-cardinality fields.

If `timestamp_column` is configured, the distribution is collected per `time_bucket`. If not, it counts the total rows per dimension.

Each value is compared against its own past, with its own expected range. So a value that drops to zero gets caught even when the table's total row count barely changes.

> [card] [Understanding dimension anomalies](https://docs.elementary-data.com/data-tests/anomaly-detection-tests/understanding-dimension-anomalies.md)
>
> What happens when you list more than one column, how to think about `detection_delay`, and why a long detection period can hide problems.

### Test configuration

*Required configuration: `dimensions`*

<pre>
  `data_tests:
    -- elementary.dimension_anomalies:
      arguments:
        dimensions: sql expression
        timestamp_column: column name
        where_expression: sql expression
        anomaly_sensitivity: int
        anomaly_direction: [both | spike | drop]
        detection_period:
          period: [hour | day | week | month]
          count: int
        training_period:
          period: [hour | day | week | month]
          count: int
        time_bucket:
          period: [hour | day | week | month]
          count: int
        seasonality: day_of_week
        detection_delay:
          period: [hour | day | week | month]
          count: int
        ignore_small_changes:
          spike_failure_percent_threshold: int
          drop_failure_percent_threshold: int
        anomaly_exclude_metrics: [SQL expression]
        exclude_final_results: [SQL expression]`
</pre>

```yml Models theme={null}
models:
  - name: < model name >
    config:
      elementary:
        timestamp_column: < timestamp column >
    data_tests:
      - elementary.dimension_anomalies:
          arguments:
            dimensions: < columns or sql expressions of columns >
            # optional - configure a where a expression to accurate the dimension monitoring
            where_expression: < sql expression >
            time_bucket: # Daily by default
              period: < time period >
              count: < number of periods >
```

```yml Models example theme={null}
models:
  - name: login_events
    config:
      elementary:
        timestamp_column: "loaded_at"
    data_tests:
      - elementary.dimension_anomalies:
          arguments:
            dimensions:
              - event_type
              - country_name
            where_expression: "event_type in ('event_1', 'event_2') and country_name != 'unwanted country'"
            time_bucket:
              period: hour
              count: 4
          config:
            # optional - use tags to run elementary tests on a dedicated run
            tags: ["elementary"]
            # optional - change severity
            severity: warn

  - name: users
    # if no timestamp is configured, elementary will monitor without time filtering
    data_tests:
      - elementary.dimension_anomalies:
          arguments:
            dimensions:
              - event_type
          config:
            tags: ["elementary"]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.