Polars Python API

https://docs.pola.rs/api/python/stable/
Admin
Polars is a fast, expressive data manipulation library for Python that provides DataFrame and...
Tokens:2,020,002
Snippets:11,126
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Get Polars thread pool size

Source: https://docs.pola.rs/api/python/stable/reference/api/polars.thread_pool_size.html

Returns the number of threads in the Polars thread pool. The output shown (16) is an example; the actual value depends on the system and can be overridden by the POLARS_MAX_THREADS environment variable before process start.

```python
>>> pl.thread_pool_size()  
16

```

--------------------------------

### Create DataFrame for or_ examples

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.or_.html

Initializes a DataFrame with columns x, y, and z used in the subsequent examples.

```python
>>> df = pl.DataFrame(
...     data={
...         "x": [5, 6, 7, 4, 8],
...         "y": [1.5, 2.5, 1.0, 4.0, -5.75],
...         "z": [-9, 2, -1, 4, 8],
...     }
... )
```

--------------------------------

### Catalog.__init__

Source: https://docs.pola.rs/api/python/stable/reference/catalog/api/polars.Catalog.html

Initializes a Unity catalog client with the given workspace URL and optional bearer token.

```APIDOC
## Catalog.__init__

### Description
Initializes a Unity catalog client with the given workspace URL and optional bearer token.

### Method
Constructor

### Signature
`__init__(workspace_url: str, *, bearer_token: str | None = 'auto', require_https: bool = True) -> None`

### Parameters
- **workspace_url** (str) - Required - URL of the workspace, or alternatively the URL of the Unity catalog API endpoint.
- **bearer_token** (str | None) - Optional - Bearer token to authenticate with. Can be set to "auto" to automatically retrieve bearer tokens from the environment, or "databricks-sdk" to use the Databricks SDK to retrieve and use the bearer token from the environment. Defaults to "auto".
- **require_https** (bool) - Optional - Require the `workspace_url` to use HTTPS. Defaults to True.

### Returns
None
```

--------------------------------

### get example: group_by agg with get(1)

Source: https://docs.pola.rs/api/python/stable/reference/expressions/index.html

Demonstrates using get to extract a single value by index within groups.

```python
>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.group_by("group", maintain_order=True).agg(pl.col("value").get(1))
shape: (2, 2)
┌───────┬───────┐
│ group ┆ value │
│ ---   ┆ ---   │
│ str   ┆ i64   │
╞═══════╪═══════╡
│ one   ┆ 98    │
│ two   ┆ 99    │
└───────┴───────┘
```

--------------------------------

### Get Series flags

Source: https://docs.pola.rs/api/python/stable/reference/series/index.html

Gets the flags set on the Series. The example shows the flags dictionary for a simple Series.

```python
>>> s = pl.Series("a", [1, 2, 3])
>>> s.flags
{'SORTED_ASC': False, 'SORTED_DESC': False}
```

--------------------------------

### PartitionBy.__init__()

Source: https://docs.pola.rs/api/python/stable/reference/api/polars.PartitionBy.html

Initializes a new PartitionBy configuration object with parameters for base path, file path provider, partitioning keys, and file size/row limits.

```APIDOC
## PartitionBy.__init__()

### Description
Initializes a new PartitionBy configuration object. This is used to specify how data should be split into multiple output files when writing.

### Method
Constructor

### Signature
```python
__init__(
    _base_path: str | Path_,
    _*_,
    _file_path_provider: Callable[[FileProviderArgs], str | Path | IO[bytes] | IO[str]] | _InternalPlPathProviderConfig | None = None_,
    _key: str | Expr | Sequence[str | Expr] | Mapping[str, Expr] | None = None_,
    _include_key: bool | None = None_,
    _max_rows_per_file: int | None = None_,
    _approximate_bytes_per_file: int | Literal['auto'] | None = 'auto'_,
) -> None
```

### Parameters
#### Path Parameters
- **base_path** (str | Path) - Required - Base path to write to.

#### Query Parameters
- **file_path_provider** (Callable[[FileProviderArgs], str | Path | IO[bytes] | IO[str]] | _InternalPlPathProviderConfig | None) - Optional - Callable for custom file output paths.
- **key** (str | Expr | Sequence[str | Expr] | Mapping[str, Expr] | None) - Optional - Expressions to partition by.
- **include_key** (bool | None) - Optional - Include the partition key expression outputs in the output files.
- **max_rows_per_file** (int | None) - Optional - Maximum number of rows to write for each file. Note that files may have less than this amount of rows.
- **approximate_bytes_per_file** (int | Literal['auto'] | None) - Optional - Approximate number of bytes to write to each file. This is measured as the estimated size of the DataFrame in memory. Default is 'auto'.

### Request Example
```python
pl.PartitionBy(
    "data/",
    key="year",
    max_rows_per_file=1000,
    approximate_bytes_per_file=100_000_000,
)
```

### Response
#### Success Response (200)
- **None** - The constructor returns None.

#### Response Example
```python
None
```

### Error Handling
- This is a constructor and does not return errors directly. Errors may be raised during initialization if invalid parameters are provided.
```

