Primitives reference

featurizer registers 67 aggregations (applied across backward relationships, parent ← child) and 83 transformers (applied to features within an entity). This page is generated from the registry at build time, so it cannot drift from the code. Select primitives per config with the aggregations: / transformations: keys — see the configuration reference.

Prefer to browse interactively?

Open the primitives explorer — faceted filter by type and category, live search, and the SQL each primitive emits.

Note

Peer-group features (peer_groups), spatial second-table features (spatial_relationships), and the φ-bridge companion are planner passes driven by their own config blocks — deliberately not registry primitives, so they are not listed here.

Discover the same information from the CLI:

uv run python -m featurizer list-primitives --type agg --show-sql

Aggregations (67)

basic

primitive	description	SQL example
count	Count of non-null values	COUNT(status)
max	Maximum value	MAX(amount)
mean	Arithmetic mean (average)	AVG(amount)
min	Minimum value	MIN(amount)
nunique	Count of distinct values	COUNT(DISTINCT status)
stddev	Standard deviation	STDDEV(amount)
sum	Sum of all values	SUM(amount)
variance	Statistical variance	VARIANCE(amount)

boolean

primitive	description	SQL example
all	True if all values are true (boolean AND)	BOOL_AND(is_active)
any	True if any value is true (boolean OR)	BOOL_OR(is_active)

drift

primitive	description	SQL example
kl_drift	KL divergence: recent vs prior-window category distribution	SUM(p_recent * LN(p_recent / p_baseline)) over shared support
wasserstein_drift	Quantile L1 drift: recent vs prior-window numeric distribution	|q10_r - q10_b| + |q50_r - q50_b| + |q90_r - q90_b|

gap

primitive	description	SQL example
gap_cv	Coefficient of variation of inter-event gaps	STDDEV(gap) / NULLIF(AVG(gap), 0)
gap_max	Maximum inter-event gap duration	MAX(ts - LAG(ts) OVER (ORDER BY ts))
gap_mean	Mean inter-event gap duration	AVG(ts - LAG(ts) OVER (ORDER BY ts))
gap_min	Minimum inter-event gap duration	MIN(ts - LAG(ts) OVER (ORDER BY ts))
gap_stddev	Standard deviation of inter-event gaps	STDDEV(ts - LAG(ts) OVER (ORDER BY ts))

inequality

primitive	description	SQL example
entropy	Shannon entropy of categorical distribution	-SUM(p * LN(p)) where p = COUNT(val) / SUM(COUNT(val))
gini	Gini coefficient (inequality measure, 0-1)	2 * SUM(rank * val) / (n * SUM(val)) - (n+1)/n
hhi	Herfindahl-Hirschman Index (concentration measure)	SUM(p^2) where p = COUNT(val) / SUM(COUNT(val))
theil	Theil-T inequality index over positive values	AVG((x/mean) * LN(x/mean))

mean_variant

primitive	description	SQL example
geometric_mean	Geometric mean (for growth rates)	EXP(AVG(LOG(value)))
harmonic_mean	Harmonic mean (for rates and ratios)	COUNT(value) / SUM(1.0/value)
trimmed_mean_10	Mean of values within the 10th-90th percentile range	AVG(x) WHERE x BETWEEN p10 AND p90

ordered_set

primitive	description	SQL example
median	Median value (50th percentile)	PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY amount)
mode	Most frequent value	MODE() WITHIN GROUP (ORDER BY status)
p10	10th percentile	PERCENTILE_CONT(0.10) WITHIN GROUP (ORDER BY amount)
p25	25th percentile (first quartile)	PERCENTILE_CONT(0.25) WITHIN GROUP (ORDER BY amount)
p75	75th percentile (third quartile)	PERCENTILE_CONT(0.75) WITHIN GROUP (ORDER BY amount)
p90	90th percentile	PERCENTILE_CONT(0.90) WITHIN GROUP (ORDER BY amount)
p95	95th percentile	PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY amount)
p99	99th percentile	PERCENTILE_CONT(0.99) WITHIN GROUP (ORDER BY amount)

sequence

primitive	description	SQL example
longest_streak	Longest consecutive streak of same value	MAX(streak_length) using gaps-and-islands
ngram_2_freq	Bigram frequency distribution of categorical sequences	COUNT(DISTINCT val || '->' || LEAD(val)) / COUNT(*)
ngram_3_freq	Trigram frequency distribution of categorical sequences	COUNT(DISTINCT val || '->' || LEAD(val,1) || '->' || LEAD(val,2)) / COUNT(*)
sequence_entropy	Transition entropy of categorical sequences	-SUM(p_ij * LN(p_ij)) over transition matrix

