# Aggregation Comparison Check API

Source: https://userguide.qualytics.io/data-quality-checks/aggregation-comparison/api/

This page documents how to create and manage an Aggregation Comparison check via the REST API. The check uses the standard Quality Checks endpoints: set `rule` to `aggregationComparison` and provide both aggregation expressions plus the comparison operator under `properties`. The rule evaluates one aggregate per side; `fields` only records which fields the check is associated with and never changes the result. All endpoints share the base URL of your deployment (for example, `https://your-instance.qualytics.io/api`) and require a Bearer token.

> **Tip**
>
> For complete API documentation, including request and response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

> **Note: Permissions**
>
> All endpoints require the **Member** role plus a team permission on the check's datastore: **Reporter** to read, **Author** to create or update an Active check, archive, or delete, and **Drafter** to create or update a Draft. See [Permissions](https://userguide.qualytics.io/data-quality-checks/aggregation-comparison/deep-dive/permissions/) for the full matrix.

## The `properties` object

Aggregation Comparison carries all of its rule-specific configuration under `properties`:

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `expression` | Yes | `string` | The target aggregation, evaluated against `container_id`. Must produce a single aggregate value. Accepts Check Variables. |
| `comparison` | Yes | `string` | The operator applied as target `<op>` reference: `lt`, `lte`, `eq`, `gte`, or `gt`. Shown in the UI as **Less Than**, **Less Than Or Equal To**, **Equal To**, **Greater Than Or Equal To**, and **Greater Than**. |
| `ref_datastore_id` | No | `int` | Datastore holding the reference container. Omit or send `null` when it lives in the same datastore as the target. |
| `ref_container_id` | Yes | `int` | The reference container. Can be the same as `container_id`. |
| `ref_expression` | Yes | `string` | The reference aggregation. Must also produce a single aggregate value. Accepts Check Variables. |
| `ref_filter` | No | `string` | SQL `WHERE` expression applied to the reference container before its aggregation runs. Accepts Check Variables. |

## Create

**Endpoint:** `POST /api/quality-checks`

**Permission:** Member role + **Author** team permission on the container's datastore (**Drafter** when `status` is `"Draft"`).

> **Example: Create an Aggregation Comparison check (every accepted field)**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "description": "Order totals must equal the line-item roll-up.",
>     "rule": "aggregationComparison",
>     "fields": [],
>     "container_id": 145,
>     "filter": null,
>     "properties": {
>         "expression": "ROUND(SUM(o_totalprice))",
>         "comparison": "eq",
>         "ref_container_id": 178,
>         "ref_expression": "ROUND(SUM(l_extendedprice * (1 - l_discount) * (1 + l_tax)))",
>         "ref_filter": null
>     },
>     "tags": ["reconciliation", "finance"],
>     "additional_metadata": {"jira": "DATA-4012"},
>     "template_id": null,
>     "status": "Active",
>     "owner_id": 7,
>     "default_anomaly_assignee_id": 12
>   }'
> ```
>
> To reference a container in a **different** datastore, add `ref_datastore_id` inside `properties`.

### Field notes

| Field | Required | Notes |
| --- | --- | --- |
| `description` | Yes | Free-text description shown in the UI. |
| `rule` | Yes | Must be `"aggregationComparison"`. |
| `fields` | No | Derived from the expressions by default. Omit it, or send `null` or `[]`, and the API stores the target container's fields that either expression names and returns them on the response. A reference-side column is only included when the target container has a field with the same name. Send a list to override that: it replaces the derived fields as given, and each name must be an active field on the target container. A `PUT` without `fields` derives them again, so include the check's current `fields` to keep an override. The list does not change what the check evaluates. |
| `container_id` | Yes | ID of the target container (table or file) the check runs against. |
| `filter` | No | SQL `WHERE` expression applied to the target container **before** the target aggregation runs. Send `null` for no filter. |
| `properties` | Yes | Object holding the rule-specific configuration. See [above](https://userguide.qualytics.io/data-quality-checks/aggregation-comparison/api/#the-properties-object). |
| `tags` | No | List of tag names applied to the check for filtering and organization. |
| `additional_metadata` | No | Free-form key-value pairs (typically links to catalog entries, tickets, governance records). |
| `template_id` | No | ID of a Check Template to associate the check with. `null` if not using a template. |
| `status` | No | `"Active"` (default) or `"Draft"`. Draft checks are not evaluated by Scans. |
| `owner_id` | No | ID of the user who owns the check. Defaults to the user creating the check when omitted. |
| `default_anomaly_assignee_id` | No | ID of the user automatically assigned to anomalies produced by the check. |

Two payload fields exist for other rule types but do not apply here:

- Omit `coverage` or send `1`. The rule asserts a single boolean condition between two aggregates, so there is no per-row violation rate to set.
- `anomaly_message_field` is ignored. Aggregation Comparison emits Shape Anomalies only, and Shape Anomalies always use the fixed message.

## Read

**Endpoint:** `GET /api/quality-checks/{id}`

**Permission:** Member role + **Reporter** team permission on the check's datastore.

> **Example: Retrieve a check by ID**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/quality-checks/101" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

## Update

**Endpoint:** `PUT /api/quality-checks/{id}`

**Permission:** Member role + **Author** team permission on the check's datastore (**Drafter** when the check stays Draft).

The `PUT` endpoint requires `description` and the whole `properties` object on every request, even when you only change the status, tags, or metadata. Include the check's current description (or a new one) and its current properties along with what you want to change. Partial property updates are not merged.

> **Example: Switch the operator and rewrite the reference aggregation**
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "description": "Order totals must not exceed the line-item roll-up.",
>     "properties": {
>         "expression": "ROUND(SUM(o_totalprice))",
>         "comparison": "lte",
>         "ref_container_id": 178,
>         "ref_expression": "ROUND(SUM(l_extendedprice))",
>         "ref_filter": "l_shipdate >= current_date() - INTERVAL 1 DAY"
>     }
>   }'
> ```

