terrine

Build datasets directly from event logs.

You have event tables: orders, sessions, payments. You want a modeling table, for example one row per customer per snapshot date, with features computed from the past and labels from the future. Terrine builds that table in your warehouse (DuckDB, PostgreSQL, BigQuery, Snowflake, and more) from a few lines of Python.

Why Terrine?

Most data science datasets come in a few shapes:

• snapshots with features and labels;
• cohort curves;
• time-to-event tables;
• before-and-after windows around an event.

Each time, the SQL is the same pile of date joins and window boundaries, rewritten by hand. Terrine takes the shape as a starting point. You name the rows you want and the windows to aggregate over; Terrine writes and runs the queries.

Because Terrine knows each row's snapshot time, features can only look backwards and targets only forwards. Each value also says whether its window was fully covered by your data, so you decide how to treat gaps for your problem.

Example: a customer spend forecasting table

Requires Python 3.13 or 3.14.

pip install --pre "terrine[duckdb,pandas]"

import ibis
import pandas as pd
import terrine as tr

customers = pd.DataFrame({"customer_id": ["alice", "bob", "carol"]})
orders = pd.DataFrame({
    "customer_id": ["alice", "alice", "alice", "alice", "bob"],
    "ordered_at": pd.to_datetime(
        ["2025-01-03", "2025-01-20", "2025-02-10", "2025-03-05", "2025-01-05"]
    ),
    "amount": [30.0, 45.0, 25.0, 60.0, 80.0],
})

con = ibis.duckdb.connect()  # or your warehouse: ibis.bigquery.connect(...), ...
con.create_table("customers", customers)
con.create_table("orders", orders)

# Tell Terrine who the rows are about and which dates the orders table covers.
model = tr.Model.from_tables(
    con,
    units={"customer": tr.UnitSource("customers", "customer_id")},
    events={"orders": tr.Events(
        "orders", "ordered_at", {"customer": "customer_id"},
        values=("amount",), complete=("2025-01-01", "2025-03-20"),
    )},
)

# One row per customer every 28 days: the last 30 days as features,
# spend in the next 30 days as the target.
design = tr.recipes.time_series(
    "customer", every="28d", start="2025-02-01", end="2025-03-02",
    features={
        "orders_30d": tr.agg("orders_count", window=("-30d", "0s")),
        "spend_30d": tr.agg("orders_amount_sum", window=("-30d", "0s")),
    },
    outcomes={
        "spend_next_30d": tr.agg("orders_amount_sum", window=("0s", "30d")),
    },
)

data = design.build(model).to_pandas()
columns = ["unit", "t0", "orders_30d", "spend_30d", "spend_next_30d", "spend_next_30d__reason"]
print(data[columns].assign(t0=data["t0"].dt.date).sort_values(["t0", "unit"]).to_string(index=False))

 unit         t0  orders_30d  spend_30d  spend_next_30d spend_next_30d__reason
alice 2025-02-01           2       75.0            25.0                   <NA>
  bob 2025-02-01           1       80.0             0.0                   <NA>
carol 2025-02-01           0        0.0             0.0                   <NA>
alice 2025-03-01           1       25.0            <NA>    incomplete_coverage
  bob 2025-03-01           0        0.0            <NA>    incomplete_coverage
carol 2025-03-01           0        0.0            <NA>    incomplete_coverage

(Only some columns are printed; t0 is shown as a date.)

Reading the output:

• Carol has no orders. She still has a row at each snapshot, with zero counts.
• Alice's February 10 order is in her February 1 target and her March 1 features. The same order is the future for one row and the past for the next.
• The March targets are unknown. Their 30-day window runs past March 20, where the orders data ends. Drop them, keep them for scoring, or handle them however suits your model.

Terrine names metrics after your table and columns: orders_count, orders_amount_sum and orders_amount_mean. Every value has a <name>__complete flag and a <name>__reason column, so you can filter or impute deliberately.

The four ideas

Other datasets

tr.recipes covers the usual shapes. Each one returns a normal Design you can edit.

More feature recipes are in common feature patterns: recency, "active in the last N days" filters, attributes as of t0, conversions after a purchase, and true/false labels.

Where it runs

Queries run where your data lives; nothing is uploaded. Results come back as pandas, Polars or Arrow.

See backend compatibility for extras and details.

Learn more

• Your first dataset: this example step by step, with output limits and saved datasets.
• Training and scoring sets: reproducible train/score tables and saved definitions.
• Library hand-offs: pass datasets to modeling libraries. Terrine builds data and makes no causal claims.
• All guides, limitations and error codes.

Contributing? See CONTRIBUTING.md.

License

Apache License 2.0; see NOTICE.