Skip to content

Primitives

primitives

Primitives: the expression builders DFS composes into features.

Base classes

Primitive

Bases: ABC

Base class for every primitive.

Attributes:

Name Type Description
name str

Registry key, also the upper-cased stem of generated names.
input_dtypes tuple[DtypeFamily, ...]

One dtype family per input. Empty means the primitive takes no column input, e.g. count.
output_dtype Any

Fixed output dtype, or None to preserve the first input's.
commutative bool

Whether argument order is irrelevant, so that only one of f(a, b) and f(b, a) is generated.
stack_on_self bool

Whether this primitive may be applied to its own output.
default_value Any

Value substituted for empty groups after a left join.

name class-attribute 

name

input_dtypes class-attribute 

input_dtypes = ()

output_dtype class-attribute 

output_dtype = None

commutative class-attribute 

commutative = False

stack_on_self class-attribute 

stack_on_self = True

default_value class-attribute 

default_value = None

number_of_outputs property 

number_of_outputs

How many columns this primitive produces.

return_dtype 

return_dtype(input_dtypes)

Compute the output dtype without touching data.

Parameters:

Name Type Description Default
input_dtypes tuple[Any, ...]

Dtypes of the input features, in order.

 required

Returns:

Type Description
Any

The dtype of this primitive's output.

generate_name 

generate_name(arg_names)

Build the column name for an application of this primitive.

Every part is joined with __ so the result is a plain SQL identifier. Parentheses and commas would be parsed as a function call by any backend that generates SQL; see :meth:generate_display_name for the readable form.

Parameters:

Name Type Description Default
arg_names Sequence[str]

Names of the inputs. For a zero-input aggregation this is the child table's name, giving e.g. COUNT__transactions.

 required

Returns:

Type Description
str

The feature name.

generate_display_name 

generate_display_name(arg_names)

Build the readable name for an application of this primitive.

Parameters:

Name Type Description Default
arg_names Sequence[str]

Display names of the inputs.

 required

Returns:

Type Description
str

The conventional parenthesised form, e.g. MEAN(amount).

output_names 

output_names(base_name)

Expand a feature name into one name per output column.

Parameters:

Name Type Description Default
base_name str

The name from :meth:generate_name.

 required

Returns:

Type Description
tuple[str, ...]

One name per output column; indexed when there is more than one.

display_output_names 

display_output_names(base_name)

Expand a display name into one readable name per output column.

Parameters:

Name Type Description Default
base_name str

The name from :meth:generate_display_name.

 required

Returns:

Type Description
tuple[str, ...]

One name per output column; indexed when there is more than one.

outputs 

outputs(*inputs)

Normalize :meth:build to a tuple of expressions.

Parameters:

Name Type Description Default
*inputs Expr

One expression per declared input.

 ()

Returns:

Type Description
tuple[Expr, ...]

One expression per output column.

build abstractmethod 

build(*inputs)

Build this primitive's narwhals expression.

Parameters:

Name Type Description Default
*inputs Expr

One expression per declared input.

 ()

Returns:

Type Description
Expr | Sequence[Expr]

A single expression, or a sequence for multi-output primitives.

AggregationPrimitive

Bases: Primitive

A primitive applied to a child table's rows, grouped by foreign key.

TransformPrimitive

Bases: Primitive

A primitive applied row-wise within a single table.

Attributes:

Name Type Description
order_dependent bool

Whether the expression needs an explicit ordering. Narwhals requires .over(order_by=...) for these on lazy backends, so tusk requires a row_creation_time on the table.

order_dependent class-attribute 

order_dependent = False

Registry

register 

register(cls)

Register a primitive class under its name.

Parameters:

Name Type Description Default
cls type[_P]

The primitive class to register.

 required

Returns:

Type Description
type[_P]

The class unchanged, so this works as a decorator.

Raises:

Type Description
PrimitiveError

If the name is already registered to a different class. Re-registering the same class under its own name is a no-op.

resolve 

resolve(spec)

Turn a name or instance into a primitive instance.

Parameters:

Name Type Description Default
spec str | Primitive

A registered primitive name, or an already-built instance.

 required

Returns:

