Preparing your data
The exact monthly file contract, hierarchy, regressors, and validation rules for QR Demand Planning.
Required columns
| Column | Description |
|---|---|
| Hierarchy dimensions | One or more columns that identify a DFU, such as family, product, and location. Select these columns in hierarchy order after upload. Values cannot be blank |
| ds | Monthly date. Each value must be parseable and aligned to the first day of a month |
| y | Historical demand. Use a numeric value greater than or equal to zero |
The names ds and y are fixed and case-insensitive. They cannot be selected as hierarchy dimensions. Hierarchy column names must exist in the file and cannot repeat.
The hierarchy values are joined to form the DFU identifier. Avoid / in dimension values because different combinations could otherwise produce the same identifier.
Optional regressors
Every column that is not a hierarchy dimension, ds, or y is treated as a regressor. Examples include promotion, price, or a calendar indicator.
A regressor is classified as:
- known future when it has values in future rows where
yis blank; - past only when it appears only in historical rows.
Use stable column names and consistent values. This delivery does not provide a separate column mapping or ignore-list for extra columns.
File format
- CSV or XLSX
- maximum file size: 100 MB
- one header row with unique, non-blank column names
- monthly data
- one row per DFU and month is recommended
Use YYYY-MM-01 for ds whenever possible. Dates on any day other than the first of the month are rejected. Do not upload daily or weekly data; aggregate it to months before upload.
If the same DFU and month appears more than once, the platform sums the y values and reports a warning. Pre-aggregating makes this behavior easier to review.
Historical and future rows
Historical rows require y >= 0. Negative values and non-numeric values are rejected.
Future rows may leave y blank, but only for months after the latest month that contains historical y. A blank y inside history is invalid. Include future rows when you need to supply known-future regressors such as a planned promotion.
The current contract has no special stockout, return, or missing-history marker. Clean these cases before upload:
- convert returns according to your business rule while keeping final monthly
ynon-negative; - decide whether a stockout month should remain a real observed zero;
- harmonize old and new item codes when their history should remain one DFU.
Do not leave historical y blank to represent any of these conditions.
Example
family,product,location,ds,y,promotion Beverages,Coffee,North,2025-01-01,120,0 Beverages,Coffee,North,2025-02-01,132,1 Beverages,Coffee,North,2025-03-01,,
The final row is a future month: y is blank and promotion is known.
How much history
More complete history generally produces a more useful evaluation. Two to three years of monthly observations is a practical target when yearly seasonality matters, but it is not a file-validation requirement.
The forecast horizon must be shorter than the number of months covered by the historical data. New DFUs without usable history can use a configured client relation or another cold-start method selected by the engine.
Validation
After you select the hierarchy, validation checks:
- required and duplicate headers;
- monthly
dsvalues; - non-blank hierarchy values;
- numeric, non-negative historical
y; - blanks in
yonly after the last historical month; - DFU identifier collisions;
- duplicate DFU-month rows.
Errors block the run. Duplicate rows are warnings because their values are summed. Review the downloadable validation report before configuring the forecast.