GLQL display types

A display type controls how an embedded view renders the results of a GLQL query. Set the display type with the display parameter in the view source.

If you do not set a display parameter, results render as a list.

Some display types work with any query. Others work only in analytics mode, which aggregates data into dimensions and metrics.

The following display types are available in any mode:

The following display types are available only in analytics mode:

Table

A table renders one row per result and one column per field.

To sort a table by a column, select the column header. This view reorders the rows loaded in the view, not the full result set.

A table can describe its result. This requires analytics mode. Set description under displayConfig, and set hiddenMetrics to keep a metric out of the columns. See Dynamic descriptions for placeholder syntax and rules.

Example

To display the first five open issues assigned to the current user in the gitlab-org/gitlab project as a table, with the title, state, health, epic, milestone, weight, and updated columns:

```glql
display: table
title: My open issues
fields: title, state, health, epic, milestone, weight, updated
limit: 5
query: type = Issue AND project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
```

List

A list renders results as an unordered list. Lists are the default display type.

Example

To display the first five open issues assigned to the current user in the gitlab-org/gitlab project as a list, sorted by due date with the earliest first, and showing the title, health, and due fields:

```glql
display: list
fields: title, health, due
limit: 5
sort: due asc
query: type = Issue AND project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
```

Ordered list

An ordered list renders results as a numbered list. Use an ordered list when the order of the results is meaningful, such as a ranking.

Example

To display the first five open issues assigned to the current user in the gitlab-org/gitlab project as an ordered list, sorted by due date with the earliest first, and showing the title, health, and due fields:

```glql
display: orderedList
fields: title, health, due
limit: 5
sort: due asc
query: type = Issue AND project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
```

Single stat

A single stat visualizes one aggregated metric from analytics mode as a large value. Use a single stat to highlight a key number, such as a total or a rate.

A single stat requires:

• Analytics mode, set with mode: analytics.
• One or more metrics, set with the metrics parameter. The stat displays the value of the first metric and ignores the rest, unless the description references them.
• No dimensions.

Values format automatically based on the metric. For example, counts use thousands separators and rates display as percentages. To render numbers in compact notation instead, for example 1.45M, set compact: true under displayConfig. Rates keep their percentage format, and durations drop to their largest unit, for example 1h 1m 1s becomes 1h.

To describe the value, set description under displayConfig. See Dynamic descriptions for placeholder syntax and rules.

Example

To display the total number of Code Suggestions over the last 30 days as a single stat:

```glql
display: stat
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
metrics: totalCount
```

To describe the value with the other metrics the query selects:

```glql
display: stat
displayConfig:
  description: "%{acceptedCount} of %{shownCount} suggestions accepted"
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
metrics: acceptanceRate, acceptedCount, shownCount
```

Column chart

A column chart visualizes aggregated data from analytics mode. Use a column chart to compare metrics across the categories defined by your dimensions.

A column chart requires:

• Analytics mode, set with mode: analytics.
• One or two dimensions to group results by.
• At least one metric to plot (using the metrics parameter).

The number of dimensions and metrics determines how the chart renders:

• One dimension with one or more metrics plots a column for each metric. To stack these columns, set stacked: true under displayConfig. With a single metric, stacked has no visible effect.
• Two dimensions with one metric plots a stacked column chart grouped by the second dimension. With two dimensions, you can use only one metric, and GitLab ignores displayConfig.stacked.

With two dimensions, the maxSeries option under displayConfig limits how many second dimension values get their own segment. The values with the largest totals keep theirs, and the rest combine into an Other (N) segment. A single value past the limit stays as-is. Without maxSeries, every value gets a segment. A maxSeries value that is not a whole number greater than zero is ignored.

Example

To display Code Suggestions usage by language over the last 30 days as a column chart:

```glql
display: columnChart
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: totalCount
```

To stack the metrics into a single column instead of plotting them side by side:

```glql
display: columnChart
displayConfig:
  stacked: true
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: acceptedCount, rejectedCount
```