Type Description
Primitive

A primitive instance.

Raises:

Type Description
PrimitiveError

If the name is not registered, or the primitive is not a frozen dataclass with equality enabled.

resolve_all 

resolve_all(specs)

Resolve a collection of names or instances.

Parameters:

Name Type Description Default
specs Iterable[str | Primitive]

Names or instances.

 required

Returns:

Type Description
tuple[Primitive, ...]

Primitive instances in the given order.

Aggregation primitives

AGG_DEFAULTS module-attribute 

AGG_DEFAULTS = (
    "count",
    "sum",
    "mean",
    "min",
    "max",
    "std",
    "n_unique",
)

Count dataclass 

Count()

Bases: AggregationPrimitive

Number of child rows in the group.

name class-attribute instance-attribute 

name = 'count'

input_dtypes class-attribute instance-attribute 

input_dtypes = ()

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int64

default_value class-attribute instance-attribute 

default_value = 0

stack_on_self class-attribute instance-attribute 

stack_on_self = False

build 

build()

Build the row-count expression.

Returns:

Type Description
Expr

A narwhals expression counting rows.

Sum dataclass 

Sum()

Bases: AggregationPrimitive

Sum of a numeric column.

name class-attribute instance-attribute 

name = 'sum'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

default_value class-attribute instance-attribute 

default_value = 0

build 

build(expr)

Build the sum expression.

Parameters:

Name Type Description Default
expr Expr

The column to sum.

 required

Returns:

Type Description
Expr

A narwhals expression.

Mean dataclass 

Mean()

Bases: AggregationPrimitive

Arithmetic mean of a numeric column.

name class-attribute instance-attribute 

name = 'mean'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

build 

build(expr)

Build the mean expression.

Parameters:

Name Type Description Default
expr Expr

The column to average.

 required

Returns:

Type Description
Expr

A narwhals expression.

Min dataclass 

Min()

Bases: AggregationPrimitive

Smallest value of a numeric column.

name class-attribute instance-attribute 

name = 'min'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

build 

build(expr)

Build the minimum expression.

Parameters:

Name Type Description Default
expr Expr

The column to reduce.

 required

Returns:

Type Description
Expr

A narwhals expression.

Max dataclass 

Max()

Bases: AggregationPrimitive

Largest value of a numeric column.

name class-attribute instance-attribute 

name = 'max'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

build 

build(expr)

Build the maximum expression.

Parameters:

Name Type Description Default
expr Expr

The column to reduce.

 required

Returns:

Type Description
Expr

A narwhals expression.

Std dataclass 

Std()

Bases: AggregationPrimitive

Sample standard deviation of a numeric column.

name class-attribute instance-attribute 

name = 'std'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

build 

build(expr)

Build the standard-deviation expression.

Parameters:

Name Type Description Default
expr Expr

The column to reduce.

 required

Returns:

Type Description
Expr

A narwhals expression.

Median dataclass 

Median()

Bases: AggregationPrimitive

Median of a numeric column.

name class-attribute instance-attribute 

name = 'median'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

build 

build(expr)

Build the median expression.

Parameters:

Name Type Description Default
expr Expr

The column to reduce.

 required

Returns:

Type Description
Expr

A narwhals expression.

NUnique dataclass 

NUnique()

Bases: AggregationPrimitive

Number of distinct known values in a column; nulls are not a value.

name class-attribute instance-attribute 

name = 'n_unique'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.ANY,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int64

default_value class-attribute instance-attribute 

default_value = 0

stack_on_self class-attribute instance-attribute 

stack_on_self = False

build 

build(expr)

Build the distinct-count expression, excluding null.

Polars counts null as one more distinct value, which contradicts this primitive's own default_value: a customer whose only session had no transactions would report 0 rows and 1 distinct value at once. featuretools' NUM_UNIQUE excludes nulls, so counting them would also diverge silently on any data containing them.

Subtracting a null indicator is deliberate rather than expr.drop_nulls().n_unique(): drop_nulls is a length-changing (filtration) expression, and narwhals rejects those inside a lazy group_by().agg() on backends that cannot express them. Both operands here are plain reductions.

Parameters:

