GitLab Query Language (GLQL)
-
Introduced in GitLab 17.4 with a flag named
glql_integration
. Disabled by default. - Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
GitLab Query Language (GLQL) is an experimental attempt to create a single query language for all of GitLab. Use it to filter and embed content from anywhere in the platform, using familiar syntax. Embed queries in Markdown code blocks.
This feature is an experiment.
Share your feedback in epic 14939,
either as a comment on the epic, or by creating a new issue under the epic with labels
~"group::knowledge"
and ~"type::feature"
or ~"type::bug"
.
Supported areas
GLQL blocks are rendered in the following areas:
- Wikis (group and project)
- Epics and epic comments
- Issue and issue comments
- Merge requests and merge request comments
- Work items (tasks, OKRs, epics with the new look) and work item comments
Supported objects to query
GLQL can only query issues under a project or group.
Syntax
The syntax of GLQL is composed of two parts:
- The query: Expressions joined together with a logical operator, such as
AND
. - The presentation layer: YAML front matter.
A GLQL block is defined in Markdown as a code block, similar to other code blocks like Mermaid.
For example:
Display a table of first 5 open issues assigned to the authenticated user in
gitlab-org/gitlab
. Display columnstitle
,state
,health
,description
,epic
,milestone
,weight
, andupdated
.
```glql
---
display: table
fields: title, state, health, epic, milestone, weight, updated
limit: 5
---
project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true
```
This query should render a table like the one below:
Query syntax
GLQL syntax consists primarily of logical expressions.
These expressions follow the syntax of <field name> [< | > | = | != | in] <value> [AND] ...
.
Field names include assignee
, author
, label
, and epic
.
For a full list of supported fields, see the table at the bottom of this section.
Comparison operators:
GLQL operator | Description | Equivalent in search |
---|---|---|
=
| Equals |
is (equal to)
|
!=
| Doesn’t equal |
is not (equal to)
|
in
| Contained in list |
or / is one of
|
>
| Greater than | No |
<
| Less than | No |
Logical operators: Only AND
is supported.
OR
is indirectly supported for some fields by using the IN
comparison operator.
Values: Values can include:
- Strings
- Numbers
- Dates (relative or absolute)
- Functions (like
currentUser()
for assignee ortoday()
for dates) - Special tokens (like
upcoming
orstarted
for milestones)
The following table lists all supported fields and their value types:
Field | Operators | Values | Examples |
---|---|---|---|
assignee author
|
= != in
|
String Collection<String> currentUser() any none
|
assignee = "foobar" assignee in ("foobar", "baz") author = currentUser() author = any assignee = none
|
epic reaction
|
= !=
|
String any none
|
epic = any reaction = ":thumbsup:"
|
project group
|
= !=
| String
|
project = "gitlab-org/gitlab" group = "gitlab-org"
|
closed opened confidential
|
= !=
| Boolean
|
closed = true opened = true confidential = true
|
closed opened created updated
|
= != < >
|
Date String today()
|
updated = today() created > -28d (created in the last 28 days)created < -7d (created at least a week ago)created > 2024-08-12 updated < "2024-08-12"
|
health
|
= !=
|
Enum( "on track" "needsAttention" "at risk" )
|
health = "on track" health != "on track" health = "at risk"
|
milestone iteration
|
= !=
|
String any none started upcoming
|
milestone = "17.4" milestone = "Backlog" milestone != none iteration = any
|
label
|
= != in
|
String Collection<String> any none
|
label != none label in ("feature", "bug") (has the feature or bug label) label = ("bug", "priority::1") (has both bug and priority::1 labels)label = "bug"
|
weight
|
= !=
| Number
|
weight = 1 weight != 2 and weight != 1
|
Query shorthand syntax
When querying multiple labels and assignees, you can also use the shorthand syntax to simplify the query.
For example:
Shorthand syntax | Full equivalent |
---|---|
label != ("label 1", "label 2")
| label != "label 1" and label != "label 2"
|
label = ("label 1", "label 2")
| label = "label 1" and label = "label 2"
|
assignee != ("user1", "user2")
| assignee != "user1" and assignee != "user2"
|
assignee = ("user1", "user2")
| assignee = "user1" and assignee = "user2"
|
Presentation syntax
GLQL presentation is configured in a YAML front matter block.
A YAML front matter block begins and ends with ---
and contains YAML.
Three options are supported:
Option | Default | Description |
---|---|---|
display
| table
| How to display the data. Supported options: table , list or orderedList .
|
limit
| 100
| How many items to display. The maximum value is 100 .
|
fields
| title
| A comma-separated list of fields. |
Supported fields to display:
assignees
author
closed
created
description
due
epic
health
labels
milestone
state
title
type
updated
weight
For example:
Display first five issues assigned to current user in the
gitlab-org/gitlab
project as a list, displaying fieldstitle
,health
, anddue
.
```glql
---
display: list
fields: title, health, due
limit: 5
---
project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true
```
Field functions
In the fields
parameter, you can also include functions to derive a column from an existing field.
In the initial version, only the labels
function is supported.
labels
-
Syntax:
labels("field1", "field2")
-
Description: The
labels
function takes one or more label name string values as parameter, and creates a filtered column with only those labels on issues. The function also works as an extractor, so if a label has been extracted, it no longer shows up in the regularlabels
column, if you choose to display that column as well.By default, this function looks for an exact match to the label name. You can include
*
in the string to match one or more wildcard characters.The label names you pass are case-insensitive, so
Deliverable
anddeliverable
are equivalent. -
Limits: A minimum of 1 and maximum of 100 label names can be passed to the
labels
function. -
Usage examples:
-
labels("workflow::*")
: Include allworkflow
scoped labels in the column. -
labels("Deliverable", "Stretch", "Spike")
: Include labelsDeliverable
,Stretch
, andSpike
. -
labels("*end")
: Include all labels likebackend
,frontend
, and others that end withend
.
To include the function in the query, follow this example:
```glql --- display: list fields: title, health, due, labels("workflow::*"), labels limit: 5 --- project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true ```
-
Known issues
For a full list of known issues, see epic 14437 and GLQL issues.