--------------------------------

### Starts-with operator ^@

Source: https://docs.pola.rs/api/python/stable/reference/sql/operators/index.html

Returns True if the first string value starts with the second string value. The example filters rows where name starts with 'A'.

```python
df = pl.DataFrame({"name": ["Alice", "Bob", "Arthur", "David"]})
df.sql("SELECT * FROM self WHERE name ^@ 'A'")
# shape: (2, 1)
# ┌────────┐
# │ name   │
# │ ---    │
# │ str    │
# ╞════════╡
# │ Alice  │
# │ Arthur │
# └────────┘

```

--------------------------------

### Create a DataFrame and display it

Source: https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.to_dict.html

Creates a sample DataFrame with columns A, fruits, B, cars, and optional, then displays it. The output shows the shape and the table with column types.

```python
>>> df = pl.DataFrame(
...     {
...         "A": [1, 2, 3, 4, 5],
...         "fruits": ["banana", "banana", "apple", "apple", "banana"],
...         "B": [5, 4, 3, 2, 1],
...         "cars": ["beetle", "audi", "beetle", "beetle", "beetle"],
...         "optional": [28, 300, None, 2, -30],
...     }
... )
>>> df
shape: (5, 5)
┌─────┬────────┬─────┬────────┬──────────┐
│ A   ┆ fruits ┆ B   ┆ cars   ┆ optional │
│ --- ┆ ---    ┆ --- ┆ ---    ┆ ---      │
│ i64 ┆ str    ┆ i64 ┆ str    ┆ i64      │
╞═════╪════════╪═════╪════════╪══════════╡
│ 1   ┆ banana ┆ 5   ┆ beetle ┆ 28       │
│ 2   ┆ banana ┆ 4   ┆ audi   ┆ 300      │
│ 3   ┆ apple  ┆ 3   ┆ beetle ┆ null     │
│ 4   ┆ apple  ┆ 2   ┆ beetle ┆ 2        │
│ 5   ┆ banana ┆ 1   ┆ beetle ┆ -30      │
└─────┴────────┴─────┴────────┴──────────┘
```

--------------------------------

### Import styling helpers and create example data

Source: https://docs.pola.rs/api/python/stable/reference/dataframe/style.html

Imports Polars selectors and Great Tables styling helpers, then creates a sample DataFrame with site_id, measure_a, and measure_b columns.

```python
>>> import polars.selectors as cs
>>> from great_tables import loc, style
>>> df = pl.DataFrame(
...     {
...         "site_id": [0, 1, 2],
...         "measure_a": [5, 4, 6],
...         "measure_b": [7, 3, 3],
...     }
... )

```

--------------------------------

### Get run-length IDs with rle_id

Source: https://docs.pola.rs/api/python/stable/reference/series/index.html

Gets a distinct integer ID for each run of identical values using `rle_id()`. The output shows the IDs starting at 0 and increasing each time the value changes.

```python
>>> s = pl.Series("s", [1, 1, 2, 1, None, 1, 3, 3])
>>> s.rle_id()
shape: (8,)
Series: 's' [u32]
[
    0
    0
    1
    2
    3
    4
    5
    5
]

```

--------------------------------

### Get top k rows with DataFrame.top_k

Source: https://docs.pola.rs/api/python/stable/reference/dataframe/index.html

Examples for the DataFrame.top_k method, showing how to get the k largest rows by a single column or by multiple columns. The output is not guaranteed to be sorted; call sort() if needed.

