Implementation:Nautechsystems Nautilus trader BacktestDataConfig Init

Field	Value
sources	https://github.com/nautechsystems/nautilus_trader, https://nautilustrader.io/docs/
domains	backtesting, data-management, configuration-management
last_updated	2026-02-10 12:00 GMT

Overview

Concrete tool for declarative backtest data source configuration provided by NautilusTrader.

Description

BacktestDataConfig is a frozen, immutable configuration dataclass that specifies which market data to load from a Parquet-based data catalog for a backtest run. It inherits from NautilusConfig and provides properties that translate the configuration into catalog queries.

The class encapsulates:

Catalog location -- the path to the Parquet data catalog and optional fsspec filesystem protocol and storage options (for S3, GCS, or other remote stores).
Data type resolution -- a string-based data_cls field that is resolved at runtime to the actual data type (e.g., QuoteTick, TradeTick, Bar, OrderBookDelta).
Instrument filtering -- single instrument_id, multiple instrument_ids, or explicit bar_types for bar data.
Time windowing -- start_time and end_time (ISO 8601 strings or UNIX nanoseconds) that bound the data window.
Additional filtering -- a filter_expr string that is parsed into PyArrow filter expressions.
Bar specification -- a bar_spec field for constructing bar type identifiers from instrument IDs.

Key properties:

data_type -- resolves the data_cls string to the actual Python type.
query -- builds a dictionary suitable for catalog querying.
start_time_nanos / end_time_nanos -- converts time boundaries to UNIX nanoseconds.

Usage

Import and instantiate BacktestDataConfig whenever you need to declare a data source for a backtest. Typical scenarios:

Loading quote tick data for a specific instrument from a local catalog.
Loading bar data with a specific bar specification across multiple instruments.
Combining multiple BacktestDataConfig instances to feed different data types into the same backtest run.
Loading data from remote catalogs via S3 or other fsspec-compatible protocols.

Code Reference

Source Location

nautilus_trader/backtest/config.py, lines 174-321.

Signature

class BacktestDataConfig(NautilusConfig, frozen=True):
    catalog_path: str
    data_cls: str
    catalog_fs_protocol: str | None = None
    catalog_fs_storage_options: dict | None = None
    catalog_fs_rust_storage_options: dict | None = None
    instrument_id: InstrumentId | None = None
    start_time: str | int | None = None
    end_time: str | int | None = None
    filter_expr: str | None = None
    client_id: str | None = None
    metadata: dict | Any | None = None
    bar_spec: str | None = None
    instrument_ids: list[str] | None = None
    bar_types: list[str] | None = None
    optimize_file_loading: bool = False

Import

from nautilus_trader.backtest.config import BacktestDataConfig

I/O Contract

Inputs

Parameter	Type	Required	Default	Description
`catalog_path`	`str`	Yes	--	Path to the Parquet data catalog
`data_cls`	`str`	Yes	--	Fully qualified data class name (e.g., "nautilus_trader.model.data:QuoteTick")
`catalog_fs_protocol`	None	No	`None`	fsspec filesystem protocol (e.g., "s3", "file")
`catalog_fs_storage_options`	None	No	`None`	fsspec storage options for Python backend
`catalog_fs_rust_storage_options`	None	No	`None`	fsspec storage options for Rust backend
`instrument_id`	None	No	`None`	Single instrument ID filter
`start_time`	int \| None	No	`None`	Start time (ISO 8601 or UNIX nanoseconds)
`end_time`	int \| None	No	`None`	End time (ISO 8601 or UNIX nanoseconds)
`filter_expr`	None	No	`None`	PyArrow-compatible filter expression string
`client_id`	None	No	`None`	Client ID for data association
`metadata`	Any \| None	No	`None`	Metadata for the catalog query
`bar_spec`	None	No	`None`	Bar specification (e.g., "1-MINUTE-LAST")
`instrument_ids`	None	No	`None`	Multiple instrument IDs (alternative to instrument_id)
`bar_types`	None	No	`None`	Explicit bar type identifiers
`optimize_file_loading`	`bool`	No	`False`	Register directories instead of individual files

Outputs

Output	Type	Description
BacktestDataConfig instance	`BacktestDataConfig`	Frozen, immutable data configuration object. Consumed by `BacktestRunConfig` and processed by `BacktestNode` to load data from catalogs into the backtest engine.
`.data_type` (property)	`type`	The resolved Python data type from the `data_cls` string.
`.query` (property)	`dict[str, Any]`	A dictionary suitable for querying the data catalog.
`.start_time_nanos` (property)	`int`	Start time as UNIX nanoseconds (0 if not set).
`.end_time_nanos` (property)	`int`	End time as UNIX nanoseconds (sys.maxsize if not set).

Usage Examples

Loading quote tick data for a single instrument:

from nautilus_trader.backtest.config import BacktestDataConfig

data_config = BacktestDataConfig(
    catalog_path="/data/catalog",
    data_cls="nautilus_trader.model.data:QuoteTick",
    instrument_id="EUR/USD.SIM",
    start_time="2024-01-01",
    end_time="2024-06-30",
)

Loading bar data with a bar specification:

from nautilus_trader.backtest.config import BacktestDataConfig

data_config = BacktestDataConfig(
    catalog_path="/data/catalog",
    data_cls="nautilus_trader.model.data:Bar",
    instrument_id="AAPL.XNAS",
    bar_spec="1-MINUTE-LAST",
    start_time="2024-01-01",
    end_time="2024-12-31",
)

Loading bar data for multiple instruments:

from nautilus_trader.backtest.config import BacktestDataConfig

data_config = BacktestDataConfig(
    catalog_path="/data/catalog",
    data_cls="nautilus_trader.model.data:Bar",
    instrument_ids=["AAPL.XNAS", "MSFT.XNAS", "GOOGL.XNAS"],
    bar_spec="5-MINUTE-LAST",
    start_time="2024-01-01",
    end_time="2024-12-31",
)

Loading from an S3-based catalog:

from nautilus_trader.backtest.config import BacktestDataConfig

data_config = BacktestDataConfig(
    catalog_path="s3://my-bucket/data/catalog",
    data_cls="nautilus_trader.model.data:TradeTick",
    catalog_fs_protocol="s3",
    catalog_fs_storage_options={
        "key": "AWS_ACCESS_KEY",
        "secret": "AWS_SECRET_KEY",
    },
    instrument_id="BTCUSDT-PERP.BINANCE",
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment