> ## 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 title="Generate your anomaly test with Elementary AI" icon="wand-magic-sparkles" horizontal="true" href="https://elementary-data.com/community">
  Let our Slack chatbot create the anomaly test you need.
</Card>

`elementary.dimension_anomalies`

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

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.

### Test configuration

*Required configuration: `dimensions`*

<pre>
  <code>
    data\_tests:
      -- elementary.dimension\_anomalies:
        arguments:
          <a href="/data-tests/anomaly-detection-configuration/dimensions"><font color="#CD7D55">dimensions: sql expression</font></a>
          <a href="/data-tests/anomaly-detection-configuration/timestamp-column"><font color="#CD7D55">timestamp\_column: column name</font></a>
          <a href="/data-tests/anomaly-detection-configuration/where-expression"><font color="#CD7D55">where\_expression: sql expression</font></a>
          <a href="/data-tests/anomaly-detection-configuration/anomaly-sensitivity"><font color="#CD7D55">anomaly\_sensitivity: int</font></a>
          <a href="/data-tests/anomaly-detection-configuration/anomaly-direction"><font color="#CD7D55">anomaly\_direction: \[both | spike | drop]</font></a>
          <a href="/data-tests/anomaly-detection-configuration/detection-period"><font color="#CD7D55">detection\_period:</font></a>
            <a href="/data-tests/anomaly-detection-configuration/detection-period"><font color="#CD7D55">period: \[hour | day | week | month]</font></a>
            <a href="/data-tests/anomaly-detection-configuration/detection-period"><font color="#CD7D55">count: int</font></a>
          <a href="/data-tests/anomaly-detection-configuration/training-period"><font color="#CD7D55">training\_period:</font></a>
            <a href="/data-tests/anomaly-detection-configuration/training-period"><font color="#CD7D55">period: \[hour | day | week | month]</font></a>
            <a href="/data-tests/anomaly-detection-configuration/training-period"><font color="#CD7D55">count: int</font></a>
          <a href="/data-tests/anomaly-detection-configuration/time-bucket"><font color="#CD7D55">time\_bucket:</font></a>
            <a href="/data-tests/anomaly-detection-configuration/time-bucket"><font color="#CD7D55">period: \[hour | day | week | month]</font></a>
            <a href="/data-tests/anomaly-detection-configuration/time-bucket"><font color="#CD7D55">count: int</font></a>
          <a href="/data-tests/anomaly-detection-configuration/seasonality"><font color="#CD7D55">seasonality: day\_of\_week</font></a>
          <a href="/data-tests/anomaly-detection-configuration/detection-delay"><font color="#CD7D55">detection\_delay:</font></a>
            <a href="/data-tests/anomaly-detection-configuration/detection-delay"><font color="#CD7D55">period: \[hour | day | week | month]</font></a>
            <a href="/data-tests/anomaly-detection-configuration/detection-delay"><font color="#CD7D55">count: int</font></a>
          <a href="/data-tests/anomaly-detection-configuration/ignore_small_changes"><font color="#CD7D55">ignore\_small\_changes:</font></a>
            <a href="/data-tests/anomaly-detection-configuration/ignore_small_changes"><font color="#CD7D55">spike\_failure\_percent\_threshold: int</font></a>
            <a href="/data-tests/anomaly-detection-configuration/ignore_small_changes"><font color="#CD7D55">drop\_failure\_percent\_threshold: int</font></a>
          <a href="/data-tests/anomaly-detection-configuration/anomaly-exclude-metrics"><font color="#CD7D55">anomaly\_exclude\_metrics: \[SQL expression]</font></a>
          <a href="/data-tests/anomaly-detection-configuration/exclude-final-results"><font color="#CD7D55">exclude\_final\_results: \[SQL expression]</font></a>
  </code>
</pre>

<RequestExample>
  ```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"]
  ```
</RequestExample>
