left_join: Join two vectra tables

In vectra: Columnar Query Engine for Larger-than-RAM Data

Join two vectra tables

Description

Join two vectra tables

Usage

left_join(
  x,
  y,
  by = NULL,
  suffix = c(".x", ".y"),
  na_matches = c("na", "never"),
  ...
)

inner_join(
  x,
  y,
  by = NULL,
  suffix = c(".x", ".y"),
  na_matches = c("na", "never"),
  ...
)

right_join(
  x,
  y,
  by = NULL,
  suffix = c(".x", ".y"),
  na_matches = c("na", "never"),
  ...
)

full_join(
  x,
  y,
  by = NULL,
  suffix = c(".x", ".y"),
  na_matches = c("na", "never"),
  ...
)

semi_join(x, y, by = NULL, na_matches = c("na", "never"), ...)

anti_join(x, y, by = NULL, na_matches = c("na", "never"), ...)

Arguments

x	A vectra_node object (left table).
y	A vectra_node object (right table).
by	A character vector of column names to join by, or a named vector like c("a" = "b"). NULL for natural join (common columns).
suffix	A character vector of length 2 for disambiguating non-key columns with the same name (default c(".x", ".y")).
na_matches	How to match NA keys: "na" (default, as in dplyr) treats NA as matching NA; "never" uses SQL semantics where NA never matches.
...	Ignored.

Details

All joins use a build-right, probe-left hash join. The entire right-side table is materialized into a hash table; left-side batches stream through. Memory cost is proportional to the right-side table size.

By default NA keys match NA (dplyr's na_matches = "na"); pass na_matches = "never" for SQL NULL semantics. Key types are auto-coerced following the ⁠bool < int64 < double⁠ hierarchy. Joining string against numeric keys is an error.

Value

A vectra_node with the joined result.

Examples

f1 <- tempfile(fileext = ".vtr")
f2 <- tempfile(fileext = ".vtr")
write_vtr(data.frame(id = c(1, 2, 3), x = c(10, 20, 30)), f1)
write_vtr(data.frame(id = c(1, 2, 4), y = c(100, 200, 400)), f2)
left_join(tbl(f1), tbl(f2), by = "id") |> collect()
unlink(c(f1, f2))

vectra documentation built on July 31, 2026, 1:07 a.m.