# Dimension anomalies

The `elementary.dimension_anomalies` test counts rows grouped by given `dimensions` (columns/expressions). It monitors the frequency of values in the configured dimension over time and alerts on unexpected changes in the distribution. This test is best configured on low-cardinality fields.

### How it works

* If `timestamp_column` is configured, the distribution is collected per `time_bucket`.
  * If not, it counts the total rows per dimension.
* The test alerts on unexpected changes in the distribution of dimension values over time.

{% tabs %}
{% tab title="Models" %}

```yml
models:
  - name: < model name >
    config:
      elementary:
        timestamp_column: < timestamp column >
    tests:
      - elementary.dimension_anomalies:
          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 >
```

{% endtab %}

{% tab title="Models example" %}

```yml
models:
  - name: login_events
    config:
      elementary:
        timestamp_column: "loaded_at"
    tests:
      - elementary.dimension_anomalies:
          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
          # optional - use tags to run elementary tests on a dedicated run
          tags: ["elementary"]
          config:
            # optional - change severity
            severity: warn

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

{% endtab %}
{% endtabs %}

### [​](https://docs.elementary-data.com/data-tests/anomaly-detection-tests/dimension-anomalies#test-configuration)Test configuration <a href="#test-configuration" id="test-configuration"></a>

```yaml
tests:
  — elementary.dimension_anomalies:
    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]
```

{% hint style="info" %}

#### Important Notes

* **Required configuration**: `dimensions`
* The test is best suited for low-cardinality fields.
* If `timestamp_column` is not configured, the test will monitor without time filtering.
* Tags can be used to run elementary tests on a dedicated run.
* Severity can be optionally changed in the config section.
* The `where_expression` can be used to refine the scope of dimension monitoring.
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paradime.io/app-help/documentation/integrations/observability/elementary-data/anomaly-detection-tests/dimension-anomalies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.