Restrict an Expectation to specific rows
By default, Expectations apply to the entire dataset retrieved in a Batch. However, there are instances when an Expectation may not be relevant for every row. Validating every row could lead to false positives or false negatives in the Validation Results.
For example, you might define an Expectation that a column indicating the country of origin for a product should not be null. If this Expectation is only applicable when the product is an import, applying it to every row in the Batch could result in many false negatives when the country of origin column is null for products produced locally.
To address this issue, GX Core allows you to restrict Expectations to apply to only a subset of the data retrieved in a Batch.
Create an Expectation with row conditions
To restrict an Expectation to a subset of the data retrieved in a Batch, use the row_condition argument. The row_condition argument takes a boolean expression built with Python objects. Rows will be validated for the Expectation when the row_condition expression evaluates to True. Conversely, if the row_condition evaluates to False, the corresponding row will not be validated for the Expectation.
Prerequisites
- Python version 3.10 to 3.14.
- An installation of GX Core.
- A preconfigured Data Context.
- Recommended. A preconfigured Data Source and Data Asset connected to your data for testing your customized Expectation.
Procedure
- Instructions
- Sample code
-
Determine the
row_conditionexpression.To support complex business use cases, logical clauses can be combined with AND / OR relationships within the
row_conditionargument.Pythonfrom great_expectations.expectations.row_conditions import Column
# Create condition statements with column references and Python comparisons.
statement_1 = Column("tenure") > 2
statement_2 = Column("salary") <= 50000
statement_3 = Column("department") == "Sales"
# Combine condition statements with an AND relationship into condition blocks.
block_1 = statement_1 & statement_2
block_2 = statement_3
# Combine condition blocks with OR.
row_condition = block_1 | block_2Here are some examples of how to create common patterns in row conditions:
-
A and B.
Python# Two condition statements within a single condition block.
statement_1 = Column("A") == "a"
statement_2 = Column("B") == "b"
block_1 = statement_1 & statement_2
row_condition = block_1 -
A or B.
Python# Two condition statements, each in its own condition block.
statement_1 = Column("A") == "a"
statement_2 = Column("B") == "b"
block_1 = statement_1
block_2 = statement_2
row_condition = block_1 | block_2 -
(A and B) or (C and D).
Python# Two condition statements in one condition block and two statements in another block.
statement_1 = Column("A") == "a"
statement_2 = Column("B") == "b"
statement_3 = Column("C") == "c"
statement_4 = Column("D") == "d"
block_1 = statement_1 & statement_2
block_2 = statement_3 & statement_4
row_condition = block_1 | block_2 -
A and (B or C). This pattern is not supported verbatim, but you can achieve the same result with (A and B) or (A and C).
Python# Two condition statements in one condition block and two statements in another block.
statement_1 = Column("A") == "a"
statement_2 = Column("B") == "b"
statement_3 = Column("C") == "c"
block_1 = statement_1 & statement_2
block_2 = statement_1 & statement_3
row_condition = block_1 | block_2
The following comparison operators are supported:
==,!=,>,<,>=,<=,is_in,is_not_in,is_null,is_not_null. The==,!=,>,<,>=, and<=operators compare a column either to a value or to another column. To learn more, see Compare two columns. Here are some examples of using different kinds of operators:Python# Single value comparisons: ==, !=, >, <, >=, <=
statement_1 = Column("count") == 1
statement_2 = Column("date") > datetime(year=2025, month=1, day=31, tzinfo=timezone.utc)
# Column comparisons: ==, !=, >, <, >=, <= with another column on the right-hand side
statement_column_comparison = Column("end_date") > Column("start_date")
# Set comparisons: is_in, is_not_in
statement_3 = Column("department").is_in(["sales", "finance"])
# Nullity checks: is_null, is_not_null
statement_4 = Column("name").is_null() -
-
Configure the Expectation.
Python# Add the `row_condition` parameter alongside the Expectation's other arguments.
expectation = gx.expectations.ExpectColumnValuesToBeBetween(
column="bonus", min_value=5000, max_value=10000, row_condition=row_condition
) -
Optional. Configure additional variations of the Expectation.
Expectations that have different row conditions are treated as unique, even if they are of the same type, apply to the same column, and belong to the same Expectation Suite. This allows you to validate your data through multiple lenses.
For instance, the following code establishes an Expectation that the value in the
cycle_typecolumn is eitherunicycle,bicycle, ortricycle.Pythonexpectation_without_row_conditions = (
gx.expectations.ExpectColumnDistinctValuesToBeInSet(
column="cycle_type", value_set=["unicycle", "bicycle", "tricycle"]
)
)While, for example, the following code creates an Expectation that the value of the
cycle_typecolumn isunicycleif the item has one wheel.Pythonexpectation_with_row_conditions = gx.expectations.ExpectColumnValuesToBeInSet(
column="cycle_type",
value_set=["unicycle"],
row_condition=(Column("wheels") == 1),
)
Now you can add your Expectations to an Expectation Suite.
import great_expectations as gx
context = gx.get_context()
from great_expectations.expectations.row_conditions import Column
# Create condition statements with column references and Python comparisons.
statement_1 = Column("tenure") > 2
statement_2 = Column("salary") <= 50000
statement_3 = Column("department") == "Sales"
# Combine condition statements with an AND relationship into condition blocks.
block_1 = statement_1 & statement_2
block_2 = statement_3
# Combine condition blocks with OR.
row_condition = block_1 | block_2
# Add the `row_condition` parameter alongside the Expectation's other arguments.
expectation = gx.expectations.ExpectColumnValuesToBeBetween(
column="bonus", min_value=5000, max_value=10000, row_condition=row_condition
)
Compare two columns
A row condition can compare the values in two columns of the same row. Put a Column on the right-hand side of the comparison instead of a value. A row is validated when the comparison evaluates to True for that row.
from great_expectations.expectations.row_conditions import Column
# Put a `Column` on the right-hand side to compare two columns row by row.
# An invoice that was paid less than it was billed for must not be marked as paid.
row_condition = Column("amount_paid") < Column("amount_due")
expectation_with_column_comparison = gx.expectations.ExpectColumnValuesToBeInSet(
column="status",
value_set=["unpaid", "partially_paid"],
row_condition=row_condition,
)
A column comparison can be combined with other condition statements using & and |, the same as any other condition. For the rules that apply when the columns hold null values, NaN values, strings, or values of different types, see Column comparisons.
Row conditions in Data Docs
If an Expectation has row conditions, this will be indicated in the Data Docs. Each Expectation with row conditions is prefaced with if row_condition, then values must ... as illustrated in the following example:

