极狐 GitLab Logo

极狐GitLab 查询语言 (GLQL)

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com，私有化部署
  • Status: Beta
History
    • 引入于极狐GitLab 17.4，使用名为 glql_integration 的功能标志，默认关闭。
    • 极狐GitLab 17.4 在 JihuLab.com 部分群组和项目中启用。
    • 极狐GitLab 17.10 从实验阶段变更为 Beta。
    • 极狐GitLab 17.10 在 JihuLab.com、极狐GitLab 私有化部署和极狐GitLab Dedicated 中启用。
此功能的可用性由功能标志控制。更多信息请参阅历史记录。该功能目前可用于测试，但尚未准备好用于生产环境。

极狐GitLab 查询语言 (GLQL) 是创建一个统一查询语言以用于极狐GitLab 的尝试。使用它可以在平台的任何地方过滤和嵌入内容，使用熟悉的语法。

将查询嵌入到 Markdown 代码块中。该查询的渲染输出称为视图。

查询语法#

查询语法主要由逻辑表达式组成。这些表达式遵循 <field> <operator> <value> and ... 的语法。

字段#

字段名称可以有值，如 assignee、author、label 和 milestone。可以使用 type 字段通过对象类型过滤查询，如 Issue、MergeRequest 或工作项类型，如 Task 或 Objective。

有关支持的字段、支持的运算符和值类型的完整列表，请参阅 GLQL fields。

运算符#

比较运算符：

GLQL 运算符描述搜索中的等效项
=等于 / 包含列表中所有项is (等于)
!=不等于 / 不包含在列表中is not (不等于)
in包含在列表中or / is one of
>大于 No
<小于 No

逻辑运算符：仅支持 and。对于某些字段，通过使用 in 比较运算符间接支持 or。

值#

值可以包括：

  • 字符串
  • 数字
  • 相对日期（如 -1d、2w、-6m 或 1y）
  • 绝对日期（使用 YYYY-MM-DD 格式，如 2025-01-01）
  • 函数（如用于用户字段的 currentUser() 或用于日期的 today()）
  • 枚举值（如 upcoming 或 started 用于里程碑）
  • 布尔值（true 或 false）
  • 可为空值（如 null、none 或 any）
  • 极狐GitLab 引用（如用于标签的 ~label、用于里程碑的 %Backlog 或用于用户的 @username）
  • 包含上述任何内容的列表（用括号 () 包围并用逗号 , 分隔）

GLQL 视图#

History
    • 在极狐GitLab 17.1 中进行了更改：使用 YAML front matter 配置表示层已弃用。
    • 参数 title 和 description 引入于极狐GitLab 17.10。

使用 GLQL 创建的视图是执行查询以获取所需结果的显示表示。

支持的区域#

可以在以下区域嵌入视图：

  • 群组和项目维基
  • 描述和评论：
    • 史诗
    • 议题
    • 合并请求
    • 工作项（任务、OKRs、史诗 新外观）

语法#

视图的语法是 YAML 的超集，包括：

  • query 参数：使用逻辑运算符如 and 连接在一起的表达式。
  • 与表示层相关的参数，如 display、limit 或 fields、title 和 description。

GLQL 视图在 Markdown 中定义为代码块，类似于其他代码块如 Mermaid。

例如：

显示分配给认证用户的前 5 个打开的议题的表格，位于 gitlab-org/gitlab。 显示列 title、state、health、description、epic、milestone、weight 和 updated。

yaml
1```glql
2display: table
3title: GLQL table 🎉
4description: This view lists my open issues
5fields: title, state, health, epic, milestone, weight, updated
6limit: 5
7query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
8```

此查询应渲染如下表格：

A table listing issues assigned to the current user

表示语法#

除了 query 参数之外，还可以使用一些更多的可选参数配置 GLQL 查询的表示细节。

支持的参数：

参数默认值描述
descriptionNone显示在标题下方的可选描述。
displaytable数据的显示方式。支持的选项：table、list 或 orderedList。
fieldstitle以逗号分隔的字段 列表。GLQL 视图中的列支持所有字段。
limit100显示的项目数量。最大值为 100。
titleGLQL table 或 GLQL list显示在 GLQL 视图顶部的标题。

例如，显示分配给当前用户的前五个议题，在 gitlab-org/gitlab 项目中作为列表，显示字段 title、health 和 due：

yaml
1```glql
2display: list
3fields: title, health, due
4limit: 5
5query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
6```

字段函数#

要创建动态生成的列，请在视图中的 fields 参数中使用函数。有关完整列表，请参阅GLQL 视图功能。