Features & Limits

FinanceDatabase 边界与配合:它不提供什么,拿到代码之后接什么

FinanceDatabase 以简洁 API 提供证券代码与元数据查询能力:全量取数、select 筛选、search 搜索,均返回 pandas DataFrame。这一页的重点不是再讲一遍功能,而是把「它能做什么、明确不做什么、许可怎么看、配什么用」摊开讲清楚,方便你在动手前判断该不该用它。建议的阅读顺序是:先看功能与不适用场景,再看许可与限制,最后用决策表选定路线。

show:展示select:筛选search:搜索
证券元数据查询代码/名称/国家/行业
条件筛选按国家/行业/市值
API 手册select / search / show_options
不提供行情价格需另接数据源
FinanceDatabase 功能特性与边界示意(证券元数据查询,不提供行情价格),基于官方 README 与仓库说明。

事实核验卡(核验日期 2026-09-29)

FinanceDatabase 版本
2.4.0(PyPI 与 GitHub Release,2026-06-02 发布)
Python 版本
3.11.9(本站实测);包要求 ≥3.10, <3.16
数据库快照
GitHub main 分支 compression/*.bz2(main 最后提交 2026-09-27)
核验日期
2026-09-29
Equities 行数
112,718 行 × 21 列
ETF 行数
36,481 行 × 9 列
数据来源
raw.githubusercontent.com/JerBouma/FinanceDatabase/main/compression/
最后验证时间
2026-09-29(本机 venv 实跑,输出已归档)

以上数字来自本站 2026-09-29 在 Windows + Python 3.11.9 + financedatabase 2.4.0 下的真实运行输出,不是从文章里转抄的;数据文件由上游持续更新,行数会变,以官方 PyPI 与 GitHub Release 为准。采集时 GitHub star 约 9,374(2026-09-29)。

Features

功能清单:每项能力到底能拿到什么?

官方 README 声明的主要能力,这里补上「什么时候用得上」与「容易误判的地方」两列。FinanceDatabase 的能力都集中在「把证券找出来」这件事上。

能力具体表现适用场景注意点
证券展示无参数的 select() 一次性获取某类证券的完整列表先摸清某一类证券有多少、都有哪些字段返回的是清单,不是行情;数据量较大时注意内存与打印截断
条件筛选select()按国家 / 行业 / 板块 / 市值筛出子集搭建候选池、按市场或行业分箱条件值要按官方取值口径写,写错通常返回空表而不是报错
名称搜索search() 按名称模糊查找证券只记得中文简称或英文名,不确定代码模糊匹配会给出多个候选,需自己确认哪一个才是目标标的
七类证券覆盖股票 / ETF / 基金 / 指数 / 货币 / 加密货币 / 货币市场分别有查询入口跨资产类别找标的同一标的可能在不同类别下以不同代码出现,跨类比较前先去重
DataFrame 返回查询结果统一以 pandas DataFrame 返回直接接入后续清洗、落库、导出流程列名与索引要自己核对,别默认首列就是代码
元数据字段名称 / 代码 / 国家 / 行业 / 板块 / 市值 / 货币等给数据管道补上标的维表字段由上游数据源提供,可能存在空值与滞后
可导出可复用DataFrame 可直接存成 CSV 或写入数据库把证券清单固化下来做可复现研究导出的快照会过时,定期重跑比长期沿用旧文件可靠
一句话定位:FinanceDatabase 解决的是「有哪些证券、分别叫什么、属于哪个市场与行业」,不解决「它现在多少钱、涨跌多少」。判断标准很简单:如果你的问题能用「列一份清单」来回答,它就在范围内;如果需要「算出某个随时间变化的数」,就已经超出范围了。先把定位分清,后面的选型判断会简单很多。另外有个容易忽略的点:清单类需求对时效的要求通常低于行情类需求,这决定了它的更新频率不必和行情一样高,但也不意味着可以下载一次用到底。
Capabilities

select / search / show_options 分别负责什么?

select / search / show_options 三类方法各司其职,分清职责就不会在错误的函数上反复试参数。

无参数 select():先看全量

Equities、ETFs、Funds、Indices、Currencies、Cryptos、Moneymarkets 七个类 这类入口,一次性把某一类证券的清单取回来。适合初次探索字段结构、确认某一类到底覆盖多少标的,也适合做全量导出。它不做筛选,所以拿到的是最全的集合。

select():按维度收窄

Equities().select() 支持按 country、sector、industry、market_cap 这些维度筛出子集,是把「全量清单」变成「我的候选池」的主要手段。它的输出仍然是清单而非行情,筛选依据来自元数据字段,所以字段本身的滞后会直接传导到筛选结果上。

search():按名称反查

search() 支持按名称模糊搜索,也可以指定在某一类数据库内搜索。它的价值在于「我只记得名字、不知道代码」这一步:先用名称找到候选,再把代码交给后续流程。模糊匹配天然会返回多条结果,需要人工或规则确认目标只有一个。

常见误用:把三类方法当成「越靠后越高级」的替代关系。实际上它们解决的是三种不同问题——想看全量用无参数 select(),想按维度收缩用带参数的 select(),想从名字反查用 search;先确定问题类型,再选函数。如果拿不准该用哪一类方法,先看你要的答案长什么样:一份完整清单、一个符合条件的子集,还是某只标的的代码。
Not for this

这个库明确不做什么:七条不适用场景

官方资料对「不提供行情价格」有明确说明,但很少把「所以你拿它做不了哪些事」逐条写出来。这一节把边界翻到使用场景一侧,避免装完才发现方向不对。FinanceDatabase 的定位是证券清单与元数据,凡是要时间序列或交易能力的需求都不在它的范围内。

你想做的事它能不能做该用什么替代注意点
取某只标的的历史收盘价不能:只提供代码与元数据,不提供价格公开行情接口或商业行情源元数据里的字段不是价格,不要拿市值当价格用
算 MACD、RSI 等技术指标不能:没有时间序列输入行情源自带的指标能力或指标计算库指标必须先有行情,顺序上行情在前
做策略回测不能:不含撮合、手续费、持仓与计费回测框架(另行评估选型)回测框架本身也要自带或外接行情数据
盘中盯盘与实时推送不能:属于静态清单与元数据实时行情接口或推送服务清单更新节奏与行情推送节奏是两件事
做财务报表与基本面分析不直接提供:定位在清单与元数据基本面数据工具(同作者另有 FinanceToolkit 方向)以官方说明与实际返回为准
覆盖全部市场(含 A 股全量)覆盖范围以官方声明为准,A 股并不完整面向国内市场的财经数据接口用之前先用一只你熟悉的标的试查,确认是否覆盖
保证字段始终最新不保证:字段由上游数据源提供以官方更新节奏为准,自行定期重跑市值一类字段可能滞后于实时市场
判断口诀:问题里只要出现「价格」「涨跌」「指标」「回测」「实时」这几个词,就说明这件事不在 FinanceDatabase 的范围内——它负责把标的找齐,后面的数据与计算都要另外接。反过来说,如果你要的是一份「有哪些、叫什么、属于哪里」的清单,它就正好对口。装之前先用这个口诀过一遍,能省掉装完才发现方向不对的返工。如果发现你需要的能力有一半以上都落在「不能做」那一列,那就说明你要找的其实是行情源或研究终端,而不是一个证券数据库。
DataFrame

返回格式:拿到 DataFrame 之后先做什么?

所有查询返回 pandas DataFrame,便于二次分析。下面这张表按「调用 → 返回 → 怎么用」把常见入口串起来,右侧两列是实际使用中较易踩到的点。表里这几行覆盖了从探索到落盘的完整过程,照着走一遍基本能把常见入口都试到。

调用返回典型内容什么时候用它注意点
Equities().select()DataFrame该类全部股票及其元数据探索字段、全量导出行数多,直接打印会被截断,先看 shape 与列名
ETFs().select() 等同族DataFrame对应类别的清单跨类别铺开找标的类别之间的列名不完全一致,合并前先对齐
Equities().select(country=...)DataFrame某国家/地区的股票子集按市场收窄候选池取值口径以官方为准,写错一般返回空表
Equities().select(sector=...)DataFrame某行业/板块的子集做行业分组研究行业名称需与官方字段取值一致
Equities().search(name="Apple")DataFrame名称匹配的候选证券只知道名字、要找代码返回多条候选,需确认目标只有一个
df.to_csv(...)落盘文件清单快照做可复现研究、交付给下游快照会过时,记录采集时间并定期重跑
使用建议:拿到 DataFrame 后按「先看行列、再看索引、最后看字段取值」的顺序过一遍,比直接写筛选逻辑再回头排查要省时间;导出时把采集时间一起写进文件名,避免几个月后分不清哪个快照更新。另外把「取数」和「分析」两步分开写成两个脚本或两个单元格,取数失败时只需重跑前一步,不用把后面的清洗逻辑再走一遍。当返回里有空值时,先分清是「这个字段本身就不提供」还是「上游暂未提供」,两者的处理方式完全不同。
License

许可与商用边界:七个必须先问清的问题

项目以开源许可发布,但「代码许可」和「你在上面拿到的数据能不能二次分发」是两件事。下面这张表只陈述仓库现状与该去核对的地方,具体结论请以仓库 LICENSE 文件与各上游数据源条款为准。FinanceDatabase 的许可信息请优先看仓库里的 LICENSE 原文,而不是任何二手转述。

问题现状该去哪核对注意点
用什么许可发布仓库 README 声明为 MIT 许可仓库根目录的 LICENSE 文件原文以 LICENSE 原文为准,本页不替官方下结论
能不能用于商业项目需按许可原文与你的使用方式判断LICENSE 原文开源许可通常较宽松,但请自行核对,别转述二手结论
要不要保留版权声明按许可原文执行LICENSE 原文保留原始版权与许可声明是通行做法
代码许可能否覆盖数据不能直接推定:数据来自上游源各上游数据源各自的使用条款数据条款往往比代码许可更严,商用前务必单独核对
二次分发证券清单可以吗需同时满足代码许可与上游数据条款上游源条款与 LICENSE 原文把清单打包再分发属于典型需要单独确认的场景
引用出处怎么写建议注明项目名与仓库地址仓库 README 与官方说明学术或对外材料中注明来源更稳妥
用于投资决策合规吗本库只提供清单与元数据,不构成投资建议本站披露与你的合规要求不得用于收益承诺;结果仅供研究
提醒:许可这类问题容易被二手文章带偏。核验顺序建议是:先看仓库 LICENSE 原文,再看各个上游数据源的条款,最后才看别人的解读——顺序反过来,很容易把一个宽松的代码许可误当成「数据也能随便用」。如果要把清单用于对外交付或商业产品,建议在项目里留一份注明许可与数据来源的说明文件,方便后来人复查。另外要知道:开源许可约束的是代码本身的使用方式,它并不同时放宽上游数据源对你的约束。
Limitations

限制与边界:哪些限制真的会影响你?

知道有哪几条限制只算一半,更关键的是判断「这条限制会不会影响我这件事」。下表把每条限制拆成影响面、不受影响的场景与应对方式。

限制具体影响什么时候不影响你应对方式
不提供行情价格无法直接计算收益、波动、指标你只需要一份标的清单或维表拿到代码后另接行情源
字段可能滞后市值一类字段滞后会让筛选结果偏离当下你做的是长期结构分析而非择时记录采集时间,定期重跑并说明口径
覆盖以官方声明为准某些市场(如 A 股)覆盖不完整你的研究集中在其覆盖较好的市场先用熟悉标的试查,确认覆盖后再批量用
上游数据源可达性网络受限时取数可能失败或变慢你已有稳定网络或代理条件把取数步骤与后续分析解耦,失败可重跑
字段存在空值筛选或分组时空值会造成遗漏你使用的是字段齐全的类别先统计缺失情况,再决定是否填补或排除
不是投资建议不能作为买卖依据你把它当作数据准备工具对外输出时明确标注用途与免责
版本与接口会演进旧脚本可能因接口调整而失效你锁定了可用版本升级前预留核验步骤,以官方发布说明为准
依赖 pandas 生态环境里没有 pandas 时无法直接使用你已有 Python 数据环境先把依赖装好再开始,避免中途卡在环境问题上
结论:FinanceDatabase 适合「找证券代码、按条件筛出候选池、按名称反查代码」这类数据准备场景;行情、指标与回测需要另外配数据源与框架补上。把这些限制写进项目的说明文档,比只写在脚本注释里更容易被后来人看到。
Pairing

配合使用:拿到代码之后接什么?

FinanceDatabase 常常只负责链路的上游一段:把标的找出来。下面这张表按「定位 → 拿到什么 → 拿不到什么 → 适合谁」把常见搭配摊开,其中本机技能路线只描述定位与前置条件,不代表与本项目存在集成。选哪一个取决于你的数据范围与是否愿意自己搭环境。

搭配对象定位拿得到什么拿不到什么适合谁
FinanceToolkit(同作者方向)财务与基本面分析工具基本面维度的分析能力具体能力以官方文档为准拿到代码后要接着做基本面研究
yfinance 一类的公开行情接口行情获取历史行情与基础报价覆盖范围与频率以官方说明为准需要快速把代码补成行情序列
面向国内市场的财经数据接口A 股等国内品种取数国内市场数据具体品种与频率以各项目文档为准研究范围在国内市场
本机已核验的金融数据技能路线对话式取数与研究一句话发起数据或研究任务各技能的数据源、账号与覆盖范围不同不想先搭 Python 环境
自建证券清单库 / ETL把清单沉淀为可复现资产本地可控、可版本化的维表需要自己维护更新与校验长期项目、要求结果可复现
研究终端类工具综合研究界面以各自官方文档为准以各自官方文档为准习惯在图形界面里完成研究
本地数据库或表格文件清单的落地层把清单存成可反复查询的表更新与校验仍需自己负责想用 SQL 或表格工具继续加工
说明:以上为常见配合方式的定位对照,具体接入方式、字段口径与前置条件请分别以各项目的官方文档为准;不同工具之间的数据口径不会自动一致,合并前先做一致性核对。实践中的顺序通常是:先用本库把清单定下来,再按清单到各数据源补行情或基本面,这样接口只需按代码对齐,出问题时也容易二分定位到是哪一段。如果行情源与清单的代码口径不一致(比如带后缀或交易所代码不同),先做一次代码映射再合并。
Two routes

自建还是用现成的对话式路线:前置条件对照

同一个目标——拿到一份可用的标的清单,两条路要准备的东西并不一样。下面按前置条件逐项对照,先看你要付出什么,再决定走哪条。FinanceDatabase 自建路线的优势是可控与可复现,代价是要自己维护环境与数据链路。

前置条件自建 FinanceDatabase 路线要准备对话式免部署路线要准备注意点
运行环境Python 环境与 financetoolkit 依赖(实测连带 pandas 3.0 / numpy 2.4)安装客户端后直接提问自建路线需要自己处理依赖冲突
数据范围以该库覆盖范围为准,A 股不完整取决于所用技能的数据源两条路的数据范围都不等于「全市场」
账号与密钥多数情况下不需要额外密钥部分技能需要各自的数据账号或 Key密钥类前置条件以各技能说明为准
结果形态DataFrame / CSV,可进管道对话返回的表格与摘要需要接入代码流水线时,结构化输出更省事
可复现性高:脚本与快照都可存档中:依赖当次提问与账号状态要写进报告或审计的结论,优先选可存档的方式
维护成本需要自己定期重跑与校验更新由所用技能侧负责省下的维护成本换来的是可控性下降
适合的提问方式自己写筛选条件与后处理用自然语言描述任务任务越复杂,越需要先确认数据口径
  1. 先确认数据范围覆盖你的标的

    用一只你熟悉的标的试查,确认它是否在覆盖范围内。python -c "import financedatabase as fd; print(fd.Equities().search(name='Apple').head())" —— 能打印出候选行即说明库可用且覆盖该标的,无输出则先排查覆盖范围与网络。

  2. 再确认字段够不够用

    看你需要的维度(国家、行业、市值等)是否在返回列里,缺失字段会影响后续筛选口径。

  3. 然后确认后续环节由谁承接

    清单之后的行情、指标、回测分别由哪个工具负责,提前定好接口格式,避免中途返工。

  4. 最后按结果用途选路线

    结论要进报告或需要长期复现 → 选自建并可存档的方式;只是快速看一看 → 选对话式路线更省准备时间。

  5. 把清单落盘并记录口径

    导出时在文件名里带上采集时间,并在备注中写明筛选条件与字段口径,方便几天后复查时知道自己当时筛的是什么。

  6. 写清结论的适用范围

    把「覆盖哪些市场、字段截至什么时候、后续行情来自哪里」一并写进结论,避免把一份清单当成完整的数据依据。

边界披露:FinanceDatabase 与 EasyClaw 无已证实集成——项目官方资料未提及本机技能路线,本机技能目录中也没有对应的技能。本页并列介绍的是两条独立路线,各自的前置条件与数据来源不同,请按自己的实际情况判断。
Decision

什么时候该用它、什么时候该换别的?

把常见目标逐条列出来对照,比反复读功能列表更快得出结论。下表左列是你要达成的目标,中间给出更合适的路线方向,右侧两列是判断依据与容易被忽略的地方。表里的路线方向只是更常见的选择,不是硬性规定。

你的目标更合适的路线判断依据注意点
建一份可复现的证券维表用这个库自建清单它专做清单与元数据,结果可导出存档需要自己维护更新节奏与校验流程
只想知道某只标的的代码名称搜索就够了search() 可直接由名称反查模糊匹配会给出多条候选,要确认目标
按国家 / 行业 / 市值圈定候选池条件筛选select()按维度收窄集合条件取值口径以官方为准,写错多为空表
要历史行情做指标或回测行情源加回测框架该库不提供价格与时间序列顺序上先有行情,再谈指标与回测
只想快速看看某个行业有哪些标的对话式免部署路线不必先搭 Python 环境可复现性弱于脚本,适合一次性了解
研究范围主要在国内市场面向国内市场的财经数据接口该库对 A 股的覆盖并不完整先用一只熟悉的标的试查覆盖情况
要长期维护、多人协作的数据资产自建清单库并做版本化落地脚本与快照都能归档,便于交接需要约定更新频率与字段口径,否则口径会分叉
两条路线并不互斥:可以先走对话式路线快速确认「这个方向的数据到底长什么样」,确认之后再写成脚本固化下来;反过来,已经写好脚本的人遇到一次性问题,也不必为了一个临时结论去改代码。真正的风险不是选错路线,而是把一次性判断直接当成长期资产去维护。判断路线时先问一句「这份结果要不要被别人复现」,答案是否定的,通常就不值得为它单独搭一套环境。
Toolchain

工具链接力实测:to_toolkit() 到底做了什么?

本库自己在 helpers.py 里写明了定位——不提供最新的基本面与行情。官方给出的衔接入口是 FinanceFrame.to_toolkit()。下面是 2026-09-29 的真实调用记录。

from financedatabase import FinanceFrame
import financedatabase as fd

equities = fd.Equities()
one = FinanceFrame(equities.data.iloc[[0]])   # 注意:不能用 .head(),那样会丢掉方法
tk = one.to_toolkit(start_date="2024-01-02", end_date="2024-01-05", progress_bar=False)

# 实测终端输出(原样摘录):
# The parameter api_key is not set. Therefore, using Yahoo Finance as the source which
# is limited to 5 years of fundamental data. Consider obtaining a key with the following
# link: https://www.jeroenbouma.com/fmp
# You can get 15% off by using the above affiliate link to get access to 30+ years of
# (quarterly) data which also supports the project.
# 返回类型:Toolkit(耗时 40.1 秒,含联网取数)
实测项结果你要提前知道的事
返回类型Toolkit(FinanceToolkit 对象)后续的比率、报表、技术指标都走 FinanceToolkit 的接口
是否要 API Key不必填,但会打印提示不填 api_key 时回落到 Yahoo Finance,官方提示只有 5 年基本面数据
官方提示里的链接是带 15% 折扣的推广链接该提示文本把商业推广写进了运行日志,介意的话可自行换成别的数据源
耗时单标的 40.1 秒(含联网)批量传入多标的会明显更久,且受上游限流影响
可否先切片再调用不行.head() / 布尔切片返回普通 DataFrame,to_toolkit() 直接 AttributeError
依赖需已装 financetoolkit本库已把它设为直接依赖,因此通常已经具备
边界再强调一次:本库负责「有哪些标的」,to_toolkit() 负责「这些标的的行情与财务长什么样」。两者是两件事、两个上游,任一侧故障都会让整条链路断掉——排查时先分清是哪一侧。
Who does what

按任务挑下游工具:哪一步该交给谁

不要问「哪个工具更好」,要问「这一步该谁做」。下表按任务拆分,并把实测到的失败点写在同一行。

任务FinanceDatabaseyfinanceAKShare / OpenBBFinanceToolkit典型失败点
证券名录与元数据强(30 万+条)弱(按代码查)部分支持弱本库字段缺失率差异大,先跑 isna().mean()
按国家 / 行业 / 市值筛选强不支持依赖各自数据源不支持取值写错会静默返回空表
历史行情不提供支持部分市场支持部分市场支持(含缓存)本库不提供,必须换工具
财报与估值指标不提供有限支持视市场而定强免 key 走 Yahoo 只有 5 年数据
A 股 / 港股代码映射提供后缀代码(.SS/.SZ/.HK)用同一套后缀中国市场更友好依赖行情源各源后缀写法并不完全一致
离线可用性支持(需自行缓存数据文件)不支持部分支持支持缓存本库默认每次都重新下载
回测与策略验证不提供不提供不提供不提供需另接回测框架,注意复权与成本口径
一条完整的建池链路(本站在首页与筛选页分别拆解):分类筛选 → 去重 → 过滤退市 → 核对证券代码 → 接入行情 → 补充基本面 → 加入流动性与估值条件 → 形成可回测标的池。本库只覆盖链路的前四步,后面四步都要换工具,而且换的时候代码口径会变。
FAQ

功能特性与边界常见问题

FinanceDatabase 是行情数据源吗?

不是。它是证券代码与元数据库,官方说明中明确不提供行情价格;历史价格、实时报价一类需求需要另接行情源。以官方 README 与仓库说明为准。

能不能用它筛 A 股?

该库的覆盖范围以官方声明为准,A 股并不完整,直接用国内标的试查最可靠。如果研究范围主要在国内市场,更适合用面向国内市场的财经数据接口;本机已核验的金融数据技能路线里也有覆盖 A 股的技能方向,但与本项目并无集成关系。

DataFrame 能直接导出给别的程序用吗?

可以。查询结果就是 pandas DataFrame,能存成 CSV、写入数据库或直接接进下游管道。建议在导出文件名里带上采集时间,方便区分不同批次的快照。如果下游是数据库,导入前先去重,避免同一标的被重复写入。

为什么它不提供行情价格?

它的定位是「证券清单与元数据」这一层:把标的、代码、市场、行业整理清楚,价格与基本面交由别的工具承接。这样职责单一,也解释了为什么它适合做数据准备的起步环节。

市值这类字段能信到什么程度?

字段来自上游数据源,可能滞后于实时市场;官方并未承诺实时性。用它做筛选时,建议记录采集时间并在结论里说明口径,涉及时效敏感的用途要另行核对。另外不同上游源的统计口径可能不同,跨源比较前先确认字段定义一致。

许可上有什么要注意的?

仓库 README 声明为 MIT 许可,正式使用请以仓库 LICENSE 文件原文为准;同时注意证券清单的数据来自上游数据源,数据条款可能与代码许可不同,商用或再分发前需单独核对上游条款。

下一步怎么走?

边界清楚之后,落地路径通常是先装起来跑通一次查询,再按你要研究的数据范围决定后续接什么;如果不想先搭环境,本机已核验的金融数据技能路线可以作为对照方向。