Name Type Description Default
expr Expr

The column to count distinct values of.

 required

Returns:

Type Description
Expr

A narwhals expression.

PercentTrue dataclass 

PercentTrue()

Bases: AggregationPrimitive

Fraction of rows where a boolean column is true.

name class-attribute instance-attribute 

name = 'percent_true'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.BOOLEAN,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

build 

build(expr)

Build the true-fraction expression.

Parameters:

Name Type Description Default
expr Expr

The boolean column.

 required

Returns:

Type Description
Expr

A narwhals expression.

Quantiles dataclass 

Quantiles(qs=(0.25, 0.5, 0.75))

Bases: AggregationPrimitive

Several quantiles of a numeric column, one output column per quantile.

Attributes:

Name Type Description
name

Registry key.
input_dtypes

Tuple containing one dtype family (NUMERIC).
output_dtype

The output dtype (Float64).
qs tuple[float, ...]

The quantiles to compute, each in [0, 1].

name class-attribute instance-attribute 

name = 'quantiles'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

qs class-attribute instance-attribute 

qs = field(default=(0.25, 0.5, 0.75))

number_of_outputs property 

number_of_outputs

One output column per requested quantile.

build 

build(expr)

Build one expression per quantile.

Parameters:

Name Type Description Default
expr Expr

The column to reduce.

 required

Returns:

Type Description
Sequence[Expr]

One narwhals expression per quantile.

Transform primitives

TRANS_DEFAULTS module-attribute 

TRANS_DEFAULTS = ('year', 'month', 'weekday')

Year dataclass 

Year()

Bases: TransformPrimitive

Calendar year.

name class-attribute instance-attribute 

name = 'year'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int32

build 

build(expr)

Build the calendar-year expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals expression of the calendar year.

Month dataclass 

Month()

Bases: TransformPrimitive

Calendar month, 1-12.

name class-attribute instance-attribute 

name = 'month'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int8

build 

build(expr)

Build the calendar-month expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals expression of the calendar month.

Day dataclass 

Day()

Bases: TransformPrimitive

Day of month, 1-31.

name class-attribute instance-attribute 

name = 'day'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int8

build 

build(expr)

Build the day-of-month expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals expression of the day of month.

Hour dataclass 

Hour()

Bases: TransformPrimitive

Hour of day, 0-23.

name class-attribute instance-attribute 

name = 'hour'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int8

build 

build(expr)

Build the hour-of-day expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals expression of the hour of day.

Weekday dataclass 

Weekday()

Bases: TransformPrimitive

ISO weekday, 1 (Monday) to 7 (Sunday).

name class-attribute instance-attribute 

name = 'weekday'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int8

build 

build(expr)

Build the ISO-weekday expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals expression of the ISO weekday.

IsWeekend dataclass 

IsWeekend()

Bases: TransformPrimitive

Whether the date falls on a Saturday or Sunday.

name class-attribute instance-attribute 

name = 'is_weekend'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Boolean

build 

build(expr)

Build the weekend-indicator expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals boolean expression.

Absolute dataclass 

Absolute()

Bases: TransformPrimitive

Absolute value.

name class-attribute instance-attribute 

name = 'absolute'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

build 

build(expr)

Build the absolute-value expression.

Parameters:

Name Type Description Default
expr Expr

A numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression with absolute values.

NaturalLog dataclass 

NaturalLog()

Bases: TransformPrimitive

Natural logarithm. Non-positive inputs yield null or negative infinity.

name class-attribute instance-attribute 

name = 'natural_log'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

build 

build(expr)

Build the natural-logarithm expression.

Parameters:

Name Type Description Default
expr Expr

A numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression of natural logarithms.

AddNumeric dataclass 

AddNumeric()

Bases: TransformPrimitive

Sum of two numeric columns.

name class-attribute instance-attribute 

name = 'add_numeric'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC, F.NUMERIC)

commutative class-attribute instance-attribute 

commutative = True

build 

build(left, right)

Build the addition expression.

Parameters:

Name Type Description Default
left Expr

First column.

 required
right Expr

Second column.

 required

Returns:

Type Description
Expr

A narwhals expression.