```python
>>> df = pl.DataFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [2, 1, 1, 3, 2, 1],
...     }
... )

```

```python
>>> df.top_k(4, by="b")
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ a   ┆ 2   │
│ b   ┆ 2   │
│ b   ┆ 1   │
└─────┴─────┘

```

```python
>>> df.top_k(4, by=["b", "a"])
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ b   ┆ 2   │
│ a   ┆ 2   │
│ c   ┆ 1   │
└─────┴─────┘

```

--------------------------------

### DataFrame.__getitem__ selection examples

Source: https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.__getitem__.html

Shows how different key types select data from a DataFrame with columns 'a', 'd', 'c', 'b'. The example creates a DataFrame and demonstrates scalar, row, column, slice, and multi-axis selections, each with its output.

```python
>>> df = pl.DataFrame(
...     {"a": [1, 2, 3], "d": [4, 5, 6], "c": [1, 3, 2], "b": [7, 8, 9]}
... )
>>> df[0]
shape: (1, 4)
┌─────┬─────┬─────┬─────┐
│ a   ┆ d   ┆ c   ┆ b   │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╡
│ 1   ┆ 4   ┆ 1   ┆ 7   │
└─────┴─────┴─────┴─────┘
>>> df[0, "a"]
1
>>> df["a"]
shape: (3,)
Series: 'a' [i64]
[
    1
    2
    3
]
>>> df[0:2]
shape: (2, 4)
┌─────┬─────┬─────┬─────┐
│ a   ┆ d   ┆ c   ┆ b   │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╡
│ 1   ┆ 4   ┆ 1   ┆ 7   │
│ 2   ┆ 5   ┆ 3   ┆ 8   │
└─────┴─────┴─────┴─────┘
>>> df[0:2, "a"]
shape: (2,)
Series: 'a' [i64]
[
    1
    2
]
>>> df[0:2, 0]
shape: (2,)
Series: 'a' [i64]
[
    1
    2
]
>>> df[[0, 1], [0, 1, 2]]
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ d   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 4   ┆ 1   │
│ 2   ┆ 5   ┆ 3   │
└─────┴─────┴─────┘
>>> df[0:2, ["a", "c"]]
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ c   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 1   │
│ 2   ┆ 3   │
└─────┴─────┘
>>> df[:, 0:2]
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ d   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 4   │
│ 2   ┆ 5   │
│ 3   ┆ 6   │
└─────┴─────┘
>>> df[:, "a":"c"]
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ d   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 4   ┆ 1   │
│ 2   ┆ 5   ┆ 3   │
│ 3   ┆ 6   ┆ 2   │
└─────┴─────┴─────┘
```

--------------------------------

### arg_sort() example

Source: https://docs.pola.rs/api/python/stable/reference/series/index.html

Get the index values that would sort this Series. Supports `descending` and `nulls_last` parameters.

```python
>>> s = pl.Series("a", [5, 3, 4, 1, 2])
>>> s.arg_sort()
shape: (5,)
Series: 'a' [u32]
[
    3
    4
    1
    2
    0
]
```

--------------------------------

### Create example DataFrame

Source: https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.top_k.html

Creates the example DataFrame used in the subsequent top_k examples. The DataFrame has columns 'a' (string) and 'b' (integer).

```python
>>> df = pl.DataFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [2, 1, 1, 3, 2, 1],
...     }
... )
```

--------------------------------

### Strip custom characters with strip_chars_start

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.str.strip_chars_start.html

Removes any of the specified characters from the start of each string. Note that whitespace is not stripped automatically when a `characters` argument is provided. The example strips the characters 'w', 'o', 'd', and a tab from the start of each string.

```python
>>> df.with_columns(
...     foo_strip_start=pl.col("foo").str.strip_chars_start("wod\t"),
... )
shape: (2, 2)
┌─────────┬─────────────────┐
│ foo     ┆ foo_strip_start │
│ ---     ┆ ---             │
│ str     ┆ str             │
╞═════════╪═════════════════╡
│  hello  ┆  hello          │
│   world   ┆ rld             │
└─────────┴─────────────────┘
```

--------------------------------

### SQLContext.__init__()

Source: https://docs.pola.rs/api/python/stable/reference/sql/python_api.html

Initializes a new SQLContext with optional frame mappings, global registration, and eager execution mode.

