Make predictions
There are two ways to score with a trained model:
- Send records:
model.predict(rows=...). You pass the data. - Score from your data:
model.predict(). Predictabl reads the data the model was trained on and builds the features itself.
Which one fits depends on the model's kind.
Model kinds
model = pb.model("<model id>")
print(model.kind, "·", model.meaning)
kind |
One prediction is for… | Score with |
|---|---|---|
flat |
One record (a survey answer, a sensor reading, a form) | rows=: send the records |
event |
One row of your data at a point in time (an order, a booking, a customer) | model.predict() with a date window, or rows= |
forecast |
One entity on each future day or week (sales per store, demand per item) | model.predict(), optionally as_of= |
model.meaning says what the number is, for example "probability that customer
churned" or "predicted sales: daily sales for a store". Show it next to the
numbers; a score without it is easy to misread.
Send records
preds = model.predict(rows=[
{"tenure": 2, "Contract": "Month-to-month", "MonthlyCharges": 89.1, ...},
])
rows can be one dict, a list of dicts, or a pandas DataFrame. Use the same
column names as the data the model was trained on. Predictabl applies the
model's own feature SQL to them, so the features are built exactly as in
training. Any number of rows works; the library sends them in batches of 1,000.
Send every column you know. A column you leave out counts as unknown: the
request still works, but the score rests on less information and is less
reliable. If a record has no id column, its entity_id is its position in
your list ("0", "1", …).
A record that still contains its outcome column (a row copied from the training
file, say) scores the same as without it: the outcome never reaches the model.
It comes back as actual, which makes a quick check easy.
If a model summarises history (counts or averages over many rows per
customer), the records you send are the only history it sees.
preds.warning says so; score from your data instead.
Score from your data
Forecast models
preds = model.predict() # from the latest data
preds = model.predict(as_of="2026-10-01") # as if today were 1 October
print(preds.as_of)
preds.as_of is the date the forecast is made from; each prediction's
entity_id reads entity·as_of·step, where step 1 is the first period after
it. Check as_of: if your data stopped updating, it will be in the past.
Event models
By default, model.predict() scores rows dated today. Choose a window:
preds = model.predict(since_days=7) # the last 7 days
preds = model.predict(since="2026-10-01", until="2026-10-31") # October
If nothing matched, preds.note says why and gives the newest date in the data.
Narrow it down
model.predict(ids=["store_12", "store_40"]) # specific entities
model.predict(limit=100) # the 100 highest scores
model.predict(filters=[{"column": "city", "op": "eq", "value": "Milano"}])
model.predict(include=["city", "branch_name"]) # extra columns per prediction
Filters accept eq, ne, in, contains, gt, gte, lt, lte, on the
model's table or a table it joins. Results are sorted highest first, at most
2,000 per call. Filters and include apply to event models.
Read the predictions
model.predict() returns a list of dicts with extra attributes:
preds[0] # {'entity_id': 'C-1042', 'prediction': 0.83, ...}
preds.meaning # what 'prediction' is
preds.kind # flat | event | forecast
preds.as_of # forecasts: the date they are made from
preds.note # why nothing matched, if so
preds.warning # a caveat about how the scores were made, if any
preds.count # how many matched (can exceed len(preds) when limited)
preds.to_pandas()
Each prediction has:
| Key | |
|---|---|
entity_id |
Which customer, order, store… (forecasts add ·as_of·step) |
prediction |
Probability of the outcome (classification) or the value (regression) |
predicted_class, probabilities |
Multiclass models only: the likeliest class and every class's probability |
actual |
The real outcome, when the record you sent contained it |
context |
The columns you asked for with include |
label |
A display name for the entity, when the data has one |
For multiclass models, read predicted_class, not prediction: prediction is
the probability of the likeliest class and does not say which class that is.
Calibrated probabilities
Classification scores rank well but are not always true probabilities. When
scoring from your data, model.predict(calibrated=True) returns probabilities
you can read as "how often this happens", for models that have a calibrator.