The mutating joins add columns from y to x, matching rows based on the keys:

  • inner_join(): includes all rows in x and y.

  • left_join(): includes all rows in x.

  • right_join(): includes all rows in y.

  • full_join(): includes all rows in x or y.

If a row in x matches multiple rows in y, all the rows in y will be returned once for each matching row in x.

inner_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

# S3 method for data.frame
inner_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  na_matches = c("na", "never")
)

left_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = FALSE
)

# S3 method for data.frame
left_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = FALSE,
  na_matches = c("na", "never")
)

right_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = FALSE
)

# S3 method for data.frame
right_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = FALSE,
  na_matches = c("na", "never")
)

full_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = FALSE
)

# S3 method for data.frame
full_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = FALSE,
  na_matches = c("na", "never")
)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A character vector of variables to join by.

If NULL, the default, *_join() will perform a natural join, using all variables in common across x and y. A message lists the variables so that you can check they're correct; suppress the message by supplying by explicitly.

To join by different variables on x and y, use a named vector. For example, by = c("a" = "b") will match x$a to y$b.

To join by multiple variables, use a vector with length > 1. For example, by = c("a", "b") will match x$a to y$a and x$b to y$b. Use a named vector to match different variables in x and y. For example, by = c("a" = "b", "c" = "d") will match x$a to y$b and x$c to y$d.

To perform a cross-join, generating all combinations of x and y, use by = character().

copy

If x and y are not from the same data source, and copy is TRUE, then y will be copied into the same src as x. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.

suffix

If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.

...

Other parameters passed onto methods.

na_matches

Should NA and NaN values match one another?

The default, "na", treats two NA or NaN values as equal, like %in%, match(), merge().

Use "never" to always treat two NA or NaN values as different, like joins for database sources, similarly to merge(incomparables = FALSE).

keep

Should the join keys from both x and y be preserved in the output? Only applies to nest_join(), left_join(), right_join(), and full_join().

Value

An object of the same type as x. The order of the rows and columns of x is preserved as much as possible. The output has the following properties:

  • For inner_join(), a subset of x rows. For left_join(), all x rows. For right_join(), a subset of x rows, followed by unmatched y rows. For full_join(), all x rows, followed by unmatched y rows.

  • For all joins, rows will be duplicated if one or more rows in x matches multiple rows in y.

  • Output columns include all x columns and all y columns. If columns in x and y have the same name (and aren't included in by), suffixes are added to disambiguate.

  • Output columns included in by are coerced to common type across x and y.

  • Groups are taken from x.

Methods

These functions are generics, which means that packages can provide implementations (methods) for other classes. See the documentation of individual methods for extra arguments and differences in behaviour.

Methods available in currently loaded packages:

  • inner_join(): dbplyr (tbl_lazy), dplyr (data.frame) .

  • left_join(): dbplyr (tbl_lazy), dplyr (data.frame) .

  • right_join(): dbplyr (tbl_lazy), dplyr (data.frame) .

  • full_join(): dbplyr (tbl_lazy), dplyr (data.frame) .

See also

Other joins: filter-joins, nest_join()

Examples

band_members %>% inner_join(band_instruments)
#> Joining, by = "name"
#> # A tibble: 2 x 3 #> name band plays #> <chr> <chr> <chr> #> 1 John Beatles guitar #> 2 Paul Beatles bass
band_members %>% left_join(band_instruments)
#> Joining, by = "name"
#> # A tibble: 3 x 3 #> name band plays #> <chr> <chr> <chr> #> 1 Mick Stones NA #> 2 John Beatles guitar #> 3 Paul Beatles bass
band_members %>% right_join(band_instruments)
#> Joining, by = "name"
#> # A tibble: 3 x 3 #> name band plays #> <chr> <chr> <chr> #> 1 John Beatles guitar #> 2 Paul Beatles bass #> 3 Keith NA guitar
band_members %>% full_join(band_instruments)
#> Joining, by = "name"
#> # A tibble: 4 x 3 #> name band plays #> <chr> <chr> <chr> #> 1 Mick Stones NA #> 2 John Beatles guitar #> 3 Paul Beatles bass #> 4 Keith NA guitar
# To suppress the message about joining variables, supply `by` band_members %>% inner_join(band_instruments, by = "name")
#> # A tibble: 2 x 3 #> name band plays #> <chr> <chr> <chr> #> 1 John Beatles guitar #> 2 Paul Beatles bass
# This is good practice in production code # Use a named `by` if the join variables have different names band_members %>% full_join(band_instruments2, by = c("name" = "artist"))
#> # A tibble: 4 x 3 #> name band plays #> <chr> <chr> <chr> #> 1 Mick Stones NA #> 2 John Beatles guitar #> 3 Paul Beatles bass #> 4 Keith NA guitar
# By default, the join keys from `x` and `y` are coalesced in the output; use # `keep = TRUE` to keep the join keys from both `x` and `y` band_members %>% full_join(band_instruments2, by = c("name" = "artist"), keep = TRUE)
#> # A tibble: 4 x 4 #> name band artist plays #> <chr> <chr> <chr> <chr> #> 1 Mick Stones NA NA #> 2 John Beatles John guitar #> 3 Paul Beatles Paul bass #> 4 NA NA Keith guitar
# If a row in `x` matches multiple rows in `y`, all the rows in `y` will be # returned once for each matching row in `x` df1 <- tibble(x = 1:3) df2 <- tibble(x = c(1, 1, 2), y = c("first", "second", "third")) df1 %>% left_join(df2)
#> Joining, by = "x"
#> # A tibble: 4 x 2 #> x y #> <dbl> <chr> #> 1 1 first #> 2 1 second #> 3 2 third #> 4 3 NA
# By default, NAs match other NAs so that there are two # rows in the output of this join: df1 <- data.frame(x = c(1, NA), y = 2) df2 <- data.frame(x = c(1, NA), z = 3) left_join(df1, df2)
#> Joining, by = "x"
#> x y z #> 1 1 2 3 #> 2 NA 2 3
# You can optionally request that NAs don't match, giving a # a result that more closely resembles SQL joins left_join(df1, df2, na_matches = "never")
#> Joining, by = "x"
#> x y z #> 1 1 2 3 #> 2 NA 2 NA