SubtractNumeric dataclass 

SubtractNumeric()

Bases: TransformPrimitive

Difference of two numeric columns.

name class-attribute instance-attribute 

name = 'subtract_numeric'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC, F.NUMERIC)

build 

build(left, right)

Build the subtraction expression.

Parameters:

Name Type Description Default
left Expr

First numeric expression.

 required
right Expr

Second numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression of the difference.

MultiplyNumeric dataclass 

MultiplyNumeric()

Bases: TransformPrimitive

Product of two numeric columns.

name class-attribute instance-attribute 

name = 'multiply_numeric'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC, F.NUMERIC)

commutative class-attribute instance-attribute 

commutative = True

build 

build(left, right)

Build the multiplication expression.

Parameters:

Name Type Description Default
left Expr

First column.

 required
right Expr

Second column.

 required

Returns:

Type Description
Expr

A narwhals expression.

DivideNumeric dataclass 

DivideNumeric()

Bases: TransformPrimitive

Ratio of two numeric columns.

name class-attribute instance-attribute 

name = 'divide_numeric'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC, F.NUMERIC)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

build 

build(left, right)

Build the division expression.

Parameters:

Name Type Description Default
left Expr

First numeric expression (numerator).

 required
right Expr

Second numeric expression (denominator).

 required

Returns:

Type Description
Expr

A narwhals expression of the ratio.

Order-dependent transform primitives

CumSum dataclass 

CumSum()

Bases: TransformPrimitive

Running total in row-creation order.

name class-attribute instance-attribute 

name = 'cum_sum'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

order_dependent class-attribute instance-attribute 

order_dependent = True

build 

build(expr)

Build the cumulative-sum expression.

Parameters:

Name Type Description Default
expr Expr

A numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression of cumulative sum.

CumCount dataclass 

CumCount()

Bases: TransformPrimitive

Running count of non-null values in row-creation order.

name class-attribute instance-attribute 

name = 'cum_count'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.ANY,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Int64

order_dependent class-attribute instance-attribute 

order_dependent = True

build 

build(expr)

Build the cumulative-count expression.

Parameters:

Name Type Description Default
expr Expr

An expression.

 required

Returns:

Type Description
Expr

A narwhals expression of cumulative count.

CumMin dataclass 

CumMin()

Bases: TransformPrimitive

Running minimum in row-creation order.

name class-attribute instance-attribute 

name = 'cum_min'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

order_dependent class-attribute instance-attribute 

order_dependent = True

build 

build(expr)

Build the cumulative-minimum expression.

Parameters:

Name Type Description Default
expr Expr

A numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression of cumulative minimum.

CumMax dataclass 

CumMax()

Bases: TransformPrimitive

Running maximum in row-creation order.

name class-attribute instance-attribute 

name = 'cum_max'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

order_dependent class-attribute instance-attribute 

order_dependent = True

build 

build(expr)

Build the cumulative-maximum expression.

Parameters:

Name Type Description Default
expr Expr

A numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression of cumulative maximum.

Diff dataclass 

Diff()

Bases: TransformPrimitive

Change from the previous row in row-creation order.

name class-attribute instance-attribute 

name = 'diff'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.NUMERIC,)

order_dependent class-attribute instance-attribute 

order_dependent = True

build 

build(expr)

Build the row-difference expression.

Parameters:

Name Type Description Default
expr Expr

A numeric expression.

 required

Returns:

Type Description
Expr

A narwhals expression of differences.

TimeSincePrevious dataclass 

TimeSincePrevious()

Bases: TransformPrimitive

Seconds elapsed since the previous row in row-creation order.

name class-attribute instance-attribute 

name = 'time_since_previous'

input_dtypes class-attribute instance-attribute 

input_dtypes = (F.TEMPORAL,)

output_dtype class-attribute instance-attribute 

output_dtype = nw.Float64

order_dependent class-attribute instance-attribute 

order_dependent = True

build 

build(expr)

Build the elapsed-seconds expression.

Parameters:

Name Type Description Default
expr Expr

A temporal expression.

 required

Returns:

Type Description
Expr

A narwhals expression of time elapsed in seconds.