Struct CheckBuilder 

pub struct CheckBuilder { /* private fields */ }

Builder for constructing Check instances.

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("completeness_check")
    .level(Level::Error)
    .description("Ensures all required fields are present")
    .build();

Implementations

impl CheckBuilder

pub fn new(name: impl Into<String>) -> Self

Creates a new check builder with the given name.

pub fn level(self, level: Level) -> Self

Sets the severity level for the check.

Arguments

• level - The severity level

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("critical_check")
    .level(Level::Error)
    .build();

pub fn description(self, description: impl Into<String>) -> Self

Sets the description for the check.

Arguments

• description - A description of what this check validates

pub fn constraint(self, constraint: impl Constraint + 'static) -> Self

Adds a constraint to the check.

Arguments

• constraint - The constraint to add

pub fn boxed_constraint(self, constraint: Box<dyn Constraint>) -> Self

Adds a boxed constraint to the check.

Arguments

• constraint - The boxed constraint to add

pub fn arc_constraint(self, constraint: Arc<dyn Constraint>) -> Self

Adds an Arc constraint to the check.

Arguments

• constraint - The Arc constraint to add

pub fn constraints<I>(self, constraints: I) -> Self

where I: IntoIterator<Item = Box<dyn Constraint>>,

Adds multiple constraints to the check.

Arguments

• constraints - An iterator of constraints to add

pub fn has_size(self, assertion: Assertion) -> Self

Adds a constraint that checks the dataset size (row count).

Arguments

• assertion - The assertion to evaluate against the row count

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("size_validation")
    .level(Level::Error)
    .has_size(Assertion::GreaterThan(1000.0))
    .build();

pub fn has_column_count(self, assertion: Assertion) -> Self

Adds a constraint that checks the number of columns in the dataset.

This constraint validates that the dataset has the expected number of columns by examining the schema.

Arguments

• assertion - The assertion to evaluate against the column count

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("schema_validation")
    .level(Level::Error)
    .has_column_count(Assertion::Equals(15.0))
    .has_column_count(Assertion::GreaterThanOrEqual(10.0))
    .build();

pub fn has_approx_count_distinct( self, column: impl Into<String>, assertion: Assertion, ) -> Self

Adds a constraint that checks the approximate count of distinct values in a column.

Uses DataFusion’s APPROX_DISTINCT function which provides an approximate count using HyperLogLog algorithm. This is much faster than exact COUNT(DISTINCT) for large datasets while maintaining accuracy within 2-3% error margin.

Arguments

• column - The column to count distinct values in
• assertion - The assertion to evaluate against the approximate distinct count

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("cardinality_validation")
    .level(Level::Warning)
    // High cardinality check (e.g., user IDs)
    .has_approx_count_distinct("user_id", Assertion::GreaterThan(1000000.0))
    // Low cardinality check (e.g., country codes)
    .has_approx_count_distinct("country_code", Assertion::LessThan(200.0))
    .build();

pub fn has_approx_quantile( self, column: impl Into<String>, quantile: f64, assertion: Assertion, ) -> Self

Adds a constraint that checks an approximate quantile of a column.

Arguments

• column - The column to check
• quantile - The quantile to compute (0.0 to 1.0)
• assertion - The assertion to evaluate against the quantile value

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("quantile_validation")
    .level(Level::Warning)
    .has_approx_quantile("response_time", 0.95, Assertion::LessThan(1000.0))
    .build();

Panics

Panics if quantile is not between 0.0 and 1.0

pub fn has_mutual_information( self, column1: impl Into<String>, column2: impl Into<String>, assertion: Assertion, ) -> Self

Adds a constraint that checks the mutual information between two columns.

Arguments

• column1 - The first column
• column2 - The second column
• assertion - The assertion to evaluate against the mutual information

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("mi_validation")
    .level(Level::Info)
    .has_mutual_information("feature1", "feature2", Assertion::GreaterThan(0.5))
    .build();

pub fn has_correlation( self, column1: impl Into<String>, column2: impl Into<String>, assertion: Assertion, ) -> Self

Adds a constraint that checks the correlation between two columns.

Arguments

• column1 - The first column
• column2 - The second column
• assertion - The assertion to evaluate against the correlation

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("correlation_validation")
    .level(Level::Warning)
    .has_correlation("height", "weight", Assertion::GreaterThan(0.7))
    .build();

pub fn has_min_length( self, column: impl Into<String>, min_length: usize, ) -> Self

Adds a constraint that checks minimum string length.

Note: Consider using the new length() method for more flexibility.

Arguments

• column - The column to check
• min_length - The minimum acceptable string length

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::LengthAssertion;

// Using the convenience method:
let check = Check::builder("password_validation")
    .level(Level::Error)
    .has_min_length("password", 8)
    .build();

// Or using the unified length API:
let check = Check::builder("password_validation")
    .level(Level::Error)
    .length("password", LengthAssertion::Min(8))
    .build();

pub fn has_max_length( self, column: impl Into<String>, max_length: usize, ) -> Self

Adds a constraint that checks maximum string length.

Arguments

• column - The column to check
• max_length - The maximum acceptable string length

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("username_validation")
    .level(Level::Error)
    .has_max_length("username", 20)
    .build();

pub fn has_length_between( self, column: impl Into<String>, min_length: usize, max_length: usize, ) -> Self

Adds a constraint that checks string length is between bounds (inclusive).

Arguments

• column - The column to check
• min_length - The minimum acceptable string length
• max_length - The maximum acceptable string length

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("description_validation")
    .level(Level::Warning)
    .has_length_between("description", 10, 500)
    .build();

pub fn has_exact_length(self, column: impl Into<String>, length: usize) -> Self

Adds a constraint that checks string has exact length.

Arguments

• column - The column to check
• length - The required exact string length

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("code_validation")
    .level(Level::Error)
    .has_exact_length("verification_code", 6)
    .build();

pub fn is_not_empty(self, column: impl Into<String>) -> Self

Adds a constraint that checks strings are not empty.

Arguments

• column - The column to check

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("name_validation")
    .level(Level::Error)
    .is_not_empty("name")
    .build();

pub fn has_consistent_data_type( self, column: impl Into<String>, threshold: f64, ) -> Self

Adds a constraint that checks data type consistency.

This analyzes the actual data types present in a column and reports on consistency, helping identify columns with mixed types.

Arguments

• column - The column to check
• threshold - The minimum ratio of values that must have the most common type (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("consistency_validation")
    .level(Level::Warning)
    .has_consistent_data_type("user_id", 0.95)
    .build();

Panics

Panics if threshold is not between 0.0 and 1.0

pub fn satisfies( self, sql_expression: impl Into<String>, hint: Option<impl Into<String>>, ) -> Self

Adds a constraint that evaluates a custom SQL expression.

This allows users to define custom validation logic using SQL expressions. The expression should evaluate to a boolean value for each row. For safety, the expression cannot contain data-modifying operations.

Arguments

• sql_expression - The SQL expression to evaluate (must return boolean)
• hint - Optional hint message to provide context when the constraint fails

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("business_rules")
    .level(Level::Error)
    .satisfies("price > 0 AND price < 1000000", Some("Price must be positive and reasonable"))
    .satisfies("order_date <= ship_date", Some("Orders cannot ship before being placed"))
    .build();

Panics

Panics if the SQL expression contains dangerous operations like DROP, DELETE, UPDATE, etc.

pub fn has_histogram( self, column: impl Into<String>, assertion: HistogramAssertion, ) -> Self

Adds a constraint that analyzes value distribution and applies custom assertions.

This constraint computes a histogram of value frequencies in the specified column and allows custom assertion functions to validate distribution characteristics.

Arguments

• column - The column to analyze
• assertion - The assertion function to apply to the histogram

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Histogram;
use std::sync::Arc;

let check = Check::builder("distribution_validation")
    .level(Level::Warning)
    // No single value should dominate
    .has_histogram("status", Arc::new(|hist: &Histogram| {
        hist.most_common_ratio() < 0.5
    }))
    // Check expected number of categories
    .has_histogram("category", Arc::new(|hist| {
        hist.bucket_count() >= 5 && hist.bucket_count() <= 10
    }))
    .build();

pub fn has_histogram_with_description( self, column: impl Into<String>, assertion: HistogramAssertion, description: impl Into<String>, ) -> Self

Adds a constraint that analyzes value distribution with a custom description.

This is similar to has_histogram but allows providing a description of what the assertion checks, which is useful for error messages.

Arguments

• column - The column to analyze
• assertion - The assertion function to apply to the histogram
• description - A description of what the assertion checks

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Histogram;
use std::sync::Arc;

let check = Check::builder("distribution_validation")
    .level(Level::Error)
    .has_histogram_with_description(
        "age",
        Arc::new(|hist: &Histogram| hist.is_roughly_uniform(2.0)),
        "age distribution is roughly uniform"
    )
    .build();

pub fn has_format( self, column: impl Into<String>, format: FormatType, threshold: f64, options: FormatOptions, ) -> Self

Adds a general format validation constraint with full configuration options.

This is the most flexible format validation method, supporting all format types and configuration options through the unified FormatConstraint API.

Arguments

• column - The column to validate
• format - The format type to validate against
• threshold - The minimum ratio of values that must match (0.0 to 1.0)
• options - Configuration options for the validation

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::{FormatType, FormatOptions};

let check = Check::builder("format_validation")
    .level(Level::Error)
    // Custom regex with case-insensitive matching
    .has_format(
        "phone",
        FormatType::Regex(r"^\+?\d{3}-\d{3}-\d{4}$".to_string()),
        0.95,
        FormatOptions::default().case_sensitive(false).trim_before_check(true)
    )
    // Email validation with custom options
    .has_format(
        "email",
        FormatType::Email,
        0.99,
        FormatOptions::default().null_is_valid(true)
    )
    // UUID validation
    .has_format(
        "user_id",
        FormatType::UUID,
        1.0,
        FormatOptions::default()
    )
    .build();

Errors

Returns error if column name is invalid, threshold is out of range, or regex pattern is invalid.

pub fn validates_regex( self, column: impl Into<String>, pattern: impl Into<String>, threshold: f64, ) -> Self

Adds a regex pattern validation constraint.

This is a convenience method for has_format() with FormatType::Regex.

Arguments

• column - The column to validate
• pattern - The regular expression pattern
• threshold - The minimum ratio of values that must match (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("regex_validation")
    .level(Level::Error)
    .validates_regex("phone", r"^\+?\d{3}-\d{3}-\d{4}$", 0.95)
    .validates_regex("product_code", r"^[A-Z]{2}\d{6}$", 1.0)
    .build();

Errors

Returns error if column name is invalid, threshold is out of range, or regex pattern is invalid.

pub fn validates_email(self, column: impl Into<String>, threshold: f64) -> Self

Adds an email address validation constraint.

This is a convenience method for has_format() with FormatType::Email.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid emails (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("email_validation")
    .level(Level::Error)
    .validates_email("primary_email", 0.99)
    .validates_email("secondary_email", 0.80)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_url( self, column: impl Into<String>, threshold: f64, allow_localhost: bool, ) -> Self

Adds a URL validation constraint.

This is a convenience method for has_format() with FormatType::Url.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid URLs (0.0 to 1.0)
• allow_localhost - Whether to allow localhost URLs

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("url_validation")
    .level(Level::Error)
    .validates_url("website", 0.90, false)
    .validates_url("dev_endpoint", 0.80, true)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_credit_card( self, column: impl Into<String>, threshold: f64, detect_only: bool, ) -> Self

Adds a credit card number detection constraint.

This is a convenience method for has_format() with FormatType::CreditCard. Note: For PII detection, you typically want a low threshold (e.g., 0.01 or 0.05) to catch any potential credit card numbers.

Arguments

• column - The column to validate
• threshold - The maximum ratio of values that can be credit card numbers (0.0 to 1.0)
• detect_only - If true, optimizes for detection; if false, for validation

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("pii_detection")
    .level(Level::Error)
    // PII detection - should find very few or no credit cards
    .validates_credit_card("comments", 0.01, true)
    .validates_credit_card("description", 0.0, true)
    // Credit card validation - most values should be valid credit cards
    .validates_credit_card("payment_info", 0.95, false)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_phone( self, column: impl Into<String>, threshold: f64, country: Option<&str>, ) -> Self

Adds a phone number validation constraint.

This is a convenience method for has_format() with FormatType::Phone.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid phone numbers (0.0 to 1.0)
• country - Optional country code for country-specific validation (e.g., “US”, “CA”)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("phone_validation")
    .level(Level::Error)
    .validates_phone("phone", 0.95, Some("US"))
    .validates_phone("international_phone", 0.90, None)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_postal_code( self, column: impl Into<String>, threshold: f64, country: &str, ) -> Self

Adds a postal code validation constraint.

This is a convenience method for has_format() with FormatType::PostalCode.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid postal codes (0.0 to 1.0)
• country - Country code for country-specific validation (e.g., “US”, “CA”, “UK”)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("postal_code_validation")
    .level(Level::Error)
    .validates_postal_code("zip_code", 0.98, "US")
    .validates_postal_code("postal_code", 0.95, "CA")
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_uuid(self, column: impl Into<String>, threshold: f64) -> Self

Adds a UUID validation constraint.

This is a convenience method for has_format() with FormatType::UUID.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid UUIDs (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("uuid_validation")
    .level(Level::Error)
    .validates_uuid("user_id", 1.0)
    .validates_uuid("session_id", 0.99)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_ipv4(self, column: impl Into<String>, threshold: f64) -> Self

Adds an IPv4 address validation constraint.

This is a convenience method for has_format() with FormatType::IPv4.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid IPv4 addresses (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("ip_validation")
    .level(Level::Error)
    .validates_ipv4("client_ip", 0.98)
    .validates_ipv4("server_ip", 1.0)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_ipv6(self, column: impl Into<String>, threshold: f64) -> Self

Adds an IPv6 address validation constraint.

This is a convenience method for has_format() with FormatType::IPv6.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid IPv6 addresses (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("ipv6_validation")
    .level(Level::Error)
    .validates_ipv6("client_ipv6", 0.95)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_json(self, column: impl Into<String>, threshold: f64) -> Self

Adds a JSON format validation constraint.

This is a convenience method for has_format() with FormatType::Json.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid JSON (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("json_validation")
    .level(Level::Error)
    .validates_json("metadata", 0.99)
    .validates_json("config", 1.0)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_iso8601_datetime( self, column: impl Into<String>, threshold: f64, ) -> Self

Adds an ISO 8601 datetime validation constraint.

This is a convenience method for has_format() with FormatType::Iso8601DateTime.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid ISO 8601 datetimes (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("datetime_validation")
    .level(Level::Error)
    .validates_iso8601_datetime("order_date", 1.0)
    .validates_iso8601_datetime("modified_date", 0.98)
    .build();

Errors

Returns error if column name is invalid or threshold is out of range.

pub fn validates_email_with_options( self, column: impl Into<String>, threshold: f64, options: FormatOptions, ) -> Self

Adds an enhanced email validation constraint with configurable options.

This method provides more control than validates_email() by supporting case sensitivity, whitespace trimming, and null handling options.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid emails (0.0 to 1.0)
• options - Format validation options

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::FormatOptions;

let check = Check::builder("enhanced_email_validation")
    .level(Level::Error)
    // Case-insensitive email validation with trimming
    .validates_email_with_options(
        "email",
        0.95,
        FormatOptions::new()
            .case_sensitive(false)
            .trim_before_check(true)
            .null_is_valid(false)
    )
    .build();

pub fn validates_url_with_options( self, column: impl Into<String>, threshold: f64, allow_localhost: bool, options: FormatOptions, ) -> Self

Adds an enhanced URL validation constraint with configurable options.

This method provides more control than validates_url() by supporting case sensitivity, whitespace trimming, and null handling options.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid URLs (0.0 to 1.0)
• allow_localhost - Whether to allow localhost URLs
• options - Format validation options

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::FormatOptions;

let check = Check::builder("enhanced_url_validation")
    .level(Level::Error)
    // Case-insensitive URL validation with trimming
    .validates_url_with_options(
        "website",
        0.90,
        true, // allow localhost
        FormatOptions::new()
            .case_sensitive(false)
            .trim_before_check(true)
    )
    .build();

pub fn validates_phone_with_options( self, column: impl Into<String>, threshold: f64, country: Option<String>, options: FormatOptions, ) -> Self

Adds an enhanced phone number validation constraint with configurable options.

This method provides more control than validates_phone() by supporting case sensitivity, whitespace trimming, and null handling options.

Arguments

• column - The column to validate
• threshold - The minimum ratio of values that must be valid phone numbers (0.0 to 1.0)
• country - Optional country code for region-specific validation
• options - Format validation options

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::FormatOptions;

let check = Check::builder("enhanced_phone_validation")
    .level(Level::Error)
    // US phone validation with trimming
    .validates_phone_with_options(
        "phone",
        0.95,
        Some("US".to_string()),
        FormatOptions::new().trim_before_check(true)
    )
    .build();

pub fn validates_regex_with_options( self, column: impl Into<String>, pattern: impl Into<String>, threshold: f64, options: FormatOptions, ) -> Self

Adds an enhanced regex pattern validation constraint with configurable options.

This method provides more control than validates_regex() by supporting case sensitivity, whitespace trimming, and null handling options.

Arguments

• column - The column to validate
• pattern - The regular expression pattern
• threshold - The minimum ratio of values that must match (0.0 to 1.0)
• options - Format validation options

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::FormatOptions;

let check = Check::builder("enhanced_regex_validation")
    .level(Level::Error)
    // Case-insensitive product code validation
    .validates_regex_with_options(
        "product_code",
        r"^[A-Z]{2}\d{4}$",
        0.98,
        FormatOptions::new()
            .case_sensitive(false)
            .trim_before_check(true)
    )
    .build();

pub fn uniqueness<I, S>( self, columns: I, uniqueness_type: UniquenessType, options: UniquenessOptions, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Adds a unified uniqueness constraint with full control over validation type and options.

This method provides a comprehensive alternative to is_unique, are_unique, has_uniqueness, is_primary_key, has_distinctness, and has_unique_value_ratio by supporting all uniqueness validation types with flexible configuration options.

Arguments

• columns - The column(s) to check (single string, vec, or array)
• uniqueness_type - The type of uniqueness validation to perform
• options - Configuration options for null handling, case sensitivity, etc.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::{UniquenessType, UniquenessOptions, NullHandling, Assertion};

let check = Check::builder("unified_uniqueness")
    // Full uniqueness with threshold
    .uniqueness(
        vec!["user_id"],
        UniquenessType::FullUniqueness { threshold: 1.0 },
        UniquenessOptions::default()
    )
    // Primary key validation
    .uniqueness(
        vec!["order_id", "line_item_id"],
        UniquenessType::PrimaryKey,
        UniquenessOptions::default()
    )
    // Distinctness check
    .uniqueness(
        vec!["category"],
        UniquenessType::Distinctness(Assertion::LessThan(0.1)),
        UniquenessOptions::default()
    )
    // Unique value ratio
    .uniqueness(
        vec!["transaction_id"],
        UniquenessType::UniqueValueRatio(Assertion::GreaterThan(0.99)),
        UniquenessOptions::default()
    )
    // Composite uniqueness with null handling
    .uniqueness(
        vec!["email", "domain"],
        UniquenessType::UniqueComposite {
            threshold: 0.95,
            null_handling: NullHandling::Exclude,
            case_sensitive: false
        },
        UniquenessOptions::new()
            .with_null_handling(NullHandling::Exclude)
            .case_sensitive(false)
    )
    .build();

Errors

Returns error if column names are invalid or thresholds are out of range.

pub fn validates_uniqueness<I, S>(self, columns: I, threshold: f64) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Adds a full uniqueness constraint for single or multiple columns.

This is a convenience method for uniqueness() with UniquenessType::FullUniqueness.

Arguments

• columns - The column(s) to check for uniqueness
• threshold - The minimum acceptable uniqueness ratio (0.0 to 1.0)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("uniqueness_validation")
    .level(Level::Error)
    .validates_uniqueness(vec!["user_id"], 1.0)
    .validates_uniqueness(vec!["email", "domain"], 0.95)
    .build();

Errors

Returns error if column names are invalid or threshold is out of range.

pub fn validates_distinctness<I, S>( self, columns: I, assertion: Assertion, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Adds a distinctness constraint with assertion-based validation.

This is a convenience method for uniqueness() with UniquenessType::Distinctness.

Arguments

• columns - The column(s) to check for distinctness
• assertion - The assertion to apply to the distinctness ratio

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("distinctness_validation")
    .level(Level::Warning)
    .validates_distinctness(vec!["status"], Assertion::LessThan(0.1))
    .validates_distinctness(vec!["user_id"], Assertion::GreaterThan(0.95))
    .build();

Errors

Returns error if column names are invalid.

pub fn validates_unique_value_ratio<I, S>( self, columns: I, assertion: Assertion, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Adds a unique value ratio constraint with assertion-based validation.

This is a convenience method for uniqueness() with UniquenessType::UniqueValueRatio.

Arguments

• columns - The column(s) to check for unique value ratio
• assertion - The assertion to apply to the unique value ratio

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("unique_ratio_validation")
    .level(Level::Warning)
    .validates_unique_value_ratio(vec!["transaction_id"], Assertion::GreaterThan(0.99))
    .validates_unique_value_ratio(vec!["category"], Assertion::LessThan(0.01))
    .build();

Errors

Returns error if column names are invalid.

pub fn validates_primary_key<I, S>(self, columns: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Adds a primary key constraint (unique + non-null).

This is a convenience method for uniqueness() with UniquenessType::PrimaryKey.

Arguments

• columns - The column(s) that form the primary key

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("primary_key_validation")
    .level(Level::Error)
    .validates_primary_key(vec!["user_id"])
    .validates_primary_key(vec!["order_id", "line_item_id"])
    .build();

Errors

Returns error if column names are invalid.

pub fn validates_uniqueness_with_nulls<I, S>( self, columns: I, threshold: f64, null_handling: NullHandling, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Adds a uniqueness constraint that allows NULL values with configurable handling.

This is a convenience method for uniqueness() with UniquenessType::UniqueWithNulls.

Arguments

• columns - The column(s) to check for uniqueness
• threshold - The minimum acceptable uniqueness ratio (0.0 to 1.0)
• null_handling - How to handle NULL values in uniqueness calculations

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::NullHandling;

let check = Check::builder("null_handling_validation")
    .level(Level::Warning)
    .validates_uniqueness_with_nulls(vec!["optional_id"], 0.9, NullHandling::Exclude)
    .validates_uniqueness_with_nulls(vec!["reference"], 0.8, NullHandling::Include)
    .build();

Errors

Returns error if column names are invalid or threshold is out of range.

pub fn completeness( self, columns: impl Into<ColumnSpec>, options: ConstraintOptions, ) -> Self

Adds a completeness constraint using the unified options pattern.

This method provides a more flexible alternative to is_complete, has_completeness, are_complete, and are_any_complete by supporting arbitrary logical operators and thresholds.

Arguments

• columns - The column(s) to check (single string, vec, or array)
• options - Configuration options including threshold and logical operator

Examples

use term_guard::core::{Check, ConstraintOptions, LogicalOperator};

let check = Check::builder("unified_completeness")
    // Single column with threshold
    .completeness("email", ConstraintOptions::new().with_threshold(0.95))
    // Multiple columns - all must be complete
    .completeness(
        vec!["first_name", "last_name"],
        ConstraintOptions::new()
            .with_operator(LogicalOperator::All)
            .with_threshold(1.0)
    )
    // At least 2 of 4 contact methods must be 90% complete
    .completeness(
        vec!["email", "phone", "address", "postal_code"],
        ConstraintOptions::new()
            .with_operator(LogicalOperator::AtLeast(2))
            .with_threshold(0.9)
    )
    .build();

pub fn length( self, column: impl Into<String>, assertion: LengthAssertion, ) -> Self

Adds a string length constraint using the unified options pattern.

This method provides a more flexible alternative to the individual length methods by supporting all length assertion types in a single interface.

Arguments

• column - The column to check
• assertion - The length assertion (Min, Max, Between, Exactly, NotEmpty)

Examples

use term_guard::core::Check;
use term_guard::constraints::LengthAssertion;

let check = Check::builder("length_validation")
    .length("password", LengthAssertion::Min(8))
    .length("username", LengthAssertion::Between(3, 20))
    .length("verification_code", LengthAssertion::Exactly(6))
    .length("name", LengthAssertion::NotEmpty)
    .build();

pub fn statistic( self, column: impl Into<String>, statistic: StatisticType, assertion: Assertion, ) -> Self

Adds a statistical constraint using the unified options pattern.

This method provides a unified interface for all statistical constraints (min, max, mean, sum, standard deviation) with consistent assertion patterns.

Arguments

• column - The column to analyze
• statistic - The type of statistic to compute
• assertion - The assertion to apply to the statistic

Examples

use term_guard::core::Check;
use term_guard::constraints::{StatisticType, Assertion};

let check = Check::builder("statistical_validation")
    .statistic("age", StatisticType::Min, Assertion::GreaterThanOrEqual(0.0))
    .statistic("age", StatisticType::Max, Assertion::LessThanOrEqual(120.0))
    .statistic("salary", StatisticType::Mean, Assertion::Between(50000.0, 100000.0))
    .statistic("response_time", StatisticType::StandardDeviation, Assertion::LessThan(100.0))
    .build();

pub fn has_min(self, column: impl Into<String>, assertion: Assertion) -> Self

Adds a minimum value constraint for a column.

This is a convenience method for statistic() with StatisticType::Min.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("age_validation")
    .level(Level::Error)
    .has_min("age", Assertion::GreaterThanOrEqual(0.0))
    .build();

pub fn has_max(self, column: impl Into<String>, assertion: Assertion) -> Self

Adds a maximum value constraint for a column.

This is a convenience method for statistic() with StatisticType::Max.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("age_validation")
    .level(Level::Error)
    .has_max("age", Assertion::LessThanOrEqual(120.0))
    .build();

pub fn has_mean(self, column: impl Into<String>, assertion: Assertion) -> Self

Adds a mean (average) value constraint for a column.

This is a convenience method for statistic() with StatisticType::Mean.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("salary_validation")
    .level(Level::Warning)
    .has_mean("salary", Assertion::Between(50000.0, 100000.0))
    .build();

pub fn has_sum(self, column: impl Into<String>, assertion: Assertion) -> Self

Adds a sum constraint for a column.

This is a convenience method for statistic() with StatisticType::Sum.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("revenue_validation")
    .level(Level::Error)
    .has_sum("revenue", Assertion::GreaterThan(1000000.0))
    .build();

pub fn has_standard_deviation( self, column: impl Into<String>, assertion: Assertion, ) -> Self

Adds a standard deviation constraint for a column.

This is a convenience method for statistic() with StatisticType::StandardDeviation.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("response_time_validation")
    .level(Level::Warning)
    .has_standard_deviation("response_time", Assertion::LessThan(100.0))
    .build();

pub fn has_variance( self, column: impl Into<String>, assertion: Assertion, ) -> Self

Adds a variance constraint for a column.

This is a convenience method for statistic() with StatisticType::Variance.

Examples

use term_guard::core::{Check, Level};
use term_guard::constraints::Assertion;

let check = Check::builder("score_validation")
    .level(Level::Warning)
    .has_variance("score", Assertion::LessThan(250.0))
    .build();

pub fn foreign_key( self, child_column: impl Into<String>, parent_column: impl Into<String>, ) -> Self

Adds a foreign key constraint for referential integrity validation.

This constraint ensures that all values in the child table’s foreign key column exist as values in the parent table’s referenced column. This is essential for maintaining data consistency and preventing orphaned records in joined datasets.

Arguments

• child_column - The column in the child table (qualified as “table.column”)
• parent_column - The column in the parent table (qualified as “table.column”)

Examples

use term_guard::core::{Check, Level};

let check = Check::builder("referential_integrity")
    .level(Level::Error)
    .foreign_key("orders.customer_id", "customers.id")
    .foreign_key("order_items.order_id", "orders.id")
    .build();

Foreign Key Configuration

For more advanced configuration (null handling, join strategy, violation reporting), use ForeignKeyConstraint::new() directly with the constraint() method:

use term_guard::core::Check;
use term_guard::constraints::ForeignKeyConstraint;

let check = Check::builder("advanced_foreign_key")
    .constraint(
        ForeignKeyConstraint::new("orders.customer_id", "customers.id")
            .allow_nulls(true)
            .use_left_join(false)
            .max_violations_reported(50)
    )
    .build();

Requirements

This constraint requires that both referenced tables are available in the DataFusion session context. When using with JoinedSource, ensure the joined source is registered with the appropriate table name.

pub fn cross_table_sum( self, left_column: impl Into<String>, right_column: impl Into<String>, ) -> Self

Adds a constraint that validates sums between two tables match within tolerance.

This is essential for Phase 2 joined data sources validation, ensuring that aggregated values are consistent across related tables. Common use cases include validating that order totals match payment amounts, or inventory quantities align with transaction logs.

Arguments

• left_column - Left side column in table.column format (e.g., “orders.total”)
• right_column - Right side column in table.column format (e.g., “payments.amount”)

Examples

Basic Cross-Table Sum Validation

use term_guard::core::{Check, Level};

let check = Check::builder("financial_integrity")
    .level(Level::Error)
    .cross_table_sum("orders.total", "payments.amount")
    .build();

For Advanced Configuration, Use the Constraint Directly

use term_guard::core::Check;
use term_guard::constraints::CrossTableSumConstraint;

let check = Check::builder("advanced_cross_table")
    .constraint(
        CrossTableSumConstraint::new("orders.total", "payments.amount")
            .group_by(vec!["customer_id"])
            .tolerance(0.01)
            .max_violations_reported(50)
    )
    .build();

Requirements

This constraint requires that both referenced tables are available in the DataFusion session context. When using with JoinedSource, ensure the joined source is registered with the appropriate table names and that the tables can be joined on the specified group-by columns if provided.

pub fn join_coverage( self, left_table: impl Into<String>, right_table: impl Into<String>, ) -> Self

Adds a join coverage constraint for validating join quality.

This constraint measures what percentage of rows from the left table successfully join with the right table, helping identify missing reference data, data quality issues in foreign key relationships, and incomplete data loads.

Arguments

• left_table - Name of the left table in the join
• right_table - Name of the right table in the join

Examples

Basic Usage

use term_guard::core::{Check, Level};

let check = Check::builder("join_quality")
    .level(Level::Warning)
    .join_coverage("sales", "customers")
    .build();

For Advanced Configuration, Use the Constraint Directly

use term_guard::core::Check;
use term_guard::constraints::{JoinCoverageConstraint, CoverageType};

let check = Check::builder("advanced_join_coverage")
    .constraint(
        JoinCoverageConstraint::new("orders", "products")
            .on_multiple(vec![("product_id", "id"), ("variant", "variant_code")])
            .expect_match_rate(0.98)
            .coverage_type(CoverageType::BidirectionalCoverage)
            .distinct_only(true)
    )
    .build();

Requirements

Both tables must be registered with the DataFusion session context. Use .on() or .on_multiple() on the constraint to specify join keys.

pub fn temporal_ordering(self, table_name: impl Into<String>) -> Self

Adds a temporal ordering constraint for time-based validation.

This constraint ensures that temporal data follows expected patterns, including chronological ordering between columns, business hour compliance, date range validation, and event sequence validation.

Arguments

• table_name - Name of the table to validate

Examples

Basic Temporal Ordering

use term_guard::core::{Check, Level};

let check = Check::builder("temporal_consistency")
    .level(Level::Error)
    .temporal_ordering("events")
    .build();

For Advanced Configuration, Use the Constraint Directly

use term_guard::core::Check;
use term_guard::constraints::TemporalOrderingConstraint;

let check = Check::builder("advanced_temporal")
    .constraint(
        TemporalOrderingConstraint::new("transactions")
            .business_hours("timestamp", "09:00", "17:00")
            .weekdays_only(true)
            .with_timezone("America/New_York")
    )
    .constraint(
        TemporalOrderingConstraint::new("events")
            .before_after("created_at", "processed_at")
            .tolerance_seconds(60)
            .allow_nulls(true)
    )
    .build();

Requirements

The table must be registered with the DataFusion session context. Configure the specific temporal validation type using the constraint’s methods.

pub fn with_constraint(self, constraint: impl Constraint + 'static) -> Self

Adds a constraint using a fluent constraint builder.

This method provides the most flexible API for building complex constraints with full access to all unified constraint features.

Arguments

• constraint - A constraint built using the fluent API

Examples

use term_guard::core::{Check, ConstraintOptions, LogicalOperator};
use term_guard::constraints::{CompletenessConstraint, LengthConstraint, LengthAssertion};

let check = Check::builder("advanced_validation")
    .with_constraint(
        CompletenessConstraint::new(
            vec!["phone", "email"],
            ConstraintOptions::new()
                .with_operator(LogicalOperator::Any)
                .with_threshold(0.99)
        )
    )
    .with_constraint(
        LengthConstraint::new("description", LengthAssertion::Between(50, 2000))
    )
    .build();

pub fn any_complete<I, S>(self, columns: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Convenience method for requiring any of multiple columns to be complete.

Equivalent to completeness(columns, ConstraintOptions::new().with_operator(LogicalOperator::Any).with_threshold(1.0)) but more concise for this common pattern.

Examples

use term_guard::core::Check;

let check = Check::builder("contact_validation")
    .any_complete(vec!["phone", "email", "address"])
    .build();

pub fn at_least_complete<I, S>( self, n: usize, columns: I, threshold: f64, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Convenience method for requiring at least N columns to meet a threshold.

Examples

use term_guard::core::Check;

let check = Check::builder("contact_validation")
    .at_least_complete(2, vec!["email", "phone", "address", "postal_code"], 0.9)
    .build();

pub fn exactly_complete<I, S>( self, n: usize, columns: I, threshold: f64, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Convenience method for exactly N columns meeting a threshold.

Examples

use term_guard::core::Check;

let check = Check::builder("balance_validation")
    .exactly_complete(1, vec!["primary_phone", "secondary_phone"], 1.0)
    .build();

pub fn build(self) -> Check

Builds the Check instance.

Returns

The constructed Check

impl CheckBuilder

Extension methods for CheckBuilder providing the new unified API.

pub fn statistics( self, column: impl Into<String>, options: StatisticalOptions, ) -> Result<Self>

Adds statistical constraints using the new unified API.

Examples

use term_guard::core::{Check, builder_extensions::StatisticalOptions};
use term_guard::constraints::Assertion;

// Single statistic
let check = Check::builder("age_stats")
    .statistics(
        "age",
        StatisticalOptions::new()
            .min(Assertion::GreaterThanOrEqual(0.0))
            .max(Assertion::LessThan(150.0))
    )?
    .build();

// Multiple statistics optimized in one query
let check = Check::builder("response_time_stats")
    .statistics(
        "response_time",
        StatisticalOptions::new()
            .min(Assertion::GreaterThanOrEqual(0.0))
            .max(Assertion::LessThan(5000.0))
            .mean(Assertion::Between(100.0, 1000.0))
            .percentile(0.95, Assertion::LessThan(2000.0))
    )?
    .build();

pub fn with_constraints<F>(self, build_fn: F) -> Self

where F: FnOnce(Self) -> Self,

Adds multiple constraints using a fluent builder API.

Note: This is an advanced API. For simple cases, use the individual builder methods.

Examples

use term_guard::core::Check;
use term_guard::core::builder_extensions::{CompletenessOptions, StatisticalOptions};
use term_guard::constraints::{FormatType, FormatOptions, UniquenessType, UniquenessOptions, Assertion};

let check = Check::builder("user_validation")
    // Use individual methods for constraints
    .completeness("user_id", CompletenessOptions::full().into_constraint_options())
    .completeness("email", CompletenessOptions::threshold(0.95).into_constraint_options())
    .has_format("email", FormatType::Email, 0.95, FormatOptions::default())
    .uniqueness(
        vec!["email"],
        UniquenessType::FullUniqueness { threshold: 1.0 },
        UniquenessOptions::default()
    )
    .build();

impl CheckBuilder

Convenience methods for common validation patterns.

pub fn primary_key<I, S>(self, columns: I) -> Self

where I: IntoIterator<Item = S> + Clone, S: Into<String>,

Adds a primary key validation (non-null and unique).

This is a convenience method that combines completeness and uniqueness constraints.

Examples

use term_guard::core::Check;

let check = Check::builder("primary_key")
    .primary_key(vec!["user_id"])
    .build();

// Composite primary key
let check = Check::builder("composite_pk")
    .primary_key(vec!["tenant_id", "user_id"])
    .build();

pub fn email(self, column: impl Into<String>, threshold: f64) -> Self

Adds email validation with common settings.

Examples

use term_guard::core::Check;

let check = Check::builder("email_validation")
    .email("email_address", 0.95)
    .build();

pub fn url(self, column: impl Into<String>, threshold: f64) -> Self

Adds URL validation with common settings.

Examples

use term_guard::core::Check;

let check = Check::builder("url_validation")
    .url("website", 0.90)
    .build();

pub fn phone( self, column: impl Into<String>, threshold: f64, country_code: Option<&str>, ) -> Self

Adds phone number validation.

Examples

use term_guard::core::Check;

let check = Check::builder("phone_validation")
    .phone("contact_phone", 0.90, Some("US"))
    .build();

pub fn contains_ssn(self, column: impl Into<String>, threshold: f64) -> Self

Adds Social Security Number (SSN) pattern validation.

Validates that values in the specified column match US Social Security Number patterns. Accepts both hyphenated (XXX-XX-XXXX) and non-hyphenated (XXXXXXXXX) formats. Automatically excludes known invalid SSNs (e.g., 000-xx-xxxx, xxx-00-xxxx, 666-xx-xxxx, 9xx-xx-xxxx).

Examples

use term_guard::core::Check;

let check = Check::builder("ssn_validation")
    .contains_ssn("ssn_column", 0.95)
    .build();

pub fn value_range( self, column: impl Into<String>, min: f64, max: f64, ) -> Result<Self>

Adds value range validation (min and max).

Examples

use term_guard::core::Check;

let check = Check::builder("age_range")
    .value_range("age", 0.0, 150.0)?
    .build();

Trait Implementations

impl Debug for CheckBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.