CLI

Command-line interface for Koality.

This module provides the CLI for running, validating, and inspecting Koality data quality check configurations.

Commands

run: Execute data quality checks from a configuration file. validate: Validate a configuration file without executing checks. print: Print the resolved configuration in various formats.

Example

$ koality run --config_path checks.yaml $ koality validate --config_path checks.yaml $ koality print --config_path checks.yaml --format json

cli()

Koality - Data quality monitoring CLI.

Koality provides commands to run, validate, and inspect data quality check configurations. Use --help on any command for more details.

Source code in src/koality/cli.py

@click.group()
def cli() -> None:
    """Koality - Data quality monitoring CLI.

    Koality provides commands to run, validate, and inspect data quality
    check configurations. Use --help on any command for more details.
    """

print_config(config_path, output_format, indent, overwrites, database_setup_variable)

Print the resolved koality configuration.

Displays the fully resolved configuration after default propagation. This shows the effective configuration that would be used during execution. Filter values can be overridden using --overwrites (-o) options. Overwrites are applied to defaults before validation, so they propagate to all checks automatically.

Database setup variables can be provided using --database_setup_variable (-dsv) to substitute ${VAR_NAME} placeholders in the database_setup SQL. Variables can also be set via the DATABASE_SETUP_VARIABLES environment variable using comma-separated VAR=value pairs.

Output formats:

model: Pydantic model representation (Python repr).

yaml: YAML formatted output (default).

json: JSON formatted output.

Examples:

koality print --config_path checks.yaml

koality print --config_path checks.yaml --format json

koality print --config_path checks.yaml --format yaml --indent 4

koality print --config_path checks.yaml -o partition_date=2023-01-01

koality print --config_path checks.yaml -dsv PROJECT_ID=my-gcp-project

DATABASE_SETUP_VARIABLES="PROJECT_ID=my-project" koality print --config_path checks.yaml

Source code in src/koality/cli.py

@cli.command(name="print")
@click.option(
    "--config_path",
    required=True,
    type=click.Path(exists=True, dir_okay=False),
    help="Path to the YAML configuration file.",
)
@click.option(
    "--format",
    "output_format",
    type=click.Choice(["model", "yaml", "json"]),
    default="yaml",
    help="Output format: 'model' (Pydantic repr), 'yaml', or 'json'.",
)
@click.option(
    "--indent",
    default=2,
    type=int,
    help="Indentation level for yaml/json output.",
)
@click.option(
    "--overwrites",
    "-o",
    multiple=True,
    help="Override filter values in defaults. Format: filter_name=value. "
    "Overwrites propagate to all checks. Can be used multiple times. "
    "Example: -o partition_date=2023-01-01 -o shop_id=SHOP02",
)
@click.option(
    "--database_setup_variable",
    "-dsv",
    multiple=True,
    help="Set variables for database_setup substitution. Format: VAR_NAME=value. "
    "Variables are substituted in database_setup using ${VAR_NAME} syntax. "
    "Can be used multiple times. Also reads from DATABASE_SETUP_VARIABLES env var "
    "(format: VAR1=value1,VAR2=value2). CLI options override env vars. "
    "Example: -dsv PROJECT_ID=my-gcp-project",
)
def print_config(
    config_path: Path,
    output_format: str,
    indent: int,
    overwrites: tuple[str, ...],
    database_setup_variable: tuple[str, ...],
) -> None:
    """Print the resolved koality configuration.

    Displays the fully resolved configuration after default propagation.
    This shows the effective configuration that would be used during execution.
    Filter values can be overridden using --overwrites (-o) options.
    Overwrites are applied to defaults before validation, so they
    propagate to all checks automatically.

    Database setup variables can be provided using --database_setup_variable (-dsv)
    to substitute ${VAR_NAME} placeholders in the database_setup SQL. Variables
    can also be set via the DATABASE_SETUP_VARIABLES environment variable using
    comma-separated VAR=value pairs.

    Output formats:

        model: Pydantic model representation (Python repr).

        yaml: YAML formatted output (default).

        json: JSON formatted output.

    Examples:
        koality print --config_path checks.yaml

        koality print --config_path checks.yaml --format json

        koality print --config_path checks.yaml --format yaml --indent 4

        koality print --config_path checks.yaml -o partition_date=2023-01-01

        koality print --config_path checks.yaml -dsv PROJECT_ID=my-gcp-project

        DATABASE_SETUP_VARIABLES="PROJECT_ID=my-project" koality print --config_path checks.yaml

    """
    variables = _get_variables_with_env(database_setup_variable)
    try:
        config = _load_config_with_overwrites(config_path, overwrites, variables)
    except ValidationError as e:
        click.echo(f"Configuration '{config_path}' is invalid:\n{e}", err=True)
        raise SystemExit(1) from None

    if output_format == "model":
        click.echo(config)
    elif output_format == "json":
        click.echo(config.model_dump_json(indent=indent))
    else:  # yaml
        click.echo(_dump_yaml(config.model_dump(), indent=indent))

