2026-07-13|17:57:23
PolarsWARNING0.2ERROR0.3CRITICAL0.4
col_vals_gt()
0.90
0.10
col_vals_lt()
0.80
0.20
col_vals_ge()
0.70
0.30
Validate.assert_passing() to verify that every single test unit passes
2. Threshold-Based Assertions: using Validate.assert_below_threshold() to verify that failure rates stay within acceptable thresholds
## [assert_passing()](../../reference/Validate.assert_passing.md#pointblank.Validate.assert_passing)
The Validate.assert_passing() method is the strictest form of assertion, requiring every single validation test unit to pass:
``` python
try:
(
pb.Validate(data=sample_data)
.col_vals_gt(columns="value", value=0)
# Direct assertion: automatically interrogates ---
.assert_passing()
)
except AssertionError as e:
print("AssertionError:", str(e))
```
AssertionError: The following assertions failed:
- Step 1: Expect that values in `value` should be > `0`.
## [assert_below_threshold()](../../reference/Validate.assert_below_threshold.md#pointblank.Validate.assert_below_threshold)
The Validate.assert_below_threshold() method is more flexible as it allows some failures as long as they stay below specified threshold levels. Pointblank uses three severity thresholds that increase in order of seriousness:
- **'warning'** (least severe): the first threshold that gets triggered when failures exceed this level
- **'error'** (more severe): the middle threshold indicating more serious data quality issues
- **'critical'** (most severe): the highest threshold indicating critical data quality problems
``` python
# Create a two-column DataFrame for this example
tbl_pl = pl.DataFrame({
"a": [4, 6, 9, 7, 12, 8, 7, 12, 10, 7],
"b": [9, 8, 10, 5, 10, 9, 14, 6, 6, 8],
})
# Set thresholds: warning=0.2 (20%), error=0.3 (30%), critical=0.4 (40%)
validation = (
pb.Validate(data=tbl_pl, thresholds=(0.2, 0.3, 0.4))
.col_vals_gt(columns="b", value=5) # 1/10 failing (10% failure rate)
.col_vals_lt(columns="a", value=11) # 2/10 failing (20% failure rate)
.col_vals_ge(columns="b", value=8) # 3/10 failing (30% failure rate)
.interrogate()
)
validation
```
| Pointblank Validation | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2026-07-13|17:57:23
PolarsWARNING0.2ERROR0.3CRITICAL0.4
|
|||||||||||||
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
| #4CA64C66 | 1 |
col_vals_gt()
|
|
✓ | 10 | 9 0.90 |
1 0.10 |
○ | ○ | ○ | CSV | ||
| #AAAAAA | 2 |
col_vals_lt()
|
|
✓ | 10 | 8 0.80 |
2 0.20 |
● | ○ | ○ | CSV | ||
| #EBBC14 | 3 |
col_vals_ge()
|
|
✓ | 10 | 7 0.70 |
3 0.30 |
● | ● | ○ | CSV | ||
Validate.assert_below_threshold() assertion for the 'error' level because step 3 exceeds this threshold (30% failure rate matches the error threshold):
``` python
try:
validation.assert_below_threshold(level="error")
except AssertionError as e:
print("AssertionError:", str(e))
```
AssertionError: The following steps exceeded the error threshold level:
Step 3: Expect that values in `b` should be >= `8`.
We can check against the 'error' threshold for specific steps with the `i=` parameter:
``` python
validation.assert_below_threshold(level="error", i=[1, 2])
```
This passes because the highest threshold exceeded in steps 1 and 2 is 'warning'.
The Validate.assert_below_threshold() method takes these parameters:
- `level=`: threshold level to check against (`"warning"`, `"error"`, or `"critical"`)
- `i=`: optional specific step number(s) to check
- `message=`: optional custom error message
This is particularly useful when:
- working with real-world data where some percentage of failures is acceptable
- implementing different severity levels for data quality rules
- gradually improving data quality with stepped thresholds
> **Note: Note**
>
> Assertion methods like Validate.assert_passing() and Validate.assert_below_threshold() will automatically call Validate.interrogate() if needed, so you don't have to explicitly include this step when using assertions directly.
# Using Status Check Methods
In addition to assertion methods that raise exceptions, Pointblank provides status check methods that return boolean values:
## [all_passed()](../../reference/Validate.all_passed.md#pointblank.Validate.all_passed)
The Validate.all_passed() method will return `True` only if every single test unit in every validation step passed:
``` python
validation = (
pb.Validate(data=sample_data)
.col_vals_gt(columns="value", value=0)
.interrogate()
)
if not validation.all_passed():
print("Validation failed: some values are not positive")
```
Validation failed: some values are not positive
## [warning()](../../reference/Validate.warning.md#pointblank.Validate.warning), [error()](../../reference/Validate.error.md#pointblank.Validate.error), and [critical()](../../reference/Validate.critical.md#pointblank.Validate.critical)
The methods Validate.warning(), Validate.error(), and Validate.critical() all return information about whether validation steps exceeded that specific threshold level.
While assertion methods raise exceptions to halt execution when thresholds are exceeded, these status methods give you fine-grained control to implement custom logic based on different validation quality levels.
``` python
validation = (
pb.Validate(data=sample_data, thresholds=(0.05, 0.10, 0.20))
.col_vals_gt(columns="value", value=0) # Some values are negative
.interrogate()
)
validation
```
| Pointblank Validation | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2026-07-13|17:57:24
PolarsWARNING0.05ERROR0.1CRITICAL0.2
|
|||||||||||||
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
| #FF3300 | 1 |
col_vals_gt()
|
|
✓ | 5 | 4 0.80 |
1 0.20 |
● | ● | ● | CSV | ||
Validate.warning() method returns a dictionary mapping step numbers to boolean values. A `True` value means that step exceeds the warning threshold:
``` python
# Get dictionary of warning status for each step
warning_status = validation.warning()
print(f"Warning status: {warning_status}") # {1: True} means step 1 exceeds warning threshold
```
Warning status: {1: True}
You can check a specific step using the `i=` parameter, and get a single boolean with `scalar=True`:
``` python
# Check error threshold for specific step
has_errors = validation.error(i=1, scalar=True)
if has_errors:
print("Step 1 exceeded the error threshold.")
```
Step 1 exceeded the error threshold.
Similarly, we can check if any steps exceed the 'critical' threshold:
``` python
# Check against critical threshold
critical_status = validation.critical()
print(f"Critical status: {critical_status}")
```
Critical status: {1: True}
These methods are particularly useful for:
1. Conditional logic: taking different actions based on threshold severity
2. Reporting: generating summary reports about validation quality
3. Monitoring: tracking data quality trends over time
4. Graceful degradation: implementing fallback logic when quality decreases
Each method has these options:
- without parameters: returns a dictionary mapping step numbers to boolean status values
- with `i=`: check specific step(s)
- with `scalar=True`: return a single boolean instead of a dictionary (when checking a specific step)
While assertion methods raise exceptions to halt execution when thresholds are exceeded, these methods give you fine-grained control to implement custom logic based on different validation quality levels.
# Customizing Error Messages
You can provide custom error messages when assertions fail to make them more meaningful in your specific workflow context:
``` python
# Create a validation with potential failures
validation = (
pb.Validate(data=sample_data, thresholds=(0.2, 0.3, 0.4))
.col_vals_gt(columns="value", value=0)
.interrogate()
)
# Display the validation results
validation
```
| Pointblank Validation | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2026-07-13|17:57:24
PolarsWARNING0.2ERROR0.3CRITICAL0.4
|
|||||||||||||
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
| #AAAAAA | 1 |
col_vals_gt()
|
|
✓ | 5 | 4 0.80 |
1 0.20 |
● | ○ | ○ | CSV | ||
Validate.assert_passing() for critical validations where any failure is unacceptable
- use Validate.assert_below_threshold() for validations where some failure rate is acceptable
2. **Set appropriate thresholds** that match your data quality requirements:
``` python
# Example threshold strategy
validation = pb.Validate(
data=sample_data,
# warning at 1%, error at 5%, critical at 10%
thresholds=pb.Thresholds(warning=0.01, error=0.05, critical=0.10)
)
```
3. **Use a graduated approach** to validation severity:
``` python
# Critical validations: must be perfect
validation_1.assert_passing()
# Important validations: must be below error threshold
validation_2.assert_below_threshold(level="error")
# Monitor-only validations: check warning status
warning_status = validation_3.warning()
```
4. **Placement in pipelines**: place assertions at critical points where data quality is essential
5. **Error handling**: wrap assertions in try-except blocks for better error handling in production systems
6. **Combine with reporting**: use both assertions and reporting approaches for comprehensive quality control
# Conclusion
Pointblank's assertion methods give you flexible options for enforcing data quality requirements:
- Validate.assert_passing() for strict validation where every test unit must pass
- Validate.assert_below_threshold() for more flexible validation where some failures are tolerable
- Status methods (Validate.warning(), Validate.error(), and Validate.critical()) for programmatic threshold checking
By using these assertion methods appropriately, you can build robust data pipelines with different levels of quality enforcement (from strict validation of critical data properties to more lenient checks for less critical aspects). This graduated approach to data quality helps create systems that are both reliable and practical in real-world data environments.