feat: optimizations arguments [skip ci]

Author: eitsupi

R/lazyframe-frame.R

@@ -446,59 +446,54 @@ lazyframe__profile <- function(
 #' lazy_query <- lazy_frame$sort("Species")$filter(pl$col("Species") != "setosa")
 #'
 #' # This is the query that was written by the user, without any optimizations
-#' # (use cat() for better printing)
-#' lazy_query$explain(optimized = FALSE) |> cat()
+#' # (use writeLines() for better printing)
+#' lazy_query$explain(optimized = FALSE) |> writeLines()
 #'
 #' # This is the query after `polars` optimizes it: instead of sorting first and
 #' # then filtering, it is faster to filter first and then sort the rest.
-#' lazy_query$explain() |> cat()
+#' lazy_query$explain() |> writeLines()
 #'
 #' # Also possible to see this as tree format
-#' lazy_query$explain(format = "tree") |> cat()
+#' lazy_query$explain(format = "tree") |> writeLines()
 lazyframe__explain <- function(
   ...,
   format = c("plain", "tree"),
+  engine = c("auto", "in-memory", "streaming"),
   optimized = TRUE,
-  type_coercion = TRUE,
-  `_type_check` = 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,
-  collapse_joins = deprecated(),
-  `_check_order` = TRUE
+  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(),
+  collapse_joins = deprecated()
 ) {
   wrap({
     check_dots_empty0(...)
 
     format <- arg_match0(format, c("plain", "tree"))
+    engine <- arg_match0(engine, c("auto", "in-memory", "streaming"))
+    check_is_S7(optimizations, QueryOptFlags)
 
-    if (is_present(collapse_joins)) {
-      deprecate_warn(
-        c(
-          `!` = sprintf("%s is deprecated.", format_arg("collapse_joins")),
-          `i` = sprintf("Use %s instead.", format_arg("predicate_pushdown"))
-        )
-      )
-    }
+    optimizations <- forward_old_opt_flags(
+      optimizations,
+      type_coercion = type_coercion,
+      predicate_pushdown = predicate_pushdown,
+      projection_pushdown = projection_pushdown,
+      simplify_expression = simplify_expression,
+      slice_pushdown = slice_pushdown,
+      comm_subplan_elim = comm_subplan_elim,
+      comm_subexpr_elim = comm_subexpr_elim,
+      cluster_with_columns = cluster_with_columns,
+      collapse_joins = collapse_joins
+    )
 
     if (isTRUE(optimized)) {
-      ldf <- self$`_ldf`$optimization_toggle(
-        type_coercion = type_coercion,
-        `_type_check` = `_type_check`,
-        predicate_pushdown = predicate_pushdown,
-        projection_pushdown = projection_pushdown,
-        simplify_expression = simplify_expression,
-        slice_pushdown = slice_pushdown,
-        comm_subplan_elim = comm_subplan_elim,
-        comm_subexpr_elim = comm_subexpr_elim,
-        cluster_with_columns = cluster_with_columns,
-        `_check_order` = `_check_order`,
-        `_eager` = FALSE
-      )
+      prop(optimizations, "streaming", check = FALSE) <- engine == "streaming"
+      ldf <- self$`_ldf` # TODO: with_optimizations
 
       if (format == "tree") {
         ldf$describe_optimized_plan_tree()

R/lazyframe-utils.R

@@ -158,3 +158,82 @@ parse_percentiles <- function(percentiles, inject_median = FALSE) {
 
   c(sub_50_percentiles, at_or_above_50_percentiles)
 }
+
+forward_old_opt_flags <- function(
+  optimizations,
+  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(),
+  collapse_joins = deprecated()
+) {
+  call <- caller_env(2L)
+  warn_func <- function(arg_name) {
+    deprecate_warn(
+      c(
+        `!` = sprintf("%s is deprecated.", format_arg(arg_name)),
+        `i` = sprintf("Use %s instead.", format_arg("optimizations"))
+      ),
+      always = TRUE,
+      user_env = call
+    )
+  }
+
+  need_validation <- FALSE
+
+  if (is_present(type_coercion)) {
+    warn_func("type_coercion")
+    prop(optimizations, "type_coercion", check = FALSE) <- type_coercion
+    need_validation <- TRUE
+  }
+  if (is_present(predicate_pushdown)) {
+    warn_func("predicate_pushdown")
+    prop(optimizations, "predicate_pushdown", check = FALSE) <- predicate_pushdown
+    need_validation <- TRUE
+  }
+  if (is_present(projection_pushdown)) {
+    warn_func("projection_pushdown")
+    prop(optimizations, "projection_pushdown", check = FALSE) <- projection_pushdown
+    need_validation <- TRUE
+  }
+  if (is_present(simplify_expression)) {
+    warn_func("simplify_expression")
+    prop(optimizations, "simplify_expression", check = FALSE) <- simplify_expression
+    need_validation <- TRUE
+  }
+  if (is_present(slice_pushdown)) {
+    warn_func("slice_pushdown")
+    prop(optimizations, "slice_pushdown", check = FALSE) <- slice_pushdown
+    need_validation <- TRUE
+  }
+  if (is_present(comm_subplan_elim)) {
+    warn_func("comm_subplan_elim")
+    prop(optimizations, "comm_subplan_elim", check = FALSE) <- comm_subplan_elim
+    need_validation <- TRUE
+  }
+  if (is_present(comm_subexpr_elim)) {
+    warn_func("comm_subexpr_elim")
+    prop(optimizations, "comm_subexpr_elim", check = FALSE) <- comm_subexpr_elim
+    need_validation <- TRUE
+  }
+  if (is_present(cluster_with_columns)) {
+    warn_func("cluster_with_columns")
+    prop(optimizations, "cluster_with_columns", check = FALSE) <- cluster_with_columns
+    need_validation <- TRUE
+  }
+  if (is_present(collapse_joins)) {
+    warn_func("collapse_joins")
+    prop(optimizations, "predicate_pushdown", check = FALSE) <- collapse_joins
+    need_validation <- TRUE
+  }
+
+  if (need_validation) {
+    validate(optimizations)
+  }
+
+  optimizations
+}