Quick Start

The following example renders a simple bar chart from a toy Polars DataFrame.

from dataclasses import dataclass

import polars as pl
from babel.support import NullTranslations
from fields_metadata import MetadataExtractor
from polychromos.color import HSLColor

from orama.strategies.bar import BarChartStrategy
from orama.theme import Theme
from orama.variables import Aggregation

# ── Step 1: extract field metadata ────────────────────────────────────────────

@dataclass
class SalesRecord:
    region: str    # categorical — accepted by CategoricalVariable
    revenue: float # numeric    — accepted by NumericalAggregationVariable

fields_metadata = MetadataExtractor(SalesRecord).extract()

# ── Step 2: instantiate the strategy ──────────────────────────────────────────

strategy = BarChartStrategy(
    fields_metadata=fields_metadata,
    category_variables=["region"],
    aggregation=Aggregation(
        name="total_revenue",   # column name in the result DataFrame
        function="sum",         # therismos AggregationFunction value
        field="revenue",        # source field to aggregate
    ),
)

# ── Step 3: get query params, execute, and plot ───────────────────────────────

query_params = strategy.get_query_params()
# query_params["main"].group_fields   == ["region"]
# query_params["main"].aggregations   == [Aggregation(id="total_revenue", ...)]
# query_params["main"].dataframe_schema expresses the expected Polars schema

# Execute query with your data layer; here we build a toy DataFrame directly:
df = pl.DataFrame({
    "region": ["North", "South", "East", "West"],
    "total_revenue": [120.5, 98.3, 145.2, 87.6],
})

theme = Theme(colors={
    "background": HSLColor.from_hex("#ffffff"),
    "primary_color_normal": HSLColor.from_hex("#3b82f6"),
    "secondary_color_normal": HSLColor.from_hex("#f59e0b"),
})

view = strategy.plot(
    dfs={"main": df},
    tr=NullTranslations(),
    theme=theme,
)
view.figure.show()

The Aggregation.function string must be a valid value of therismos.grouping.AggregationFunction (e.g. "count", "sum", "average", "min", "max"). Refer to the therismos documentation for the complete list.