asof_join()

Match each left row with the latest right row at or before it.

Usage

asof_join(
    left,
    right,
    on,
    by=(),
    tolerance=None,
    *,
    key=None,
    how="left",
)

on is the time column of both tables; rows match only when their by columns are equal and left.on - tolerance <= right.on <= left.on. key identifies left rows (default: by and on); the left table must not repeat it. With how="left", left rows without a match are kept with NULLs. The output has the left columns, then the right ones except by, with clashing names suffixed _right (so on_right is the time of the match).

Parameters

left: ir.Table: The table whose rows are matched; one output row per left row.
right: ir.Table: The table to take the latest earlier row from. For the result to be determined, requires must give it a key on (*by, on).
on: str: The time column, of the same name in both tables.
by: str | Sequence[str] = (): Columns that must be equal for rows to match, as one name or a sequence. Default: none.
tolerance: Any = None: How much earlier than the left row a match may be (an Ibis interval, or a number for numeric time columns). Default None: no limit. The join computes on - tolerance, which overflows at the type’s smallest value; a contract infers the lower bound on the left on column that rules it out (#244).
key: Sequence[str] | None = None: Columns that identify left rows. Default: by and on.
how: Literal["left", "inner"] = "left": "left" (the default) keeps left rows without a match, with NULLs; "inner" drops them.

Returns

ir.Table: An Ibis table expression, built from a range join and ROW_NUMBER.