feat: Implement argument matching for funnel (#546)

* feat: Implement argument matching for `funnel`

* Text

* 1

* 3

* 4

* 5

* 6

* 7

* 2

Author: krlmlr

R/ducktbl.R

@@ -50,7 +50,7 @@
 #' try(length(y$a))
 #' length(collect(y)$a)
 #' @export
-duckdb_tibble <- function(..., .funnel = "open") {
+duckdb_tibble <- function(..., .funnel = c("open", "drip", "closed")) {
   out <- tibble::tibble(...)
 
   # Side effect: check compatibility
@@ -70,7 +70,7 @@ duckdb_tibble <- function(..., .funnel = "open") {
 #' @param x The object to convert or to test.
 #' @rdname duckdb_tibble
 #' @export
-as_duckdb_tibble <- function(x, ..., funnel = "open") {
+as_duckdb_tibble <- function(x, ..., funnel = c("open", "drip", "closed")) {
   # Handle the funnel arg in the generic, only the other args will be dispatched
   as_duckdb_tibble <- function(x, ...) {
     UseMethod("as_duckdb_tibble")
@@ -87,6 +87,7 @@ as_duckdb_tibble.tbl_duckdb_connection <- function(x, ...) {
   con <- dbplyr::remote_con(x)
   sql <- dbplyr::remote_query(x)
 
+  # Start restrictive to avoid accidental materialization
   read_sql_duckdb(sql, funnel = "closed", con = con)
 }
 

R/funnel.R

@@ -30,7 +30,7 @@ new_duckdb_tibble <- function(x, class = NULL, funnel = "open", refunnel = FALSE
   }
 
   class(x) <- c(
-    if (!identical(funnel, "open")) "funneled_duckplyr_df",
+    if (!identical(funnel_parsed$funnel, "open")) "funneled_duckplyr_df",
     "duckplyr_df",
     class
   )
@@ -78,6 +78,8 @@ funnel_parse <- function(funnel, call = caller_env()) {
   } else if (!is.character(funnel)) {
     cli::cli_abort("{.arg funnel} must be an unnamed character vector or a named numeric vector", call = call)
   } else {
+    funnel <- arg_match(funnel, c("open", "closed", "drip"), error_call = call)
+
     allow_materialization <- !identical(funnel, "closed")
     if (!allow_materialization) {
       n_cells <- 0

R/io2.R

@@ -13,7 +13,7 @@ NULL
 #'
 #' @rdname read_file_duckdb
 #' @export
-read_parquet_duckdb <- function(path, ..., funnel = "drip", options = list()) {
+read_parquet_duckdb <- function(path, ..., funnel = c("drip", "open", "closed"), options = list()) {
   check_dots_empty()
 
   read_file_duckdb(path, "read_parquet", funnel = funnel, options = options)
@@ -50,7 +50,7 @@ read_parquet_duckdb <- function(path, ..., funnel = "drip", options = list()) {
 #'   path,
 #'   options = list(delim = ",", types = list(c("DOUBLE", "VARCHAR")))
 #' )
-read_csv_duckdb <- function(path, ..., funnel = "drip", options = list()) {
+read_csv_duckdb <- function(path, ..., funnel = c("drip", "open", "closed"), options = list()) {
   check_dots_empty()
 
   read_file_duckdb(path, "read_csv_auto", funnel = funnel, options = options)
@@ -71,7 +71,7 @@ read_csv_duckdb <- function(path, ..., funnel = "drip", options = list()) {
 #' db_exec("INSTALL json")
 #' db_exec("LOAD json")
 #' read_json_duckdb(path)
-read_json_duckdb <- function(path, ..., funnel = "drip", options = list()) {
+read_json_duckdb <- function(path, ..., funnel = c("drip", "open", "closed"), options = list()) {
   check_dots_empty()
 
   read_file_duckdb(path, "read_json", funnel = funnel, options = options)
@@ -104,7 +104,7 @@ read_file_duckdb <- function(
   path,
   table_function,
   ...,
-  funnel = "drip",
+  funnel = c("drip", "open", "closed"),
   options = list()
 ) {
   check_dots_empty()

R/sql.R

@@ -18,7 +18,7 @@
 #' @export
 #' @examples
 #' read_sql_duckdb("FROM duckdb_settings()")
-read_sql_duckdb <- function(sql, ..., funnel = "drip", con = NULL) {
+read_sql_duckdb <- function(sql, ..., funnel = c("drip", "open", "closed"), con = NULL) {
   if (!is_string(sql)) {
     cli::cli_abort("{.arg sql} must be a string.")
   }

man/duckdb_tibble.Rd

@@ -244,17 +244,17 @@ In dtplyr and dbplyr, there are no unfunneled frames: collection always needs to
 
 ## Partial funneling
 
-Partial funneling is a compromise between funneling and unfunneling.
+Partial funneling is a compromise between funneled and unfunneled.
 Materialization is allowed for data up to a certain size, measured in cells (values) and rows in the resulting data frame.
 
 ```{r}
 nrow(flights)
 flights_partial <-
   flights |>
-  duckplyr::as_duckdb_tibble(funnel = c(rows = 100000))
+  duckplyr::as_duckdb_tibble(funnel = "drip")
 ```
 
-In this example, the data is materialized only if the result has fewer than 100,000 rows.
+With this setting, the data is materialized only if the result has fewer than 1,000,000 cells (rows multiplied by columns).
 
 ```{r error = TRUE}
 flights_partial |>
@@ -272,5 +272,5 @@ flights_partial |>
 ```
 
 Partial funneling is a good choice for data sets where the cost of materializing the data is prohibitive only for large results.
-The default for the ingestion functions like `read_parquet_duckdb()` is to limit the result size to one million cells (values in the resulting data frame).
+This is the default for the ingestion functions like `read_parquet_duckdb()`.
 See `vignette("large")` for more details on working with large data sets.