Appearance
常见问题
怎么申请 token？
联系官方客服（邮箱：kefu@zltquant.com）申请。客服会给你两样东西：服务地址（endpoint）和 token，并按你需要的数据范围开通权限。
token 形如 fk_ 开头的一串字符，相当于账号密码，别发到公开仓库或者聊天群里。需要扩大数据范围（比如原来只开了行情，现在还想要财报）同样找客服。
pip 装不上，提示找不到包？
客户端只发布在智量通的官方源，公共 pip 源上没有，安装时必须带 --index-url：
bash
pip install ZltFinOrmClient --index-url https://pypip.zltquant.com/如果是 pip install ZltFinOrmClient[pandas] 这种写法报错，那是因为官方源里只有智量通自己的包，没有 pandas。pandas、numpy 和 mcp 要单独从公共镜像装：
bash
pip install pandas numpy mcp --index-url https://pypi.tuna.tsinghua.edu.cn/simple完整步骤见安装。
报「无该表访问权限」怎么办？
text
AuthError: [AUTH_TABLE_DENIED] 无该表访问权限你的账号没有开通这张表。这不是临时故障，重试没有用，联系客服开通即可。
联表查询要求每一张参与的表都有权限，缺一张就会报这个错。
一共有哪些数据？
15 个数据库、476 张表，覆盖 A股、公募基金、债券、期货、指数、行业与商品、宏观统计、海关进出口、资讯研报。数据范围那页按库列出了每一张表和每一个字段的中文名。
能看到目录不等于能查。目录对所有账号都是完整的，实际能查哪些表取决于开通的授权，这样你可以先看清有什么、再决定要开通哪些。
怎么找到想要的数据？
可以翻数据范围按中文业务名称搜索，也可以让客户端或 AI 根据中文需求查询服务端目录：
python
client.describe("cneqa_bsc_stk_bsc_info") # 这张表有哪些字段表和字段编码是内部标识，不建议手工猜测；上游目录调整时，客户端会以当前目录为准。
查出来是空的，或者数据对不上？
先检查时间范围。start_date 和 end_date 过滤的是表的时间轴字段，当前多数表的时间轴是数据更新时间而不是业务日期。上游重刷一次历史数据，所有记录的更新时间都会变成重刷那天，按年份筛就可能什么都查不到。
要按交易日、公告日这类业务日期筛，用 filter_expr 指定字段：
python
filter_expr={"field": "txn_dt", "op": "between", "value": ["20260101", "20260630"]}该用哪个字段，看 client.query_spec(表名) 返回的 business_date_fields 和 filterable_fields。详见接口参考。
结果被截断了怎么办？
返回里带 truncated=True，说明行数达到上限。默认会打印一条告警并返回已有的部分。缩小时间范围、减少证券数量，或者分批查。
每张表的上限可以在 client.query_spec(表名) 的 constraints.max_rows 里看到。
支持哪些返回格式？
format="json" 返回字典，format="pandas" 返回 DataFrame（需要先装 pandas）， format="npz" 返回 numpy 列式数组（需要先装 numpy）， format="arrow" 返回 Arrow 列式数据（需要先装 pyarrow）。
format="parquet" 还没做，传了会报错。
npz 和 arrow 怎么选？
两条都是列式二进制通道，只有一处语义差异：DECIMAL。
npz 没有 decimal 类型，只能按声明精度降级——15 位以内编成 float64，超过则编成字符串。 库里 58% 的 decimal 列声明精度超过 15 位（成交额、涨跌幅、总资产这些都在内）， 所以这不是边角情况。arrow 用原生 decimal128 原样承载，要不要转 float 由你决定。
其余列类型两者逐一对应。按这个选：
- 纯 Python，后续喂 numba 做数值计算 →
npz，依赖更轻（numpy 通常已经有了） - 要跨语言消费（C++/Rust/CUDA），或不想让高精度列变字符串 →
arrow
详见 npz 格式说明 与 arrow 格式说明。
什么时候该用 npz？
两个条件同时满足才划算：行数上万，而且取回来要自己做数值计算。
npz 的价值不是"取得快"，是"取完直接能算"——它给的是 numpy 数组，可以直接喂给 numba 这类 JIT 编译器，不用先转 DataFrame 再把列掏出来。
反过来说，只是把数据查出来看看、导成 Excel，或者接下来全是 groupby/merge 这类 pandas 操作，那就用 format="pandas"。npz 要多装一个 numpy，还有几处和 json 不同的地方（高精度金额以字符串返回等），不做计算的话这些成本换不回什么。
解析耗时的实测（每行 8 个字段）：
| 行数 | json 解析 | npz 解析 | 传输体积对比 |
|---|---|---|---|
| 1 千 | 1 毫秒 | 0.1 毫秒 | npz 大 10% |
| 1 万 | 9.9 毫秒 | 0.6 毫秒 | 基本持平 |
| 10 万 | 122 毫秒 | 4.3 毫秒 | npz 省 20% |
| 100 万 | 1301 毫秒 | 34 毫秒 | npz 省 21% |
体积最多省两成，一千行以下还是负的——它省的是你这边的 CPU，不是网络流量。
计算环节的差距更明显：60 万行按标的分组算日收益率与 20 日滚动波动率， npz + numba 用 15 毫秒，pandas groupby 用 142 毫秒。
为什么要通过查询参数获取数据？
你通过函数参数表达要查询的主题、时间范围、字段、过滤条件和行数。服务端据此执行权限校验、参数校验和用量控制，并返回结构化结果与明确错误信息。
数据多久更新一次？
行情、财务、股东等数据的更新节奏不同。行情通常随交易日或行情批次更新，财务和股东数据通常在公告披露并完成采集、清洗、同步后更新。查询结果中的业务日期与记录更新时间不是一回事，具体鲜活性应以 query_spec、返回元数据和服务公告为准。
关键词搜表怎么没生效？
client.tables(keyword="财务") 当前版本会返回完整表清单，筛选还没生效。自己在结果里过滤即可：
python
tables = client.tables()["tables"]
hit = [t for t in tables if "财务" in t["table_name"]]或者直接翻数据范围搜中文。
联表最多几张表？
加上主表最多 5 张。连接条件支持多个字段同时对应，写法见示例。
怎么让 AI 助手帮我查数据？
装上配套的 skill 和 MCP：
bash
zltfinorm install-skill
zltfinorm install-mcp --endpoint http://finorm.zltquant.com:7761 --token fk_你的token装完重启 AI 助手，然后用中文提需求就行。详见安装和示例。
MCP 装完 AI 助手里没看到？
改完配置要重启 AI 助手才生效（换 token 也一样）。重启后在 Claude Code 里输 /mcp，应该能看到 finorm。
还是没有的话，在终端直接运行 zltfinorm mcp，它应该安静地等待输入而不是报错退出。如果报错了，错误信息会指出问题所在。最常见的原因是配置里 command 没写完整路径，取路径的办法见安装。