> ## 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.

# Create a Data Rule

> Walk through writing, validating, and saving a project data rule.

This guide walks through creating a data rule end to end: choosing what to evaluate, setting the effective period, writing an expression, validating it, and saving.

## Before you start

You need:

* **Write access** to the project's Data Rules. Ask an admin if the **Add Rule** button is greyed out.
* A clear sense of the **measurement or calculation** you want to validate, and the **threshold** or pattern that defines a problem.

## Step-by-step

<Steps>
  <Step title="Open Data Rules">
    Navigate to **Project Settings → Data Rules**. The Data Rules page lists every rule configured for the project, along with what it evaluates, its status, and the dates it applies to.

    Click **Add Rule** in the top right to start a new rule.
  </Step>

  <Step title="Choose what the rule evaluates">
    Pick a **target** for the rule:

    | Target                 | When to use                                                                                                                                          |
    | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Event Data**         | Validate raw measurements as events are created or updated. Best for catching ingestion-time errors (out-of-range readings, missing values).         |
    | **Batch Calculations** | Validate model outputs after a batch is generated. Best for catching downstream calculation issues (a CI score that drifts outside expected bounds). |

    * For **Event Data**, optionally select an **event type** to scope the rule. Leaving this blank evaluates the rule against any event whose datapoints match the expression.
    * For **Batch Calculations**, select the **model** whose calculation results should be evaluated. The available variables come from that model's nodes.
  </Step>

  <Step title="Set the effective period">
    Pick the dates the rule should apply to:

    * **Effective from** — the earliest date the rule applies to. Required.
    * **Effective to** — the date the rule stops applying. Leave blank for **Ongoing**.

    When you save the rule, Mangrove evaluates every matching record within this range — both historical and going forward. Records outside the range are not touched.

    Use a bounded effective period when a check only applies during a specific reporting cycle or methodology version. Use **Ongoing** for evergreen data quality checks.
  </Step>

  <Step title="Write the rule expression">
    Use the rule editor to write the condition that should trigger an alert. Type `{{` to open autocomplete and pick a datapoint slug or model node.

    ```
    {{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 language reference and more examples.
  </Step>

  <Step title="Name the rule and write an alert message">
    Two short fields describe the rule to anyone who later sees it on a record or in the rules list:

    * **Rule Name** — a short identifier shown in the Data Rules list and in audit history (for example, "Carbon content cap"). Keep it brief and stable, even if you later edit the expression.
    * **Alert Message** — the human-readable explanation shown on each alerted record (for example, "Carbon content out of range"). Defaults to a humanized version of the rule expression; edit it to read more naturally for the people triaging alerts.

    The Alert preview underneath shows how the alert will appear when the rule triggers.
  </Step>

  <Step title="Validate the rule">
    Click **Validate Rule** to check the expression. Mangrove will:

    * Confirm the syntax parses correctly
    * Confirm every variable resolves to a real datapoint or model node
    * Run the rule against recent project data and show a **Results Preview** of records that would have been flagged

    If validation fails, the editor highlights the issue. If validation succeeds and the preview shows unexpected matches, refine the expression and validate again.
  </Step>

  <Step title="Save and run the rule">
    Click **Save Rule**. Mangrove confirms the effective range and evaluates every matching record within it — both historical and going forward. Records outside the range are left untouched.
  </Step>

  <Step title="Confirm the rule is active">
    After saving, you land on the rule detail page. The header shows the rule status, its effective period, and a list of any matching records found during evaluation.

    The rule is now live: every new event or batch generation within the effective period will run the expression and raise an alert if it matches.
  </Step>
</Steps>

## Editing a rule

Open a rule from the Data Rules list and click **Edit**. Changing the expression saves a new version and re-evaluates matching records within the effective period. The new version's results replace the rule's existing alerts, so earlier alerts — including any you dismissed — are reset.

To stop a rule from applying to new data, shorten its **Effective to** date instead of editing the expression.

## Stopping or deleting a rule

| Action                           | Effect                                                                                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shorten the effective period** | Set or pull in the **Effective to** date so the rule stops evaluating new records. Its past alerts are preserved. Use when the rule has served its purpose for past data. |
| **Delete**                       | Permanently removes the rule along with all of its evaluations and alerts. Use when the rule was a mistake or you no longer need it.                                      |