> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracebloc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Time-series forecasting

> Dataset template for time-series forecasting: one time-ordered CSV with a timestamp column, numeric features and a numeric target, ingest.yaml and the checks the data ingestor runs.

Predict future values from past ones. The dataset is a single CSV where every row is one time step: a `timestamp` column, numeric feature columns and a numeric target. Rows must be in chronological order.

## Folder layout

```text theme={null}
/data/shared/energy-demand/
└── demand.csv
```

## Data CSV

```csv theme={null}
timestamp,day_of_week,month,day_of_month,week_of_year,is_weekend,lag_1,moving_avg_7,value
2023-10-01,7,10,1,40,1,,,125.50
2023-10-02,1,10,2,40,0,125.50,,132.30
2023-10-03,2,10,3,40,0,132.30,,128.75
2023-10-07,6,10,7,40,1,152.40,132.75,148.60
```

| Column                       | Meaning                                                                                                                                                                                                                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`                  | **Fixed name.** One value per row in ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`). Rows must be sorted ascending; every value must parse; every value must be before today. Dates that read differently day-first and month-first (such as `03.04.2026`) are rejected — use ISO 8601. |
| feature columns              | Numeric, declared in `schema`. Empty cells are allowed (stored as NULL) — lag and rolling-window features are typically blank at the start of the series.                                                                                                                                 |
| target column (`value` here) | Numeric; named by `label.column`, not declared in `schema`.                                                                                                                                                                                                                               |

Categorical features (region, segment, ...) must be encoded as integers before ingest: every non-timestamp column in `schema` must be numeric.

## ingest.yaml

```yaml theme={null}
apiVersion: tracebloc.io/v1
kind: IngestConfig
category: time_series_forecasting
table: energy_demand_train
intent: train
csv: /data/shared/energy-demand/demand.csv
schema:
  timestamp: TIMESTAMP     # required; TIMESTAMP, DATETIME or DATE
  day_of_week: INT
  month: INT
  day_of_month: INT
  week_of_year: INT
  is_weekend: INT
  lag_1: FLOAT             # blank on the first row
  moving_avg_7: FLOAT      # blank until 7 rows of history exist
label:
  column: value
  policy: bucket
```

| Field                         | Required             | Meaning                                                                                                                                                           |
| ----------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `csv`                         | yes                  | Path to the data CSV.                                                                                                                                             |
| `schema`                      | **yes**              | Must contain `timestamp` with a calendar type (`TIMESTAMP`, `DATETIME` or `DATE`) plus the numeric feature columns.                                               |
| `label`                       | **yes, object form** | `column` names the target; `policy: bucket` keeps raw targets in your secure environment (the platform receives 64 hash buckets; stored rows keep the raw value). |
| `time_column`                 | leave out            | The time column is always `timestamp`. Any other value is rejected at preflight.                                                                                  |
| `columns`                     | no                   | Per-column `unit` and `ordinal` facts.                                                                                                                            |
| `data_id`, `spec.csv_options` | no                   | See [the contract](/create-use-case/templates#the-ingestyaml-contract).                                                                                           |

## What the ingestor checks

| Check             | Rejects                                                                                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time format       | A `schema` without `timestamp`, or with `timestamp` typed as text or a number; a CSV without a `timestamp` column; unparseable values; day-first/month-first ambiguous dates. |
| Time ordered      | Any pair of consecutive rows whose timestamps decrease.                                                                                                                       |
| Time before today | Any timestamp on or after today's date.                                                                                                                                       |
| Numeric columns   | A non-numeric value in any schema column other than `timestamp`. Empty cells are allowed.                                                                                     |
| Data types        | Duplicate headers, schema columns missing from the CSV, values that do not match their type (checked for every schema column except `timestamp`).                             |

Plus the [checks every ingest runs](/create-use-case/templates#checks-every-ingest-runs). There is no label-diversity check.

## Sample dataset

The template ships 31 daily rows starting 2023-10-01 with calendar features (`day_of_week`, `month`, `day_of_month`, `week_of_year`, `is_weekend` as `INT`), lag and moving-average features (`lag_1`, `moving_avg_7` as `FLOAT`, blank until enough history exists) and the target `value` — the rows shown above are from it. The `ingest.yaml` above ingests it as is; only `csv:` changes to wherever you staged the file.

## Next steps

* Stage the data and run the ingest: [Prepare Data](/create-use-case/prepare-dataset)
* Shared rules for every template: [Dataset templates](/create-use-case/templates)