Implementation:Nautechsystems Nautilus trader BacktestEngine Add Data
| Field | Value |
|---|---|
| sources | https://github.com/nautechsystems/nautilus_trader , https://nautilustrader.io/docs/ |
| domains | backtesting, data management, event streaming |
| last_updated | 2026-02-10 12:00 GMT |
Overview
Concrete tool for injecting historical market data into the backtest engine's internal event stream provided by NautilusTrader.
Description
The add_data method on BacktestEngine accepts a list of Data objects (trade ticks, quote ticks, bars, order book deltas, custom data) and appends them to the engine's internal data list. It optionally validates that the data's instrument is registered in the cache, sorts the merged stream by ts_init, syncs the sorted data to the internal BacktestDataIterator, and registers subscription names. For large datasets, sorting can be deferred by passing sort=False and calling sort_data() once after all data has been added.
Usage
Call engine.add_data(data) after registering instruments. Call it once per data stream (e.g., once for trade ticks, once for bars). For optimal performance with multiple streams, use sort=False on all calls and finalize with engine.sort_data().
Code Reference
- Source location:
nautilus_trader/backtest/engine.pyx, lines 771--910 - Signature:
def add_data(
self,
data: list[Data],
client_id: ClientId | None = None,
validate: bool = True,
sort: bool = True,
) -> None
- Import:
from nautilus_trader.backtest.engine import BacktestEngine
from nautilus_trader.model.data import TradeTick, QuoteTick, Bar
I/O Contract
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
data |
list[Data] |
Yes | Non-empty list of data objects. All elements should be the same type. Cannot be PyO3 Rust data types (not yet supported). |
client_id |
None | No | Required only for custom data that does not carry an instrument_id.
|
validate |
bool |
No | Whether to validate that the instrument is in the cache and the data type is consistent. Default True.
|
sort |
bool |
No | Whether to sort the entire data stream by ts_init after appending. Default True. Set to False for deferred sorting.
|
Outputs / Side Effects:
| Output | Type | Description |
|---|---|---|
| None (return) | None |
Method mutates engine state in place. |
| Data stream | side effect | Data is appended to engine._data and (if sorted) synced to the internal BacktestDataIterator.
|
| Subscription names | side effect | Data type + instrument ID combinations are registered as backtest subscriptions. |
| Sorted flag | side effect | engine._sorted is set to True if sort was performed, False otherwise.
|
Raises:
| Exception | Condition |
|---|---|
ValueError |
data is empty, contains non-Data types, or references an unregistered instrument.
|
TypeError |
Data is a Rust PyO3 data type (not yet supported for direct engine addition). |
Usage Examples
Adding trade tick data with default sorting:
from nautilus_trader.persistence.wranglers import TradeTickDataWrangler
wrangler = TradeTickDataWrangler(instrument)
ticks = wrangler.process(df)
engine.add_data(ticks)
Adding multiple data streams with deferred sorting for performance:
engine.add_data(ticks_instrument_1, sort=False)
engine.add_data(ticks_instrument_2, sort=False)
engine.add_data(bars_instrument_3, sort=False)
# Sort once after all data has been added
engine.sort_data()
Adding custom data with explicit client ID:
from nautilus_trader.model.identifiers import ClientId
engine.add_data(
custom_data_list,
client_id=ClientId("CUSTOM_FEED"),
validate=True,
)