diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py index 8dcbbe8fc391..6ab52fe37f8a 100644 --- a/ibis/expr/types/generic.py +++ b/ibis/expr/types/generic.py @@ -370,6 +370,8 @@ def nullif(self, null_if_expr: Value) -> Value: Commonly used to avoid divide-by-zero problems by replacing zero with `NULL` in the divisor. + Equivalent to `(self == null_if_expr).ifelse(ibis.null(), self)`. + Parameters ---------- null_if_expr @@ -379,6 +381,36 @@ def nullif(self, null_if_expr: Value) -> Value: ------- Value Value expression + + Examples + -------- + >>> import ibis + >>> ibis.options.interactive = True + >>> vals = ibis.examples.penguins.fetch().head(5).sex + >>> vals + ┏━━━━━━━━┓ + ┃ sex ┃ + ┡━━━━━━━━┩ + │ string │ + ├────────┤ + │ male │ + │ female │ + │ female │ + │ NULL │ + │ female │ + └────────┘ + >>> vals.nullif("male") + ┏━━━━━━━━━━━━━━━━━━━━━┓ + ┃ NullIf(sex, 'male') ┃ + ┡━━━━━━━━━━━━━━━━━━━━━┩ + │ string │ + ├─────────────────────┤ + │ NULL │ + │ female │ + │ female │ + │ NULL │ + │ female │ + └─────────────────────┘ """ return ops.NullIf(self, null_if_expr).to_expr()