Bar chart

A bar chart visualizes aggregated data from analytics mode as horizontal bars. Use a bar chart to compare metrics across the categories defined by your dimensions, especially when category labels are long.

A bar chart requires:

• Analytics mode, set with mode: analytics.
• One or two dimensions to group results by.
• At least one metric to plot (using the metrics parameter).

The number of dimensions and metrics determines how the chart renders:

• One dimension with one or more metrics plots a bar for each metric. To stack these bars, set stacked: true under displayConfig. With a single metric, stacked has no visible effect.
• Two dimensions with one metric plots a stacked bar chart grouped by the second dimension. With two dimensions, you can use only one metric, and GitLab ignores displayConfig.stacked.

A bar chart draws the first row at the bottom, so sort in ascending order to put the largest value at the top. The chart is as tall as its rows need, up to the default chart height.

A bar chart also accepts these options under displayConfig:

• categoryLabels: valueAndShare appends each category’s value and its share of the total to the category label, for example Returning · 1,555 · 78%. The default, plain, shows the category name only. It applies only to count metrics, such as usersCount, totalCount, or acceptedCount, with one dimension and one metric, and is ignored otherwise. The total is the sum of the rows shown, so the shares always add up to 100% of what is displayed. The share is only meaningful when each item falls in exactly one category. For example, with usersCount, a user who is active in several categories is counted once in each row, so the share is not a share of users. When the query uses a limit, the total covers only the rows that are shown.
• colorBy: category gives each bar its own solid shade from a blue scale, instead of one color for the series. The top bar gets the boldest shade, darkest in light mode and lightest in dark, so bars stay readable either way. Requires one dimension and one metric, and is ignored otherwise.
• showAxisTitles: false hides both axis titles.

Example

To display Code Suggestions usage by language over the last 30 days as a bar chart:

```glql
display: barChart
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: totalCount
```

To stack the metrics into a single bar instead of plotting them side by side:

```glql
display: barChart
displayConfig:
  stacked: true
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: acceptedCount, rejectedCount
```

To show each language’s share of accepted suggestions as a labeled, individually colored bar without axis titles:

```glql
display: barChart
displayConfig:
  categoryLabels: valueAndShare
  colorBy: category
  showAxisTitles: false
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: acceptedCount
sort: acceptedCount asc
```

Bar list

A bar list visualizes aggregated data from analytics mode as horizontal bars. By default, each bar’s length is that row’s percentage of the total of all rows, not a comparison against the largest row. A bar list answers “what share of the whole is this”, while a bar chart answers “how do these compare to each other”.

A bar list requires:

• Analytics mode, set with mode: analytics.
• Up to two dimensions values.
• At least one metric, set with the metrics parameter.

With one dimension, each row is a value of that dimension and the first metric sets the row’s value. A query that names more than one metric renders the first and ignores the rest. Rows sort in descending order by value. More than two dimensions causes a validation error in the view, as does more than one metric together with two dimensions.

Without a dimension, each metric becomes a row, in the order the query names them. Use this to compare percentiles or counts of a single measure, such as the median and 75th percentile time to merge. Each row’s value is formatted in the unit of its metric, so a duration reads as 9h 24m rather than as a number of milliseconds. These rows keep their order, are never folded into an Other row, and show no change against the previous period. A metric with no value in the response, such as a percentile over no merge requests, renders as an em dash (—) with an empty bar.

Some metrics cannot drop their dimension. A metric that compares one time bucket against the previous one, such as returningUsersCount, requires the date dimension. To get one row per metric from a query that has one, set metricRows: true under displayConfig. Values come from the first row of the response, so sort the query to put the row you want first.

With dimensions, the maxRows option under displayConfig sets how many rows each page shows. The default is six, and rows are ranked by value, highest first. When the query returns more rows, Previous and Next controls page through rows already fetched automatically, so turning a page fetches nothing new. That fetch stops at 1,000 rows, so paging covers at most the first 1,000 rows. A single row past the page size stays on the first page rather than starting a page of its own. Shares stay relative to the total across all pages. A maxRows value that is not a whole number greater than zero falls back to the default.

