DataType expressions

Data type expressions allow lazily determining a datatype of a column or expression and using in expressions.

This page gives an overview of all public Polars expressions.

class polars.DataTypeExpr

A lazily instantiated DataType that can be used in an Expr.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

This expression is made to represent a DataType that can be used to reference a datatype in a lazy context.

Examples

>>> lf = pl.LazyFrame({"a": [1, 2, 3]})
>>> lf.with_columns(
...     pl.col.a.map_batches(lambda x: x * 2, return_dtype=pl.dtype_of("a"))
... ).collect()
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 4   │
│ 6   │
└─────┘

Methods:

collect_dtype	Materialize the DataTypeExpr in a specific context.
default_value	Get a default value of a specific type.
display	Get a formatted version of the output DataType.
inner_dtype	Get the inner DataType of a List or Array.
matches	Get whether the output DataType is matches a certain selector.
to_signed_integer	Get the signed integer version of the same bitsize.
to_unsigned_integer	Get the unsigned integer version of the same bitsize.
wrap_in_array	Get the DataType wrapped in an array.
wrap_in_list	Get the DataType wrapped in a list.

collect_dtype(
    context: SchemaDict | Schema | DataFrame | LazyFrame,
) → DataType

Materialize the DataTypeExpr in a specific context.

This is a useful function when debugging datatype expressions.

Examples

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3],
...     }
... )
>>> pl.dtype_of("a").collect_dtype(lf)
Int64
>>> pl.dtype_of("a").collect_dtype({"a": pl.String})
String

default_value(
    n: int = 1,
    *,
    numeric_to_one: bool = False,
    num_list_values: int = 0,
) → Expr

Get a default value of a specific type.

• Integers and floats are their zero value as default, unless otherwise specified
• Temporals are a physical zero as default
• pl.Decimal is zero as default
• pl.String and pl.Binary are an empty string
• pl.List is an empty list, unless otherwise specified
• pl.Array is the inner default value repeated over the shape
• pl.Struct is the inner default value for all fields
• pl.Enum is the first category if it exists
• pl.Null, pl.Object and pl.Categorical are null.

Parameters:

n

Number of types you want the value

numeric_to_one

Use 1 instead of 0 as the default value for numeric types

num_list_values

The amount of values a list contains

Examples

>>> uint32 = pl.UInt32.to_dtype_expr()
>>> pl.select(default=uint32.default_value())
shape: (1, 1)
┌─────────┐
│ default │
│ ---     │
│ u32     │
╞═════════╡
│ 0       │
└─────────┘

display() → Expr

Get a formatted version of the output DataType.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["X", "Y", "Z"],
...         "c": [1.3, 3.7, 4.2],
...     }
... )
>>> df.select(
...     a=pl.dtype_of("a").display(),
...     b=pl.dtype_of("b").display(),
...     c=pl.dtype_of("c").display(),
... ).transpose(include_header=True, column_names=["dtype"])
shape: (3, 2)
┌────────┬───────┐
│ column ┆ dtype │
│ ---    ┆ ---   │
│ str    ┆ str   │
╞════════╪═══════╡
│ a      ┆ i64   │
│ b      ┆ str   │
│ c      ┆ f64   │
└────────┴───────┘

inner_dtype() → DataTypeExpr

Get the inner DataType of a List or Array.

matches(
    selector: Selector,
) → Expr

Get whether the output DataType is matches a certain selector.

Examples

>>> import polars.selectors as cs
>>> pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...     }
... ).select(
...     a_is_string=pl.dtype_of("a").matches(cs.string()),
...     a_is_integer=pl.dtype_of("a").matches(cs.integer()),
... )
shape: (1, 2)
┌─────────────┬──────────────┐
│ a_is_string ┆ a_is_integer │
│ ---         ┆ ---          │
│ bool        ┆ bool         │
╞═════════════╪══════════════╡
│ false       ┆ true         │
└─────────────┴──────────────┘

to_signed_integer() → DataTypeExpr

Get the signed integer version of the same bitsize.

Examples

>>> uint32 = pl.UInt32.to_dtype_expr()
>>> uint32.to_signed_integer().collect_dtype({})
Int32

to_unsigned_integer() → DataTypeExpr

Get the unsigned integer version of the same bitsize.

Examples

>>> int32 = pl.Int32.to_dtype_expr()
>>> int32.to_unsigned_integer().collect_dtype({})
UInt32

wrap_in_array(
    *,
    width: int,
) → DataTypeExpr

Get the DataType wrapped in an array.

Examples

>>> pl.Int32.to_dtype_expr().wrap_in_array(width=5).collect_dtype({})
Array(Int32, shape=(5,))

wrap_in_list() → DataTypeExpr

Get the DataType wrapped in a list.

Examples

>>> pl.Int32.to_dtype_expr().wrap_in_list().collect_dtype({})
List(Int32)