docs: Introduce concept of funneling alongside eagerness and lazyness (#496)

* check_funneled()

* docs: Introduce concept of funneling alongside eagerness and lazyness

* chore: Auto-update from GitHub Actions

Run: https://github.com/tidyverse/duckplyr/actions/runs/12962250056

Author: krlmlr

NAMESPACE

@@ -8,7 +8,7 @@ S3method(add_count,duckplyr_df)
 S3method(anti_join,duckplyr_df)
 S3method(arrange,duckplyr_df)
 S3method(as.data.frame,duckplyr_df)
-S3method(as.data.frame,lazy_duckplyr_df)
+S3method(as.data.frame,funneled_duckplyr_df)
 S3method(as_duckdb_tibble,data.frame)
 S3method(as_duckdb_tibble,default)
 S3method(as_duckdb_tibble,duckplyr_df)
@@ -19,7 +19,7 @@ S3method(as_duckdb_tibble,tbl_duckdb_connection)
 S3method(as_tibble,duckplyr_df)
 S3method(auto_copy,duckplyr_df)
 S3method(collect,duckplyr_df)
-S3method(collect,lazy_duckplyr_df)
+S3method(collect,funneled_duckplyr_df)
 S3method(compute,duckplyr_df)
 S3method(count,duckplyr_df)
 S3method(cross_join,duckplyr_df)

R/add_count.R

@@ -10,7 +10,7 @@ add_count.duckplyr_df <- function(x, ..., wt = NULL, sort = FALSE, name = NULL,
   )
 
   # dplyr forward
-  check_lazy(x, duckplyr_error)
+  check_funneled(x, duckplyr_error)
 
   add_count <- dplyr$add_count.data.frame
   out <- add_count(x, ..., wt = {{ wt }}, sort = sort, name = name, .drop = .drop)

R/anti_join.R

@@ -19,7 +19,7 @@ anti_join.duckplyr_df <- function(x, y, by = NULL, copy = FALSE, ..., na_matches
   )
 
   # dplyr forward
-  check_lazy(x, duckplyr_error)
+  check_funneled(x, duckplyr_error)
 
   anti_join <- dplyr$anti_join.data.frame
   out <- anti_join(x, y, by, copy = FALSE, ..., na_matches = na_matches)

R/arrange.R

@@ -52,7 +52,7 @@ arrange.duckplyr_df <- function(.data, ..., .by_group = FALSE, .locale = NULL) {
   )
 
   # dplyr forward
-  check_lazy(.data, duckplyr_error)
+  check_funneled(.data, duckplyr_error)
 
   arrange <- dplyr$arrange.data.frame
   out <- arrange(.data, ..., .by_group = .by_group, .locale = .locale)

R/compute-rd.R

@@ -1,19 +1,19 @@
 #' @title Compute results
 #'
 #' @description  This is a method for the [dplyr::compute()] generic.
-#' For a (lazy) duckplyr frame,
+#' For a (funneled) duckplyr frame,
 #' `compute()` executes a query but stores it in a (temporary) table,
 #' or in a Parquet or CSV file.
 #' The result is a duckplyr frame that can be used with subsequent dplyr verbs.
 #'
 #' @inheritParams dplyr::compute
-#' @param lazy Set to `TRUE` to return a lazy or `FALSE` to return an eager data frame,
-#'   see the "Eager and lazy" section.
-#'   The default is to inherit the lazyness of the input.
+#' @param funnel Set to `TRUE` to return a funneled or `FALSE` to return an unfunneled data frame,
+#'   see the "Funneling" section.
+#'   The default is to inherit the funnelness of the input.
 #' @param name The name of the table to store the result in.
 #' @param schema_name The schema to store the result in, defaults to the current schema.
 #' @param temporary Set to `FALSE` to store the result in a permanent table.
-#' @inheritSection duckdb_tibble Eager and lazy
+#' @inheritSection duckdb_tibble Funneling
 #' @examples
 #' library(duckplyr)
 #' df <- duckdb_tibble(x = c(1, 2))

R/compute.R

@@ -4,13 +4,13 @@
 compute.duckplyr_df <- function(
   x,
   ...,
-  lazy = NULL,
+  funnel = NULL,
   name = NULL,
   schema_name = NULL,
   temporary = TRUE
 ) {
-  if (is.null(lazy)) {
-    lazy <- get_lazy_duckplyr_df(x)
+  if (is.null(funnel)) {
+    funnel <- get_funnel_duckplyr_df(x)
   }
   if (is.null(schema_name)) {
     schema_name <- ""
@@ -35,16 +35,16 @@ compute.duckplyr_df <- function(
 
       out <- duckplyr_reconstruct(out_rel, x)
 
-      if (get_lazy_duckplyr_df(out) != lazy) {
-        out <- as_duckdb_tibble(out, lazy = lazy)
+      if (get_funnel_duckplyr_df(out) != funnel) {
+        out <- as_duckdb_tibble(out, funnel = funnel)
       }
 
       return(out)
     }
   )
 
   # dplyr forward
-  check_lazy(x, duckplyr_error)
+  check_funneled(x, duckplyr_error)
 
   compute <- dplyr$compute.data.frame
   out <- compute(x, ...)

R/compute_file.R

@@ -1,15 +1,15 @@
 #' @title Compute results to a file
 #'
 #' @description
-#' These functions apply to (lazy) duckplyr frames.
+#' These functions apply to (funneled) duckplyr frames.
 #' They executes a query and stores the results in a flat file.
 #' The result is a duckplyr frame that can be used with subsequent dplyr verbs.
 #'
 #' `compute_parquet()` creates a Parquet file.
 #'
 #' @inheritParams rlang::args_dots_empty
 #' @inheritParams compute.duckplyr_df
-#' @inheritSection duckdb_tibble Eager and lazy
+#' @inheritSection duckdb_tibble Funneling
 #' @param path The path to store the result in.
 #' @param options A list of additional options to pass to create the storage format,
 #'   see <https://duckdb.org/docs/data/parquet/overview#writing-to-parquet-files>
@@ -26,15 +26,15 @@
 #' explain(df)
 #' @seealso [compute.duckplyr_df()], [dplyr::collect()]
 #' @name compute_file
-compute_parquet <- function(x, path, ..., lazy = NULL, options = NULL) {
+compute_parquet <- function(x, path, ..., funnel = NULL, options = NULL) {
   check_dots_empty()
 
   if (is.null(options)) {
     options <- list()
   }
 
-  if (is.null(lazy)) {
-    lazy <- get_lazy_duckplyr_df(x)
+  if (is.null(funnel)) {
+    funnel <- get_funnel_duckplyr_df(x)
   }
 
   rel <- duckdb_rel_from_df(x)
@@ -46,23 +46,23 @@ compute_parquet <- function(x, path, ..., lazy = NULL, options = NULL) {
     path <- file.path(path, "**", "**.parquet")
   }
 
-  read_parquet_duckdb(path, lazy = lazy)
+  read_parquet_duckdb(path, funnel = funnel)
 }
 
 #' compute_csv()
 #'
 #' `compute_csv()` creates a CSV file.
 #' @rdname compute_file
 #' @export
-compute_csv <- function(x, path, ..., lazy = NULL, options = NULL) {
+compute_csv <- function(x, path, ..., funnel = NULL, options = NULL) {
   check_dots_empty()
 
   if (is.null(options)) {
     options <- list()
   }
 
-  if (is.null(lazy)) {
-    lazy <- get_lazy_duckplyr_df(x)
+  if (is.null(funnel)) {
+    funnel <- get_funnel_duckplyr_df(x)
   }
 
   rel <- duckdb_rel_from_df(x)
@@ -74,5 +74,5 @@ compute_csv <- function(x, path, ..., lazy = NULL, options = NULL) {
     path <- file.path(path, "**", "**.csv")
   }
 
-  read_csv_duckdb(path, lazy = lazy)
+  read_csv_duckdb(path, funnel = funnel)
 }

R/count.R

@@ -59,7 +59,7 @@ count.duckplyr_df <- function(x, ..., wt = NULL, sort = FALSE, name = NULL, .dro
   # out <- count(x_df, !!!quos, wt = {{ wt }}, sort = sort, name = name, .drop = .drop)
 
   # dplyr forward
-  check_lazy(x, duckplyr_error)
+  check_funneled(x, duckplyr_error)
 
   count <- dplyr$count.data.frame
   out <- count(x, ..., wt = {{ wt }}, sort = sort, name = name, .drop = .drop)

R/cross_join.R

@@ -10,7 +10,7 @@ cross_join.duckplyr_df <- function(x, y, ..., copy = FALSE, suffix = c(".x", ".y
   )
 
   # dplyr forward
-  check_lazy(x, duckplyr_error)
+  check_funneled(x, duckplyr_error)
 
   cross_join <- dplyr$cross_join.data.frame
   out <- cross_join(x, y, ..., copy = copy, suffix = suffix)

R/distinct.R

@@ -69,7 +69,7 @@ distinct.duckplyr_df <- function(.data, ..., .keep_all = FALSE) {
   )
 
   # dplyr forward
-  check_lazy(.data, duckplyr_error)
+  check_funneled(.data, duckplyr_error)
 
   distinct <- dplyr$distinct.data.frame
   out <- distinct(.data, ..., .keep_all = .keep_all)