@@ -1166,9 +1166,17 @@ def collect(
11661166 ).to_expr ()
11671167
11681168 def identical_to (self , other : Value , / ) -> ir .BooleanValue :
1169- """Return whether this expression is identical to other .
1169+ """Like `==`, but always returns non-NULL, even when comparing NULLs .
11701170
1171- Corresponds to `IS NOT DISTINCT FROM` in SQL.
1171+ With regular equality, `NULL == <anything>` is always `NULL`,
1172+ even for `NULL == NULL`.
1173+
1174+ In contrast, `identical_to` treats `NULL` as a singleton value, so that
1175+
1176+ - `NULL.identical_to(NULL)` is `True`.
1177+ - `NULL.identical_to(<non-null>)` is `False`.
1178+
1179+ This corresponds to `IS NOT DISTINCT FROM` in SQL.
11721180
11731181 Parameters
11741182 ----------
@@ -1184,12 +1192,31 @@ def identical_to(self, other: Value, /) -> ir.BooleanValue:
11841192 --------
11851193 >>> import ibis
11861194 >>> ibis.options.interactive = True
1187- >>> one = ibis.literal(1)
1188- >>> two = ibis.literal(2)
1189- >>> two.identical_to(one + one)
1190- ┌──────┐
1191- │ True │
1192- └──────┘
1195+ >>> t = ibis.memtable(
1196+ ... [
1197+ ... (1, 1),
1198+ ... (1, 2),
1199+ ... (1, None),
1200+ ... (None, None),
1201+ ... ],
1202+ ... schema={"a": "int64", "b": "int64"},
1203+ ... )
1204+ >>> t.mutate(
1205+ ... eq=_.a == _.b,
1206+ ... neq=_.a != _.b,
1207+ ... identical=_.a.identical_to(_.b),
1208+ ... not_identical=~_.a.identical_to(_.b),
1209+ ... )
1210+ ┏━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
1211+ ┃ a ┃ b ┃ eq ┃ neq ┃ identical ┃ not_identical ┃
1212+ ┡━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
1213+ │ int64 │ int64 │ boolean │ boolean │ boolean │ boolean │
1214+ ├───────┼───────┼─────────┼─────────┼───────────┼───────────────┤
1215+ │ 1 │ 1 │ True │ False │ True │ False │
1216+ │ 1 │ 2 │ False │ True │ False │ True │
1217+ │ 1 │ NULL │ NULL │ NULL │ False │ True │
1218+ │ NULL │ NULL │ NULL │ NULL │ True │ False │
1219+ └───────┴───────┴─────────┴─────────┴───────────┴───────────────┘
11931220 """
11941221 try :
11951222 return ops .IdenticalTo (self , other ).to_expr ()
0 commit comments