UKG Dimensions设count=500仍报员工数超500限制问题问询

报错提示：Number of employees in request (624) exceeds allowed limit (500)

报错触发场景 #

调用UKG Dimensions聚合数据接口时触发：

POST {{DIMENSIONSHOST}}/v1/commons/data/multi_read

触发报错的请求体如下：

{
  "select": [
    {"key": "EMP_COMMON_FULL_NAME"}
  ],
  "from": {
    "view": "EMP",
    "employeeSet": {
        "hyperfind": {
            "id": -9
        },
        "dateRange": {
            "startDate": "2022-01-01",
            "endDate": "2022-04-30"
      }
    }
  },
  "index": 0,
  "count": 500
}

请求中已显式设置"count": 500，仍触发员工数超限报错。

问题产生原因 #

• count参数作用为控制单次分页返回的结果条数，不参与员工集合范围的计算。/v1/commons/data/multi_read接口的500条上限，校验的是请求中employeeSet条件圈定的全量匹配员工总数，和单页返回条数设置无关。
• 本次请求使用的hyperfind id -9 是UKG Dimensions内置的全量员工视图，匹配2022-01-01至2022-04-30时间段的员工总数为624。接口收到请求后会先做员工集合范围的合法性校验，此时还未进入分页返回逻辑，因此即使设置"count":500，依然会触发超限报错。

对应解决方案 #

• 拆分查询时间范围：将原请求中4个月的时间窗口拆分为多个更短的区间，保证每个区间内hyperfind匹配的员工总数不超过500，逐次请求后合并所有返回结果即可。例如可将原时间范围拆为2022-01-01_{2022-02-28、2022-03-01}2022-04-30两个区间分别调用。
• 拆分员工筛选范围：不直接使用id=-9的全量员工hyperfind，自定义按部门、用工类型等维度拆分的细粒度hyperfind条件，保证单次请求传入的hyperfind匹配员工总数不超过500，分批拉取后聚合结果。
• 异步导出方案：如果所属租户开通了UKG高级API权限，可改用支持大数据集拉取的异步报表接口提交导出任务，轮询获取任务结果即可，不受单次请求500员工数的限制。

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