```APIDOC
## SQLContext.__init__()

### Description
Initializes a new SQLContext. The `eager_execution` parameter was renamed `eager` in version 0.20.31.

### Method
Constructor

### Parameters
- **frames** (Mapping[str, CompatibleFrameType | None] | None) - Optional - A `{name:frame, ...}` mapping which can include Polars frames _and_ pandas DataFrames, Series and pyarrow Table and RecordBatch objects.
- **register_globals** (bool | int) - Optional - Register compatible objects (polars DataFrame, LazyFrame, and Series) found in the globals, automatically mapping their variable name to a table name. To register other objects (pandas/pyarrow data) pass them explicitly, or call the `execute_global` classmethod. If given an integer then only the most recent “n” objects found will be registered.
- **eager** (bool) - Optional - If True, returns execution results as `DataFrame` instead of `LazyFrame`. (Note that the query itself is always executed in lazy-mode; this parameter impacts whether `execute()` returns an eager or lazy result frame).
- **named_frames** (CompatibleFrameType | None) - Optional - Named eager/lazy frames, provided as kwargs.

### Example
```python
>>> lf = pl.LazyFrame({"a": [1, 2, 3], "b": ["x", None, "z"]})
>>> res = pl.SQLContext(frame=lf).execute(
...     "SELECT b, a*2 AS two_a FROM frame WHERE b IS NOT NULL"
... )
>>> res.collect()
shape: (2, 2)
┌─────┬───────┐
│ b   ┆ two_a │
│ --- ┆ ---   │
│ str ┆ i64   │
╞═════╪═══════╡
│ x   ┆ 2     │
│ z   ┆ 6     │
└─────┴───────┘
```

### Notes
Can also be used as a context manager.
```

--------------------------------

### Basic sink_parquet example

Source: https://docs.pola.rs/api/python/stable/reference/api/polars.LazyFrame.sink_parquet.html

Shows how to sink a lazy frame to a Parquet file using `sink_parquet`.

```python
>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_parquet("out.parquet")  
```

--------------------------------

### Get output name of an expression

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.meta.output_name.html

Shows how to use `Expr.meta.output_name()` to get the column name that an expression would produce. The examples include multiplication, filter, over, slice, and len expressions, each returning the expected output name.

```python
>>> e = pl.col("foo") * pl.col("bar")
>>> e.meta.output_name()
'foo'
>>> e_filter = pl.col("foo").filter(pl.col("bar") == 13)
>>> e_filter.meta.output_name()
'foo'
>>> e_sum_over = pl.sum("foo").over("groups")
>>> e_sum_over.meta.output_name()
'foo'
>>> e_sum_slice = pl.sum("foo").slice(pl.len() - 10, pl.col("bar"))
>>> e_sum_slice.meta.output_name()
'foo'
>>> pl.len().meta.output_name()
'len'
```

--------------------------------

### Example: Using DataFrame.rows() and DataFrame.rows(named=True)

Source: https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.rows.html

Creates a polars DataFrame with columns x, y, and z, then calls df.rows() to get a list of tuples and df.rows(named=True) to get a list of dictionaries. The output shows the returned values for both calls.

```python
>>> df = pl.DataFrame(
...     {
...         "x": ["a", "b", "b", "a"],
...         "y": [1, 2, 3, 4],
...         "z": [0, 3, 6, 9],
...     }
... )
>>> df.rows()
[('a', 1, 0), ('b', 2, 3), ('b', 3, 6), ('a', 4, 9)]
>>> df.rows(named=True)
[{'x': 'a', 'y': 1, 'z': 0},
 {'x': 'b', 'y': 2, 'z': 3},
 {'x': 'b', 'y': 3, 'z': 6},
 {'x': 'a', 'y': 4, 'z': 9}]
```

--------------------------------

### Create a list strategy with create_list_strategy

Source: https://docs.pola.rs/api/python/stable/reference/api/polars.testing.parametric.create_list_strategy.html

Creates a strategy that generates a list of i32 values. The example output is illustrative; actual values vary.

```python
>>> from polars.testing.parametric import create_list_strategy
>>> lst = create_list_strategy(inner_dtype=pl.Int32)  
>>> lst.example()  
[-11330, 24030, 116]

```

--------------------------------

### Draw an interactive example with .example()

