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

# Checks

> Author and run Validation Checks with WHERE/CHECK logic in Data Validation.

<Warning>
  **Current limitation**

  In v0, after creation you can rename a check only; scope, rule list, and predicates stay
  frozen. For different behaviour, create a new check.
</Warning>

Use this page for **Validation Check** authoring and execution.

<Info>
  Checks are executable validation definitions tied to tracked models. For reusable
  templates, use [Standards](/analytics/data-validation/standards).
</Info>

<Note>
  **v0 release behavior (available today):**
  checks can be defined and run against all models in a project. Editing an existing
  check is currently limited to its name; scope and rules are not yet editable after
  creation.

  This will evolve. We would value feedback on the expected **versioning behavior** for
  checks (for example: mutable checks vs immutable versions/forks).
</Note>

## Run a first check

Use **Run check** from the project sidebar when you want to test rule logic on
real project data.

<Steps>
  <Step title="Load preview model">
    Empty first screen until a preview model loads. Load preview to unlock starters and pick
    model/version context first.
  </Step>

  <Step title="Draft and preview rules">
    Define `WHERE` / `CHECK`; preview (**Run Preview** or `Ctrl+Enter` / `Cmd+Enter`) to validate
    logic before save.
  </Step>

  <Step title="Review first output">
    First preview yields one aggregate plus one row per rule.
  </Step>

  <Step title="Refine before save">
    Preview is ephemeral, so tune scope before save. Edited rules prompt a rerun so displayed
    numbers stay trusted.
  </Step>

  <Step title="Handle large-model behavior">
    Large models may skip the 3D pane; assertions still evaluate when preview is unloaded.
  </Step>

  <Step title="Confirm persistence">
    Done when **Checks** shows the new card, which confirms persistence.
  </Step>
</Steps>

## Build a check with many rules

One topical check can own many rules (e.g. fire ratings on walls/doors/windows) so failures
stay rule-level inspectable—use **Add rule**, one requirement per rule, per-rule **Run**,
duplicate when scopes match.

## Operate checks over time

Saving locks rules to tracked models—later versions rerun the same predicates without redoing ad-hoc spreadsheets.

Manual vs auto trigger matches how tightly you gate runs. Charts need repeated runs—the
first save is often your baseline-only pass. Expanded rule rows expose `WHERE` → `CHECK`
counts when a filter swallowed your elements prematurely.

Layouts: [What you see on the
page](/analytics/data-validation/viewing-results#what-you-see-on-the-page). Ordering:
[Practical review
flow](/analytics/data-validation/viewing-results#practical-review-flow).

Save the check after scope is final, then read combined scores on
[Viewing Results](/analytics/data-validation/viewing-results).

First visit to results can lag when many rules, models, or deep history enqueue work.

## Rule structure in checks

Each rule is filters plus one assertion.

| Component       | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `WHERE`         | Filter scope of objects evaluated by the rule                               |
| `AND`           | Optional additional filters within the same scope                           |
| `CHECK`         | Final validation assertion                                                  |
| Property path   | Target property (`category`, `baseline.length`, `parameters.Width.value`)   |
| Predicate       | Comparison operator (**Equals**, **Exists**, **Matches pattern**, and more) |
| Value           | Reference value for the predicate                                           |
| Report severity | `ERROR` or `INFO`                                                           |
| Message         | Human-facing explanation for failed outcomes                                |

## Default scope

Default filter: `speckle_type` **Contains** `DataObject`, the connector-produced base BIM
bucket (Revit, IFC, ...). `DataObject` is the base type Speckle connectors produce, so most BIM
objects match it. Narrow with category/type/parameters—dropping `DataObject` widens noise risk.

<Warning>One terminal `CHECK` per rule—extra assertions belong in extra rules.</Warning>

## Thresholds and status

Rates map through thresholds:

| Setting           | Effect                                                      |
| ----------------- | ----------------------------------------------------------- |
| Pass threshold    | Minimum pass-rate for `PASS`.                               |
| Warn threshold    | Optional lower bound yielding `WARN` between warn and pass. |
| No warn threshold | Below pass ⇒ `FAIL` (no intermediate `WARN`).               |

Statuses: **`PASS`** (≥ pass), **`WARN`** (between thresholds when warn is set), **`FAIL`**
(under thresholds), **`PENDING`** (evaluation not finished).

## Predicates and matching

Type-aware predicates:

* Text: **Exists**, **Equals**, **Contains**, **Matches pattern**
* Number: **Is greater than**, **Is less than**, **Is between**
* Boolean: **Is true**, **Is false**

**Matches pattern** accepts wildcard or regex-like syntax per field help.

## Best practices

Tighten `WHERE` first so broad scopes do not flood triage.

Write descriptive **Message** text so fix owners can act without extra clarification.

Run preview before save so you catch false positives before history is recorded.

## FAQ

<AccordionGroup>
  <Accordion title="Can I create a check from a standard?">
    Yes—pick models and triggers after choosing the standard as the base.
  </Accordion>

  <Accordion title="How do I know a check is too strict?">
    Noise usually means tighten `WHERE`, tune predicates, or downgrade severity.
  </Accordion>

  <Accordion title="What happens to check results when a tracked model is deleted?">
    Existing results stay in history because they store the evaluated model/version ids from
    run time. The deleted model no longer appears in live scope, so future runs exclude it.
  </Accordion>

  <Accordion title="Can rules inside one check be reordered?">
    Rule order follows how rules were authored and saved. Reordering is not supported in v0, so
    duplicate/delete is the fallback when order matters for review.
  </Accordion>

  <Accordion title="What is the difference between preview and saving a check?">
    Preview runs against the current session model/version and is not persisted after you leave.
    Saving persists tracked models, trigger mode, thresholds, and result history.
  </Accordion>

  <Accordion title="How do I recover when a version update spikes unexpected failures?">
    First confirm the result used the model/version you expected, then inspect failing rules for
    missing or changed properties in the new version. If needed, duplicate the check for debug
    narrowing, export BCF for issue handoff, then create a replacement check once root cause is clear.
  </Accordion>
</AccordionGroup>