Skip to content

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 = "plain",
  optimized = TRUE,
  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,
  streaming = FALSE
)

Arguments

… Ignored.
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 Logical. Coerce types such that operations succeed and run on minimal required memory.
predicate_pushdown Logical. Applies filters as early as possible at scan level.
projection_pushdown Logical. Select only the columns that are needed at the scan level.
simplify_expression Logical. Various optimizations, such as constant folding and replacing expensive operations with faster alternatives.
slice_pushdown Logical. Only load the required slice from the scan level. Don’t materialize sliced outputs (e.g. join$head(10)).
comm_subplan_elim Logical. Will try to cache branching subplans that occur on self-joins or unions.
comm_subexpr_elim Logical. Common subexpressions will be cached and reused.
cluster_with_columns Combine sequential independent calls to with_columns().
streaming Logical. Run parts of the query in a streaming fashion (this is in an alpha state).

Value

A character value containing the query plan.

Examples

library("polars")

lazy_frame = pl$LazyFrame(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")) != (String(setosa))] FROM
#>   SORT BY [col("Species")]
#>     DF ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width"]; PROJECT */5 COLUMNS; SELECTION: None

# 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")]
#>   DF ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width"]; PROJECT */5 COLUMNS; SELECTION: [(col("Species")) != (String(setosa))]

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

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