Create a string representation of the query plan

Source code

Description

The query plan is read from bottom to top. When optimized = FALSE, the query as it was written by the user is shown. This is not what Polars runs. Instead, it applies optimizations that are displayed by default by $explain(). One classic example is the predicate pushdown, which applies the filter as early as possible (i.e. at the bottom of the plan).

Usage

<LazyFrame>$explain(
  ...,
  format = c("plain", "tree"),
  engine = c("auto", "in-memory", "streaming"),
  optimized = TRUE,
  optimizations = pl\$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()
)

Arguments

…	These dots are for future extensions and must be empty.
format	The format to use for displaying the logical plan. Must be either “plain” (default) or “tree”.
engine	The engine name to use for processing the query. One of the followings: “auto” (default): Select the engine automatically. The “in-memory” engine will be selected for most cases. “in-memory”: Use the in-memory engine. “streaming”: Use the (new) streaming engine.
optimized	Return an optimized query plan. If TRUE (default), the subsequent optimization flags control which optimizations run.
optimizations	A QueryOptFlags object to indicate optimization passes done during query optimization.
type_coercion	Use the type_coercion property of a QueryOptFlags object, then pass that to the optimizations argument instead.
predicate_pushdown	Use the predicate_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.
projection_pushdown	Use the projection_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.
simplify_expression	Use the simplify_expression property of a QueryOptFlags object, then pass that to the optimizations argument instead.
slice_pushdown	Use the slice_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.
comm_subplan_elim	Use the comm_subplan_elim property of a QueryOptFlags object, then pass that to the optimizations argument instead.
comm_subexpr_elim	Use the comm_subexpr_elim property of a QueryOptFlags object, then pass that to the optimizations argument instead.
cluster_with_columns	Use the cluster_with_columns property of a QueryOptFlags object, then pass that to the optimizations argument instead.
collapse_joins	Use the predicate_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.

Value

A character value containing the query plan.

Examples

library("polars")

lazy_frame <- as_polars_lf(iris)

# Prepare your query
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 writeLines() for better printing)
lazy_query$explain(optimized = FALSE) |> writeLines()

#> FILTER [(col("Species")) != ("setosa")]
#> FROM
#>   SORT BY [col("Species")]
#>     DF ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", ...]; PROJECT */5 COLUMNS

# 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() |> writeLines()

#> SORT BY [col("Species")]
#>   FILTER [(col("Species")) != ("setosa")]
#>   FROM
#>     DF ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", ...]; PROJECT */5 COLUMNS

# You can disable specific optimizations.
lazy_query$explain(
  optimizations = pl$QueryOptFlags(predicate_pushdown = FALSE)
) |>
  writeLines()

#> FILTER [(col("Species")) != ("setosa")]
#> FROM
#>   SORT BY [col("Species")]
#>     DF ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", ...]; PROJECT */5 COLUMNS

# Also possible to see this as tree format
lazy_query$explain(format = "tree") |> writeLines()

#>               0                            1                                                        2
#>    ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#>    │
#>    │     ╭─────────╮
#>  0 │     │ SORT BY │
#>    │     ╰────┬┬───╯
#>    │          ││
#>    │          │╰───────────────────────────╮
#>    │          │                            │
#>    │  ╭───────┴────────╮                   │
#>    │  │ expression:    │               ╭───┴────╮
#>  1 │  │ col("Species") │               │ FILTER │
#>    │  ╰────────────────╯               ╰───┬┬───╯
#>    │                                       ││
#>    │                                       │╰───────────────────────────────────────────────────────╮
#>    │                                       │                                                        │
#>    │                      ╭────────────────┴─────────────────╮  ╭───────────────────────────────────┴────────────────────────────────────╮
#>    │                      │ predicate:                       │  │ FROM:                                                                  │
#>  2 │                      │ [(col("Species")) != ("setosa")] │  │ DF ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", ...] │
#>    │                      ╰──────────────────────────────────╯  │ PROJECT */5 COLUMNS                                                    │
#>    │                                                            ╰────────────────────────────────────────────────────────────────────────╯