Delphi FireDAC TFDQuery DateTime字段过滤报错排查

问题场景 #

• 开发环境：Delphi + FireDAC，对接SQL Server数据库，核心数据组件为TFDQuery
• 业务逻辑：从cxGrid表格导入已生效的过滤条件到TFDQuery，涉及三类核心字段：
  • DateTime类型Date字段：精度需保留到秒，用于库存、财务核算场景
  • Float类型Value字段：浮点数格式匹配问题已修复
  • String类型Supplier字段：字符串过滤逻辑运行正常
• 原有实现代码：

MyTFDQuery.Filtered := False;
MyTFDQuery.Filter := cxGridDBTableView.DataController.Filter.FilterText;
MyTFDQuery.Filtered := True;

报错记录与排查过程 #

1. 初始启用Date字段过滤时触发第一个报错：

[FireDAC][Stan][Eval]-114. Expected []
该字段未配置任何显示格式或输入掩码，测试过程中覆盖了多种DateTime过滤值写法、日期排列格式、日期分隔符组合均未解决问题，一度怀疑故障与Delphi IDE、FireDAC、数据库端的区域设置相关。
测试过的无效写法示例：

MyTFDQuery.Filter := 'Date = ''2021-01-01 10:00:00'''
MyTFDQuery.Filter := 'Date = {dt 2021-01-01 10:00:00}'
MyTFDQuery.Filter := 'Date = ' + Chr(39) + '2021-01-01 10:00:00' + Chr(39)
MyTFDQuery.Filter := 'Date = {CONVERT(''2021-01-01 10:00:00'', DATETIME)}

2. 排查确认初始无匹配结果的根因：cxGrid生成过滤条件时默认将DateTime的毫秒部分四舍五入到秒（例如将2021-02-01 18:05:03.822处理为2021-02-01 18:05:04），导致精确时间匹配无对应结果，并非格式问题。
3. 配置cxGridDBTableView.DataController.Filter.DateTimeFormat := 'yy-mm-dd hh:mm:ss.zzz'让过滤条件保留毫秒值、取消秒级四舍五入后，触发第二个报错：

[FireDAC][Stan][Eval]-118. Couldn't convert variant of type (UnicodeString) into type (Date)

故障根因 #

• FireDAC开启Filtered := True时使用的是客户端内置的Stan Eval引擎做本地过滤，而非把过滤条件下发到数据库执行，解析规则和SQL语法、cxGrid默认输出规则存在三处核心不匹配：
  • 客户端过滤引擎不支持{dt ...}、CONVERT()这类SQL专属的日期常量写法，这类语法仅在条件作为SQL语句一部分下发到数据库端时生效
  • cxGrid配置输出的带毫秒日期字符串格式，和FireDAC客户端默认解析的日期格式不匹配，导致字符串转DateTime类型失败
  • 未做精度适配时，cxGrid的秒级四舍五入会导致过滤条件里的时间值和数据库存储的实际值存在偏差，无法匹配到结果
• 未显式指定日期格式时，FireDAC和cxGrid都会读取系统区域设置解析日期，跨环境部署时很容易出现分隔符、年月日顺序不匹配的问题。

解决方案 #

方案1：适配FireDAC客户端过滤规则（兼容原有逻辑架构，推荐） #

1. 统一cxGrid输出的日期格式为FireDAC客户端可识别的固定格式，不受系统区域设置影响，配置代码：

// FireDAC客户端过滤默认解析的日期格式为 月/日/年 时:分:秒.毫秒，分隔符固定为/
// 注意Delphi格式符中分钟用nn表示，避免和月份mm冲突
cxGridDBTableView.DataController.Filter.DateTimeFormat := 'mm/dd/yyyy hh:nn:ss.zzz';

2. 配置TFDQuery的格式选项，强制使用固定格式解析日期，屏蔽区域设置干扰：

// 清空默认格式映射规则，避免自动适配逻辑干扰
MyTFDQuery.FormatOptions.MapRules := [];
MyTFDQuery.FormatOptions.DateFormat := 'mm/dd/yyyy';
MyTFDQuery.FormatOptions.TimeFormat := 'hh:nn:ss.zzz';
MyTFDQuery.FormatOptions.DateTimeFormat := 'mm/dd/yyyy hh:nn:ss.zzz';

3. 若业务要求精度仅到秒、无需匹配毫秒，可直接在cxGrid日期格式中去掉毫秒部分，同时在查询侧统一截断DateTime字段的毫秒值，避免精度差异导致匹配失败：

// cxGrid侧配置，仅输出到秒级精度
cxGridDBTableView.DataController.Filter.DateTimeFormat := 'mm/dd/yyyy hh:nn:ss';
// 查询SQL中直接把DateTime字段截断到秒，从数据源侧消除毫秒差异
// SQL示例：SELECT DATEADD(second, DATEDIFF(second, 0, [Date]), 0) AS Date, Value, Supplier FROM 业务表

方案2：过滤逻辑下推到数据库端执行（适合大数据量场景） #

本地过滤需要把全量数据拉到客户端再做匹配，数据量较大时性能较差，可将cxGrid生成的过滤条件转换为SQL Where子句，通过TFDQuery下发到SQL Server执行。该方案下日期条件只要符合SQL Server语法要求即可，可直接使用'2021-01-01 10:00:00'这类ODBC标准日期格式，无需适配客户端解析规则。

注意事项 #

• 禁止在TFDQuery的Filter属性中使用SQL专属函数、ODBC日期转义序列（如{dt ...}），客户端过滤引擎无法识别这类语法
• 涉及DateTime字段匹配时，必须先统一业务侧的精度要求，避免因毫秒、微秒的存储差异导致匹配不到预期结果
• 跨区域部署场景下，禁止依赖系统默认日期格式，必须显式指定固定的日期格式字符串，避免分隔符、年月日顺序差异引发解析错误

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