金蝶云星空接口支持SQL查询吗：FilterString能写什么、不能写什么（实测）

目录一、先说结论二、测试环境三、能用的写法3.1 比较、模糊、范围3.2 关联字段和明细字段3.3 SQL Server 函数也能用四、三个坑4.1 空文本不是 NULL是空格4.2 and / or 不加括号结果会错4.3 FieldKeys 能写表达式但不能聚合五、不能用的写法5.1 子查询直接被拦5.2 聚合count、sum 都不行六、拼 FilterString 的安全写法七、几个常用的过滤写法八、最后一、先说结论不能直接写 SQL 语句但查询接口的过滤条件FilterString基本就是 SQL 的 WHERE 子句。写法能不能用实测、、!、、能✔like、in、not in、between ... and能✔and、or、括号能但要注意优先级✔is null、is not null能写但空文本不是 NULL✔关联字段FCustomerID.FNumber能✔明细字段FMaterialID.FNumber能✔SQL Server 函数GETDATE()、DATEADD()、YEAR()、LEN()、LTRIM()、RTRIM()能测试环境是 SQL Server✔子查询in (select ...)不能被拦截✘在FieldKeys里聚合count()、sum()不能直接报 SQL 错✘下面是逐条实测报错原文照抄。二、测试环境金蝶云星空官方公开体验环境账套「金蝶蓝海实业集团」用户 demo日期2026-09-26接口DynamicFormService.ExecuteBillQuery单据销售出库单SAL_OUTSTOCK只调查询接口没有写入、修改任何数据请求格式后面只写FilterString这一段{data:{FormId:SAL_OUTSTOCK,FieldKeys:FBillNo,FilterString:这里是过滤条件,OrderString:FBillNo,Limit:5}}三、能用的写法3.1 比较、模糊、范围FBillNoXSCKD000001 → 1 条 FDocumentStatusC → 正常返回 FDocumentStatus!C → 和 结果一样 FBillNo like XSCKD00000% → 正常返回 FBillNo in (XSCKD000001,XSCKD000002) → 2 条 FDocumentStatus not in (C) → 正常返回 FDate between 2026-09-01 and 2026-09-30 → 正常返回 FModifyDate2026-09-20 → 正常返回修改时间带时分秒几个细节字符串用单引号日期直接写成字符串2026-09-01就能比较字段名不区分大小写fbillnoXSCKD000001和FBillNoXSCKD000001结果一样字符串里的单引号要写两个FNote like %%不报错3.2 关联字段和明细字段基础资料字段用点号取它的编码或名称FCustomerID.FNumberCUST0001 → 按客户编码过滤 FCustomerID.FName like %金蝶% → 按客户名称模糊查 FMaterialID.FNumber1.1110001 → 按明细里的物料过滤按明细字段过滤返回的是包含这个物料的单据。实测FMaterialID.FNumber1.1110001返回了XSCKD000001、XSCKD000003两张单。注意如果FieldKeys里也带了明细字段返回会变成一条明细一行分页时一张单可能被切断。这个坑我在「金蝶云星空 WebAPI 查询和查看接口的区别」那篇里专门写过。3.3 SQL Server 函数也能用FDateDATEADD(day,-30,GETDATE()) → 最近 30 天正常返回 year(FDate)2026 → 正常返回 len(FBillNo)6 → 正常返回 ltrim(rtrim(FNote)) → 正常返回这说明FilterString基本是原样拼进 SQL 的 WHERE 里的数据库能认的函数就能用。注意公开体验环境的数据库是 SQL Server后面报错信息都是 SQL Server 的原文。金蝶云星空也支持 Oracle如果客户账套是 Oracle函数写法不一样比如GETDATE()在 Oracle 里要换成SYSDATE。Oracle 账套我没测过用之前先在客户的测试账套试一下。另外GETDATE()取的是数据库服务器的时间服务器时区不对的话「最近 30 天」会差几个小时。做增量同步更稳的写法是把时间点算好直接写成字符串传进去。四、三个坑4.1 空文本不是 NULL是空格想查「备注为空」的单据第一反应是FNote is null → 0 条结果一条都没有。换成FNote is not null → 正常返回备注值是 一个空格 FNote → 正常返回 FNote → 正常返回结果和 FNote 一样原因金蝶里没填的文本字段存的是一个空格不是 NULL。而 SQL Server 比较字符串时会忽略末尾空格所以和 算相等。查空文本用FNote别用is null。顺带一个现象公开体验环境里有单据编号就是一个空格 的出库单应该是有人暂存了没填单号。做同步时对单号要有空值判断别拿空格单号去做唯一键。4.2 and / or 不加括号结果会错想要「已审核或审核中并且单号以 XSCKD 开头」FDocumentStatusC or FDocumentStatusB and FBillNo like XSCKD%实测返回了26091、260912、26093这些不是 XSCKD 开头的单。因为 SQL 里and优先级比or高上面这句实际等于FDocumentStatusC or (FDocumentStatusB and FBillNo like XSCKD%)加上括号就对了(FDocumentStatusC or FDocumentStatusB) and FBillNo like XSCKD%只要同时出现 and 和 or一律加括号。4.3 FieldKeys 能写表达式但不能聚合FieldKeys里写简单表达式可以FieldKeys: FBillNo,FRealQty*2 返回[[XSCKD000001, 4.0000000000]]但想用聚合函数汇总就不行见下一节。五、不能用的写法5.1 子查询直接被拦FID in (select FID from T_SAL_OUTSTOCK where FDOCUMENTSTATUSC)报错原文过滤条件不能包含关键字【select】请重新检查金蝶在接口层拦了select关键字。不过写在字符串里的 select 不会被误伤实测FNote like %select%正常返回0 条没报错。5.2 聚合count、sum 都不行FieldKeys写count(FID)报错原文Column T_SAL_OUTSTOCK.FID is invalid in the select list because it is not contained in either an aggregate function or the GROUP BY clause.FieldKeys写sum(FRealQty)报错原文Invalid column name FRealQty.两个都是 SQL Server 的原始报错从第一条还能看出销售出库单表头的物理表名是T_SAL_OUTSTOCK。结论查询接口不做汇总。要汇总有两个办法把明细拉回来在自己程序里算用金蝶自己的报表或者让懂 BOS 的人做一张汇总报表六、拼 FilterString 的安全写法FilterString是拼进 SQL 的外部传进来的值别直接拼。虽然金蝶拦了select但单引号没处理好轻则报错重则条件被改写。最少要做单引号转义// 把一个值变成 FilterString 里安全的字符串字面量constsqlStrvString(v).replace(//g,);// 单号来自外部系统constbillNoorder.no;constfilterFBillNo${sqlStr(billNo)};// 多个值constlistids.map(sqlStr).join(,);constfilter2FBillNo in (${list});更稳的做法是对外部输入先校验格式单号只允许字母、数字、横线不符合的直接拒绝根本不进FilterString。七、几个常用的过滤写法对接里最常用的几种直接抄场景FilterString只要已审核的单FDocumentStatusC增量同步上次同步之后改过的FModifyDate2026-09-26 08:00:00某段日期的单FDate between 2026-09-01 and 2026-09-30按客户编码FCustomerID.FNumberCUST0001推单前查重金蝶里有没有这些单号FBillNo in (A001,A002,A003)备注为空FNote组合条件(条件1 or 条件2) and 条件3一定加括号八、最后金蝶云星空接口支持 SQL 查询吗不能直接写 SQL但FilterString就是 WHERE 子句大部分写法和 SQL Server 函数都能用不能用子查询拦select、聚合count、sum报 SQL 错三个坑空文本是空格不是 NULLand/or 要加括号明细字段会让一单变多行安全外部输入先校验、单引号转义别直接拼上一篇讲了查询接口和查看接口的区别这一篇是查询接口的过滤条件。在写金蝶对接、被过滤条件卡住的评论区贴你的 FilterString 和报错看到都会回。