Freqtrade list-data 命令实战：全面盘点本地 OHLCV 与成交数据的时间跨度

本文聚焦 Freqtrade 的 list-data 子命令，它是数据管理工具链（download-data、convert-data 等）中的"查看器"，用于快速盘点本地已下载的历史 K 线（OHLCV）或逐笔成交（trades）数据覆盖了哪些交易对、时间框架、数据类型与时间范围。读完后，你将掌握其全部命令行参数的用法与默认值、理解其底层如何基于数据处理器（DataHandler）扫描数据目录并解析文件名、以及如何用 --show-timerange 精确核对数据缺口——这些能力在回测前确认数据完整性、跨交易所迁移数据时校验文件命名，都是日常高频操作。

命令定位：数据工作流中的"盘点器"

list-data 在 docs/commands/main.md 的命令总览中归入数据管理子命令，其文档片段通过 include 机制嵌入 docs/data-download.md 的 "Sub-command list-data" 小节。它不连接交易所（运行模式为 UTIL_NO_EXCHANGE，即纯本地读盘），因此执行很快、无 API 负担，适合在任何机器上随时核对数据资产。

入口函数是 start_list_data，它在 arguments.py 中注册了 ARGS_LIST_DATA 选项组：

ARGS_LIST_DATA = [
    "exchange",
    "dataformat_ohlcv",
    "dataformat_trades",
    "trades",
    "pairs",
    "trading_mode",
    "show_timerange",
]

完整参数解析

下面是 freqtrade list-data --help 的完整参数清单（源自 docs/commands/list-data.md）：

usage: freqtrade list-data [-h] [-v] [--no-color] [--logfile FILE] [-V]
                           [-c PATH] [-d PATH] [--userdir PATH]
                           [--exchange EXCHANGE]
                           [--data-format-ohlcv {json,jsongz,feather,parquet}]
                           [--data-format-trades {json,jsongz,feather,parquet}]
                           [--trades] [-p PAIRS [PAIRS ...]]
                           [--trading-mode {spot,margin,futures}]
                           [--show-timerange]

options:
  -h, --help            show this help message and exit
  --exchange EXCHANGE   Exchange name. Only valid if no config is provided.
  --data-format-ohlcv {json,jsongz,feather,parquet}
                        Storage format for downloaded candle (OHLCV) data.
                        (default: `feather`).
  --data-format-trades {json,jsongz,feather,parquet}
                        Storage format for downloaded trades data. (default:
                        `feather`).
  --trades              Work on trades data instead of OHLCV data.
  -p, --pairs PAIRS [PAIRS ...]
                        Limit command to these pairs. Pairs are space-
                        separated.
  --trading-mode, --tradingmode {spot,margin,futures}
                        Select Trading mode
  --show-timerange      Show timerange available for available data. (May take
                        a while to calculate).

Common arguments:
  -v, --verbose         Verbose mode (-vv for more, -vvv to get all messages).
  --no-color            Disable colorization of hyperopt results. May be
                        useful if you are redirecting output to a file.
  --logfile, --log-file FILE
                        Log to the file specified. Special values are:
                        'syslog', 'journald'. See the documentation for more
                        details.
  -V, --version         show program's version number and exit
  -c, --config PATH     Specify configuration file (default:
                        `userdir/config.json` or `config.json` whichever
                        exists). Multiple --config options may be used. Can be
                        set to `-` to read config from stdin.
  -d, --datadir, --data-dir PATH
                        Path to the base directory of the exchange with
                        historical backtesting data. To see futures data, use
                        trading-mode additionally.
  --userdir, --user-data-dir PATH
                        Path to userdata directory.

逐项说明如下：

参数	取值/默认值	作用
--exchange EXCHANGE	字符串，默认取配置	指定交易所名，用于拼接数据目录 user_data/data/<exchange>/。仅在不提供配置文件时有效（源码见 cli_options.py 的 exchange 选项定义）。
--data-format-ohlcv	json / jsongz / feather / parquet，默认 feather	指定 K 线数据的存储格式，决定处理器按哪种文件扩展名扫描目录。
--data-format-trades	同上，默认 feather	指定成交数据的存储格式。
--trades	布尔开关	改为盘点 trades（逐笔成交）数据而非 OHLCV 数据。
-p, --pairs	空格分隔的交易对列表	将结果限制到指定交易对；支持通配符展开。
--trading-mode	spot / margin / futures，默认 spot	选择交易模式。查看期货数据时必须额外使用此参数。
--show-timerange	布尔开关	显示每个数据文件的时间范围（起始/结束时间、K 线数），计算量较大，耗时较长。

数据格式选项如何落到数据处理器