spatial

primitive	description	SQL example
bbox_area	Approximate latitude-corrected bounding-box area (m^2)	(max(lat)-min(lat))*(max(lon)-min(lon))*cos(avg(lat))*111320^2
distance_travelled	Total great-circle distance over consecutive events (m)	SUM(haversine(lag(lat,lon), (lat,lon)))
radius_of_gyration	RMS great-circle distance of events from their centroid (m)	sqrt(AVG(haversine(centroid, point)^2))
spatial_std	Degree-space dispersion: sqrt(var(lat) + var(lon))	sqrt(var_samp(lat) + var_samp(lon))

state_dynamics

primitive	description	SQL example
markov_conditional_entropy	First-order Markov entropy rate H(X_t | X_{t-1}) in nats	-SUM(p(i,j) * LN(p(j|i))) over the transition matrix
max_transition_prob	Predictability: largest conditional transition probability	MAX(freq / row_total) over the transition matrix
recurrence_interval	Mean days between consecutive occurrences of the same state	AVG(ts - LAG(ts) OVER (PARTITION BY value ORDER BY ts))
rework_count	Count of consecutive repeats (self-loops, prev == curr)	count(*) WHERE prev = curr
state_volatility	Count of categorical value changes over time	count(*) WHERE prev IS DISTINCT FROM curr
time_in_current_state	Days since the most recent change of a categorical attribute	aod.as_of_date - max(ts WHERE value changed)
transition_matrix_summary	Number of distinct observed (prev -> curr) transitions	count(DISTINCT (prev, curr))

statistical

primitive	description	SQL example
cv	Coefficient of variation (STDDEV / MEAN)	STDDEV(amount) / NULLIF(AVG(amount), 0)
iqr	Interquartile range (P75 - P25)	PERCENTILE_CONT(0.75) WITHIN GROUP (ORDER BY amount) - PERCENTILE_CONT(0.25) WITHIN GROUP (ORDER BY amount)
kurtosis	Measure of distribution tailedness	((value - AVG(value)) / STDDEV(value))^4
mean_deviation	Average absolute deviation from the mean (two-pass subquery)	AVG(ABS(value - (SELECT AVG(value) ...)))
median_absolute_deviation	Robust spread: median(|x - median(x)|)	percentile_cont(0.5) WITHIN GROUP (ORDER BY abs(x - median))
range	Range (MAX - MIN)	MAX(amount) - MIN(amount)
skewness	Measure of distribution asymmetry	((value - AVG(value)) / STDDEV(value))^3
variance_ratio	Variance ratio: var(value) / var(first difference)	var_samp(x) / NULLIF(var_samp(x - LAG(x)), 0)

survival

primitive	description	SQL example
cross_type_latency	Mean seconds from an A-typed event to the next B-typed event	AVG(MIN(b.ts) - a.ts) for a=A-rows, b=next B-rows
first_passage_time	Days from the first event to the first ‘target’ state (else NULL)	MIN(ts) FILTER (WHERE col = 'target') - MIN(ts)
right_censoring_indicator	1 if the terminal event has not occurred by t0 (censored)	(count(*) FILTER (WHERE col = 'terminal') = 0)::int

temporal

primitive	description	SQL example
age_in_system	Alias of tenure: days since the first observed event	aod.as_of_date - min(event_ts)
event_rate	Events per unit time	COUNT(*) / EXTRACT(EPOCH FROM MAX(ts) - MIN(ts))
inter_event_hazard_proxy	Events per day over the observed lifespan (count / tenure)	count(*) / (aod.as_of_date - min(event_ts))
recency	Days since the most recent event (aod - max event ts)	aod.as_of_date - max(event_ts)
tenure	Days since the first observed event (age in system)	aod.as_of_date - min(event_ts)
time_span	Time span between first and last event	EXTRACT(EPOCH FROM MAX(ts) - MIN(ts))

temporal_pattern

primitive	description	SQL example
acf_1	Lag-1 autocorrelation: corr(x_t, x_{t-1})	corr(x, LAG(x,1) OVER (ORDER BY ts))
burstiness	Goh-Barabasi burstiness index (-1 to 1)	(STDDEV(gap) - AVG(gap)) / NULLIF(STDDEV(gap) + AVG(gap), 0)
cosinor_amplitude_weekly	Weekly cosinor amplitude (sin/cos regression approximation)	sqrt(regr_slope(x,sin)^2 + regr_slope(x,cos)^2)

Transformers (83)

basic

primitive	description	SQL example
identity	Pass-through (no transformation)	column_name

binning

