使用参数化DateFrom/DateTo时sp_report(QODBC)仅返回首个日期的问题

问题背景 #

QuickBooks的sp_report存储过程要求日期格式为{d'yyyy-mm-dd'}，此前采用f-string拼接的代码已稳定运行三年：

from datetime import datetime
import pandas as pd

start_iso = datetime(2026, 5, 1).date().isoformat()
end_iso = datetime(2026, 5, 31).date().isoformat()

sql_prod = f"""
sp_report
    ProfitAndLossStandard
show
    "AccountNumber",
    "Text",
    "Label",
    "RowType",
    "Amount"
parameters
    DateFrom={{d'{start_iso}'}},
    DateTo={{d'{end_iso}'}},
    ReportBasis='Accrual',
    SummarizeColumnsBy='Day',
    ReturnRows='All'
"""

cursor.execute(sql_prod)
df2 = pd.DataFrame.from_records(cursor)

本月改用参数化查询后出现异常，仅返回首个日期对应的数据，参数化代码如下：

import textwrap
import pandas as pd

sql_prod = textwrap.dedent("""
    sp_report
        ProfitAndLossStandard
    show
        "AccountNumber",
        "Text",
        "Label",
        "RowType",
        "Amount"
    parameters
        DateFrom=?,
        DateTo=?,
        ReportBasis='Accrual',
        SummarizeColumnsBy='Day',
        ReturnRows='All'
""")

cursor.execute(sql_prod, (START, END))
df1 = pd.DataFrame.from_records(cursor)

已在两台不同环境的相同Git提交版本中测试：

• 环境1：Windows 11、QuickBooks Enterprise 24.0、QODBC R/W 24.0.0.360、Python 3.11.8、pyodbc 5.0.1
• 环境2：Windows 11、QuickBooks Enterprise 24.0、QODBC R/W 23.0.0.2023、Python 3.14.3、pyodbc 5.3.0

目前临时采用字符串拼接方式替代，以下是针对pyodbc、QODBC、qbxml三个组件的具体排查方法：

各组件排查方法 #

1. pyodbc排查 #

• 验证参数传递格式：执行查询前开启pyodbc调试日志（设置pyodbc.pooling = False，并在连接字符串中添加driver={QODBC Driver};LogPath=C:\\qodbc_logs;LogLevel=7;），查看实际传递给驱动的参数格式是否符合{d'yyyy-mm-dd'}要求。
• 版本回退测试：将环境2中的pyodbc降级至环境1的5.0.1版本，测试参数化查询是否恢复正常，确认是否为新版本参数处理逻辑变化导致问题。
• 检查参数类型映射：打印START、END变量的类型，确认是datetime.date还是datetime.datetime；尝试将参数转换为{d'yyyy-mm-dd'}格式的字符串后传入，测试是否能返回完整数据。

2. QODBC排查 #

• 版本差异对比：对比两台环境的运行结果，若环境1正常、环境2异常，重点排查QODBC 24.0版本的参数解析逻辑变化。
• 查看驱动日志：在QODBC管理器中开启最高级别日志，检查参数化查询中DateFrom和DateTo的解析过程，确认是否存在参数丢失或格式转换错误。
• 原生工具测试：使用QODBC自带的Query Builder工具执行参数化sp_report查询，验证是否能返回全日期范围数据，排除Python代码层面问题。

3. qbxml排查 #

• 捕获请求对比：通过QODBC日志或本地抓包工具捕获参数化查询对应的qbxml请求，与f-string拼接方式生成的请求对比，检查日期参数格式、请求结构的差异。
• 验证规范匹配：查阅QuickBooks最新qbxml文档，确认ProfitAndLossStandard报告的日期参数是否有格式或传递方式更新，检查参数化查询生成的qbxml是否符合规范。
• 手动构造请求测试：手动编写符合规范的qbxml请求，通过QODBC发送至QuickBooks，验证是否能正常返回数据，确认是否为参数化查询生成的qbxml不符合要求导致异常。

内容的提问来源于stack exchange，提问作者xtian