Core sorted-merge algorithm for as-of join.
Part 1 — asof-search / asof-indices: asof-search — binary search for the last right index where value <= target. asof-indices — two-pointer merge over pre-sorted, pre-grouped vectors; public utility, not used internally by asof-match.
Part 2 — asof-match: full key-handling layer. Builds (or accepts a prebuilt)
:asof index from datajure.index, then runs asof-search (binary search) per
left row. Returns a lazy sequence of [left-row-idx right-row-idx-or-nil] pairs.
Part 3 — build-result: assembles a tech.v3.dataset from the index pairs.
Left columns always present in original order; right non-key columns
appended (nil-filled for unmatched rows). Conflicting non-key column
names prefixed with right. (e.g. :v -> :right.v).
The right-side index construction lives in datajure.index (the :asof kind);
this namespace owns the search (asof-search) and result assembly.
Core sorted-merge algorithm for as-of join.
Part 1 — asof-search / asof-indices:
asof-search — binary search for the last right index where value <= target.
asof-indices — two-pointer merge over pre-sorted, pre-grouped vectors;
public utility, not used internally by asof-match.
Part 2 — asof-match: full key-handling layer. Builds (or accepts a prebuilt)
`:asof` index from datajure.index, then runs asof-search (binary search) per
left row. Returns a lazy sequence of [left-row-idx right-row-idx-or-nil] pairs.
Part 3 — build-result: assembles a tech.v3.dataset from the index pairs.
Left columns always present in original order; right non-key columns
appended (nil-filled for unmatched rows). Conflicting non-key column
names prefixed with `right.` (e.g. :v -> :right.v).
The right-side index construction lives in datajure.index (the `:asof` kind);
this namespace owns the search (asof-search) and result assembly.(asof-indices left-vals right-vals)Two-pointer merge: for each element in left-vals, return a long-array
of the matched right-row index within right-vals (both must be pre-sorted
ascending). Returns -1 for left rows with no match. Nil values are skipped.
Public utility — not used internally by asof-match, which uses asof-search (binary search per group) instead.
Two-pointer merge: for each element in `left-vals`, return a long-array of the matched right-row index within `right-vals` (both must be pre-sorted ascending). Returns -1 for left rows with no match. Nil values are skipped. Public utility — not used internally by asof-match, which uses asof-search (binary search per group) instead.
(asof-match left right left-keys right-keys)(asof-match left right left-keys right-keys opts)(asof-match left right left-keys right-keys direction tolerance)Produce index pairs for an as-of join: a lazy sequence of
[left-row-idx right-row-idx-or-nil] in left-row order (unmatched left rows
yield nil). Thin wrapper over asof-row-indices.
Arities: 4-arg defaults; 5-arg opts map (:direction / :tolerance / :right-index — see asof-row-indices); 6-arg (… direction tolerance) kept for back-compatibility.
Produce index pairs for an as-of join: a lazy sequence of [left-row-idx right-row-idx-or-nil] in left-row order (unmatched left rows yield nil). Thin wrapper over `asof-row-indices`. Arities: 4-arg defaults; 5-arg opts map (:direction / :tolerance / :right-index — see asof-row-indices); 6-arg (… direction tolerance) kept for back-compatibility.
(asof-row-indices left right left-keys right-keys opts)Core as-of matching. Returns {:li <long[]> :ri <long[]>}: for each left row,
in left-row order, li is the left row index and ri the matched right row
index (-1 = no match). Both arrays have length (row-count left). This is the
primitive-array form asof-match and the join layer build on — it allocates no
per-row pair objects.
Arguments: left, right, left-keys, right-keys (last key col = asof, rest =
exact), and opts:
:direction — :backward (default), :forward, or :nearest
:tolerance — numeric max abs distance; nil = unbounded. Requires a numeric
asof key. Matches exceeding it become no-match (-1).
:right-index — (optional) a prebuilt :asof index over right/right-keys
(from datajure.index); reused instead of rebuilt. Validated
against right (identical?) and right-keys.
Core as-of matching. Returns {:li <long[]> :ri <long[]>}: for each left row,
in left-row order, `li` is the left row index and `ri` the matched right row
index (-1 = no match). Both arrays have length (row-count left). This is the
primitive-array form asof-match and the join layer build on — it allocates no
per-row pair objects.
Arguments: left, right, left-keys, right-keys (last key col = asof, rest =
exact), and `opts`:
:direction — :backward (default), :forward, or :nearest
:tolerance — numeric max abs distance; nil = unbounded. Requires a numeric
asof key. Matches exceeding it become no-match (-1).
:right-index — (optional) a prebuilt :asof index over `right`/`right-keys`
(from datajure.index); reused instead of rebuilt. Validated
against `right` (identical?) and `right-keys`.(asof-search right-vals n target)(asof-search right-vals n target direction)Binary search over sorted right-vals for the best match to target.
Nils in right-vals are treated as greater than any real value (they sort last).
Nil target always returns -1.
direction (optional, default :backward): :backward — last index where right-val <= target (default, SQL ASOF convention) :forward — first index where right-val >= target :nearest — closest index by absolute distance; ties prefer :backward
Returns -1 if no qualifying match exists.
Binary search over sorted `right-vals` for the best match to `target`. Nils in right-vals are treated as greater than any real value (they sort last). Nil target always returns -1. direction (optional, default :backward): :backward — last index where right-val <= target (default, SQL ASOF convention) :forward — first index where right-val >= target :nearest — closest index by absolute distance; ties prefer :backward Returns -1 if no qualifying match exists.
(build-result left right pairs right-keys)Assemble the as-of join result dataset from index pairs (back-compat wrapper
over build-result-arrays).
Arguments: left — tech.v3.dataset (all rows preserved, in original order) right — tech.v3.dataset pairs — seq of [left-row-idx right-row-idx-or-nil] right-keys — right key columns (dropped from the appended right columns)
Returns a dataset with:
right. (e.g. :v -> :right.v)Assemble the as-of join result dataset from index pairs (back-compat wrapper over `build-result-arrays`). Arguments: left — tech.v3.dataset (all rows preserved, in original order) right — tech.v3.dataset pairs — seq of [left-row-idx right-row-idx-or-nil] right-keys — right key columns (dropped from the appended right columns) Returns a dataset with: - all left columns in original order - right non-key columns appended (nil-filled for unmatched rows) - conflicting non-key column names prefixed with `right.` (e.g. :v -> :right.v)
(build-result-arrays left right li-arr ri-arr right-keys)Assemble the as-of join result from primitive li/ri arrays (ri = -1 for an
unmatched left row). See build-result for the column layout. Each right
column is gathered into a single object-array (unmatched positions stay nil),
so peak working memory is one column-width rather than all right columns at
once, and no per-row pair objects are allocated.
Assemble the as-of join result from primitive li/ri arrays (ri = -1 for an unmatched left row). See `build-result` for the column layout. Each right column is gathered into a single object-array (unmatched positions stay nil), so peak working memory is one column-width rather than all right columns at once, and no per-row pair objects are allocated.
(window-indices left right left-keys right-keys opts)(window-indices left right left-keys right-keys lo-offset hi-offset)For each left row, find all right row indices whose asof-key falls within [left-asof-key + lo-offset, left-asof-key + hi-offset] (both bounds inclusive).
Arguments: left, right — tech.v3.dataset left-keys — column keywords (last = asof col, rest = exact-match cols) right-keys — column keywords (same structure as left-keys) lo-offset — lower bound offset added to left asof-key (numeric, raw units) hi-offset — upper bound offset added to left asof-key (numeric, raw units)
An opts-map arity {:lo :hi :right-index} is also accepted; :right-index is
an optional prebuilt :asof index over right/right-keys (validated, reused
instead of rebuilt).
Returns a sequence of [left-row-idx [matched-right-original-row-indices]] pairs. Empty inner vector means no right rows fell in the window (left row still appears). Left rows with nil asof-key always yield an empty inner vector.
For each left row, find all right row indices whose asof-key falls within
[left-asof-key + lo-offset, left-asof-key + hi-offset] (both bounds inclusive).
Arguments:
left, right — tech.v3.dataset
left-keys — column keywords (last = asof col, rest = exact-match cols)
right-keys — column keywords (same structure as left-keys)
lo-offset — lower bound offset added to left asof-key (numeric, raw units)
hi-offset — upper bound offset added to left asof-key (numeric, raw units)
An opts-map arity `{:lo :hi :right-index}` is also accepted; `:right-index` is
an optional prebuilt :asof index over `right`/`right-keys` (validated, reused
instead of rebuilt).
Returns a sequence of [left-row-idx [matched-right-original-row-indices]] pairs.
Empty inner vector means no right rows fell in the window (left row still appears).
Left rows with nil asof-key always yield an empty inner vector.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |