#03-查询接口

数据库对上提供的查询能力总览。站点内分析文档（中间段、终点段）与其他三类智能体（推演、回测、执行）通过这些接口获取数据，不直接写 SQL，保证查询逻辑统一、可维护。

#设计原则

1. Python 封装优先：常用查询封装为函数，返回 pandas DataFrame，分析文档直接调用
2. SQL 模板可复用：复杂查询提供 SQL 模板，便于在 SQLite 客户端直接执行验证
3. 数据质量过滤：所有查询默认过滤 data_quality IN ('ok', 'manual_fixed')，避免异常数据污染分析
4. 标的不硬编码：查询函数接受 code 参数，不内置标的列表，保持通用性

#接口分类

#快速使用

#Python 调用示例

import sys
sys.path.insert(0, "03-仿真库/01-数据库/02-采集脚本")

from db import get_connection
from query_utils import get_index_valuation_percentile

conn = get_connection()
df = get_index_valuation_percentile(conn, "000300", years=10)
print(df.tail())

#SQL 直接执行

在 SQLite 客户端打开 03-仿真库/01-数据库/04-共享资源/trend_invest.db，复制各接口文档中的 SQL 模板执行。

#站点内引用

分析文档中引用数据时，注明数据来源与时间：

> 数据来源：本地数据库 `trend_invest.db`，截至 2026-07-14。
> 沪深300 当前 PE 分位 35.2%，处于历史中低区域。

#数据新鲜度

查询前建议检查数据新鲜度：

from db import get_connection

conn = get_connection()
for table in ["index_daily", "fund_daily", "stock_daily"]:
    row = conn.execute(
        f"SELECT MAX(trade_date) AS latest FROM {table}"
    ).fetchone()
    print(f"{table}: 最新日期 {row['latest']}")

如果最新日期明显滞后（如日级数据超过 3 天），先运行 update_all.py 更新数据，再进行分析。

#性能注意

• SQLite 读性能优秀，单次查询通常 <100ms
• 全表扫描避免：所有查询都走主键或索引
• 大范围历史数据查询（如 10 年日线）建议加 trade_date >= ? 限制
• 交叉关联查询（如基金持仓反向查股票）注意 JOIN 的表大小

#延伸阅读

• 数据库--本模块的所属层级与职责边界
• 方案设计--数据库选型与表结构设计