Skip to content

Manage check templates

Goal

Treat a curated set of quality checks as reusable templates that can be applied across many containers or datastores. Templates are how teams enforce "every PII column must have these checks" or "every transactional table must have a freshness check" without copy-pasting check definitions everywhere.

Permissions

Step Endpoint Role Team permission
Export templates GET /api/quality-check-templates Member N/A
Import templates (create) POST /api/quality-check-templates Manager N/A
Apply template to a check POST /api/quality-checks/{id}/template Manager N/A

Template management is Manager-only

Creating templates and applying them programmatically requires the Manager global role. Plain Member users can only view templates.

Prerequisites

  • The CLI is installed and authenticated with a Manager token.
  • Optionally: an enrichment datastore configured if you want to export templates as data records (rather than a local file).

CLI workflow

graph LR
    Export[checks export-templates] --> File[templates.yaml]
    File --> Review[Review / edit]
    Review --> Import[checks import-templates]
    Import --> Templates[(Templates in target instance)]

1. Export templates from the source instance

# To a local YAML file
qualytics checks export-templates --output ./templates/golden.yaml

# Filter by rule types and tags
qualytics checks export-templates \
    --output ./templates/pii.yaml \
    --rules "isNotNull,matchesPattern" \
    --tags "pii"

2. (Optional) Edit the file

The exported YAML is a list of templates with their full definitions. You can hand-edit them before re-importing. Keep the _qualytics_check_uid if present so updates are idempotent.

3. Import templates to the target instance

qualytics checks import-templates --input ./templates/pii.yaml

4. Use templates in checks create

Reference a template by name when creating a new check, and the CLI fills in the rule type and properties from the template:

# checks/from-template.yaml
- template: pii-email-format
  container: customers
  fields: [email]
  status: Active

qualytics checks create --datastore-id 42 --file ./checks/from-template.yaml

Behind the scenes

CLI step Method Path Notes
checks export-templates GET /api/quality-check-templates Paginated; the CLI walks all pages.
checks export-templates --enrichment_datastore_id POST /api/operations/run (export) Writes templates as records to the enrichment datastore.
checks import-templates POST /api/quality-check-templates One call per template in the file. Create-only: existing templates are not updated.

Python equivalent

import os
import yaml
import httpx

BASE_URL = os.environ["QUALYTICS_URL"].rstrip("/")
TOKEN    = os.environ["QUALYTICS_TOKEN"]
HEADERS  = {"Authorization": f"Bearer {TOKEN}"}

with httpx.Client(headers=HEADERS, timeout=30.0) as client:
    # Export
    r = client.get(f"{BASE_URL}/api/quality-check-templates")
    r.raise_for_status()
    templates = r.json()
    with open("./templates/golden.yaml", "w") as f:
        yaml.safe_dump(templates, f, sort_keys=False)

    # Import (create-only)
    with open("./templates/golden.yaml") as f:
        for tpl in yaml.safe_load(f):
            try:
                client.post(
                    f"{BASE_URL}/api/quality-check-templates", json=tpl
                ).raise_for_status()
            except httpx.HTTPStatusError as e:
                if e.response.status_code == 409:
                    print(f"skip (exists): {tpl['name']}")
                else:
                    raise

Variations and advanced usage

Lock a template

In the web app, a template can be locked. Locked templates can't be edited, only applied. Useful for compliance-mandated rule sets.

qualytics checks export-templates --status true   # locked templates only
qualytics checks export-templates --status false  # unlocked only

Export to enrichment datastore for downstream analytics

qualytics checks export-templates --enrichment_datastore_id 10

The templates are written as records into the enrichment datastore. Useful if you want to track template usage and changes as part of your data pipeline.

Apply a template to many containers in one operation

This is a web-app-only operation today (apply-template-to-multiple-containers). See Apply Check Template.

Troubleshooting

Symptom Likely cause Fix
import-templates reports 0 created Templates with the same name already exist Imports are create-only; use the web app to update an existing template, or rename the new one.
403 on import-templates Token has Member role Use a Manager or Admin token.
Template references a rule type the target instance doesn't support Different Qualytics versions between source and target Upgrade the target instance, or remove unsupported templates from the YAML.
Imported template doesn't appear in the web app UI cache Refresh the page; templates list updates immediately on import.