Source: https://docs.pola.rs/api/python/stable/reference/api/polars.testing.parametric.series.html

Draw a concrete example interactively using the .example() method. This is useful while developing a strategy/test but should be avoided while running tests. The example shows a Series of lists generated from the provided select_from values.

```python
>>> from polars.testing.parametric import lists
>>> s = series(strategy=lists(pl.String, select_from=["xx", "yy", "zz"]))
>>> s.example()  
shape: (4,)
Series: '' [list[str]]
[
        ["zz", "zz"]
        ["zz", "xx", "yy"]
        []
        ["xx"]
]

```

--------------------------------

### polars.tail examples

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.tail.html

Shows how to use polars.tail to get the last n rows of a column. The first example returns all rows (n defaults to 10, but only 3 exist), and the second returns the last 2 rows. The output is displayed as a DataFrame.

```python
>>> df = pl.DataFrame(
...     {
...         "a": [1, 8, 3],
...         "b": [4, 5, 2],
...         "c": ["foo", "bar", "foo"],
...     }
... )
>>> df.select(pl.tail("a"))
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 8   │
│ 3   │
└─────┘
>>> df.select(pl.tail("a", 2))
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 8   │
│ 3   │
└─────┘
```

--------------------------------

### GPUEngine.__init__()

Source: https://docs.pola.rs/api/python/stable/reference/lazyframe/api/polars.lazyframe.engine_config.GPUEngine.html

Constructor for the GPUEngine class, allowing configuration of device, memory resource, error handling, and monitoring.

```APIDOC
## GPUEngine.__init__()

### Description
Initializes a new GPUEngine instance with the specified configuration options for the GPU execution engine.

### Method
Constructor

### Signature
```python
GPUEngine(
    *,
    device: int | None = None,
    memory_resource: Any | None = None,
    raise_on_fail: bool = False,
    monitoring: bool = False,
    **kwargs: Any
) -> None
```

### Parameters
- **device** (int, optional) - Select the GPU used to run the query. If not provided, the query uses the current CUDA device.
- **memory_resource** (rmm.mr.DeviceMemoryResource, optional) - Provide a memory resource for GPU memory allocations. Must be valid for the selected device.
- **raise_on_fail** (bool, optional) - If True, do not fall back to the Polars CPU engine if the GPU engine cannot execute the query, but instead raise an error.
- **monitoring** (bool, optional) - Whether queries are monitored (None uses the configured default).
- **kwargs** (Any) - Additional configuration options for the engine.
```

--------------------------------

### Get chunk lengths of a Series

Source: https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.chunk_lengths.html

These examples create two Series and then concatenate them with rechunk=True and rechunk=False to show the resulting chunk lengths.

```python
>>> s = pl.Series("a", [1, 2, 3])
>>> s2 = pl.Series("a", [4, 5, 6])
```

```python
>>> pl.concat([s, s2], rechunk=True).chunk_lengths()
[6]
```

```python
>>> pl.concat([s, s2], rechunk=False).chunk_lengths()
[3, 3]
```

--------------------------------

### Generate query plan with LazyFrame.explain()

Source: https://docs.pola.rs/api/python/stable/reference/lazyframe/api/polars.LazyFrame.explain.html

Creates a LazyFrame and calls explain() on a grouped, aggregated, and sorted query to display the logical plan. The example shows the default plain format with optimized plan.

```python
>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).explain()
```

--------------------------------

### Example: polars.Series.arg_min()

Source: https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.arg_min.html

Creates a Series with values [3, 2, 1] and calls arg_min() to get the index of the minimal value, which is 2.

```python
>>> s = pl.Series("a", [3, 2, 1])
>>> s.arg_min()
2
```

--------------------------------

### Create a DataFrame with column 'a'

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.rechunk.html

Initializes a DataFrame with a single column 'a' containing the values [1, 1, 2]. This is the setup for the rechunk example.

```python
>>> df = pl.DataFrame({"a": [1, 1, 2]})
```

--------------------------------

### EXPLAIN

Source: https://docs.pola.rs/api/python/stable/reference/sql/table_operations.html

Returns the execution plan for a SQL query.

```APIDOC
## EXPLAIN

### Description
Returns the Polars execution plan for a given SQL query.

### Syntax
```sql
EXPLAIN SELECT * FROM some_table
```

### Parameters
- **query** (SQL query) - Required - The query to explain.
```