--data-format-ohlcv 与 --data-format-trades 在配置中被记录为 dataformat_ohlcv / dataformat_trades（见 configuration.py 中打印 "Using ... to store OHLCV data" 的位置）。随后 start_list_data 通过 get_datahandler 依格式实例化对应的 IDataHandler 子类：json / jsongz 映射到 jsondatahandler.py，feather 映射到 featherdatahandler.py，parquet 映射到 parquetdatahandler.py。值得注意的是，旧的 hdf5 格式在 idatahandler.py 中已显式抛错废弃，并建议迁移到 feather。

docs/data-download.md 中还给出了一组同数据量下各格式的体积/读取耗时对比（BTC/USDT 1m spot，约 470 万根 K 线）：feather 约 115 MB / 1.6s，json 约 265 MB / 17.1s，jsongz 约 83 MB / 23.6s，parquet 约 149 MB / 2.5s，官方推荐默认的 feather 作为性能与体积的最优折中。

两种运行模式：快速盘点与时间范围核查

start_list_data 的核心逻辑分两支：

if args["trades"]:
    start_list_trades_data(args)
    return

config = setup_utils_configuration(args, RunMode.UTIL_NO_EXCHANGE)
dhc = get_datahandler(config["datadir"], config["dataformat_ohlcv"])
paircombs = dhc.ohlcv_get_available_data(
    config["datadir"], config.get("trading_mode", TradingMode.SPOT)
)

（源码见 data_commands.py。）

默认模式：交易对 × 时间框架组合表

不加 --show-timerange 时，命令按 (pair, timeframe, candle_type) 三元组去重、按交易对和时间框架分钟数排序，并将同一交易对的多个时间框架合并到一行，输出 Pair / Timeframe / Type 三列的富文本表格。示例输出（源自 docs/data-download.md）：

freqtrade list-data --userdir ~/.freqtrade/user_data/

             Found 33 pair / timeframe combinations.
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┓
┃          Pair ┃                                 Timeframe ┃ Type ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━┩
│       ADA/BTC │     5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h, 1d │ spot │
│       ADA/ETH │     5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h, 1d │ spot │
│       ETH/BTC │     5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h, 1d │ spot │
│      ETH/USDT │                  5m, 15m, 30m, 1h, 2h, 4h │ spot │
└───────────────┴───────────────────────────────────────────┴───────┘

其中 "Type" 列的 spot 即 K 线类型（CandleType），期货数据会显示 futures、funding_rate、mark 等，见 candle_columns.py 与 enums/candletype.py。

--show-timerange 模式：逐文件的时间范围核查

开启 --show-timerange 后，命令对每个 (pair, timeframe, candle_type) 组合调用 ohlcv_data_min_max——该方法真正加载 DataFrame，读取首行与末行的 date 列，返回 (start, end, length) 三元组——因此会输出完整的 Pair / Timeframe / Type / From / To / Candles 六列表格：

# 以各数据格式计时
time freqtrade list-data --show-timerange --data-format-ohlcv feather

Found 6 pair / timeframe combinations.
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃     Pair ┃ Timeframe ┃ Type ┃                From ┃                  To ┃ Candles ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ BTC/USDT │        1m │ spot │ 2017-08-17 04:00:00 │ 2026-07-15 04:42:00 │ 4677171 │
│ BTC/USDT │        5m │ spot │ 2017-08-17 04:00:00 │ 2026-07-15 04:35:00 │  935445 │
│ ETH/USDT │        1m │ spot │ 2017-08-17 04:00:00 │ 2026-07-15 04:43:00 │ 4677172 │
│ ETH/USDT │        5m │ spot │ 2017-08-17 04:00:00 │ 2026-07-15 04:35:00 │  935445 │
│ XRP/USDT │        1m │ spot │ 2018-05-04 08:11:00 │ 2026-07-15 04:44:00 │ 4305252 │
│ XRP/USDT │        5m │ spot │ 2018-05-04 08:10:00 │ 2026-07-15 04:40:00 │  861055 │
└──────────┴───────────┴──────┴─────────────────────┴─────────────────────┴─────────┘

这正是回测前核查数据缺口（数据起点晚于预期、终点早于当前时间）最可靠的手段。若某行 Candles 为 0、From/To 均为 1970-01-01，说明对应文件实际为空——这正是 ohlcv_data_min_max 在空 DataFrame 时返回 Unix 纪元时间的行为（idatahandler.py）。

trades 数据盘点：--trades 开关

加 --trades 后命令转入 start_list_trades_data，改为用 trades_get_available_data 扫描 *-trades.<ext> 文件，按对输出。不带 --show-timerange 时列出 Pair / Type 两列；开启后逐对调用 trades_data_min_max（将毫秒级 timestamp 转为 UTC 时间），输出 Pair / Type / From / To / Trades 五列表格：

freqtrade list-data --trades --show-timerange

