Skip to content

Custom Quality Checks

A custom quality check is a SQL check that you define once and use by its ID from the quality rules of any data contract. Instead of copying the same SQL into many contracts, a team maintains the check in one place, and a change takes effect in every data contract that uses it on its next test run.

Custom quality checks are listed under Governance → Custom Quality Checks (/{organization}/governance/customqualitychecks).

The list

The list shows every custom quality check of the organization with its name, owner, the SQL dialects it has queries for, and how many data contracts use it (Used in). A check that is no longer valid is marked Invalid. Filter the list by Owner and by Dialect.

Open a check to see:

  • Info: name, ID, owner, description, dimension, and expected result.
  • Arguments: the values a quality rule passes in, with their types and defaults. Arguments without a default are marked as required.
  • Queries: one query per SQL dialect.
  • How to use: a quality rule to copy into a data contract.
  • Usages: the data contracts that use the check, where in the contract, and usages with errors, such as missing or unknown arguments.
  • Audit Trail: every change, with Compare Versions to see two versions side by side.

Add a custom quality check

Click Add Custom Quality Check and choose Add in Web UI or Add as YAML.

  1. Enter a Name, such as "Value range". It is what a quality rule using the check is called, unless the rule sets its own name.
  2. Enter the ID. Quality rules refer to the check by this ID. IDs are unique regardless of case and must not contain spaces, slashes, or any of the characters \ % ; # ?.
  3. Choose the owning team.
  4. Optionally enter a Description and a Dimension.
  5. Add Arguments if the check takes values from the quality rule.
  6. Add the Queries, starting with the default dialect.
  7. Optionally set the Expected result.
  8. Save.

Adding a check takes the CUSTOM_QUALITY_CHECK_ADD permission on the owning team, editing it CUSTOM_QUALITY_CHECK_EDIT, and deleting it CUSTOM_QUALITY_CHECK_DELETE. By default, the Owner, Approver, and Editor roles hold all three.

The custom quality check format

In YAML, a custom quality check has the same format as a file in a custom quality checks folder of the Data Contract CLI. The ID is the file name without .yaml.

name: "Value range"
description: "${column} is between ${arguments.min} and ${arguments.max}"
owner: "data-platform"
dimension: "accuracy"
arguments:
  min:
    type: "number"
    default: 0
  max:
    type: "number"
queries:
  default: |
    SELECT COUNT(*) FROM ${table}
    WHERE ${column} < ${arguments.min} OR ${column} > ${arguments.max}
  snowflake: |
    SELECT COUNT_IF(${column} NOT BETWEEN ${arguments.min} AND ${arguments.max}) FROM ${table}
mustBe: 0
FieldDescription
nameWhat a quality rule using the check is called, unless it sets its own name.
descriptionNames each check of a test run. It may use the placeholders and the arguments of the queries.
ownerThe ID of the team that owns the check. Required.
dimensionThe quality dimension a quality rule gets when it sets none: accuracy, completeness, conformity, consistency, coverage, timeliness, or uniqueness.
argumentsThe values a quality rule passes in, by name. Each has a type and an optional default. An argument without a default is required in every quality rule. A default is read as YAML, so 1 is a number.
queriesOne query per SQL dialect, at least one. Required. See Queries.
mustBe, mustNotBe, mustBeGreaterThan, mustBeGreaterOrEqualTo, mustBeLessThan, mustBeLessOrEqualTo, mustBeBetween, mustNotBeBetweenThe expected result: what the query has to return. At most one. A quality rule that sets its own expected result replaces it. Without one, every quality rule has to set it.

Arguments

TypeDescription
anyA literal value, or a list of values. The default type.
numberA number.
identifierThe name of one column or table.

The former type value is now called any.

Queries

A query returns one number. A test runs the query for the SQL dialect of the server, and otherwise the default query. Write the default query in ANSI SQL: Entropy Data warns about statements that are not ANSI SQL, unbalanced parentheses, unclosed quotes, and more than one statement. The dialects are those of the Data Contract CLI: athena, bigquery, clickhouse, databricks, duckdb, exasol, hive, oracle, postgres, redshift, snowflake, spark, trino, and tsql. The dialect ansi is called default in Entropy Data.

Queries can use these placeholders:

PlaceholderReplaced with
${table} (also ${model}, ${object}, ${schema}, ${dataset}, ${project}, ${catalog}, ${database})The table the quality rule belongs to.
${column} (also ${field}, ${property})The column the quality rule belongs to. A check that uses it only works on a property, not on a schema.
${arguments.<name>}The value of an argument.

Variables of the data contract are not resolved in custom quality checks.

Use a check in a data contract

Add a quality rule of type custom with the engine datacontract-cli to a schema or a property of the data contract, and name the check by its ID in implementation.check. Pass the arguments in implementation.arguments:

schema:
  - name: "orders"
    properties:
      - name: "discount_percent"
        quality:
          - type: "custom"
            engine: "datacontract-cli"
            implementation:
              check: "value-range"
              arguments:
                max: 100

The How to use section of a check shows this rule for the check, with its required arguments. In the Data Contract Editor, the organization's custom quality checks are suggested for quality rules that use one.

The data contract page shows each such quality rule with the name of its check, and tells you when the Data Contract CLI would report the rule as an error or warn about it: the check does not exist or is invalid, required arguments are missing or unknown ones are passed, an argument value has the wrong type, a check that needs a column is used on a schema, there is no expected result, or the rule is on an array item, where checks do not run.

Run custom quality checks

Custom quality checks run wherever the data contract is tested, by the Data Contract CLI. The CLI reads each check from Entropy Data with GET /api/custom-quality-checks/{id}/check.yaml:

  • In the UI: when you click Run Data Contract Test, Entropy Data passes its host and a read-only API key to the CLI server, so the CLI can read the checks.
  • With the CLI: datacontract test reads the checks when it is connected to Entropy Data with ENTROPY_DATA_API_KEY. Any API key of the organization may read the checks.

Change or delete a check

Changing a check takes effect in every data contract that uses it on its next test run. If a change would break quality rules, for example because it renames the ID or adds a required argument, Entropy Data lists the affected quality rules and asks you to confirm with Save anyway. Data contracts keep the old ID, so after a rename their quality rules no longer find the check.

Deleting a check shows how many data contracts use it. Their quality rules no longer find the check and have errors. The deletion cannot be undone.