Expression constants
Inject a constant into arithmetic, conditional, or aggregation expressions.
Polars · Function
pl.lit
Creates a Polars expression representing a literal value. The value's data type is inferred by default, or controlled with dtype.
How it works
pl.lit converts a Python value into a Polars expression representing that value. Polars infers the expression's data type by default, or you can provide one explicitly; unknown types raise an exception unless object typing is enabled.
Syntax
polars.lit(value: Any, dtype: PolarsDataType | DataTypeExpr | None = None, *, allow_object: bool = False) -> ExprParameters
| Name | Type | Description |
|---|---|---|
value | Any | Value that should be used as a literal. |
dtype | PolarsDataType | DataTypeExpr | None | Data type of the resulting expression; if None, inferred from value. |
allow_object | bool | Use object type when the input type is unknown; otherwise an unknown type raises ValueException. |
Returns
Expr
Key points
- The function wraps a supplied Python value as a Polars Expr.
- Leaving dtype unset makes Polars infer the literal's data type.
- Set allow_object=True when an input should use object typing despite unknown type inference.
- An empty Python list becomes an empty List<Null> literal.
- A list of integer values is inferred as List<i64>.
- Passing None creates a Null-typed literal.
Common mistakes
- Values whose type Polars cannot infer cause a ValueException unless allow_object=True is passed.
Example: Use a scalar literal in an expression
import polars as pl
df = pl.DataFrame({"price": [10, 20], "quantity": [2, 3]})
result = df.select(
pl.col("price") * pl.col("quantity") + pl.lit(1)
)
print(result)Adds a scalar literal to an expression computed from DataFrame columns.
When to use it
Literal collections
Represent a list or Series as literal data in a selection or transformation.
Explicit typing
Control how Polars interprets a value when inference needs to be explicit.
Interview questions
QWhat does pl.lit return?
pl.lit accepts a value and returns an Expr representing a literal. It is useful when a constant must participate in a Polars expression alongside column expressions.
Follow-up: How does dtype affect the result? It explicitly sets the resulting expression type; when omitted, Polars infers it from value.
QWhat are the main parameters?
The value argument is converted to a literal expression, while dtype controls the expression's resulting data type. allow_object can permit object typing when the input type is unknown.
Follow-up: What happens with an unknown type by default? Polars raises ValueException rather than silently choosing object type.
QWhich kinds of values can be represented?
Scalar values such as integers, floats, strings, dates, datetimes, and None are supported. Lists and Series are also accepted, with nested inputs producing list-like literal data.
Follow-up: What type does pl.lit([1, 2, 3]) infer? The documentation specifies List<i64>.
Related
polars.Exprpolars.colpolars.whenpolars.repeat