数据查询与分页（`GetById` / `GetList` / `GetCount` / `IsExist`）

IChameleonDbContext 的查询方法用于按 ID 或按条件读取业务对象数据。每个方法都提供同步与 Async 后缀的异步版本，编写 C# 脚本和微服务代码时一律使用异步版本。

概述

查询能力按场景分为四类：

场景	方法
已知主键取单条	`GetById` / `GetByIdAsync`
已知多个主键取多条	`GetListByIds` / `GetListByIdsAsync`
按条件取列表（支持排序、分页、指定列）	`GetList` / `GetListAsync`
统计数量 / 判断存在	`GetCount`、`IsExist`

条件统一使用 DynamicFilter 表达（推荐用 FilterBuilder 构建，见过滤条件构建）。返回的每条数据都是 ObjectData 字典，键为小写字段编码。

重要

查询不会自动过滤已逻辑删除（isdeleted = true）的数据。需要排除时，必须在过滤条件中显式加 FilterBuilder.Eq("isdeleted", false)。

API 方法

按 ID 获取单条

Task<ObjectData> GetByIdAsync(string metaObjectCode, Guid id, string[] columns = null);
ObjectData GetById(string metaObjectCode, Guid id, string[] columns = null);

不存在时返回 null。指定 columns 时平台会自动并入 _id 列。

按 ID 集合获取多条

Task<List<ObjectData>> GetListByIdsAsync(string metaObjectCode, Guid[] ids, string[] columns = null);
List<ObjectData> GetListByIds(string metaObjectCode, Guid[] ids, string[] columns = null);

ids 为 null 或空数组时直接返回空列表，不执行 SQL。结果顺序不保证与传入 ids 一致，需要保序时自行按 _id 排序。

按条件获取列表

Task<List<ObjectData>> GetListAsync(
    string metaObjectCode,
    DynamicFilter filter,
    string[] columns = null,
    Dictionary<string, int> sort = null,
    int skip = -1,
    int limit = -1);
List<ObjectData> GetList(
    string metaObjectCode,
    DynamicFilter filter,
    string[] columns = null,
    Dictionary<string, int> sort = null,
    int skip = -1,
    int limit = -1);

参数	说明
`metaObjectCode`	对象编码
`filter`	过滤条件（`DynamicFilter`），不可为 `null`
`columns`	要返回的字段编码数组，`null` 返回全部列；指定时自动并入 `_id`
`sort`	排序字典：键为字段编码，值大于 `0` 为升序，否则为降序（惯用 `1` 升序、`-1` 降序）；按字典顺序依次应用
`skip`	分页偏移，跳过前 N 条；默认 `-1` 表示不分页
`limit`	返回最多 N 条；默认 `-1` 表示不限制

统计与存在性判断

Task<long> GetCountAsync(string metaObjectCode, DynamicFilter filter);
long GetCount(string metaObjectCode, DynamicFilter filter);

Task<bool> IsExistAsync(string metaObjectCode, Guid id);
Task<bool> IsExistAsync(string metaObjectCode, DynamicFilter filter);
bool IsExist(string metaObjectCode, Guid id);
bool IsExist(string metaObjectCode, DynamicFilter filter);

IsExist 在数据库端执行存在性判断，比查出数据再判断 Count 更高效；判断"是否存在"优先用它而不是 GetCount。

参数明细（AI 生成代码对照）

参数名	类型	含义	取值/存储值
`metaObjectCode`	`string`	对象编码，决定查询的表	如 `"User.Information"` → 表 `user_information`
`id` / `ids`	`Guid` / `Guid[]`	主键 `_id`	`Guid.Empty` 视为未赋值
`filter`	`DynamicFilter`	过滤条件	见过滤条件构建；`null` 会抛异常
`columns`	`string[]`	返回列	小写字段编码数组；自动并入 `_id`
`sort`	`Dictionary<string, int>`	排序	值 `> 0` 升序，`<= 0` 降序
`skip` / `limit`	`int`	分页	默认 `-1` 表示不启用

使用示例

分页 + 排序 + 多条件查询

var db = sdk.DbContext;

var list = await db.GetListAsync(
    metaObjectCode: "Order",
    filter: FilterBuilder.And(
        FilterBuilder.Gte("amount", 1000),
        FilterBuilder.Eq("status", "Completed"),
        FilterBuilder.Eq("isdeleted", false)          // 显式排除已逻辑删除
    ),
    columns: new[] { "orderno", "amount", "status" }, // 只取需要的列，自动含 _id
    sort: new Dictionary<string, int> { { "createdtime", -1 } },
    skip: 0,
    limit: 20
);

标准分页（先 Count 后取页）

var filter = FilterBuilder.Eq("isdeleted", false);
var total = await db.GetCountAsync(entityCode, filter);
var pageData = await db.GetListAsync(entityCode, filter,
    sort: new Dictionary<string, int> { { "createdtime", -1 } },
    skip: (pageIndex - 1) * pageSize,
    limit: pageSize);
return new { total, list = pageData };

存在性判断防重复

var exists = await db.IsExistAsync("User.Information",
    FilterBuilder.Eq("email", email));
if (exists)
{
    throw new Exception("邮箱已被使用");
}

注意事项

filter 传 null 会抛异常；确实要取全量时用安全条件 FilterBuilder.Empty（等价于 _id != Guid.Empty），但务必配合 limit 使用，避免全表拉取
sort、skip、limit 只有在 GetList 上生效，GetById / GetListByIds 不支持
查询结果中字段键名是小写的字段编码，取值时用小写（如 row["createdtime"]）
字段名会经过 SQL 注入校验（ValidateSqlInjection），含非法字符会抛 ArgumentException

下一步

过滤条件构建 - DynamicFilter 与 FilterBuilder 全部操作符
SQL 查询与底层实例 - 需要联表、聚合等复杂查询时
数据增删改与逻辑删除 - 查出后的更新模式
查询列表组件 - 可视化编排中的等价能力

概述​

API 方法​

按 ID 获取单条​

按 ID 集合获取多条​

按条件获取列表​

统计与存在性判断​

参数明细（AI 生成代码对照）​

使用示例​

分页 + 排序 + 多条件查询​

标准分页（先 Count 后取页）​

存在性判断防重复​

注意事项​

下一步​

相关实现​

概述