--------------------------------

### Expr.slice(offset, length)

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.slice.html

Get a slice of this expression. Supports negative indexing for the offset. If length is None, all rows starting at the offset are selected.

```APIDOC
## Expr.slice(offset, length)

### Description
Get a slice of this expression. Supports negative indexing for the offset. If length is None, all rows starting at the offset are selected.

### Method
slice

### Signature
Expr.slice(_offset: int | Expr, _length: int | Expr | None = None) -> Expr

### Parameters
- **offset** (int | Expr) - Required - Start index. Negative indexing is supported.
- **length** (int | Expr | None) - Optional - Length of the slice. If set to None, all rows starting at the offset will be selected.

### Returns
- **Expr** - The sliced expression.

### Example
```python
>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10, 11],
...         "b": [None, 4, 4, 4],
...     }
... )
>>> df.select(pl.all().slice(1, 2))
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 9   ┆ 4   │
│ 10  ┆ 4   │
└─────┴─────┘
```
```

--------------------------------

### Create DataFrame for cs.by_dtype examples

Source: https://docs.pola.rs/api/python/stable/reference/selectors.html

Create a DataFrame with date, integer, and string columns to be used with cs.by_dtype() examples.

```python
>>> from datetime import date
>>> import polars.selectors as cs
>>> df = pl.DataFrame(
...     {
...         "dt": [date(1999, 12, 31), date(2024, 1, 1), date(2010, 7, 5)],
...         "value": [1_234_500, 5_000_555, -4_500_000],
...         "other": ["foo", "bar", "foo"],
...     }
... )
```

--------------------------------

### Instantiate a basic DataFrame

Source: https://docs.pola.rs/api/python/stable/reference/api/polars.DataFrame.write_excel.html

Creates a sample DataFrame with date, numeric, and value columns used in the subsequent write_excel examples.

```python
>>> from random import uniform
>>> from datetime import date
>>>
>>> df = pl.DataFrame(
...     {
...         "dtm": [date(2023, 1, 1), date(2023, 1, 2), date(2023, 1, 3)],
...         "num": [uniform(-500, 500), uniform(-500, 500), uniform(-500, 500)],
...         "val": [10_000, 20_000, 30_000],
...     }
... )

```

--------------------------------

### ARRAY_LENGTH: Get length of array

Source: https://docs.pola.rs/api/python/stable/reference/sql/functions/array.html

Returns the length of the array. The example uses ARRAY_LENGTH(foo) to count elements in each list, producing a u32 column.

```python
df = pl.DataFrame({"foo": [[1, 2], [4, 3, 2]]})
df.sql("""
  SELECT foo, ARRAY_LENGTH(foo) AS n_elems FROM self
""")
# shape: (2, 2)
# ┌───────────┬─────────┐
# │ foo       ┆ n_elems │
# │ ---       ┆ ---     │
# │ list[i64] ┆ u32     │
# ╞═══════════╪═════════╡
# │ [1, 2]    ┆ 2       │
# │ [4, 3, 2] ┆ 3       │
# └───────────┴─────────┘
```

--------------------------------

### Create a DataFrame for polars.first examples

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.first.html

Creates a DataFrame with columns 'a', 'b', and 'c' used in the subsequent examples.

```python
>>> df = pl.DataFrame(
...     {
...         "a": [1, 8, 3],
...         "b": [4, 5, 2],
...         "c": ["foo", "bar", "baz"],
...     }
... )
```

--------------------------------

### Create DataFrame with datetime and add column

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.duration.html

Creates a DataFrame with a datetime column and an add column, then displays the DataFrame. This is the setup for the subsequent duration examples.

```python
>>> from datetime import datetime
>>> df = pl.DataFrame(
...     {
...         "dt": [datetime(2022, 1, 1), datetime(2022, 1, 2)],
...         "add": [1, 2],
...     }
... )
>>> df
shape: (2, 2)
┌─────────────────────┬─────┐
│ dt                  ┆ add │
│ ---                 ┆ --- │
│ datetime[μs]        ┆ i64 │
╞═════════════════════╪═════╡
│ 2022-01-01 00:00:00 ┆ 1   │
│ 2022-01-02 00:00:00 ┆ 2   │
└─────────────────────┴─────┘
```

