Variables

Variables describe the roles that DataFrame fields play in a chart. Each strategy declares a fixed _variables map; callers select fields from their metadata to fill those roles.

Aggregation dataclass

from orama.variables import Aggregation

Aggregation(
    name="revenue_sum",   # str — output column name in the result DataFrame
    function="sum",       # str — therismos AggregationFunction value
    field="revenue",      # str | None — source field; None for count-only aggregations
)

The function string must be a valid therismos.grouping.AggregationFunction value: "count", "sum", "average", "min", "max", etc.

Variable types

Class	Candidate fields
CategoricalVariable	Fields where FieldMetadata.categorical is True
NumericalVariable	Fields where FieldMetadata.numeric is True
NonDerivedNumericalVariable	Numeric fields that are not derived (FieldMetadata.derived is False)
NumericalAggregationVariable	Same as NonDerivedNumericalVariable; used as aggregation targets
DateTimeVariable	date or datetime fields for which {field}__year and {field}__month derived fields are present in the metadata map; or standalone integer fields annotated with suggested_validation of "year" or "month"
CountryCodeVariable	Fields with extra["suggested_validation"] == "iso_a2" (ISO 3166-1 alpha-2 country codes)

All variable types validate the fields passed by the caller at strategy construction time and raise ValueError if an invalid field is supplied.

Semantic sort ordering

When sort_by_value is set to SortOrder.ASCENDING or SortOrder.DESCENDING and a category field's effective_type is a subclass of therismos.SemanticallyOrderedEnum, the category column is sorted by the enum's declared semantic order (via semantic_order()) rather than lexicographically.

This ensures that semantically ordered categories such as very small → small → medium → large → very large are always displayed in their intended order regardless of alphabetical sort.