Skip to content

Data Diff Check API

This page documents how to create and manage a Data Diff check via the REST API. The check uses the standard Quality Checks endpoints: set rule to dataDiff, list the compared fields under fields, and configure the reference container and matching behavior under properties. 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.

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 for the full matrix.

The properties object

Data Diff carries the reference target and the matching behavior under properties:

Field Required Type Description
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 (table, view, or file) compared against the target.
ref_filter No string SQL WHERE expression applied to the reference container before the comparison. Accepts Check Variables.
id_field_names No array Field names forming the key that pairs target rows with reference rows. Required to produce changed diffs and to enable the Comparison Source Records view. Omit (or send []) to fall back to a set difference that produces only added and removed.
passthrough_field_names No array Extra field names carried into the comparison output for context. They are displayed but never compared, so they never cause an anomaly.
diff_change_types No array Subset of ["added", "removed", "changed"] that restricts which statuses produce an anomaly. Defaults to all three. An empty list is rejected; at least one status must be selected. Requires id_field_names. See Restricting Anomalies by Status.
numeric_comparator No object Tolerance applied when comparing numeric fields. See Comparators.
duration_comparator No object Tolerance applied when comparing date and timestamp fields. See Comparators.
string_comparator No object Normalization applied when comparing string fields. See Comparators.

Create

Endpoint: POST /api/quality-checks

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

Create a Data Diff check (every accepted field) 
curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ensure NATION matches NATION_BACKUP on N_NATIONKEY and N_NATIONNAME",
    "rule": "dataDiff",
    "fields": ["N_NATIONKEY", "N_NATIONNAME"],
    "container_id": 145,
    "filter": null,
    "properties": {
        "ref_datastore_id": 22,
        "ref_container_id": 803,
        "id_field_names": ["N_NATIONKEY"],
        "passthrough_field_names": [],
        "diff_change_types": ["added", "changed"]
    },
    "tags": ["replication"],
    "additional_metadata": {"jira": "DATA-1234"},
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 12
  }'

This payload sets diff_change_types to ["added", "changed"] so unmatched reference rows, which arrive as removed, are not reported, a typical choice when the reference is a superset of the target (such as a long-lived backup).

Field notes

Field Required Notes
description Yes Free-text description shown in the UI.
rule Yes Must be "dataDiff".
fields Yes Array of field names compared between target and reference. Order does not affect evaluation. Every field must exist on both containers.
container_id Yes ID of the target container (the dataset the check runs on).
filter No SQL WHERE expression applied to the target container before matching. Send null for no filter. Scope the reference side with properties.ref_filter.
properties Yes Object holding the reference target and matching behavior. See above.
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. When omitted, anomalies are created unassigned.

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

  • coverage is ignored. Data Diff reports any difference that a Comparator does not tolerate; there is no per-row violation rate.
  • anomaly_message_field is ignored. Data Diff emits a Shape Anomaly 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.

Retrieve a check by ID 
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; include the check's current description (or a new one) along with the fields you want to change. Send the whole properties object: partial property updates are not merged.

Narrow the reported change types 
curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ensure NATION matches NATION_BACKUP on N_NATIONKEY and N_NATIONNAME",
    "properties": {
        "ref_datastore_id": 22,
        "ref_container_id": 803,
        "id_field_names": ["N_NATIONKEY"],
        "diff_change_types": ["changed"]
    }
  }'

A PUT can update most fields on an existing Data Diff 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.

Editable vs Immutable on PUT

Editable

  • description
  • fields (the compared fields)
  • filter
  • properties.ref_datastore_id
  • properties.ref_container_id
  • properties.ref_filter
  • properties.id_field_names
  • properties.passthrough_field_names
  • properties.diff_change_types
  • properties.numeric_comparator
  • properties.duration_comparator
  • properties.string_comparator
  • 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.
Archive a check, keeping its anomalies 
curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=true&status=Discarded&delete_anomalies=false" \
  -H "Authorization: Bearer YOUR_TOKEN"
Delete a check permanently 
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.
422 Unprocessable Entity The payload fails schema validation (for example, description missing on PUT, an empty diff_change_types list, or a field that does not exist on one of the containers).