GitLab Query Language (GLQL)
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed
- Status: Experiment
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
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. The rendered output of this query is called a view.
To test GLQL views:
- On GitLab Self-Managed, ask your administrator to enable the
glql_integration
feature flag on your instance. - On GitLab.com, contact your account representative.
Share your feedback in epic 14939.
Query syntax
The query syntax consists primarily of logical expressions. These expressions follow the
syntax of <field> <operator> <value> and ...
.
Fields
Field names can have values like assignee
, author
, label
, and milestone
.
A type
field can be used to filter a query by the object type, like Issue
, MergeRequest
,
or work item types like Task
or Objective
.
For a full list of supported fields, supported operators, and value types, see GLQL fields.
Operators
Comparison operators:
GLQL operator | Description | Equivalent in search |
---|---|---|
= | Equals / Includes all in list | is (equal to) |
!= | Doesn’t equal / Isn’t contained in list | 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
- Relative dates (like
-1d
,2w
,-6m
, or1y
) - Absolute dates (in
YYYY-MM-DD
format, like2025-01-01
) - Functions (like
currentUser()
for user fields ortoday()
for dates) - Enum values (like
upcoming
orstarted
for milestones) - Booleans (
true
orfalse
) - Nullable values (like
null
,none
, orany
) - GitLab references (like
~label
for a label,%Backlog
for a milestone, or@username
for a user) - Lists containing any of the above (surrounded by parenthesis:
()
and delimited by commas:,
)
GLQL views
A view created with GLQL is a display representation of a query that executes to fetch the desired results.
Supported areas
Views can be embedded in the following areas:
- Group and project wikis
- Descriptions and comments of:
- Epics
- Issues
- Merge requests
- Work items (tasks, OKRs, epics with the new look)
Syntax
The syntax of views is a superset of YAML that consists of:
- The
query
parameter: Expressions joined together with a logical operator, such asand
. - Parameters related to the presentation layer, like
display
,limit
, orfields
.
A GLQL view 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
query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true
```
This query should render a table like the one below:
Presentation syntax
Aside from the query
parameter, you can configure presentation details for your GLQL query using some
more parameters.
Supported parameters:
Parameter | 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. All fields allowed in columns of a GLQL view are supported. |
For example, to display first five issues assigned to current user in the gitlab-org/gitlab
project as a list, displaying fields title
, health
, and due
:
```glql
display: list
fields: title, health, due
limit: 5
query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true
```
Field functions
To create dynamically generated columns, use functions in the fields
parameters in views.
For a full list, see Functions in GLQL views.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support