primitive	description	SQL example
daily_bin	Bin days into weekday/weekend	CASE WHEN dow < 6 THEN 'weekday' ELSE 'weekend' END
hourly_bin	Bin hours into time-of-day categories	CASE WHEN hour < 5 THEN 'night' ... END

boolean

primitive	description	SQL example
in_array	Check if value is in array	value = ANY(ARRAY[...])
is_null	Check if value is null	(value IS NULL)

change_point

primitive	description	SQL example
cusum	CUSUM: cumulative sum of deviations from target mean	SUM(value - target_mean) OVER (PARTITION BY id ORDER BY date)
mean_shift_ratio_14	Ratio of recent 14-period mean to overall mean (change-point detection)	AVG(value) OVER (... ROWS 13 PRECEDING) / NULLIF(AVG(value) OVER (), 0)
mean_shift_ratio_7	Ratio of recent 7-period mean to overall mean (change-point detection)	AVG(value) OVER (... ROWS 6 PRECEDING) / NULLIF(AVG(value) OVER (), 0)

cumulative

primitive	description	SQL example
cum_count	Cumulative count over time	COUNT(value) OVER (PARTITION BY id ORDER BY date)
cum_max	Cumulative maximum over time	MAX(value) OVER (PARTITION BY id ORDER BY date)
cum_mean	Cumulative mean over time	AVG(value) OVER (PARTITION BY id ORDER BY date)
cum_min	Cumulative minimum over time	MIN(value) OVER (PARTITION BY id ORDER BY date)
cum_sum	Cumulative sum over time	SUM(value) OVER (PARTITION BY id ORDER BY date)
cumprod	Running product via log-sum-exp (positive series only)	exp(sum(ln(value)) OVER (PARTITION BY id ORDER BY date))

cyclical

primitive	description	SQL example
cyclic_day	Day of week as sin/cos pair for cyclical encoding	SIN(dow * 2*PI/7), COS(dow * 2*PI/7)
cyclic_hour	Hour as sin/cos pair for cyclical encoding	SIN(hour * 2*PI/24), COS(hour * 2*PI/24)
cyclic_month	Month as sin/cos pair for cyclical encoding	SIN((month-1) * 2*PI/12), COS((month-1) * 2*PI/12)

date

primitive	description	SQL example
century	Century number	TO_CHAR(date, 'CC')
day	Day of month (1-31)	TO_CHAR(date, 'DD')
dom	Day of month (DD format)	TO_CHAR(date, 'DD')
dow	ISO day of week (1=Monday to 7=Sunday)	TO_CHAR(date, 'ID')
doy	Day of year (1-366)	TO_CHAR(date, 'DDD')
hour	Hour (0-23)	TO_CHAR(date, 'HH24')
month	Month number (1-12)	TO_CHAR(date, 'MM')
quarter	Quarter of year (1-4)	TO_CHAR(date, 'Q')
tz	Time zone abbreviation	TO_CHAR(date, 'TZ')
tz_offset	Time zone offset	TO_CHAR(date, 'OF')
week	Week of month	TO_CHAR(date, 'W')
week_of_year	Week of year (1-53)	TO_CHAR(date, 'WW')
year	Four-digit year	TO_CHAR(date, 'YYYY')

distribution

primitive	description	SQL example
cdf	Cumulative distribution function value	CUME_DIST() OVER (PARTITION BY id ORDER BY value)
ntile	Divide into N equal groups (default: 5)	NTILE(5) OVER (PARTITION BY id ORDER BY value)
percent_rank	Relative rank as percentage (0-1)	PERCENT_RANK() OVER (PARTITION BY id ORDER BY value)

ema

primitive	description	SQL example
ema_14	14-period exponential moving average	SUM(value * EXP(decay * t)) / SUM(EXP(decay * t)) OVER (...)
ema_7	7-period exponential moving average	SUM(value * EXP(decay * t)) / SUM(EXP(decay * t)) OVER (...)

holt_winters

primitive	description	SQL example
holt_winters_level_14	14-period Holt-Winters level	AVG(value) OVER (... ROWS BETWEEN 13 PRECEDING AND CURRENT ROW)
holt_winters_level_7	7-period Holt-Winters level (smoothed average)	AVG(value) OVER (... ROWS BETWEEN 6 PRECEDING AND CURRENT ROW)
holt_winters_trend_14	14-period Holt-Winters trend	REGR_SLOPE(value, time) OVER (...)
holt_winters_trend_7	7-period Holt-Winters trend (slope)	REGR_SLOPE(value, time) OVER (...)

lag

