col_vals_gt()
1.00
0.00
interrogate() is called), Pointblank will then check that the column exists in the input table.
For creating expressions to use with the [conjointly()](Validate.conjointly.md#pointblank.Validate.conjointly) validation method, use the expr_col() function instead.
## Parameters
`exprs: str | ColumnSelector | ColumnSelectorNarwhals | nw.selectors.Selector`
Either the name of a single column in the target table, provided as a string, or, an expression involving column selector functions (e.g., `starts_with("a")`, `ends_with("e") | starts_with("a")`, etc.).
## Returns
`Column | ColumnLiteral | ColumnSelectorNarwhals:`
A column object or expression representing the column reference.
## Usage With The `columns=` Argument
The [col()](col.md#pointblank.col) function can be used in the `columns=` argument of the following validation methods:
- col_vals_gt()
- col_vals_lt()
- col_vals_ge()
- col_vals_le()
- col_vals_eq()
- col_vals_ne()
- col_vals_between()
- col_vals_outside()
- col_vals_in_set()
- col_vals_not_in_set()
- col_vals_increasing()
- col_vals_decreasing()
- col_vals_null()
- col_vals_not_null()
- col_vals_regex()
- col_vals_within_spec()
- col_exists()
If specifying a single column with certainty (you have the exact name), [col()](col.md#pointblank.col) is not necessary since you can just pass the column name as a string (though it is still valid to use `col("column_name")`, if preferred). However, if you want to select columns based on complex logic involving multiple column selector functions (e.g., columns that start with `"a"` but don't end with `"e"`), you need to use [col()](col.md#pointblank.col) to wrap expressions involving column selector functions and logical operators such as `&`, `|`, `-`, and `~`.
Here is an example of such usage with the col_vals_gt() validation method:
``` python
col_vals_gt(columns=col(starts_with("a") & ~ends_with("e")), value=10)
```
If using only a single column selector function, you can pass the function directly to the `columns=` argument of the validation method, or, you can use [col()](col.md#pointblank.col) to wrap the function (either is valid though the first is more concise). Here is an example of that simpler usage:
``` python
col_vals_gt(columns=starts_with("a"), value=10)
```
## Usage With The `value=`, `left=`, And `right=` Arguments
The [col()](col.md#pointblank.col) function can be used in the `value=` argument of the following validation methods
- col_vals_gt()
- col_vals_lt()
- col_vals_ge()
- col_vals_le()
- col_vals_eq()
- col_vals_ne()
and in the `left=` and `right=` arguments (either or both) of these two validation methods
- col_vals_between()
- col_vals_outside()
You cannot use column selector functions such as starts_with() in either of the `value=`, `left=`, or `right=` arguments since there would be no guarantee that a single column will be resolved from the target table with this approach. The [col()](col.md#pointblank.col) function is used to signal that the value being compared is a column value and not a literal value.
## Available Selectors
There is a collection of selectors available in pointblank, allowing you to select columns based on attributes of column names and positions. The selectors are:
- starts_with()
- ends_with()
- contains()
- matches()
- everything()
- first_n()
- last_n()
Alternatively, we support selectors from the Narwhals library! Those selectors can additionally take advantage of the data types of the columns. The selectors are:
- `boolean()`
- `by_dtype()`
- `categorical()`
- [matches()](matches.md#pointblank.matches)
- `numeric()`
- `string()`
Have a look at the [Narwhals API documentation on selectors](https://narwhals-dev.github.io/narwhals/api-reference/selectors/) for more information.
## Examples
Suppose we have a table with columns `a` and `b` and we'd like to validate that the values in column `a` are greater than the values in column `b`. We can use the [col()](col.md#pointblank.col) helper function to reference the comparison column when creating the validation step.
``` python
import pointblank as pb
import polars as pl
tbl = pl.DataFrame(
{
"a": [5, 6, 5, 7, 6, 5],
"b": [4, 2, 3, 3, 4, 3],
}
)
validation = (
pb.Validate(data=tbl)
.col_vals_gt(columns="a", value=pb.col("b"))
.interrogate()
)
validation
```
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| #4CA64C | 1 |
col_vals_gt()
|
|
✓ | 6 | 6 1.00 |
0 0.00 |
-- | -- | -- | -- |
starts_with(), ends_with(), etc.) to specify columns in the `columns=` argument of a validation method. Let's use the starts_with() column selector function to select columns that start with `"paid"` and validate that the values in those columns are greater than `10`.
``` python
tbl = pl.DataFrame(
{
"name": ["Alice", "Bob", "Charlie"],
"paid_2021": [16.32, 16.25, 15.75],
"paid_2022": [18.62, 16.95, 18.25],
"person_id": ["A123", "B456", "C789"],
}
)
validation = (
pb.Validate(data=tbl)
.col_vals_gt(columns=pb.col(pb.starts_with("paid")), value=10)
.interrogate()
)
validation
```
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| #4CA64C | 1 |
col_vals_gt()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 2 |
col_vals_gt()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- |
starts_with() column selector function. This is not strictly necessary when using a single column selector function, so `columns=pb.starts_with("paid")` would be equivalent usage here. However, the use of [col()](col.md#pointblank.col) is required when using multiple column selector functions with logical operators. Here is an example of that more complex usage:
``` python
tbl = pl.DataFrame(
{
"name": ["Alice", "Bob", "Charlie"],
"hours_2022": [160, 180, 160],
"hours_2023": [182, 168, 175],
"hours_2024": [200, 165, 190],
"paid_2022": [18.62, 16.95, 18.25],
"paid_2023": [19.29, 17.75, 18.35],
"paid_2024": [20.73, 18.35, 20.10],
}
)
validation = (
pb.Validate(data=tbl)
.col_vals_gt(
columns=pb.col(pb.starts_with("paid") & pb.matches("2023|2024")),
value=10
)
.interrogate()
)
validation
```
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| #4CA64C | 1 |
col_vals_gt()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 2 |
col_vals_gt()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- |
starts_with() and matches() column selector functions, combined with the `&` operator. This is necessary to specify the set of columns that start with `"paid"` *and* match the text `"2023"` or `"2024"`.
If you'd like to take advantage of Narwhals selectors, that's also possible. Here is an example of using the `numeric()` column selector function to select all numeric columns for validation, checking that their values are greater than `0`.
``` python
import narwhals.selectors as ncs
tbl = pl.DataFrame(
{
"name": ["Alice", "Bob", "Charlie"],
"hours_2022": [160, 180, 160],
"hours_2023": [182, 168, 175],
"hours_2024": [200, 165, 190],
"paid_2022": [18.62, 16.95, 18.25],
"paid_2023": [19.29, 17.75, 18.35],
"paid_2024": [20.73, 18.35, 20.10],
}
)
validation = (
pb.Validate(data=tbl)
.col_vals_ge(columns=pb.col(ncs.numeric()), value=0)
.interrogate()
)
validation
```
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| #4CA64C | 1 | 
col_vals_ge()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 2 |
col_vals_ge()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 3 |
col_vals_ge()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 4 |
col_vals_ge()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 5 |
col_vals_ge()
|
zLDguMTgxOTQ3MzYgNS44MDM3NTA0Niw4LjE4MTk0NzM2IFogTTUuODAzNzUwNDYsMTQuODE0OTE1IEM0LjE3ODIxOTk3LDE0LjgxNDkxNSAyLjg1NTc4Mjg1LDEzLjQ5MjQ3NzggMi44NTU3ODI4NSwxMS44NjY5NDc0IEMyLjg1NTc4Mjg1LDEwLjI0MTQxNjkgNC4xNzgyMTk5Nyw4LjkxODk3OTc1IDUuODAzNzUwNDYsOC45MTg5Nzk3NSBDNy40MjkyODA5NSw4LjkxODk3OTc1IDguNzUxNzE4MDcsMTAuMjQxNDE2OSA4Ljc1MTcxODA3LDExLjg2Njk0NzQgQzguNzUxNzE4MDcsMTMuNDkyNDc3OCA3LjQyOTI4MDk1LDE0LjgxNDkxNSA1LjgwMzc1MDQ2LDE0LjgxNDkxNSBaIiBpZD0iU2hhcGUiIGZpbGw9IiMwMDAwMDAiIGZpbGwtcnVsZT0ibm9uemVybyIgLz4KICAgICAgICAgICAgPHBhdGggZD0iTTEzLjk2MzgxODksOC42OTkzMzUgQzEzLjkzNjQ2MjEsOC43MDQzMDkyNSAxMy45MDkxMDU5LDguNzExNzY5NjggMTMuODg0MjM1OSw4LjcxOTIzMDc0IEMxMy43ODIyNzA0LDguNzM2NjM5NjcgMTMuNjg3NzY1NCw4Ljc3NjQzMTE1IDEzLjYwNTY5NTYsOC44Mzg2MDUxOCBMMTAuMjQzMzE1NiwxMS4zODUyNTk4IEMxMC4wNzY2ODg2LDExLjUwNDYzNDMgOS45NzcyMDk5MywxMS42OTg2MTgxIDkuOTc3MjA5OTMsMTEuOTAyNTQ5MSBDOS45NzcyMDk5MywxMi4xMDY0ODA3IDEwLjA3NjY4ODYsMTIuMzAwNDYzOSAxMC4yNDMzMTU2LDEyLjQxOTgzODMgTDEzLjYwNTY5NTYsMTQuOTY2NDkzIEMxMy44OTE2OTcsMTUuMTgwMzcyNSAxNC4yOTcwNzI5LDE1LjEyMzE3MjEgMTQuNTEwOTUxNywxNC44MzcxNzA3IEMxNC43MjQ4MzEzLDE0LjU1MTE2OTIgMTQuNjY3NjMwOSwxNC4xNDU3OTQgMTQuMzgxNjI5NCwxMy45MzE5MTQ1IEwxMi41MzEzMjU3LDEyLjUzOTIxMjcgTDIxLjg4MTI0OTUsMTIuNTM5MjEyNyBMMjEuODgxMjQ5NSwxMS4yNjU4ODU0IEwxMi41MzEzMjU3LDExLjI2NTg4NTQgTDE0LjM4MTYyOTQsOS44NzMxODM2NCBDMTQuNjM3Nzg3Miw5LjcxNjUwNDUzIDE0Ljc0OTcwMDYsOS40MDA2NjAxNCAxNC42NDc3MzUxLDkuMTE3MTQ1NTMgQzE0LjU0ODI1NjQsOC44MzM2MzE1NiAxNC4yNjIyNTUsOC42NTk1NDM1MiAxMy45NjM4MTg5LDguNjk5MzM1IFoiIGlkPSJhcnJvdyIgZmlsbD0iIzAwMDAwMCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTUuOTI5MjMwLCAxMS44OTQ3MzcpIHJvdGF0ZSgtMTgwLjAwMDAwMCkgdHJhbnNsYXRlKC0xNS45MjkyMzAsIC0xMS44OTQ3MzcpICIgLz4KICAgICAgICA8L2c+CiAgICA8L2c+Cjwvc3ZnPg==" />
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | |||
| #4CA64C | 6 |
col_vals_ge()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- |
matches() selectors together to select all numeric columns that fit a specific pattern.
``` python
tbl = pl.DataFrame(
{
"name": ["Alice", "Bob", "Charlie"],
"2022_status": ["ft", "ft", "pt"],
"2023_status": ["ft", "pt", "ft"],
"2024_status": ["ft", "pt", "ft"],
"2022_pay_total": [18.62, 16.95, 18.25],
"2023_pay_total": [19.29, 17.75, 18.35],
"2024_pay_total": [20.73, 18.35, 20.10],
}
)
validation = (
pb.Validate(data=tbl)
.col_vals_lt(columns=pb.col(ncs.numeric() & ncs.matches("2023|2024")), value=30)
.interrogate()
)
validation
```
| STEP | COLUMNS | VALUES | TBL | EVAL | UNITS | PASS | FAIL | W | E | C | EXT | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| #4CA64C | 1 | 
col_vals_lt()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- | ||
| #4CA64C | 2 |
col_vals_lt()
|
|
✓ | 3 | 3 1.00 |
0 0.00 |
-- | -- | -- | -- |
matches() column selector functions from Narwhals, combined with the `&` operator. This is necessary to specify the set of columns that are numeric *and* match the text `"2023"` or `"2024"`.
#### See Also
[Create](Create.md)