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

# Data Rules Fundamentals

> Catch data quality issues automatically with project-defined rules that flag events and batch calculations.

Data Rules let you encode the data quality checks that matter to your project as expressions Mangrove evaluates automatically. When an event is created, a datapoint is updated, or a batch is calculated, the rule runs in the background and raises an **alert** if the data matches a condition you've defined.

Use Data Rules when you want to:

* Catch out-of-range measurements before they propagate into reports
* Flag missing or implausible values during data ingestion
* Validate that calculated batch outputs stay within expected bounds
* Encode methodology guardrails that your team would otherwise check by eye

## Key concepts

#### Rule

A **rule** is a single named expression evaluated against either incoming event data or model calculation results. Rules belong to a project and are managed in **Project Settings → Data Rules**.

#### Target

Each rule has a **target** that determines what it evaluates:

| Target                 | Evaluates                                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Event Data**         | Individual datapoints as events are created or updated. Use this to validate raw measurements at ingestion. |
| **Batch Calculations** | Outputs of a model after a batch is generated. Use this to validate downstream calculation results.         |

When a rule's condition matches, Mangrove raises an **alert** on the affected event or batch — it does not block event creation, datapoint updates, or batch generation. Alerts are surfaced for review; users can dismiss them with a reason without changing the underlying data.

#### Rule expression

The **expression** is the condition that triggers the rule. Expressions are written in a domain-specific language similar to SQL — for example:

```
{{carbon_content}} not between 0.50 and 0.90
```

When the expression evaluates to true on a record, that record is flagged. See [Rule Expressions](/data-rules/rule-expressions) for the full reference.

#### Effective period

Every rule has an **Effective from** date and an optional **Effective to** date. The rule evaluates records whose date falls within this range — anything outside it is left alone.

* Set **Effective to** to a date when the rule should stop applying (for example, when a methodology version retires).
* Leave **Effective to** blank to mean **Ongoing** — the rule keeps running on new data indefinitely.

When you save a new or edited rule, Mangrove evaluates every matching record within the effective range automatically. There is no separate backfill step.

#### Alert

When a rule's expression matches a record within the effective period, Mangrove creates an **alert**. Alerts surface in three places:

* **Event drawer** — alerts appear on the affected event with a link back to the rule
* **Batch detail** — batches with rule alerts show them on the batch page
* **Reports** — alerts on records included in a report are propagated to that report

Alerts can be **dismissed** with a reason, which preserves the result for audit while clearing it from the active list.

## Lifecycle

```mermaid theme={null}
flowchart LR
  A[Draft expression] --> B[Validate / test]
  B --> C[Set effective period]
  C --> D[Save rule]
  D --> E[Evaluates records in range]
  E --> F[Edit → re-evaluate the effective range]
  E --> G[Archive]
```

To stop a rule from running on new data, set or shorten its **Effective to** date — the rule keeps its history but no longer evaluates records past that date. Rules with evaluation results cannot be deleted; they can only be **archived**, which stops future evaluation and hides their alerts while preserving history for audit.

## API access

Accessing rules over the [Mangrove API](/api-reference/authentication) requires your API token to have the **`rule` scope** enabled. Tokens missing this scope receive a `403 Unauthorized` response from any rules endpoint. To add the scope, open **Settings → API Tokens**, edit the token, and tick **Rules Engine** in the permissions list.