跳到主要内容

执行ONESQL查询

POST 
/onesql/query

ONESQL概要

  • ONESQL 是面向 ONES 工作项数据的结构化查询语言，语法接近 SQL，可表达复杂条件逻辑。

  • 语句由字段、运算符、值/函数组成，通过 AND、OR、NOT 等关键字组合；建议复杂逻辑加括号以确保结果一致。

  • 支持数值、文本、成员、日期等多类型字段比较，并可结合时间/成员函数生成动态条件。

运算符一览

类型运算符作用说明示例
比较< &lt; > >= == !=数值/日期/时间/选择/工作项/成员/文本之间比较；==、!=仅接受单值截止日期 < "2008/12/31 09:00" 负责人 != currentUser()
集合IN NOT IN字段值是否存在于枚举集合内，支持数字/日期/时间/选择/工作项/成员优先级 IN (P0, P1) 负责人 NOT IN (张三, 李四)
空值IS IS NOT判断数字/日期/时间/选择/工作项/成员/文件/文本字段是否为空关联发布 IS EMPTY 所属迭代 IS NOT EMPTY
文本匹配~ !~文本字段模糊包含或排除指定字符串标题 ~ "项目管理" 描述 !~ "已关闭"

常用函数

场景函数入参功能概述示例
时间点now(offset)(+/-)nn(y/M/w/d/h/m)，默认 + 与天当前时间加减偏移创建时间 > now(-1d)
起始时间StartOfDay/Week/Month/Year(offset)同上，默认单位分别为天、周、月、年计算对应时间单位的起始瞬间再偏移创建日期 > StartOfWeek(-1)
截止时间EndOfDay/Week/Month/Year(offset)同上计算对应时间单位的结束瞬间再偏移截止日期 < EndOfMonth(+15d)
成员集合DepartmentOf(names)部门名列表返回各部门成员负责人 IN DepartmentOf(产品部, 研发部)
成员集合GroupOf(names)用户组名列表返回各用户组成员负责人 IN GroupOf(测试)
成员集合RolesOf(names)角色名列表返回各角色成员负责人 IN RolesOf(CDT小组)
当前用户currentUser()无当前登录人负责人 == currentUser()
层级属性expand(values)节点值列表将单/多选级联或模块属性展开至子节点位置 INexpand(江苏省, 浙江省)

关键词与语法规则

  • 逻辑关键字：AND（且）、OR（或）、NOT（非）、EMPTY（空值判定），大小写不敏感。

  • 默认优先级为括号 > AND > OR，建议使用括号明确组合。

  • 文本常量需加引号（单/双皆可）；时间函数参数无需引号。

  • 日期字段支持 yyyy/MM/dd HH:mm、yyyy-MM-dd HH:mm、yyyy/MM/dd、yyyy-MM-dd 格式；间隔型字段支持 (+/-)XdYhZm。

常见查询片段

  • 当前用户未完成任务：uid(field004) == currentUser() AND uid(field_status) != uid('status_done_uuid')

  • 上周创建的缺陷：`uid(field_issue_type) == uid('defect_uuid') AND uid(field013)

StartOfWeek(-1) AND uid(field013) < StartOfWeek()`

  • 指定部门负责人：uid(field004) IN DepartmentOf(uid('department_uuid'))

  • 下月 15 日前到期：uid(field010) < EndOfMonth(+15d) （示例中的 field_status、field_issue_type、defect_uuid 等需替换为实际字段或选项 UUID。）

OpenAPI 查询要点

  • 通过 POST /onesql/query 执行语句，需显式指定数据源（如 FROM issue），LIMIT offset, size、ORDER BY、GROUP BY 等子句与标准 ONESQL 语义一致。

  • 访问字段与子属性时使用 uid(fieldUUID[.subField])，常量 UUID 写作 uid('xxx')；占位符 $1、$2 等在 variables 数组中赋值。

  • 分页使用 v$cursor 比较运算（如 v$cursor > ''）配合 limit；集合条件可混用 currentUser()、DepartmentOf()、RolesOf() 等函数。

常用虚拟字段（v$ 前缀）

字段说明是否延后
v$path返回层级路径，未开层级时等于自身 UUID否
v$sub_workitem_count当前节点的下游数量否
v$list_pin_field列表置顶信息否
v$progress_editable是否可编辑进度否
v$has_view_manhour_tab是否显示工时页签否
v$sub_workitem_done_count下游已完成数量，依赖 v$path是
v$issue_path单工作项完整路径（含上级信息）否

OpenAPI 示例

select
  uid(uuid, uuid as path, field001 as summary,
      field007.uuid, field007.name,
      field005.name, field005.category,
      v$list_pin_field as list_pin_field,
      v$has_view_manhour_tab as has_manhour_tab,
      v$sub_workitem_count as downstream_task_count,
      v$sub_workitem_done_count as downstream_task_done_count)
from issue

where uid(3nfzBs64) in (uid('VU8KxHBr'))
  and uid(field004) in (currentUser())
  and v$cursor > ''
order by field009 desc

limit 1000, 50

Request​

Query Parameters

    teamID stringrequired

    团队ID

Body

    query string

    ONESQL查询，支持参数化

    variables

    object[]

    参数化变量值列表

  • Array [

    • oneOf

    string

  • ]

    • hierarchy

    object

    层级关系配置

    lock_query string
    perspective boolean
    flat boolean

    path

    object

    upstream_field string
    downstream_field string

    config

    object

    field string
    tree string

Responses​

Request successful

Schema

    data

    object[]

    required

  • Array [

    • type 数据类型 (string)

    item

    object

    当数据类型为item时返回，key为属性标识符，value为属性值

    object

    property name*

    IssuePropertyTypeSet

    anyOf

    uuid UUID (string)

    Possible values: >= 8 characters and <= 8 characters, Value must match regular expression ^[1-9A-HJ-NP-Za-km-z]{8}$

    team_uuid 团队UUID (string)

    Possible values: >= 8 characters and <= 8 characters, Value must match regular expression ^[1-9A-HJ-NP-Za-km-z]{8}$

    type 附件类型 (integer)
    name 文件名 (string)
    description 描述 (string)
    status 状态 (integer)

    Possible values: [1, 2, 3, [object Object], [object Object], [object Object]]

    field_uuid 来源属性UUID (string)
    mime 文件MIME类型 (string)
    owner_uuid 上传者用户UUID (string)

    Possible values: >= 8 characters and <= 8 characters, Value must match regular expression ^[1-9A-HJ-NP-Za-km-z]{8}$

    owner_name 上传者用户名 (string)
    size 文件大小 (integer)
    create_time 上传时间 (integer)

    aggregate

    object

    当数据类型为aggregate时返回

    object

    group_aggregate

    object[]

    当数据类型为group_aggregate类型时返回

  • Array [

    • object

  • ]

    • group

    object

    当数据类型为group类型时返回

    key string
    total string

    info

    object

    nullable

    object
    property name* anynullable

  • ]

    • page_info

    object

    required

    has_next_page boolean

    是否有下一页

    start_cursor string

    当前页第一条数据的游标

    end_cursor string

    当前页最后一条数据的游标

    page_count integer

    当前页条数

    total_count integer

    结果集数据总条数，小于N时为准确数字，大于N时为N

    start_pos integer

    当前页第一条数据在结果集中的位置序号

    end_pos integer

    当前页最后一条数据在结果集中的位置序号

Loading...