datacontract-cli 1.2.3__tar.gz → 1.2.4__tar.gz

{datacontract_cli-1.2.3/datacontract_cli.egg-info → datacontract_cli-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacontract-cli
-Version: 1.2.3
+Version: 1.2.4
 Summary: The datacontract CLI is an open source command-line tool for working with Data Contracts. It uses data contract YAML files to lint the data contract, connect to data sources and execute schema and quality tests, detect breaking changes, and export to different formats. The tool is written in Python. It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a Python library.
 Author-email: Jochen Christ <jochen.christ@entropy-data.com>, Stefan Negele <stefan.negele@innoq.com>, Simon Harrer <simon.harrer@entropy-data.com>
 License-Expression: MIT
@@ -40,7 +40,7 @@ Requires-Dist: jsonschema<5.0.0,>=4.23.0
 Requires-Dist: pytz>=2024.1
 Requires-Dist: python-multipart<1.0.0,>=0.0.20
 Requires-Dist: rich<16.0,>=13.7
-Requires-Dist: sqlglot<30.18,>=26.6.0
+Requires-Dist: sqlglot<31.0.0,>=26.6.0
 Requires-Dist: python-dotenv<2.0.0,>=1.0.0
 Requires-Dist: boto3<2.0.0,>=1.34.41
 Requires-Dist: Jinja2<4.0.0,>=3.1.5
@@ -104,7 +104,7 @@ Requires-Dist: duckdb-extension-azure<1.6.0,>=1.5.0; extra == "azure"
 Requires-Dist: azure-identity<1.26,>=1.17.1; extra == "azure"
 Requires-Dist: azure-storage-blob<12.31,>=12.24; extra == "azure"
 Provides-Extra: snowflake
-Requires-Dist: snowflake-connector-python[pandas]<4.8,>=3.6; extra == "snowflake"
+Requires-Dist: snowflake-connector-python[pandas]<4.9,>=3.6; extra == "snowflake"
 Requires-Dist: ibis-framework[snowflake]<13.0.0,>=10.0.0; extra == "snowflake"
 Provides-Extra: sqlserver
 Requires-Dist: ibis-framework[mssql]<13.0.0,>=10.0.0; extra == "sqlserver"
@@ -141,7 +141,7 @@ Requires-Dist: pyarrow>=18.1.0; extra == "parquet"
 Provides-Extra: rdf
 Requires-Dist: rdflib==7.6.0; extra == "rdf"
 Provides-Extra: api
-Requires-Dist: fastapi<0.142.0,>=0.115.0; extra == "api"
+Requires-Dist: fastapi<0.143.0,>=0.115.0; extra == "api"
 Requires-Dist: uvicorn<0.55.0,>=0.44.0; extra == "api"
 Provides-Extra: protobuf
 Requires-Dist: proto-schema-parser<3.0,>=1.0; extra == "protobuf"
@@ -161,10 +161,10 @@ Requires-Dist: pre-commit<4.7.0,>=3.7.1; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-xdist; extra == "dev"
-Requires-Dist: pymssql==2.4.1; extra == "dev"
+Requires-Dist: pymssql==2.4.2; extra == "dev"
 Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "dev"
 Requires-Dist: mysql-connector-python<26.8.0,>=8.0.30; extra == "dev"
-Requires-Dist: ruff==0.16.9; extra == "dev"
+Requires-Dist: ruff==0.16.10; extra == "dev"
 Requires-Dist: testcontainers[kafka,minio,mssql,mysql,postgres]==4.15.0; extra == "dev"
 Requires-Dist: trino==0.339.0; extra == "dev"
 Dynamic: license-file
@@ -256,7 +256,7 @@ Server: production (type=postgres, host=aws-1-eu-central-2.pooler.supabase.com,
 │ passed │ Check that field order_total has physical type INTEGER            │ orders.order_total      │         │
 │ passed │ Check that field order_total has no missing values                │ orders.order_total      │         │
 ╰────────┴───────────────────────────────────────────────────────────────────┴─────────────────────────┴─────────╯
-🟢 Data contract is valid. Run 30 checks. Took 2.504495 seconds.
+🟢 Data contract is valid. Ran 30 checks. Took 2.504495 seconds.
 ```
 
 Voilà, the CLI tested that the YAML itself is valid, all records comply with the schema, and all quality attributes are met.

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/README.md

@@ -85,7 +85,7 @@ Server: production (type=postgres, host=aws-1-eu-central-2.pooler.supabase.com,
 │ passed │ Check that field order_total has physical type INTEGER            │ orders.order_total      │         │
 │ passed │ Check that field order_total has no missing values                │ orders.order_total      │         │
 ╰────────┴───────────────────────────────────────────────────────────────────┴─────────────────────────┴─────────╯
-🟢 Data contract is valid. Run 30 checks. Took 2.504495 seconds.
+🟢 Data contract is valid. Ran 30 checks. Took 2.504495 seconds.
 ```
 
 Voilà, the CLI tested that the YAML itself is valid, all records comply with the schema, and all quality attributes are met.

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/api.py

@@ -449,7 +449,8 @@ def config_from_headers(headers) -> "Config | None":
     → ``DATACONTRACT_SNOWFLAKE_PASSWORD``, ``entropy-data-api-key`` →
     ``ENTROPY_DATA_API_KEY``. Returns None when no config headers are present,
     so env-var-configured deployments behave exactly as before. Unknown
-    ``datacontract-*`` option names are rejected with a 400.
+    ``datacontract-*`` option names are rejected with a 400, and so is the
+    custom quality checks folder.
     """
     known = known_env_names()
     values = {}
@@ -457,6 +458,12 @@ def config_from_headers(headers) -> "Config | None":
         lowered = name.lower()
         env = lowered.upper().replace("-", "_")
         if lowered.startswith(_CONFIG_HEADER_PREFIX) or env in known:
+            if env == "DATACONTRACT_CUSTOM_QUALITY_CHECKS":
+                # A folder on the server's disk is the operator's to choose, never the caller's.
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="The custom quality checks folder is configured by the API server, not per request.",
+                )
             values[env] = value
     if not values:
         return None

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/cli.py

@@ -15,7 +15,7 @@ from rich.markup import escape
 from typer.core import TyperGroup
 from typing_extensions import Annotated
 
-from datacontract.config import Config, set_cli_config
+from datacontract.config import Config, cli_config, set_cli_config
 from datacontract.output.output_format import OutputFormat
 
 console = Console()
@@ -31,6 +31,23 @@ inline_references_option = Annotated[
     ),
 ]
 
+custom_quality_checks_option = Annotated[
+    Optional[Path],
+    typer.Option(
+        metavar="DIR",
+        help="Folder with the custom quality checks the contract's quality rules use, one YAML file per check. "
+        "Defaults to DATACONTRACT_CUSTOM_QUALITY_CHECKS.",
+    ),
+]
+
+
+def config_with_custom_quality_checks(custom_quality_checks: Optional[Path]) -> Config | None:
+    """The --config-file config, with the --custom-quality-checks folder if one was given."""
+    config = cli_config()
+    if custom_quality_checks is None:
+        return config
+    return Config.resolve(config).model_copy(update={"custom_quality_checks": str(custom_quality_checks)})
+
 
 # Order in which top-level commands appear in `datacontract --help` (cf. README.md)
 COMMAND_ORDER = [
@@ -130,6 +147,8 @@ app = typer.Typer(
     cls=OrderedCommandsWithMigrationHints,
     no_args_is_help=True,
     add_completion=False,
+    # the locals of a --debug traceback can hold credentials
+    pretty_exceptions_show_locals=False,
     help="CLI to manage data contracts. Documentation: https://docs.datacontract.com",
     epilog="Read the full documentation at https://docs.datacontract.com",
 )

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/command_ci.py

@@ -10,14 +10,15 @@ from datacontract.cli import (
     _print_logs,
     _print_publish_failure,
     app,
+    config_with_custom_quality_checks,
     console,
+    custom_quality_checks_option,
     debug_option,
     enable_debug_logging,
     inline_references_option,
     resolve_output_format,
     validate_publish_url,
 )
-from datacontract.config import cli_config
 from datacontract.data_contract import DataContract
 from datacontract.output.ci_output import write_ci_output, write_ci_summary, write_json_results
 from datacontract.output.output_format import OutputFormat
@@ -80,6 +81,7 @@ def ci(
         bool,
         typer.Option(help="SSL verification when publishing the data contract."),
     ] = True,
+    custom_quality_checks: custom_quality_checks_option = None,
     inline_references: inline_references_option = True,
     debug: debug_option = None,
 ):
@@ -104,6 +106,7 @@ def ci(
     # Plain text output for CI logs; --json sends human output to stderr.
     out = Console(stderr=True, no_color=True) if json_output else Console(no_color=True)
 
+    config = config_with_custom_quality_checks(custom_quality_checks)
     results = []
     fail_results = {
         "warning": {"warning", "failed", "error"},
@@ -115,7 +118,7 @@ def ci(
     for location in locations:
         out.print(f"Testing {location}")
         run = DataContract(
-            config=cli_config(),
+            config=config,
             data_contract_file=location,
             schema_location=schema,
             publish_url=publish,

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/command_test.py

@@ -10,7 +10,9 @@ from datacontract.cli import (
     _print_logs,
     _print_publish_failure,
     app,
+    config_with_custom_quality_checks,
     console,
+    custom_quality_checks_option,
     debug_option,
     enable_debug_logging,
     inline_references_option,
@@ -200,6 +202,7 @@ def test(
         bool,
         typer.Option(help="SSL verification when publishing the data contract."),
     ] = True,
+    custom_quality_checks: custom_quality_checks_option = None,
     inline_references: inline_references_option = True,
     debug: debug_option = None,
 ):
@@ -231,7 +234,7 @@ def test(
     if server == "all":
         server = None
     run = DataContract(
-        config=cli_config(),
+        config=config_with_custom_quality_checks(custom_quality_checks),
         data_contract_file=location,
         schema_location=schema,
         publish_test_results=publish_test_results,

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/config/settings.py

@@ -110,6 +110,7 @@ class Config(BaseSettings):
 
     # general
     api_header_authorization: SecretStr | None = None
+    custom_quality_checks: str | None = None
     max_errors: int | None = None
 
     # athena (credentials come from the s3_* options)
@@ -521,6 +522,10 @@ class Config(BaseSettings):
     def get_api_header_authorization(self, required: bool = False) -> str | None:
         return self._str_option("api_header_authorization", required)
 
+    # --- custom quality checks ---
+    def get_custom_quality_checks(self) -> str | None:
+        return self._str_option("custom_quality_checks")
+
     # --- max ---
     def get_max_errors(self) -> int | None:
         return self._int_option("max_errors")

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/config/variables.py

@@ -231,26 +231,56 @@ _DEFERRED_FIELDS = {
 }
 
 
-def resolve_runtime_variables(value, source: str = "contract", variables: Optional[Mapping[str, str]] = None):
+# Compared with the value a query returns, so a whole reference keeps the type it reads as.
+_TYPED_FIELDS = {("DataQuality", "mustBe"), ("DataQuality", "mustNotBe")}
+_PLAIN_NUMBER = re.compile(r"-?(0|[1-9][0-9]*)(\.[0-9]+)?")
+
+
+def resolve_runtime_variables(
+    value, source: str = "contract", variables: Optional[Mapping[str, str]] = None, typed: bool = False
+):
     """Copy test inputs with variables resolved, recursively, without altering the contract.
 
     Handles property names/types, enum values, logical type options, library
     quality arguments, SLA values, and nested array/map definitions. Dictionary
-    keys are structural identifiers and are never interpolated.
+    keys are structural identifiers and are never interpolated. With ``typed``, a
+    value that is one whole reference becomes a number or boolean if its resolved
+    text is a plain one (``1000``, ``-2.5``, ``true``); ``007`` stays a string.
     """
     if isinstance(value, BaseModel):
         owner = type(value).__name__
         updates = {}
         for field in type(value).model_fields:
-            if field in _DEFERRED_FIELDS:
-                continue
             original = getattr(value, field)
             field_source = f"{source}.{_field_name(field)}"
-            resolved = resolve_runtime_variables(original, field_source, variables)
+            # A custom quality check's arguments are test inputs, like a library metric's.
+            if (
+                field == "implementation"
+                and getattr(value, "engine", None) == "datacontract-cli"
+                and isinstance(original, dict)
+                and "arguments" in original
+            ):
+                arguments = resolve_runtime_variables(original["arguments"], f"{field_source}.arguments", variables)
+                updates[field] = {**original, "arguments": arguments}
+                continue
+            if field in _DEFERRED_FIELDS:
+                continue
+            resolved = resolve_runtime_variables(original, field_source, variables, (owner, field) in _TYPED_FIELDS)
             updates[field] = _checked(original, resolved, owner, field, field_source)
         return value.model_copy(update=updates)
     if isinstance(value, dict):
-        return {key: resolve_runtime_variables(item, f"{source}.{key}", variables) for key, item in value.items()}
+        return {
+            key: resolve_runtime_variables(item, f"{source}.{key}", variables, typed) for key, item in value.items()
+        }
     if isinstance(value, list):
-        return [resolve_runtime_variables(item, f"{source}[{index}]", variables) for index, item in enumerate(value)]
-    return resolve_variables(value, source=source, variables=variables)
+        return [
+            resolve_runtime_variables(item, f"{source}[{index}]", variables, typed) for index, item in enumerate(value)
+        ]
+    resolved = resolve_variables(value, source=source, variables=variables)
+    if not typed or not isinstance(value, str) or not _VARIABLE.fullmatch(value):
+        return resolved
+    if _PLAIN_NUMBER.fullmatch(resolved):
+        return float(resolved) if "." in resolved else int(resolved)
+    if resolved in ("true", "false"):
+        return resolved == "true"
+    return resolved

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/engines/checks/check_spec.py

@@ -27,6 +27,7 @@ class MetricType(str, Enum):
     MISSING_COUNT = "missing_count"
     DUPLICATE_COUNT = "duplicate_count"
     INVALID_COUNT = "invalid_count"
+    MISSING_REFERENCE_COUNT = "missing_reference_count"
     FIELD_PRESENT = "field_present"
     FIELD_TYPE = "field_type"
     FIELD_PHYSICAL_TYPE = "field_physical_type"
@@ -158,10 +159,14 @@ class CheckSpec:
     expected_schema_property: Optional["SchemaProperty"] = None  # FIELD_TYPE: structural comparison
     expected_physical_type: Optional[str] = None  # FIELD_PHYSICAL_TYPE: contract physicalType
 
-    columns: Optional[List[str]] = None  # DUPLICATE_COUNT across multiple columns
+    columns: Optional[List[str]] = None  # DUPLICATE_COUNT across multiple columns; MISSING_REFERENCE_COUNT keys
+
+    referenced_model: Optional[str] = None  # MISSING_REFERENCE_COUNT
+    referenced_columns: Optional[List[str]] = None  # MISSING_REFERENCE_COUNT, pairwise with `columns`
 
     query: Optional[str] = None  # CUSTOM_SQL (placeholders already substituted)
     dialect: Optional[str] = None  # CUSTOM_SQL input SQL dialect
+    diagnostics: Optional[dict] = None  # CUSTOM_SQL: reported alongside the measured value
 
     seconds: Optional[int] = None  # FRESHNESS / RETENTION threshold in seconds
 

{datacontract_cli-1.2.3 → datacontract_cli-1.2.4}/datacontract/engines/checks/create_checks.py

@@ -25,6 +25,14 @@ from sqlglot import Dialect, exp
 
 from datacontract.config.variables import VariableError, contains_variables, resolve_variables
 from datacontract.engines.checks.check_spec import METADATA_METRICS, CheckSpec, MetricType, Op, Threshold
+from datacontract.engines.checks.custom_quality_check import (
+    COLUMN_PLACEHOLDERS,
+    ENGINE,
+    CustomQualityCheckUnusable,
+    Instance,
+    instantiate,
+    placeholder_pattern,
+)
 from datacontract.engines.checks.dimensions import default_dimension
 from datacontract.engines.checks.sql_guard import dialect_for_server_type, refusal_reason, sqlglot_dialect_by_name
 from datacontract.engines.checks.type_normalize import normalize_type_name
@@ -191,7 +199,11 @@ def to_threshold(quality: DataQuality) -> Optional[Threshold]:
 
 
 def prepare_query(
-    quality: DataQuality, model_name: str, field_name: Optional[str], server: Optional[Server]
+    query: Optional[str],
+    model_name: str,
+    field_name: Optional[str],
+    server: Optional[Server],
+    instance: Optional[Instance] = None,
 ) -> Optional[str]:
     """Substitute placeholders in a user SQL query.
 
@@ -199,8 +211,9 @@ def prepare_query(
     cannot read it bare, so a plain name keeps the backend's case-insensitive
     resolution. Quotes the author wrote around a placeholder are dropped, except
     that backticks force the name to be quoted (e.g. a reserved word on Spark).
+    For a custom quality check ``instance``, its arguments are substituted too.
     """
-    if not quality.query:
+    if not query:
         return None
 
     dialect = sqlglot_dialect_by_name(dialect_for_server_type(get_server_type(server)))
@@ -213,17 +226,21 @@ def prepare_query(
     for placeholder in ("dataset", "project", "catalog", "database"):
         names[placeholder] = (getattr(server, placeholder, None) if server else None) or model_name
     if field_name is not None:
-        names |= dict.fromkeys(("field", "column", "property"), field_name)
+        names |= dict.fromkeys(COLUMN_PLACEHOLDERS, field_name)
 
-    def identifier(match: re.Match) -> str:
-        forced = "`" in match.group(0)
+    def identifier(name: str, forced: bool) -> str:
         return ".".join(
             exp.to_identifier(part, quoted=forced or not bare.fullmatch(part)).sql(dialect=dialect)
-            for part in names[match.group(1)].split(".")
+            for part in name.split(".")
         )
 
+    if instance is not None:
+        return instance.render(dialect, names, identifier)
+
     # one pass, so a substituted name is not searched for placeholders again
-    return re.sub(rf"[\"'`]?\$?\{{({'|'.join(names)})}}[\"'`]?", identifier, quality.query)
+    return placeholder_pattern(list(names)).sub(
+        lambda match: identifier(names[match.group(1)], "`" in match.group(0)), query
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -234,6 +251,7 @@ def create_checks(
     server: Optional[Server],
     schema_name: str = "all",
     variables: Optional[Mapping[str, str]] = None,
+    custom_quality_checks: Optional[str] = None,
 ) -> List[CheckSpec]:
     checks: List[CheckSpec] = []
     if data_contract.schema_ is None:
@@ -244,7 +262,8 @@ def create_checks(
         if _is_azure_blob_schema(schema_obj, server):
             # File-metadata checks are emitted by check_azure_blob_file
             continue
-        checks.extend(_to_schema_checks(schema_obj, server, variables))
+        checks.extend(_to_schema_checks(schema_obj, server, variables, custom_quality_checks))
+        checks.extend(_relationship_checks(schema_obj, data_contract.schema_, server))
     checks.extend(_to_servicelevel_checks(data_contract, server))
     checks = [c for c in checks if c is not None]
     # Schema and service level checks cannot declare an ODCS dimension, so fill
@@ -260,7 +279,10 @@ def _is_azure_blob_schema(schema_object: SchemaObject, server: Optional[Server])
 
 
 def _to_schema_checks(
-    schema_object: SchemaObject, server: Optional[Server], variables: Optional[Mapping[str, str]] = None
+    schema_object: SchemaObject,
+    server: Optional[Server],
+    variables: Optional[Mapping[str, str]] = None,
+    custom_quality_checks: Optional[str] = None,
 ) -> List[CheckSpec]:
     checks: List[CheckSpec] = []
     server_type = get_server_type(server) if server is not None else None
@@ -575,7 +597,7 @@ def _to_schema_checks(
             )
 
         if prop.quality:
-            checks.extend(_quality_checks(model, field, prop.quality, server, variables))
+            checks.extend(_quality_checks(model, field, prop.quality, server, variables, custom_quality_checks))
 
         # A check the server cannot run is reported, not dropped.
         unenforced = []
@@ -613,11 +635,100 @@ def _to_schema_checks(
         )
 
     if schema_object.quality:
-        checks.extend(_quality_checks(model, None, schema_object.quality, server, variables))
+        checks.extend(_quality_checks(model, None, schema_object.quality, server, variables, custom_quality_checks))
 
     return checks
 
 
+def _relationship_checks(
+    schema_object: SchemaObject, schemas: List[SchemaObject], server: Optional[Server]
+) -> List[CheckSpec]:
+    """A foreign key holds when every non-null key in this model exists in the referenced model."""
+    server_type = get_server_type(server) if server is not None else None
+    model = to_schema_name(schema_object, server_type)
+    properties = schema_object.properties or []
+    declared = [(prop.name, rel) for prop in properties for rel in prop.relationships or []]
+    declared += [(None, rel) for rel in schema_object.relationships or []]
+
+    checks: List[CheckSpec] = []
+    for source, rel in declared:
+        if (rel.type or "foreignKey") != "foreignKey":
+            continue
+        sources = [source] if source is not None else rel.from_ if isinstance(rel.from_, list) else [rel.from_]
+        targets = rel.to if isinstance(rel.to, list) else [rel.to]
+        # `from` may repeat this schema's name; any other prefix is kept, so it matches no property.
+        source_names = [str(s).removeprefix(f"{schema_object.name}.") for s in sources if s]
+        parts = [str(t).rsplit(".", 1) for t in targets if t]
+        target_schema = next((s for s in schemas if parts and len(parts[0]) == 2 and s.name == parts[0][0]), None)
+
+        def physical(props, name):
+            prop = next((p for p in props or [] if p.name == name), None)
+            return None if prop is None else prop.physicalName or prop.name
+
+        columns = [physical(properties, name) for name in source_names]
+        referenced = [
+            physical(target_schema.properties, part[-1])
+            if target_schema is not None and part[0] == target_schema.name
+            else None
+            for part in parts
+        ]
+        label = ", ".join(source_names) or "?"
+        if not columns or None in columns + referenced or len(referenced) != len(columns):
+            target_label = ", ".join(str(t) for t in targets)
+            if not columns or len(parts) != len(columns):
+                cause = "its from and to lists differ in length"
+            elif None in columns:
+                cause = f"{schema_object.name} has no property {source_names[columns.index(None)]}"
+            elif any(len(part) == 1 for part in parts):
+                cause = f"{next(part[0] for part in parts if len(part) == 1)} is not a schema.property reference"
+            elif target_schema is None:
+                cause = f"the contract has no schema {parts[0][0]}"
+            elif any(part[0] != target_schema.name for part in parts):
+                cause = "a composite key must reference a single schema"
+            else:
+                cause = f"{target_schema.name} has no property {parts[referenced.index(None)][-1]}"
+            checks.append(
+                CheckSpec(
+                    key=f"{model}__{'__'.join(source_names)}__{'__'.join('__'.join(p) for p in parts)}"
+                    "__field_relationships",
+                    category="schema",
+                    type="field_relationships",
+                    name=f"Check that {label} has no values missing from {target_label}",
+                    model=model,
+                    field=source_names[0] if len(source_names) == 1 else None,
+                    metric=MetricType.UNSUPPORTED,
+                    preset_result="warning",
+                    preset_reason=f"The relationship from {label} to {target_label} is not checked: {cause}.",
+                )
+            )
+            continue
+
+        referenced_model = to_schema_name(target_schema, server_type)
+        if len(columns) == 1:
+            name = f"Check that field {columns[0]} has no values missing from {referenced_model}.{referenced[0]}"
+        else:
+            name = (
+                f"Check that ({', '.join(columns)}) has no values missing from "
+                f"{referenced_model} ({', '.join(referenced)})"
+            )
+        checks.append(
+            CheckSpec(
+                key=f"{model}__{'__'.join(columns)}__{referenced_model}__{'__'.join(referenced)}__field_relationships",
+                category="schema",
+                type="field_relationships",
+                name=name,
+                model=model,
+                field=columns[0] if len(columns) == 1 else None,
+                metric=MetricType.MISSING_REFERENCE_COUNT,
+                threshold=Threshold(Op.EQ, 0),
+                columns=columns,
+                referenced_model=referenced_model,
+                referenced_columns=referenced,
+            )
+        )
+    return checks
+
+
 # ---------------------------------------------------------------------------
 # metric-check builders (preserve legacy keys / types)
 # ---------------------------------------------------------------------------
@@ -719,10 +830,11 @@ def _quality_checks(
     quality_list: List[DataQuality],
     server: Optional[Server],
     variables: Optional[Mapping[str, str]] = None,
+    custom_quality_checks: Optional[str] = None,
 ) -> List[CheckSpec]:
     checks: List[CheckSpec] = []
     for count, quality in enumerate(quality_list):
-        rule_checks = _quality_rule_checks(model, field, quality, count, server, variables)
+        rule_checks = _quality_rule_checks(model, field, quality, count, server, variables, custom_quality_checks)
         # Every check keeps a link back to the rule that declared it, so that
         # `test --quality-id` / `test --tag` can select it.
         for check in rule_checks:
@@ -782,6 +894,8 @@ def _unexecuted_check(
     quality: DataQuality,
     reason: str,
     result: str = "warning",
+    name: Optional[str] = None,
+    dimension: Optional[str] = None,
 ) -> List[CheckSpec]:
     """A rule the engine cannot run, reported rather than dropped."""
     return [
@@ -789,11 +903,11 @@ def _unexecuted_check(
             key=check_key,
             category="quality",
             type=check_type,
-            name=quality.description or unexecuted_check_name(model, field),
+            name=name or quality.description or unexecuted_check_name(model, field),
             model=model,
             field=field,
             metric=MetricType.UNSUPPORTED,
-            dimension=quality.dimension,
+            dimension=dimension or quality.dimension,
             severity=quality.severity,
             preset_result=result,
             preset_reason=reason,
@@ -801,6 +915,14 @@ def _unexecuted_check(
     ]
 
 
+def _array_item_reason(field: str) -> str:
+    return (
+        f"'{field}' is an array item, not a column, so it cannot be substituted into a query. "
+        f"Declare the rule on '{field.split('[]')[0]}' instead and match the elements with array "
+        f"functions, for example size(filter(...)) > 0."
+    )
+
+
 def _quality_rule_checks(
     model: str,
     field: Optional[str],
@@ -808,6 +930,7 @@ def _quality_rule_checks(
     count: int,
     server: Optional[Server],
     variables: Optional[Mapping[str, str]] = None,
+    custom_quality_checks: Optional[str] = None,
 ) -> List[CheckSpec]:
     """The checks of a single ODCS quality rule (``count`` is its index in the list)."""
     if quality.type == "custom" and quality.engine == "soda" and quality.implementation:
@@ -828,6 +951,45 @@ def _quality_rule_checks(
                 ),
             )
         ]
+    if quality.type == "custom" and quality.engine == ENGINE:
+        if field is None:
+            check_key = f"{model}__quality_custom_check_{count}"
+            check_type = "model_quality_custom"
+        else:
+            check_key = f"{model}__{field}__quality_custom_check_{count}"
+            check_type = "field_quality_custom"
+        if field is not None and "[]" in field:
+            return _unexecuted_check(check_key, check_type, model, field, quality, _array_item_reason(field))
+        dialect = dialect_for_server_type(get_server_type(server))
+        try:
+            instance = instantiate(quality, model, field, dialect, custom_quality_checks)
+            query = prepare_query(instance.query, model, field, server, instance)
+        except CustomQualityCheckUnusable as e:
+            return _unexecuted_check(
+                check_key, check_type, model, field, quality, e.reason, e.result, e.name, e.dimension
+            )
+        rule = instance.quality
+        refusal = refusal_reason(query, dialect)
+        if refusal is not None:
+            return _unexecuted_check(
+                check_key, check_type, model, field, rule, refusal, "failed", instance.name, rule.dimension
+            )
+        return [
+            CheckSpec(
+                key=check_key,
+                category="quality",
+                type=check_type,
+                name=instance.name,
+                model=model,
+                field=field,
+                metric=MetricType.CUSTOM_SQL,
+                threshold=to_threshold(rule),
+                query=query,
+                severity=rule.severity,
+                dimension=rule.dimension,
+                diagnostics=instance.diagnostics,
+            )
+        ]
     if quality.type == "sql":
         if field is None:
             check_key = f"{model}__quality_sql_{count}"
@@ -836,8 +998,6 @@ def _quality_rule_checks(
             check_key = f"{model}__{field}__quality_sql_{count}"
             check_type = "field_quality_sql"
         if field is not None and "[]" in field:
-            # An array item is not a column, so substituting it into the query
-            # would produce SQL no backend can parse.
             return [
                 CheckSpec(
                     key=check_key,
@@ -850,15 +1010,11 @@ def _quality_rule_checks(
                     dimension=quality.dimension,
                     severity=quality.severity,
                     preset_result="warning",
-                    preset_reason=(
-                        f"'{field}' is an array item, not a column, so it cannot be substituted into a query. "
-                        f"Declare the rule on '{field.split('[]')[0]}' instead and match the elements with array "
-                        f"functions, for example size(filter(...)) > 0."
-                    ),
+                    preset_reason=_array_item_reason(field),
                 )
             ]
         threshold = to_threshold(quality)
-        query = prepare_query(quality, model, field, server)
+        query = prepare_query(quality.query, model, field, server)
         if query is None:
             return _unexecuted_check(check_key, check_type, model, field, quality, "The rule has no query.")
         if threshold is None: