查询单条组件

查询单条组件（DbQuerySingle）用于按主键查询单条实体记录。

概述

查询单条组件从目标实体中取出指定主键的一条记录，并返回所选的查询字段。相比查询集合，它只返回一条数据，适合「取详情」「取唯一配置项」等场景。

记录主键由上游传入（例如上一条记录的 ID），组件本身只需选择操作对象与需要返回的字段。

配置项

配置项	说明
操作对象	要查询的实体对象，必填
查询字段	需要返回的字段，必填，可多选，支持关联（lookup）字段
输出到最终结果	开启后该组件结果作为接口返回值

主键来源

组件不单独配置主键，而是按以下顺序自动解析：

上游数据操作组件写入的 BizDataIds（取逗号分隔的第一个）。
请求 query 参数 dataId。
请求 query 参数 id。
请求体 request.list 中唯一一条数据的 Id。

若以上均未取到，组件执行时抛出「未找到 ID 参数」异常。

查询字段

「查询字段」决定返回记录包含哪些字段，支持关联字段（含 ~）。执行时会与对象字段集合取交集，并在有配置查询字段时自动附加 organization 字段。

使用场景

根据主键获取详情
读取唯一配置项
查询关联对象数据

下一步

查询集合 - 查询记录列表
查询数量 - 统计记录数量

属性明细

以下内容面向技术实现与 AI 检索，说明查询单条组件的节点元数据。

节点元数据

查询单条组件由 FlowCmpType.DbQuerySingle 标识。所有节点 meta 值均以字符串存储（布尔、数字、数组等在元数据中同样以字符串形式保存）。

属性名	类型	含义	取值/存储值
`type`	string	组件类型	固定为 `"DbQuerySingle"`
`MetaObjectId`	string(GUID)	目标实体对象	缺省取当前接口所属对象
`QueryFields`	string	查询字段编码列表	逗号分隔，例 `"Name,Code"`
`IsFinalResult`	string(bool)	是否输出到最终结果	`"true"` / `"false"`
`IsDisabled`	string(bool)	是否禁用该节点	`"true"` / `"false"`
`order`	string	同级排序	例：`"8"`

元数据存储示例

{
  "ID": "single1",
  "type": "DbQuerySingle",
  "MetaObjectId": "3f9c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
  "QueryFields": "Name,Code,Status",
  "IsFinalResult": "true",
  "order": "8"
}

字段数据源

「查询字段」下拉通过 POST /api/DataSource/GetMetaFieldDataSource 获取（带 extend.IncludeLookup = "true"），切换操作对象后重新请求。

服务端执行逻辑

本节说明 DbQuerySingleComponentManager 在服务端的真实执行过程。组件继承自 TriggerComponentManagerBase，接口链路与实体触发器链路均会执行。

执行时机与场景

执行入口为 _ExecuteAsync，按主键精确查询一条记录，执行后调用 ExecuteNextAsync 继续下游。
基类执行前读取 IsDisabled，为 "true" 时跳过本组件。

主键解析

按「上游 BizDataIds → query dataId → query id → 请求体唯一数据 Id」的顺序解析；BizDataIds 取逗号分隔后的第一个非空项，请求体分支要求 list 恰好一条且 Id 非空。全部落空时抛出 IdParameterNotFound。

查询字段解析

优先级	来源	说明
1	节点 `QueryFields`	非空即用
2	query 参数 `queryFields`	节点未配置时读取
3	query 参数 `metaFormId`	读取对象表单 `Layout`，取其中表单项的 `Code` 作为字段（优先级高于节点配置的查询字段）

随后对含 ~ 的 lookup 字段补上其前缀基础字段；若最终有字段集合，则与对象字段集取交集并追加 organization；未配置查询字段时取对象全部字段。

权限过滤

查询操作权限：除非 SkipOperationPermission 生效，否则调用 VerifyPermissionAsync(Query) 校验 MetaObjectDataOperationType.Query，无权限直接抛出 NoPermissionAccess。
MOU（数据）权限：查询到结果后，若未开启 SkipMouPermission，以 FilterBuilder.Eq(_id, result._id) 为基底，调用 CombineDataPermissionFilterAsync(context, metaObject, filter, MouPermissionStageEnum.QuerySingle) 得到带 MOU 的过滤条件，再用 GetListAsync(code, filter, ["_id"]) 复核；若结果 ID 不在返回集合中，抛出 NoPermissionAccessData。
- SkipOperationPermission 取自节点 meta 或 context.DicParam；SkipMouPermission 仅取自 context.DicParam。

执行与 SQL 形态

单条查询直接按主键读取：

var result = await chameleonDbContext.GetByIdAsync(metaObject.Code, Guid.Parse(id), columns);

即 IChameleonDbContext.GetByIdAsync(集合名称, id, columns)，对应底层按 _id 的单行查询，无需构造 DynamicFilter，也不涉及排序与分页。

数据翻译

结果非空时依次执行：

dataSourceApp.TranslateAsync(resultList, metaObject._id, metaFields)：存储值 → 展示值。
dataSourceApp.TranslateLookupAsync(resultList, metaFields, queryFields 数组)：按查询字段填充 lookup 关联字段。

输出与上下文

输出项	内容
`context.CmpResult`	`List<ObjectData>`（0 或 1 条）
`context.DicParam["BizDataIds"]`	结果记录的 `_id`
`context.DicParam["MetaObjectCode"]`	对象编码
`context.DicParam["MetaObjectId"]`	对象 ID

当 IsFinalResult="true" 时，写入 context.TransferResult.List / .Total，并赋值 context.Result = ResponseResult<List<ObjectData>>.Success(resultList).Total(resultList.Count)。

性能与限制

单条按主键查询，无分页与排序开销；结果最多一条。
组件递归深度上限 100，超过抛出异常。

异常与校验

校验阶段（_VerifyAsync）：

场景	异常
`MetaObjectId` 为空	`OperationObjectNotFound`
对象不存在	`MetaObjectNotFoundById`

执行阶段：

场景	异常
未解析到主键	`IdParameterNotFound`
无查询操作权限	`NoPermissionAccess`
记录未通过 MOU 权限复核	`NoPermissionAccessData`

概述​

配置项​

主键来源​

查询字段​

使用场景​

下一步​

属性明细​

节点元数据​

元数据存储示例​

字段数据源​

服务端执行逻辑​

执行时机与场景​

主键解析​

查询字段解析​

权限过滤​

执行与 SQL 形态​

数据翻译​

输出与上下文​

性能与限制​

异常与校验​

概述

配置项