A share of the total is meaningful only when the metric is a count or a sum. For a metric such as an average or a median, the total behind the shares has no meaning.

A bar list without dimensions renders one bar per metric. To select a metric purely for the description, without giving it a bar, add it to hiddenMetrics under displayConfig. See Dynamic descriptions for placeholder syntax and the hiddenMetrics rules.

One dimension

Each row is one value of the dimension.

Each row’s label shows a value past the end of the bar, controlled by valueLabels under displayConfig:

• valueLabels: shareAndValue is the default. It shows the row’s share of the total and a compact value, for example 89% · 85.6k.
• valueLabels: value shows only the row’s value, in full digits, for example 1,071. Use it when the count matters more than the share.

Bar color is set by color under displayConfig:

• color: orange is the default. It matches the existing look.
• color: blue draws the bars in the same blue the other GLQL charts use for their first series, the chart palette’s default color.
• color: gray draws neutral gray bars, for a baseline shown next to a colored list.

Bar length is measured against a scale, set by scale under displayConfig:

• scale: total is the default. A bar’s length is the row’s share of the total of all rows, so the track reads as 100% of the whole and the gap after a bar is the rest of the total.
• scale: max makes the largest row fill the track, with every other bar sized relative to it, so bars compare rows against each other. Use it when the rows are many or evenly spread, where shares of the total leave every bar short.

The label is unaffected by scale: with valueLabels: shareAndValue it still shows the share of the total, whatever scale is.

Any other value for valueLabels, color, or scale causes a validation error in the view.

Two dimensions

Each row is a value of the first dimension, and its bar splits into stacked segments, one per value of the second dimension, with a legend below the chart. Rows are labeled with their compact total.

The maxSeries option under displayConfig limits how many second dimension values get their own segment; the rest combine into an Other (N) segment. A single segment past the limit stays as-is. The default is six.

Rows page with the same maxRows and controls as one dimension, each row keeping its segments.

Selecting a legend entry hides that segment and rescales the remaining bars and labels to the visible total.

The valueLabels, color, and scale options and the previous-period comparison apply to one dimension only.

Examples

To display Code Suggestions usage by language over the last 30 days as a bar list:

```glql
display: barList
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: totalCount
```

To show more than the default six rows:

```glql
display: barList
displayConfig:
  maxRows: 10
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: totalCount
```

To show Duo Agent Platform sessions by flow type over the last 30 days in blue with only the value in each label, with bars sized against the largest row instead of the total:

```glql
display: barList
displayConfig:
  valueLabels: value
  color: blue
  scale: max
mode: analytics
query: type = AgentPlatformSession and created >= -30d
dimensions: flowType
metrics: usersCount
```

To compare the median and 75th percentile time to merge for merge requests merged in the last 30 days, with one row per percentile and the longer bar filling the track:

```glql
display: barList
displayConfig:
  valueLabels: value
  scale: max
mode: analytics
query: type = MergeRequest and merged >= -30d
metrics: timeToMergeQuantile(0.5) as "Median", timeToMergeQuantile(0.75) as "p75"
```

To split the users active in a period into those who also had a session in the period before and those who did not, as one row each. The query covers two consecutive 30-day periods, because returningUsersCount has nothing to compare against without the earlier one, and sorts the newest bucket first so metricRows reads the later one. origin anchors the buckets to the start of the range, so they line up with it instead of counting from the Unix epoch:

```glql
display: barList
displayConfig:
  metricRows: true
mode: analytics
query: type = DuoWorkflow and created >= 2026-07-16 and created < 2026-09-14
dimensions: created(granularity=30d, origin=2026-07-16)
metrics: joinedUsersCount as "New", returningUsersCount as "Returning"
sort: created desc
```

To split each user’s sessions over the last 30 days by flow type, with at most four flow types as their own segment:

```glql
display: barList
displayConfig:
  maxSeries: 4
mode: analytics
query: type = AgentPlatformSession and created >= -30d
dimensions: user, flowType
metrics: totalCount
```

Line chart

A line chart visualizes aggregated data from analytics mode as one or more lines. Use a line chart to show how metrics change across a dimension, such as over time.

A line chart requires:

• Analytics mode, set with mode: analytics.
• Exactly one dimension for the x-axis.
• At least one metric to plot. Each metric renders as a separate line.

Example

To display Code Suggestions usage by language over the last 30 days as a line chart, with one line for total suggestions and one for accepted suggestions:

```glql
display: lineChart
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language
metrics: totalCount, acceptedCount
```

Area chart

An area chart visualizes aggregated data from analytics mode as one or more filled areas. Use an area chart to show how metrics change across a dimension, such as over time, and to emphasize the volume behind the trend.

An area chart requires:

• Analytics mode, set with mode: analytics.
• One or two dimensions to group results by.
• At least one metric to plot (using the metrics parameter).

The number of dimensions and metrics determines how the chart renders:

• One dimension with one or more metrics plots an area for each metric. Areas overlap with semi-transparent fills. To stack the areas cumulatively instead, set stacked: true under displayConfig. With a single metric, stacked has no visible effect.
• Two dimensions with one metric plots a stacked area chart grouped by the second dimension. With two dimensions, you can use only one metric, and GitLab ignores displayConfig.stacked.

Example

To display shown and accepted Code Suggestions over the last 30 days as overlapping areas:

```glql
display: areaChart
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: timestamp
metrics: shownCount, acceptedCount
```

To stack the metrics cumulatively instead:

```glql
display: areaChart
displayConfig:
  stacked: true
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: timestamp
metrics: shownCount, acceptedCount
```

Heat map

A heat map visualizes aggregated data from analytics mode as a grid of shaded cells, one cell per pair of dimension values. Use a heat map to compare a single metric across two dimensions at once, and to see where the largest values sit.

A heat map requires:

• Analytics mode, set with mode: analytics.
• Exactly two dimensions to group results by. The first runs along the columns, the second down the rows.
• Exactly one metric to shade the cells by (using the metrics parameter).

Each cell shows its value, shaded from light to dark as the value rises. Shading uses fixed bands derived from the values in the result, so a darker cell always means a larger value. Cells with no value at all are shaded a neutral gray rather than the lightest color, so that a small value is not mistaken for an absent one. Hover a cell for its row, column, and exact value.

To describe the panel above the grid, set description under displayConfig.

To limit how many dimension values the grid draws, set maxColumns or maxRows under displayConfig. maxColumns caps the first dimension, which runs along the columns, and maxRows caps the second, which runs down the rows. The values kept are the largest, ranked by the metric totaled across the other axis, and a capped axis is ordered largest first, with ties broken by label. That ordering replaces the one sort gives to that axis. The other axis still follows the query.

Values past the limit are dropped, and nothing on the grid shows that they are missing, so state the limit in the panel title or description. Neither option has a default, and a value that is not a whole number greater than zero is ignored.

Example

To compare Code Suggestion volume across IDEs and languages over the last 30 days:

```glql
display: heatMap
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: ideName, language
metrics: totalCount
```

To add a description above the grid:

```glql
display: heatMap
displayConfig:
  description: Code Suggestions accepted per language, by IDE.
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: ideName, language
metrics: acceptedCount
```

To show only the five busiest IDEs:

```glql
display: heatMap
displayConfig:
  description: Code Suggestions accepted per language, for the five busiest IDEs.
  maxColumns: 5
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: ideName, language
metrics: acceptedCount
```

Diverging bar chart

A diverging bar chart visualizes aggregated data from analytics mode as two metrics mirrored around a shared, centered category column. Bars for the first metric grow leftward from the center, and bars for the second metric grow rightward. Use a diverging bar chart to compare two metrics across categories when one metric can dwarf the other in absolute terms.