If the row_condition is a complex expression, it will be divided into several components to enhance readability.
Scope and limitations
Keep the following in mind when working with row conditions:
- An Expectation can have up to 100 condition statements grouped in any number of condition blocks.
- The following Expectations do not accept the
row_conditionargument:expect_column_to_existexpect_query_results_to_match_comparisonexpect_table_columns_to_match_ordered_listexpect_table_columns_to_match_setexpect_table_column_count_to_be_betweenexpect_table_column_count_to_equalunexpected_rows_expectation
Column comparisons
Keep the following in mind when comparing two columns:
-
Null values. A row with a null in either column is never validated, whichever operator you use and whichever Data Source evaluates the condition. This includes
!=, because a null is neither equal to nor different from another value. To validate those rows as well, add a null check for each column to an OR group.Pythonfrom great_expectations.expectations.row_conditions import OrCondition
underpaid = Column("amount_paid") < Column("amount_due")
# An invoice with no payment recorded has a null `amount_paid`. To validate rows with a null
# in either column as well, add a null check for each column.
# Build the OR group with `OrCondition`. Chaining three conditions with `|` creates a
# nested OR, which is not allowed.
row_condition = OrCondition(
conditions=[
underpaid,
Column("amount_paid").is_null(),
Column("amount_due").is_null(),
]
)
expectation_with_null_rows = gx.expectations.ExpectColumnValuesToBeInSet(
column="status",
value_set=["unpaid", "partially_paid"],
row_condition=row_condition,
)Build the OR group with
OrCondition, as shown. Chaining three conditions with|, as ina | b | c, creates an OR group nested inside another OR group, and row conditions do not allow nested OR groups, so GX rejects the condition. -
NaN values. How NaN is compared depends on the backend that evaluates the comparison. Pandas treats NaN as a missing value, so the null rule above applies: a row with a NaN in either column is never validated, for every operator. Spark and PostgreSQL store NaN as a value and compare it the same way as when a column holding NaN is compared with a value: NaN is equal to itself and greater than every number, so a row where the left column is NaN and the right column is
2.0satisfies>,>=, and!=, but not==,<, or<=. -
Strings. Strings are compared using the collation of the backend that evaluates the comparison, the same as when a column is compared with a literal string. For example, whether
"a"and"A"are equal depends on the backend. -
Comparable values. You are responsible for making sure that the two columns hold values that can be compared. GX does not check the types of the two columns. A backend may convert one side to match the other, as SQLite does based on column type affinity, or it may raise an error, as PostgreSQL does. If a backend cannot evaluate the comparison, the Expectation is unsuccessful. When an Expectation whose row condition compares columns fails with an error, GX adds the column comparisons to the error message. This happens for any error, not only one the comparison caused, so read the original error first to see whether it concerns the compared columns.
-
Sets. The
is_inandis_not_inoperators do not accept aColumn. They only compare a column to a list of values.