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"),
  engine = c("auto", "in-memory", "streaming"),
  optimized = TRUE,
  optimizations = pl\$QueryOptFlags()
)

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. In Polars 1.16, the “in-memory” engine is selected for most cases. Starting with Polars 2.0, the streaming engine is selected instead. Use “in-memory” to keep the current execution engine explicitly.
  • “in-memory”: Use the in-memory engine. This is an escape hatch for queries whose incidental row order differs under streaming.
  • “streaming”: Use the streaming engine.
optimized Return an optimized query plan. If TRUE (default), the subsequent optimization flags control which optimizations run.
optimizations [Experimental] A QueryOptFlags object to indicate optimization passes done during query optimization.

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