feat: optimizations arguments

NEWS.md

@@ -2,9 +2,46 @@
 
 ## polars (development version)
 
+### Deprecations
+
+- The following arguments of certain LazyFrame methods, which were previously used for query optimization,
+  are deprecated in favor of the new `optimizations` argument (#1635).
+  Some arguments that were intended for internal use have been removed without deprecation.
+
+  - `type_coercion`
+  - `predicate_pushdown`
+  - `projection_pushdown`
+  - `simplify_expression`
+  - `slice_pushdown`
+  - `comm_subplan_elim`
+  - `comm_subexpr_elim`
+  - `cluster_with_columns`
+  - `no_optimization`
+  - `_type_check` (removed)
+  - `_check_order` (removed)
+  - `_eager` (removed)
+
+  Functions affected are those that gained the `optimizations` argument.
+  See the New features section below for details.
+  Also, for the experimental `<lazyframe>$sink_*` methods,
+  the above arguments are removed instead of being deprecated.
+
 ### New features
 
-- `pl$collect_all()` to efficiently collect a list of LazyFrames (#1598).
+- The following functions gain the experimental `optimizations` argument
+  taking a `QueryOptFlags` object (#1633, #1634, #1635).
+  - `<lazyframe>$collect()`
+  - `<lazyframe>$explain()`
+  - `<lazyframe>$profile()`
+  - `<lazyframe>$to_dot()`
+  - `<lazyframe>$sink_batches()`
+  - `<lazyframe>$sink_csv()`
+  - `<lazyframe>$sink_ipc()`
+  - `<lazyframe>$sink_parquet()`
+  - `<lazyframe>$sink_ndjson()`
+  - `pl$collect_all()`
+  - `as_polars_df(<lazyframe>)`
+- `pl$collect_all()` to efficiently collect a list of LazyFrames (#1598, #1635).
 - `<lazyframe>$remove()` and `<dataframe>$remove()` as a complement to
   `$filter()` (#1632).
 

R/000-wrappers.R

@@ -74,8 +74,8 @@ NULL
 }
 
 
-`collect_all` <- function(`lfs`, `engine`, `optflags`) {
-  .Call(savvy_collect_all__impl, `lfs`, `engine`, `optflags`)
+`collect_all` <- function(`lfs`, `engine`, `optimizations`) {
+  .Call(savvy_collect_all__impl, `lfs`, `engine`, `optimizations`)
 }
 
 
@@ -3999,12 +3999,6 @@ class(`PlRExpr`) <- c("PlRExpr__bundle", "savvy_polars__sealed")
   }
 }
 
-`PlRLazyFrame_optimization_toggle` <- function(self) {
-  function(`type_coercion`, `_type_check`, `predicate_pushdown`, `projection_pushdown`, `simplify_expression`, `slice_pushdown`, `comm_subplan_elim`, `comm_subexpr_elim`, `cluster_with_columns`, `_eager`, `_check_order`) {
-    .savvy_wrap_PlRLazyFrame(.Call(savvy_PlRLazyFrame_optimization_toggle__impl, `self`, `type_coercion`, `_type_check`, `predicate_pushdown`, `projection_pushdown`, `simplify_expression`, `slice_pushdown`, `comm_subplan_elim`, `comm_subexpr_elim`, `cluster_with_columns`, `_eager`, `_check_order`))
-  }
-}
-
 `PlRLazyFrame_profile` <- function(self) {
   function() {
     .Call(savvy_PlRLazyFrame_profile__impl, `self`)
@@ -4194,6 +4188,12 @@ class(`PlRExpr`) <- c("PlRExpr__bundle", "savvy_polars__sealed")
   }
 }
 
+`PlRLazyFrame_with_optimizations` <- function(self) {
+  function(`optimizations`) {
+    .savvy_wrap_PlRLazyFrame(.Call(savvy_PlRLazyFrame_with_optimizations__impl, `self`, `optimizations`))
+  }
+}
+
 `PlRLazyFrame_with_row_index` <- function(self) {
   function(`name`, `offset` = NULL) {
     .savvy_wrap_PlRLazyFrame(.Call(savvy_PlRLazyFrame_with_row_index__impl, `self`, `name`, `offset`))
@@ -4232,7 +4232,6 @@ class(`PlRExpr`) <- c("PlRExpr__bundle", "savvy_polars__sealed")
   e$`merge_sorted` <- `PlRLazyFrame_merge_sorted`(ptr)
   e$`min` <- `PlRLazyFrame_min`(ptr)
   e$`null_count` <- `PlRLazyFrame_null_count`(ptr)
-  e$`optimization_toggle` <- `PlRLazyFrame_optimization_toggle`(ptr)
   e$`profile` <- `PlRLazyFrame_profile`(ptr)
   e$`quantile` <- `PlRLazyFrame_quantile`(ptr)
   e$`remove` <- `PlRLazyFrame_remove`(ptr)
@@ -4263,6 +4262,7 @@ class(`PlRExpr`) <- c("PlRExpr__bundle", "savvy_polars__sealed")
   e$`var` <- `PlRLazyFrame_var`(ptr)
   e$`with_columns` <- `PlRLazyFrame_with_columns`(ptr)
   e$`with_columns_seq` <- `PlRLazyFrame_with_columns_seq`(ptr)
+  e$`with_optimizations` <- `PlRLazyFrame_with_optimizations`(ptr)
   e$`with_row_index` <- `PlRLazyFrame_with_row_index`(ptr)
 
   class(e) <- c("PlRLazyFrame", "savvy_polars__sealed")

R/as_polars_df.R

@@ -146,18 +146,21 @@ as_polars_df.polars_group_by <- function(x, ...) {
 as_polars_df.polars_lazy_frame <- function(
   x,
   ...,
-  type_coercion = TRUE,
-  predicate_pushdown = TRUE,
-  projection_pushdown = TRUE,
-  simplify_expression = TRUE,
-  slice_pushdown = TRUE,
-  comm_subplan_elim = TRUE,
-  comm_subexpr_elim = TRUE,
-  cluster_with_columns = TRUE,
-  no_optimization = FALSE,
-  engine = c("auto", "in-memory", "streaming")
+  engine = c("auto", "in-memory", "streaming"),
+  optimizations = QueryOptFlags(),
+  type_coercion = deprecated(),
+  predicate_pushdown = deprecated(),
+  projection_pushdown = deprecated(),
+  simplify_expression = deprecated(),
+  slice_pushdown = deprecated(),
+  comm_subplan_elim = deprecated(),
+  comm_subexpr_elim = deprecated(),
+  cluster_with_columns = deprecated(),
+  no_optimization = deprecated()
 ) {
   x$collect(
+    engine = engine,
+    optimizations = optimizations,
     type_coercion = type_coercion,
     predicate_pushdown = predicate_pushdown,
     projection_pushdown = projection_pushdown,
@@ -166,8 +169,7 @@ as_polars_df.polars_lazy_frame <- function(
     comm_subplan_elim = comm_subplan_elim,
     comm_subexpr_elim = comm_subexpr_elim,
     cluster_with_columns = cluster_with_columns,
-    no_optimization = no_optimization,
-    engine = engine
+    no_optimization = no_optimization
   )
 }