--------------------------------

### Get struct field names with polars DataTypeExpr.struct.field_names()

Source: https://docs.pola.rs/api/python/stable/reference/datatype_expr/api/polars.DataTypeExpr.struct.field_names.html

Use this snippet to retrieve the field names of a struct data type as a list. The example creates a struct with fields 'x' and 'y' and calls field_names() to get them. The output shows a DataFrame with the field names as a column named 'literal'.

```python
>>> pl.select(
...     pl.Struct({"x": pl.Int64, "y": pl.String})
...     .to_dtype_expr()
...     .struct.field_names()
... )
shape: (2, 1)
┌─────────┐
│ literal │
│ ---     │
│ str     │
╞═════════╡
│ x       │
│ y       │
└─────────┘
```

--------------------------------

### Create sample DataFrame

Source: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.map_elements.html

Creates a DataFrame with columns 'a' and 'b' used in the map_elements examples.

```python
>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 1],
...         "b": ["a", "b", "c", "c"],
...     }
... )

```

--------------------------------

### STARTS_WITH SQL function example

Source: https://docs.pola.rs/api/python/stable/reference/sql/functions/string.html

Uses the Polars SQL function STARTS_WITH to check if each string in the 'foo' column starts with 'a'. The result is a boolean column named starts_a.

```python
df = pl.DataFrame({"foo": ["apple", "banana", "avocado", "grape"]})
df.sql("""
  SELECT foo, STARTS_WITH(foo, 'a') AS starts_a FROM self
""")
# shape: (4, 2)
# ┌─────────┬──────────┐
# │ foo     ┆ starts_a │
# │ ---     ┆ ---      │
# │ str     ┆ bool     │
# ╞═════════╪══════════╡
# │ apple   ┆ true     │
# │ banana  ┆ false    │
# │ avocado ┆ true     │
# │ grape   ┆ false    │
# └─────────┴──────────┘
```

--------------------------------

### QueryOptFlags.__init__()

Source: https://docs.pola.rs/api/python/stable/reference/lazyframe/api/polars.QueryOptFlags.html

Initializes a new QueryOptFlags instance with optional boolean flags for each optimization. All parameters are keyword-only and default to None, meaning the flag is not set.

```APIDOC
## QueryOptFlags.__init__()

### Description
Initializes a new QueryOptFlags instance with optional boolean flags for each optimization. All parameters are keyword-only and default to None, meaning the flag is not set.

### Method
Constructor

### Signature
__init__(*, predicate_pushdown: None | bool = None, projection_pushdown: None | bool = None, simplify_expression: None | bool = None, slice_pushdown: None | bool = None, comm_subplan_elim: None | bool = None, comm_subexpr_elim: None | bool = None, cluster_with_columns: None | bool = None, collapse_joins: None | bool = None, check_order_observe: None | bool = None, fast_projection: None | bool = None, sort_collapse: None | bool = None, pre_partition_hive: None | bool = None) -> None

### Parameters
All parameters are keyword-only and optional.

- **predicate_pushdown** (None | bool) - Optional - Apply predicates/filters as early as possible.
- **projection_pushdown** (None | bool) - Optional - Only read columns that are used later in the query.
- **simplify_expression** (None | bool) - Optional - Run many expression optimization rules until fixed point.
- **slice_pushdown** (None | bool) - Optional - Pushdown slices/limits.
- **comm_subplan_elim** (None | bool) - Optional - Elide duplicate plans and caches their outputs.
- **comm_subexpr_elim** (None | bool) - Optional - Elide duplicate expressions and caches their outputs.
- **cluster_with_columns** (None | bool) - Optional - Cluster sequential `with_columns` calls to independent calls.
- **collapse_joins** (None | bool) - Optional - Collapse sequential joins.
- **check_order_observe** (None | bool) - Optional - Do not maintain order if the order would not be observed.
- **fast_projection** (None | bool) - Optional - Replace simple projections with a faster inlined projection that skips the expression engine.
- **sort_collapse** (None | bool) - Optional - Collapse sequential sort nodes into a single sort node.
- **pre_partition_hive** (None | bool) - Optional - Prepartition hive-partitioned joins on their partition key (requires `predicate_pushdown`).

### Returns
None
```
Tokens:
Raw