> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Shipment Delay Prediction

Predict whether a shipment will arrive late, and how late, so operations can intervene before a delay reaches the customer. This example makes two predictions for each shipment: a yes or no classification of whether it will be delayed, and a numeric estimate of the delay in days. Kumo Engine learns both from each shipment's own details and from the order, customer, and handling history connected to it in the graph.

## Data and relationships

The example assumes a prepared Kumo Engine `graph`, a matching `snapshot`, and these tables:

| Table             | Required columns                                         | Purpose                                                                                                                      |
| ----------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `shipments`       | `shipment_id`, `order_id`, `ship_date`, `delay_duration` | The shipments to score. `delay_duration` records how many days late a past shipment arrived, where `0` means it was on time. |
| `orders`          | `order_id` as the primary key, plus `order_date`         | The order each shipment fulfills, for order context and timing.                                                              |
| `customers`       | `customer_id` as the primary key                         | The customer each order belongs to.                                                                                          |
| `shipment_events` | `event_id`, `shipment_id`, `event_date`, `event_type`    | Handling events recorded for a shipment, such as pickup and transit scans.                                                   |

Connect `shipments.order_id` to `orders.order_id`, `orders.customer_id` to `customers.customer_id`, and `shipment_events.shipment_id` to `shipments.shipment_id`. Mark `ship_date` as the time column of the shipments table and `shipment_id` as its primary key, so each prediction is anchored at the moment the shipment leaves and uses only earlier information. Mark `order_date` and `event_date` as the time columns of their tables. `delay_duration` is the value each query predicts, so it is the label rather than a feature.

## Predict whether a shipment will be delayed

This query classifies each shipment as delayed or on time. The target `shipments.delay_duration > 0` turns the recorded delay into a yes or no label, and `FOR EACH shipments.shipment_id` produces one prediction per shipment. Because the shipments table is anchored at `ship_date`, the model learns from the order, customer, and handling history that exists before the shipment departs.

```python
from kumo.engine import PredictiveQuery

query_text = (
    "PREDICT shipments.delay_duration > 0 "
    "FOR EACH shipments.shipment_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # binary_classification
```

## Predict how long the delay will be

When operations needs to reschedule or reset a delivery estimate, a yes or no answer is not enough. This query predicts the delay itself as a number of days. It uses the same entity and anchor, but the target is the raw `shipments.delay_duration` value, so the task is a regression forecast rather than a classification.

```python
query_text = (
    "PREDICT shipments.delay_duration "
    "FOR EACH shipments.shipment_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # regression
```

## Reading the predictions

The classification query returns a probability that each shipment will be delayed, which lets operations rank shipments by risk and act on the ones most likely to arrive late. The regression query returns an estimated number of days late, which supports concrete choices such as revising a promised delivery date or expediting a carrier. A predicted delay of zero means the model expects the shipment to arrive on time.

Both predictions are estimates from past shipment behavior, not guarantees, and both are anchored at the shipment's departure, so they use only what is known when the shipment leaves. Refresh them as new shipments and handling events arrive so each decision reflects the latest history.