primitive	description	SQL example
lag_1	Value from 1 period ago	LAG(value, 1) OVER (PARTITION BY id ORDER BY date)
lag_3	Value from 3 periods ago	LAG(value, 3) OVER (PARTITION BY id ORDER BY date)
lag_7	Value from 7 periods ago	LAG(value, 7) OVER (PARTITION BY id ORDER BY date)

math

primitive	description	SQL example
abs	Absolute value	ABS(value)
cbrt	Cube root	CBRT(value)
ceil	Round up to nearest integer	CEIL(value)
exp	Exponential (e^x)	EXP(value)
floor	Round down to nearest integer	FLOOR(value)
ln	Natural logarithm	LN(value)
log	Base-10 logarithm	LOG(value)
sign	Sign of value (-1, 0, or 1)	SIGN(value)
sqrt	Square root	SQRT(value)
trunc	Truncate decimal portion	TRUNC(value)

pct_change

primitive	description	SQL example
pct_change_1	Percentage change from 1 period ago	(value - LAG(value, 1)) / LAG(value, 1)
pct_change_3	Percentage change from 3 periods ago	(value - LAG(value, 3)) / LAG(value, 3)

population_window

primitive	description	SQL example
cross_entity_percentile	Percentile rank across all entities in the population	PERCENT_RANK() OVER (ORDER BY value)
cross_entity_zscore	Z-score normalized across all entities in the population	(value - AVG(value) OVER ()) / NULLIF(STDDEV(value) OVER (), 0)

rolling

primitive	description	SQL example
rolling_iqr_14	14-period rolling interquartile range	PERCENTILE_CONT(0.75) - PERCENTILE_CONT(0.25) OVER (...)
rolling_iqr_7	7-period rolling interquartile range (P75 - P25)	PERCENTILE_CONT(0.75) - PERCENTILE_CONT(0.25) OVER (...)
rolling_mean_14	14-period rolling mean	AVG(value) OVER (... ROWS BETWEEN 13 PRECEDING AND CURRENT ROW)
rolling_mean_3	3-period rolling mean	AVG(value) OVER (... ROWS BETWEEN 2 PRECEDING AND CURRENT ROW)
rolling_mean_7	7-period rolling mean	AVG(value) OVER (... ROWS BETWEEN 6 PRECEDING AND CURRENT ROW)
rolling_median_5	5-period rolling median	PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY value) OVER (...)
rolling_median_7	7-period rolling median	PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY value) OVER (...)
rolling_std_14	14-period rolling standard deviation	STDDEV(value) OVER (... ROWS BETWEEN 13 PRECEDING AND CURRENT ROW)
rolling_std_3	3-period rolling standard deviation	STDDEV(value) OVER (... ROWS BETWEEN 2 PRECEDING AND CURRENT ROW)
rolling_std_7	7-period rolling standard deviation	STDDEV(value) OVER (... ROWS BETWEEN 6 PRECEDING AND CURRENT ROW)

text

primitive	description	SQL example
avg_word_length	Mean characters per word	non_space_chars::numeric / nullif(num_words, 0)
caps_ratio	Uppercase letters / all letters	upper_letters::numeric / nullif(all_letters, 0)
digit_ratio	Digits / all characters	digit_chars::numeric / nullif(length(text), 0)
exclamation_count	Count of ’!’ characters	length(text) - length(replace(text, '!', ''))
num_chars	Character count in text	CHAR_LENGTH(text)
num_sentences	Sentence-terminator count (. ! ?)	length(text) - length(regexp_replace(text, '[.!?]', '', 'g'))
num_words	Whitespace-delimited word count	(SELECT count(*) FROM regexp_split_to_table(text, '\s+') t(w) WHERE w <> '')
punct_ratio	Punctuation / all characters	punct_chars::numeric / nullif(length(text), 0)
question_count	Count of ’?’ characters	length(text) - length(replace(text, '?', ''))
unique_word_ratio	Distinct words / total words (type-token ratio)	distinct_words::numeric / nullif(num_words, 0)

window

primitive	description	SQL example
diff	Difference from previous value	value - LAG(value) OVER (...)
diff2	Second difference (acceleration): x - 2*lag1 + lag2	value - 2*LAG(value,1) OVER w + LAG(value,2) OVER w
diff3	Third difference (jerk): x - 3lag1 + 3lag2 - lag3	value - 3*LAG(value,1) + 3*LAG(value,2) - LAG(value,3) OVER w
first	First value in partition	FIRST_VALUE(value) OVER (PARTITION BY id ORDER BY date)
last	Last value in partition	LAST_VALUE(value) OVER (PARTITION BY id ORDER BY date)
previous	Previous row’s value	LAG(value) OVER (PARTITION BY id ORDER BY date)
time_since_previous	Time elapsed since previous record	date - LAG(date) OVER (...)