doc/user/glql/_index.md
{{< details >}}
{{< /details >}}
{{< history >}}
glql_integration. Disabled by default.glql_integration removed.{{< /history >}}
GitLab Query Language (GLQL) is 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. An embedded view is the rendered output of a GLQL source code block.
Share your feedback in the embedded views, powered by GLQL, feedback issue.
The query syntax consists primarily of logical expressions. These expressions follow the
syntax of <field> <operator> <value> and ....
GLQL can query different data sources such as work items, merge requests, pipelines, jobs, and projects.
For a full list of supported data sources, see GLQL data sources.
Use fields to filter, display, and sort results.
The fields you can use depend on the data source you are querying. For a full list of supported fields, operators, and values for each data source, see GLQL fields.
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 >}} |
>= | Greater than or equal to | {{< no >}} |
<= | Less than or equal to | {{< no >}} |
Logical operators: Only and is supported.
or is indirectly supported for some fields by using the in comparison operator.
Values can include:
-1d, 2w, -6m, or 1y)YYYY-MM-DD format, like 2025-01-01)currentUser() for user fields or today() for dates)upcoming or started for milestones)true or false)null, none, or any)~label for a label, %Backlog for a milestone, or @username for a user)() and delimited by commas: ,)An embedded view is the output of a GLQL source code block in Markdown. The source includes YAML attributes that describe how to display the GLQL query results, along with the query.
{{< history >}}
{{< /history >}}
Embedded views can be displayed in the following areas:
The syntax of an embedded view's source is a superset of YAML that consists of:
query parameter: Expressions joined together with a logical operator, such as and.display, limit, or fields, title, and description
represented as YAML.A view is defined in Markdown as a code block, similar to other code blocks like Mermaid.
For example:
gitlab-org/gitlab.title, state, health, description, epic, milestone, weight, and updated.```glql
display: table
title: GLQL table 🎉
description: This view lists my open issues
fields: title, state, health, epic, milestone, weight, updated
limit: 5
query: type = Issue AND group = "gitlab-org" AND assignee = currentUser() AND state = opened
```
This source should render a table like the one below:
{{< history >}}
title and description parameters introduced in GitLab 17.10.collapsed parameter introduced in GitLab 18.3.{{< /history >}}
Aside from the query parameter, you can configure presentation details for your view using some
more optional parameters.
Supported parameters:
| Parameter | Default | Description |
|---|---|---|
collapsed | false | Whether to collapse or expand the view. |
description | None | An optional description to display below the title. |
display | list | How to display query results. For the available types, see Display types. |
displayConfig | None | Display-type-specific options, such as stacked for column charts. See Display types. |
fields | title | A comma-separated list of fields to include in the view. |
limit | 100 | How many items to display on the first page. The maximum value is 100. |
sort | updated desc | The field to sort the data by followed by a sort order (asc or desc). |
title | Embedded table view or Embedded list view | A title displayed at the top of the embedded view. |
{{< history >}}
{{< /history >}}
Embedded views display the first page of results by default.
The limit parameter controls the number of items shown.
To load the next page, in the last row, select Load more.
To create dynamically generated columns, use functions in the fields parameters in views.
For a full list, see Functions in embedded views.
{{< history >}}
{{< /history >}}
To rename a table view's column to a custom value, use the AS syntax keyword to alias fields.
```glql
display: list
fields: title, labels("workflow::*") AS "Workflow", labels("priority::*") AS "Priority"
limit: 5
query: type = Issue AND project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
```
This source displays a view with columns Title, Workflow and Priority.
The display parameter controls how an embedded view renders query results, for example as a
list, table, or column chart. By default, results display as a list.
For the full list of display types and their configuration, see GLQL display types.
{{< history >}}
{{< /history >}}
When a view appears on a page, use the View actions ({{< icon name="ellipsis_v" >}}) dropdown list to take an action on it.
Supported actions:
| Action | Description |
|---|---|
| View source | View the source of the view. |
| Copy source | Copy the source of the view to clipboard. |
| Copy contents | Copy the table or list contents to clipboard. |
| Reload | Reload this view. |
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
GLQL supports an analytics mode for data sources that provide
aggregated metrics. Analytics mode queries use dimensions and metrics
instead of fields to group and aggregate data.
Some data sources support both standard and analytics mode. See each data source page for supported modes.
Analytics mode queries use the following structure:
```glql
mode: analytics
query: type = <DataSource> and <filters>
dimensions: <dimension fields>
metrics: <metric fields>
sort: <field> <direction>
limit: <number>
```
| Parameter | Required | Description |
|---|---|---|
mode: analytics | Yes | Required to use analytics mode. |
metrics | Yes | Aggregated values to compute. At least one metric is required. |
dimensions | No | Fields to group results by. Select any combination, or omit entirely to return a single aggregated row. |
sort | No | Sort fields must also appear in your selected dimensions or metrics. |
limit | No | Defaults to 100. Maximum value is 100. |
Use the as keyword to rename dimension or metric columns:
dimensions: language as "Language", ideName as "IDE"
metrics: totalCount as "Total", acceptanceRate as "Acceptance Rate"
Sort by any field that appears in your selected dimensions or metrics. You cannot sort by a field that is not in your selected dimensions or metrics.
sort: acceptanceRate desc
Multiple sort fields are supported:
sort: totalCount desc, acceptanceRate asc
The following query returns Code Suggestions acceptance rate by language for the last 30 days, sorted by acceptance rate:
```glql
display: table
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language as "Language"
metrics: totalCount as "Total", acceptanceRate as "Acceptance Rate"
sort: acceptanceRate desc
```
For more information, see the examples for a specific data source.
{{< details >}}
{{< /details >}}
{{< history >}}
glql_work_items and glql_es_integration. Enabled by default.glql_work_items removed in GitLab 18.10.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
GLQL uses Advanced Search when available to speed up queries. Advanced Search provides faster response times for complex queries across large datasets.
Advanced Search is:
If Advanced Search isn't available, GLQL uses PostgreSQL instead.