new_relational: Relational implementer's interface

Description

The constructor and generics described here define a class that helps separating dplyr's user interface from the actual underlying operations. In the longer term, this will help packages that implement the dplyr interface (such as dbplyr, dtplyr, arrow and similar) to focus on the core details of their functionality, rather than on the intricacies of dplyr's user interface.

new_relational() constructs an object of class "relational". Users are encouraged to provide the class argument. The typical use case will be to create a wrapper function.

rel_to_df() extracts a data frame representation from a relational object, to be used by dplyr::collect().

rel_filter() keeps rows that match a predicate, to be used by dplyr::filter().

rel_project() selects columns or creates new columns, to be used by dplyr::select(), dplyr::rename(), dplyr::mutate(), dplyr::relocate(), and others.

rel_aggregate() combines several rows into one, to be used by dplyr::summarize().

rel_order() reorders rows by columns or expressions, to be used by dplyr::arrange().

rel_join() joins or merges two tables, to be used by dplyr::left_join(), dplyr::right_join(), dplyr::inner_join(), dplyr::full_join(), dplyr::cross_join(), dplyr::semi_join(), and dplyr::anti_join().

rel_limit() limits the number of rows in a table, to be used by utils::head().

rel_distinct() only keeps the distinct rows in a table, to be used by dplyr::distinct().

rel_set_intersect() returns rows present in both tables, to be used by generics::intersect().

rel_set_diff() returns rows present in any of both tables, to be used by generics::setdiff().

rel_set_symdiff() returns rows present in any of both tables, to be used by dplyr::symdiff().

rel_union_all() returns rows present in any of both tables, to be used by dplyr::union_all().

rel_explain() prints an explanation of the plan executed by the relational object.

rel_alias() returns the alias name for a relational object.

rel_set_alias() sets the alias name for a relational object.

rel_names() returns the column names as character vector, to be used by colnames().

Usage

new_relational(..., class = NULL)
rel_to_df(rel, ...)
rel_filter(rel, exprs, ...)
rel_project(rel, exprs, ...)
rel_aggregate(rel, groups, aggregates, ...)
rel_order(rel, orders, ascending, ...)
rel_join(
  left,
  right,
  conds,
  join = c("inner", "left", "right", "outer", "cross", "semi", "anti"),
  join_ref_type = c("regular", "natural", "cross", "positional", "asof"),
  ...
)
rel_limit(rel, n, ...)
rel_distinct(rel, ...)
rel_set_intersect(rel_a, rel_b, ...)
rel_set_diff(rel_a, rel_b, ...)
rel_set_symdiff(rel_a, rel_b, ...)
rel_union_all(rel_a, rel_b, ...)
rel_explain(rel, ...)
rel_alias(rel, ...)
rel_set_alias(rel, alias, ...)
rel_names(rel, ...)

Value

new_relational() returns a new relational object.
rel_to_df() returns a data frame.
rel_names() returns a character vector.
All other generics return a modified relational object.

Arguments

...: Reserved for future extensions, must be empty.
class: Classes added in front of the "relational" base class.
rel, rel_a, rel_b, left, right: A relational object.
exprs: A list of "relational_relexpr" objects to filter by, created by new_relexpr().
groups: A list of expressions to group by.
aggregates: A list of expressions with aggregates to compute.
orders: A list of expressions to order by.
ascending: A logical vector describing the sort order.
conds: A list of expressions to use for the join.
join: The type of join.
join_ref_type: The ref type of join.
n: The number of rows.
alias: the new alias

Examples

Run this code

new_dfrel <- function(x) {
  stopifnot(is.data.frame(x))
  new_relational(list(x), class = "dfrel")
}
mtcars_rel <- new_dfrel(mtcars[1:5, 1:4])

rel_to_df.dfrel <- function(rel, ...) {
  unclass(rel)[[1]]
}
rel_to_df(mtcars_rel)

rel_filter.dfrel <- function(rel, exprs, ...) {
  df <- unclass(rel)[[1]]

  # A real implementation would evaluate the predicates defined
  # by the exprs argument
  new_dfrel(df[seq_len(min(3, nrow(df))), ])
}

rel_filter(
  mtcars_rel,
  list(
    relexpr_function(
      "gt",
      list(relexpr_reference("cyl"), relexpr_constant("6"))
    )
  )
)

rel_project.dfrel <- function(rel, exprs, ...) {
  df <- unclass(rel)[[1]]

  # A real implementation would evaluate the expressions defined
  # by the exprs argument
  new_dfrel(df[seq_len(min(3, ncol(df)))])
}

rel_project(
  mtcars_rel,
  list(relexpr_reference("cyl"), relexpr_reference("disp"))
)

rel_order.dfrel <- function(rel, exprs, ...) {
  df <- unclass(rel)[[1]]

  # A real implementation would evaluate the expressions defined
  # by the exprs argument
  new_dfrel(df[order(df[[1]]), ])
}

rel_order(
  mtcars_rel,
  list(relexpr_reference("mpg"))
)
rel_join.dfrel <- function(left, right, conds, join, ...) {
  left_df <- unclass(left)[[1]]
  right_df <- unclass(right)[[1]]

  # A real implementation would evaluate the expressions
  # defined by the conds argument,
  # use different join types based on the join argument,
  # and implement the join itself instead of relaying to left_join().
  new_dfrel(dplyr::left_join(left_df, right_df))
}

rel_join(new_dfrel(data.frame(mpg = 21)), mtcars_rel)

rel_limit.dfrel <- function(rel, n, ...) {
  df <- unclass(rel)[[1]]

  new_dfrel(df[seq_len(n), ])
}

rel_limit(mtcars_rel, 3)

rel_distinct.dfrel <- function(rel, ...) {
  df <- unclass(rel)[[1]]

  new_dfrel(df[!duplicated(df), ])
}

rel_distinct(new_dfrel(mtcars[1:3, 1:4]))

rel_names.dfrel <- function(rel, ...) {
  df <- unclass(rel)[[1]]

  names(df)
}

rel_names(mtcars_rel)

Run the code above in your browser using DataLab