Found trades data for 1 pair.
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃    Pair ┃ Type ┃                From ┃                  To ┃ Trades ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ XRP/ETH │ spot │ 2019-10-11 00:00:11 │ 2019-10-13 11:19:28 │  12477 │
└─────────┴──────┴─────────────────────┴─────────────────────┴────────┘

注意 trades 数据没有"时间框架"维度——逐笔成交文件按对存储（文件名形如 XRP_ETH-trades.feather），时间框架是在 trades-to-ohlcv 阶段才生成的。

底层原理：文件名即索引

理解 list-data 的关键在于：它不打开任何数据文件（默认模式），仅靠文件名正则解析出 (pair, timeframe, candle_type)。

odatahandler 的扫描逻辑 定义了两条正则：

_OHLCV_REGEX = re.compile(r"^([\w-]+)\-(\d+[a-zA-Z]{1,2})\-?([a-zA-Z_]*)?(?=\.)")
_TRADES_REGEX = re.compile(r"^([\w-]+)\-(trades)?(?=\.)")

• ohlcv_get_available_data 用 _OHLCV_REGEX 匹配 {pair}-{timeframe}-{candle_type}.{ext} 命名的文件（idatahandler.py）；
• 若 trading_mode == FUTURES，扫描目录会先 joinpath("futures")——这与 docs/commands/list-data.md 中 --datadir 的帮助文本 "To see futures data, use trading-mode additionally" 完全对应：期货 K 线文件（含 futures、funding_rate、mark 类型）存放在 user_data/data/<exchange>/futures/ 子目录（见 _pair_data_filename 中 candle_type != CandleType.SPOT 时追加 futures 目录的分支）。

文件名中的 _ 由 rebuild_pair_from_filename 还原：第一个 _ 恢复为 /，第二个恢复为 :（期货标记语法），例如 BTC_USDT_USDT → BTC/USDT:USDT；而 rebuild_timeframe_from_filename 会把磁盘上的 1Mo（月度时间框架，避免大小写不敏感文件系统冲突）还原为 1M。

-p/--pairs 过滤与通配符

--pairs 的过滤调用 expand_pairlist 对本地已有数据做子串/通配符展开（keep_invalid=True 表示未匹配的输入不会报错，只是不出现）：

pl = expand_pairlist(args["pairs"], [p[0] for p in paircombs], keep_invalid=True)
paircombs = [comb for comb in paircombs if comb[0] in pl]

因此 freqtrade list-data -p "BTC/USDT*" 或 -p ETH 都能快速定位相关数据；若指定了不存在的对，结果只会少一行而不会抛错。

典型使用场景与命令组合

结合 docs/data-download.md 的上下文，list-data 的典型用法包括：

1. 回测前数据核查：确认 pairs_whitelist 中每个对都有策略 timeframe 对应的数据，且时间范围覆盖 timerange。

   freqtrade list-data --show-timerange -p BTC/USDT ETH/USDT
   

2. 期货数据盘点（必须加 --trading-mode futures）：

   freqtrade list-data --trading-mode futures --show-timerange
   

   不指定该参数时，命令只会列出现货目录下的文件，futures/ 子目录中的期货、资金费率、标记价格文件会被完全忽略。

3. 校验数据格式转换结果：用 convert-data 把 json 转成 feather 后，可用不同 --data-format-ohlcv 复核两侧文件清单一致（hdf5 已废弃，docs/deprecated.md 中也建议用 list-data 验证转换）。

4. 核对逐笔成交数据（用于 trades-to-ohlcv 之前）：

   freqtrade list-data --trades --show-timerange --data-format-trades feather
   

5. 机器可读脚本化：配合 --no-color 将输出重定向到文件，--logfile 可写 syslog/journald，-v/-vv/-vvv 逐级提高日志详细度。

实现与测试佐证

• 命令入口与两种输出形态（组合表 / 时间范围表）：start_list_data、start_list_trades_data；
• 子命令注册（list-data → start_list_data，选项组 ARGS_LIST_DATA）：arguments.py；
• 文件名正则、min/max 统计、futures 子目录处理：idatahandler.py；
• 单元测试覆盖默认列表、--pairs 过滤、--show-timerange、--trades 与期货模式等分支，位于 tests/commands/test_commands.py（test_start_list_data 系列用例）。

小结

list-data 是 Freqtrade 数据管理链中成本最低的数据审计工具：默认模式仅凭文件名正则即可完成全量组合盘点，--show-timerange 则按需加载数据给出精确的时间边界。掌握 --trades、--trading-mode、--pairs 与 --data-format-ohlcv/--data-format-trades 的组合，即可覆盖现货/期货、K 线/成交、多格式数据目录下的绝大多数"我到底有哪些数据、缺了哪段"的核对需求。