Each half of the chart is scaled independently, to its own largest bar. This means a category can be a small share of one metric and the bulk of the other, and both bars still fill their side of the chart. Because the two halves use different scales, bar lengths are comparable only within a half, never across the center.

A diverging bar chart requires:

• Analytics mode, set with mode: analytics.
• Exactly one value in dimensions to group results by.
• Exactly two metrics to plot (using the metrics parameter).

Anything other than exactly one dimension and exactly two metrics causes a validation error in the view.

Rows render in the order the query returns them. Use sort to control this order, because a diverging bar chart does not sort rows itself. Each metric’s values are formatted in that metric’s own unit, so you can pair a count with a rate.

The category column is a share of the chart’s width, so category labels that do not fit are truncated. In a narrow panel, keep category names short.

There is no displayConfig option for this display type.

Example

To compare the number of unique users against the total number of sessions for GitLab Duo Agent Platform, grouped by flow type, over the last 30 days:

```glql
display: divergingBarChart
mode: analytics
query: type = AgentPlatformSession and created >= -30d
dimensions: flowType
metrics: usersCount, totalCount
sort: totalCount desc
```

Dynamic descriptions

The stat, barList, and table display types support a dynamic description in analytics mode. Use a description to summarize the result in a sentence, alongside the visualization.

To describe the result, set description under displayConfig. A description can include %{metricName} placeholders, where metricName identifies a metric from metrics. GitLab replaces each placeholder with that metric’s value, formatted by that metric’s own unit. A placeholder that names a metric the query does not select shows a validation error. When a metric’s value is missing from the response, its placeholder renders as an em dash (—).

Metrics are always identified by key name, unless they are duplicated parameterized metrics, in which case they need an alias to be identified. For example, metrics: totalCount as "count" is still referenced as %{totalCount}, because the alias only sets the label. When the same metric appears twice with different parameters, as in metrics: durationQuantile(0.5) as "Median", durationQuantile(0.95) as "p95 duration", each alias becomes the key, so you reference them as %{Median} and %{p95 duration}.

For bar list and table, a description can’t use placeholders when the query has dimensions. This causes a validation error in the view: Description placeholders cannot be used with dimensions. A placeholder reads a single row, so with dimensions it would show one group’s value as if it covered every group. A description with no placeholders still works with dimensions.

For bar list and table, set hiddenMetrics under displayConfig to a list of metrics to leave out of the bars or columns. Name them the same way as placeholders. Naming a duplicated metric by its base name, such as durationQuantile, hides every copy of it. GitLab still runs those metrics, so the description can quote them. A hiddenMetrics value that isn’t a list, or a name that isn’t one of the query’s metrics, causes a validation error in the view. A bar list needs at least one metric left out of hiddenMetrics.

The description renders above the visualization. While the query loads, a description that contains placeholders stays hidden, so it never flashes em dashes for values it doesn’t have yet.

Example

To plot the median and 75th percentile time to merge for merge requests created by GitLab Duo, and quote how many merged without drawing a third bar:

```glql
display: barList
mode: analytics
query: type = MergeRequest and createdByDuo = true and merged >= -30d
metrics: timeToMergeQuantile(0.5) as "Median", timeToMergeQuantile(0.75) as "p75", throughputCount
displayConfig:
  description: "%{throughputCount} merged merge requests"
  hiddenMetrics: [throughputCount]
```

Pagination support

Display types available in any mode display the first page of results and provide a Load more action to fetch additional pages. For more information, see pagination.

Analytics mode aggregated visualizations such as charts and stats don’t provide a Load more action. They fetch every page of aggregated results automatically, up to a maximum of 1,000 rows.

If your query returns more than 1,000 aggregated rows, the visualization shows the first 1,000 rows. To see all your data, add filters to the query or group by fewer dimensions.

To show a single page instead, set limit in the block. The visualization then shows at most that many rows, up to a maximum of 100.