Skip to content

Aggregation Comparison Check API

The Aggregation Comparison check is created and managed through the standard Quality Checks API by setting rule to aggregationComparison and providing both aggregation expressions plus the comparison operator under properties. The check evaluates one aggregate per side and compares them, so the fields array is not used.

Tip

For complete API documentation, including request and response schemas, visit the API docs.

Endpoints

Method Path Purpose
POST /api/quality-checks Create a new Aggregation Comparison check.
GET /api/quality-checks/{id} Retrieve an Aggregation Comparison check by ID.
PUT /api/quality-checks/{id} Update an existing Aggregation Comparison check.
DELETE /api/quality-checks/{id} Delete (or archive) an Aggregation Comparison check.

Permissions (on the target container's team):

  • POST and PUT for an Active check: Author team permission (or above).
  • POST and PUT for a Draft check: Drafter team permission (or above).
  • DELETE: Author team permission (or above).
  • GET: Reporter team permission (or above).

The team-permission hierarchy is Editor > Author > Drafter > Viewer > Reporter. "Or above" includes every higher level.

Payload Example

Create an Aggregation Comparison check on the orders container that asserts ROUND(SUM(o_totalprice)) equals the same roll-up evaluated against the lineitem container in the same datastore. The payload below shows every field accepted by the create endpoint:

{
    "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, include ref_datastore_id in the properties block. Leave it out (or set to null) when the reference container lives in the same datastore as the target.

Field Notes

Field Required Notes
description Yes Free-text description shown in the UI.
rule Yes Must be "aggregationComparison".
fields No Aggregation Comparison does not select columns. Send an empty array [] or omit.
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 the breakdown below.
properties.expression Yes The target aggregation expression. Must produce a single aggregate value. Supports Check Variables.
properties.comparison Yes One of lt, lte, eq, gte, gt.
properties.ref_datastore_id No Datastore ID for the reference container. Omit or send null when the reference container lives in the same datastore as the target.
properties.ref_container_id Yes Container ID for the reference data.
properties.ref_expression Yes The reference aggregation expression. Must produce a single aggregate value. Supports Check Variables.
properties.ref_filter No SQL WHERE expression applied to the reference container before the reference aggregation runs. Send null for no filter.
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 to Aggregation Comparison:

  • coverage is ignored. The rule asserts a single boolean condition between two aggregates and has no per-row violation rate.
  • anomaly_message_field is ignored. Aggregation Comparison emits Shape Anomalies only, and Shape Anomalies always use the fixed template.

What PUT Can Change

A PUT to /api/quality-checks/{id} can update most fields on an existing Aggregation Comparison check. Three values stay immutable: the rule type, the 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.

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
  • Introduction: formal definition, field scope, and general/anomaly properties.
  • How It Works: full semantics, NULL handling, filter behavior, and anomaly templates.
  • Examples: three production scenarios with sample data and resulting anomalies.
  • FAQ: short answers to the most frequent questions.