Skip to content

Create a string representation of the query plan

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"),
  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 = TRUE,
  streaming = FALSE,
  `_check_order` = TRUE
)

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”.
optimized Return an optimized query plan. If TRUE (default), the subsequent optimization flags control which optimizations run.
type_coercion A logical, indicats type coercion optimization.
predicate_pushdown A logical, indicats predicate pushdown optimization.
projection_pushdown A logical, indicats projection pushdown optimization.
simplify_expression A logical, indicats simplify expression optimization.
slice_pushdown A logical, indicats slice pushdown optimization.
comm_subplan_elim A logical, indicats tring to cache branching subplans that occur on self-joins or unions.
comm_subexpr_elim A logical, indicats tring to cache common subexpressions.
cluster_with_columns A logical, indicats to combine sequential independent calls to with_columns.
collapse_joins Collapse a join and filters into a faster join.
streaming [Deprecated] A logical. If TRUE, process the query in batches to handle larger-than-memory data. If FALSE (default), the entire query is processed in a single batch. Note that streaming mode is considered unstable. It may be changed at any point without it being considered a breaking change.
\_check_order, \_type_check For internal use only.

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 cat() for better printing)
lazy_query$explain(optimized = FALSE) |> cat()

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

#> SORT BY [col("Species")]
#>   FILTER [(col("Species")) != ("setosa")]
#>   FROM
#>     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") |> cat()

#>               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                                                    │
#>    │                                                            ╰────────────────────────────────────────────────────────────────────────╯