A `PUT` can update most fields on an existing Aggregation Comparison check. Three values stay immutable: the rule type, the target container the check is attached to, and the associated Check Template. If any of these needs to change, delete the check and create a new one. The reference container is not immutable: it is part of `properties` and can be repointed.

> **Info: Editable vs Immutable on PUT**
>
> **Editable**
>
> - `description`
> - `filter`
> - `properties.expression`
> - `properties.comparison`
> - `properties.ref_datastore_id`
> - `properties.ref_container_id`
> - `properties.ref_expression`
> - `properties.ref_filter`
> - `tags`
> - `additional_metadata`
> - `status`
> - `owner_id`
> - `default_anomaly_assignee_id`
>
> **Immutable**
>
> - `rule`
> - `container_id`
> - `template_id`

## Delete

**Endpoint:** `DELETE /api/quality-checks/{id}`

**Permission:** Member role + **Author** team permission on the check's datastore.

Three query parameters control what happens, mirroring the two-stage flow in the UI:

| Parameter | Default | Description |
| --- | --- | --- |
| `archive` | `true` | When `true`, the check is archived and can be restored later. When `false`, the check is permanently deleted. |
| `status` | `Discarded` | The archive resolution: `Discarded` (no longer relevant) or `Invalid` (wrong and suppressed from future AI generation). Only used when `archive=true`. |
| `delete_anomalies` | `true` | Whether to permanently delete the anomalies the check produced. A permanent delete (`archive=false`) always removes them. |

> **Example: Archive a check, keeping its anomalies**
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=true&status=Discarded&delete_anomalies=false" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

> **Example: Delete a check permanently**
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=false" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

## Error responses

| Status | Description |
| --- | --- |
| `400 Bad Request` | A business-logic conflict prevents the operation (for example, changing properties while the check is archived, or switching an archived check between `Discarded` and `Invalid`). |
| `401 Unauthorized` | Missing or invalid API token. |
| `403 Forbidden` | The caller lacks the required team permission on the check's datastore, or on the reference container's datastore. |
| `404 Not Found` | The check ID, the reference datastore, or the reference container does not exist, or a name in `fields` is not a field on the target container. |
| `409 Conflict` | Either a name in `fields` is a field on the target container that is no longer active, or an Active Aggregation Comparison check with the same expressions, comparison, reference container and filters already exists on the container. The `detail` message says which. A different `fields` list does not make a check distinct. |
| `422 Unprocessable Entity` | The payload fails schema validation (for example, `description` missing on `PUT`, an unknown `comparison` value, or a missing `ref_expression`). |

*Last updated: October 5, 2026.*
