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 = 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,
  `_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, indicates type coercion optimization.
predicate_pushdown A logical, indicates predicate pushdown optimization.
projection_pushdown A logical, indicates projection pushdown optimization.
simplify_expression A logical, indicates simplify expression optimization.
slice_pushdown A logical, indicates slice pushdown optimization.
comm_subplan_elim A logical, indicates trying to cache branching subplans that occur on self-joins or unions.
comm_subexpr_elim A logical, indicates trying to cache common subexpressions.
cluster_with_columns A logical, indicates to combine sequential independent calls to with_columns.
collapse_joins Collapse a join and filters into a faster join.
\_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                                                    │
#>    │                                                            ╰────────────────────────────────────────────────────────────────────────╯