run(config_path, overwrites, database_setup_variable)

Run koality checks from a configuration file.

Executes all data quality checks defined in the configuration file. Filter values can be overridden using --overwrites (-o) options. Overwrites are applied to defaults before validation, so they propagate to all checks automatically.

Database setup variables can be provided using --database_setup_variable (-dsv) to substitute ${VAR_NAME} placeholders in the database_setup SQL. Variables can also be set via the DATABASE_SETUP_VARIABLES environment variable using comma-separated VAR=value pairs.

Examples:

koality run --config_path checks.yaml

koality run --config_path checks.yaml -o partition_date=2023-01-01

koality run --config_path checks.yaml -dsv PROJECT_ID=my-gcp-project

koality run --config_path checks.yaml -dsv PROJECT_ID=prod -dsv DATASET=analytics

DATABASE_SETUP_VARIABLES="PROJECT_ID=my-project,DATASET=prod" koality run --config_path checks.yaml

Source code in src/koality/cli.py

@cli.command()
@click.option(
    "--config_path",
    required=True,
    type=click.Path(exists=True, dir_okay=False),
    help="Path to the YAML configuration file.",
)
@click.option(
    "--overwrites",
    "-o",
    multiple=True,
    help="Override filter values in defaults. Format: filter_name=value. "
    "Overwrites propagate to all checks. Can be used multiple times. "
    "Example: -o partition_date=2023-01-01 -o shop_id=SHOP02",
)
@click.option(
    "--database_setup_variable",
    "-dsv",
    multiple=True,
    help="Set variables for database_setup substitution. Format: VAR_NAME=value. "
    "Variables are substituted in database_setup using ${VAR_NAME} syntax. "
    "Can be used multiple times. Also reads from DATABASE_SETUP_VARIABLES env var "
    "(format: VAR1=value1,VAR2=value2). CLI options override env vars. "
    "Example: -dsv PROJECT_ID=my-gcp-project",
)
def run(
    config_path: Path,
    overwrites: tuple[str, ...],
    database_setup_variable: tuple[str, ...],
) -> None:
    """Run koality checks from a configuration file.

    Executes all data quality checks defined in the configuration file.
    Filter values can be overridden using --overwrites (-o) options.
    Overwrites are applied to defaults before validation, so they
    propagate to all checks automatically.

    Database setup variables can be provided using --database_setup_variable (-dsv)
    to substitute ${VAR_NAME} placeholders in the database_setup SQL. Variables
    can also be set via the DATABASE_SETUP_VARIABLES environment variable using
    comma-separated VAR=value pairs.

    Examples:
        koality run --config_path checks.yaml

        koality run --config_path checks.yaml -o partition_date=2023-01-01

        koality run --config_path checks.yaml -dsv PROJECT_ID=my-gcp-project

        koality run --config_path checks.yaml -dsv PROJECT_ID=prod -dsv DATASET=analytics

        DATABASE_SETUP_VARIABLES="PROJECT_ID=my-project,DATASET=prod" koality run --config_path checks.yaml

    """
    variables = _get_variables_with_env(database_setup_variable)
    config = _load_config_with_overwrites(config_path, overwrites, variables)
    check_executor = CheckExecutor(config=config)
    _ = check_executor()

validate(config_path)

Validate a koality configuration file.

Parses and validates the configuration file against the Koality schema without executing any checks. Useful for CI/CD pipelines and debugging.

Exit codes:

0: Configuration is valid.

1: Configuration is invalid.

Examples:

koality validate --config_path checks.yaml

Source code in src/koality/cli.py

@cli.command()
@click.option(
    "--config_path",
    required=True,
    type=click.Path(exists=True, dir_okay=False),
    help="Path to the YAML configuration file.",
)
def validate(config_path: Path) -> None:
    """Validate a koality configuration file.

    Parses and validates the configuration file against the Koality schema
    without executing any checks. Useful for CI/CD pipelines and debugging.

    Exit codes:

        0: Configuration is valid.

        1: Configuration is invalid.

    Examples:
        koality validate --config_path checks.yaml

    """
    try:
        config_dict = yaml.safe_load(Path(config_path).read_text())
        Config.model_validate(config_dict)
        click.echo(f"Configuration '{config_path}' is valid.")
    except ValidationError as e:
        click.echo(f"Configuration '{config_path}' is invalid:\n{e}", err=True)
        raise SystemExit(1) from None