diff --git a/doc/user/glql/fields.md b/doc/user/glql/fields.md new file mode 100644 index 0000000000000000000000000000000000000000..67dfda746a31b2906314ca6c78f38a50af06990a --- /dev/null +++ b/doc/user/glql/fields.md @@ -0,0 +1,1034 @@ +--- +stage: Plan +group: Knowledge +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GLQL fields + +DETAILS: +**Tier:** Free, Premium, Ultimate +**Offering:** GitLab.com, GitLab Self-Managed +**Status:** Experiment + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default. +> - Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects. +> - `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6. + +FLAG: +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. + +In a GitLab Query Language (GLQL) [query](index.md#query-syntax), a field is the leftmost part +of the expression. +In queries, fields follow the syntax of ` and ...`, + +In a [GLQL view](index.md#glql-views), fields are included as a comma-separated list of tokens in +the `fields:` option. + +This page lists fields available to use as filters when querying issues or work items. + +## Type + +**Field name**: `type` + +**Allowed operators**: `=`, `in` + +**Allowed value types**: + +- `Enum` (one of `Issue`, `Incident`, `TestCase`, `Requirement`, `Task`, `Ticket`, `Objective`, + `KeyResult`, `Epic`, or `MergeRequest`) +- `List` (containing one or more `enum` values above) + +**Allowed in columns of a GLQL view**: Only for issue and work item types. + +**Additional details**: + +- If omitted when used inside a GLQL view, all issue and work item types are included by default. +- Work item types (like `Issue`, `Task`, or `Objective`) cannot be used together with `MergeRequest` types. +- The type field isn't allowed in columns of a GLQL view for `MergeRequest` types. + +**Examples**: + +- List issues of type `Incident`: + + ```plaintext + type = incident + ``` + +- List issues of types `Issue` or `Task`: + + ```plaintext + type in (Issue, Task) + ``` + +- List all merge requests assigned to the current user: + + ```plaintext + type = MergeRequest and assignee = currentUser() + `` + +## Approved by user + +**Field name**: `approver` + +**Allowed operators**: `=`, `!=` + +**Allowed value types**: + +- `String` +- `User` (for example, `@username`) +- `List` (containing `String` or `User` values) +- `Nullable` (either of `null`, `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: `MergeRequest` + +**Examples**: + +- List all merge requests approved by current user and `@johndoe` + + ```plaintext + type = MergeRequest and approver = (currentUser(), @johndoe) + ``` + +## Assignees + +**Field name**: `assignee` + +**Allowed operators**: `=`, `in`, `!=` + +**Allowed value types**: + +- `String` +- `User` (for example, `@username`) +- `List` (containing `String` or `User` values) +- `Nullable` (either of `null`, `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Examples**: + +- List all issues where assignee is `@johndoe`: + + ```plaintext + assignee = @johndoe + ``` + +- List all issues where assignees are both `@johndoe` and `@janedoe`: + + ```plaintext + assignee = (@johndoe, @janedoe) + ``` + +- List all issues where assignees are either of `@johndoe` or `@janedoe`: + + ```plaintext + assignee in (@johndoe, @janedoe) + ``` + +- List all issues where assignee is neither of `@johndoe` or `@janedoe`: + + ```plaintext + assignee != (@johndoe, @janedoe) + ``` + +- List all merge requests where assignee is `@johndoe`: + + ```plaintext + type = MergeRequest and assignee = @johndoe + ``` + +**Additional details:** + +- `List` values and the `in` operator are not supported for `MergeRequest` types. + +## Author + +**Field name**: `author` + +**Allowed operators**: `=`, `in`, `!=` + +**Allowed value types**: + +- `String` +- `User` (for example, `@username`) +- `List` (containing `String` or `User` values) +- `Nullable` (either of `null`, `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Additional details**: + +- Because an issue can have only one author, the `=` operator cannot be used with `List` type for + the `author` field. +- `List` values and the `in` operator are not supported for `MergeRequest` types. + +**Examples**: + +- List all issues where author is `@johndoe`: + + ```plaintext + author = @johndoe + ``` + +- List all issues where author is either of `@johndoe` or `@janedoe`: + + ```plaintext + author in (@johndoe, @janedoe) + ``` + +- List all issues where author is neither of `@johndoe` or `@janedoe`: + + ```plaintext + author != (@johndoe, @janedoe) + ``` + +- List all merge requests where author is `@johndoe`: + + ```plaintext + type = MergeRequest and author = @johndoe + ``` + +## Cadence + +**Field name**: `cadence` + +**Allowed operators**: `=`, `in`, `!=` + +**Allowed value types**: + +- `Number` (only positive integers) +- `List` (containing `Number` values) +- `Nullable` (either of `none`, or `any`) + +**Allowed in columns of a GLQL view**: No + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Additional details**: + +- Because an issue can have only one iteration, the `=` operator cannot be used with `List` type for the `cadence` field. + +**Examples**: + +- List all issues with iteration that are a part of cadence ID `123456`: + + ```plaintext + cadences = 123456 + ``` + +- List all issues with iterations that are a part of any cadences `123` or `456`: + + ```plaintext + cadence in (123, 456) + ``` + +## Closed at + +**Field name**: `closed` + +**Allowed operators**: `=`, `>`, `<` + +**Allowed value types**: + +- `AbsoluteDate` (in the format `YYYY-MM-DD`) +- `RelativeDate` (in the format ``, where sign is `+`, `-`, or omitted, + digit is an integer, and `unit` is one of `d` (days), `w` (weeks), `m` (months) or `y` (years)) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Additional details**: + +- For the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all issues closed since yesterday: + + ```plaintext + closed > -1d + ``` + +- List all issues closed today: + + ```plaintext + closed = today() + ``` + +- List all issues closed in the month of February 2023: + + ```plaintext + closed > 2023-02-01 and closed < 2023-02-28 + ``` + +## Confidential + +**Field name**: `confidential` + +**Allowed operators**: `=`, `!=` + +**Allowed value types**: + +- `Boolean` (either of `true` or `false`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Additional details**: + +- Confidential issues queried using GLQL are only visible to people who have permission to view them. + +**Examples**: + +- List all confidential issues: + + ```plaintext + confidential = true + ``` + +- List all issues that are not confidential: + + ```plaintext + confidential = false + ``` + +## Created at + +**Field name**: `created` + +**Allowed operators**: `=`, `>`, `<` + +**Allowed value types**: + +- `AbsoluteDate` (in the format `YYYY-MM-DD`) +- `RelativeDate` (in the format ``, where sign is `+`, `-`, or omitted, + digit is an integer, and `unit` is one of `d` (days), `w` (weeks), `m` (months) or `y` (years)) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequests` + +**Additional details**: + +- For the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all issues that were created in the last week: + + ```plaintext + created > -1w + ``` + +- List all issues created today: + + ```plaintext + created = today() + ``` + +- List all issues created in the month of January 2025 that are still open: + + ```plaintext + created > 2025-01-01 and created < 2025-01-31 and state = opened + ``` + +## Deployed at + +**Field name**: `deployed` + +**Allowed operators**: `=`, `>`, `<` + +**Allowed value types**: + +- `AbsoluteDate` (in the format `YYYY-MM-DD`) +- `RelativeDate` (in the format ``, where sign is `+`, `-`, or omitted, + digit is an integer, and `unit` is one of `d` (days), `w` (weeks), `m` (months) or `y` (years)) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: `MergeRequest` + +**Additional details**: + +- For the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all merge requests that have been deployed in the past week: + + ```plaintext + type = MergeRequest and deployed > -1w + ``` + +- List all merge requests that have been deployed in the month of January 2025: + + ```plaintext + type = MergeRequest and deployed > 2025-01-01 and deployed < 2025-01-31 + ``` + +## Draft + +**Field name**: `draft` + +**Allowed operators**: `=`, `!=` + +**Allowed value types**: + +- `Boolean` (either of `true` or `false`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: `MergeRequest` + +**Examples**: + +- List all draft merge requests: + + ```plaintext + type = MergeRequest and draft = true + ``` + +- List all merge requests that are not in draft state: + + ```plaintext + type = MergeRequest and draft = false + ``` + +## Due date + +**Field name**: `due` + +**Allowed operators**: `=`, `>`, `<` + +**Allowed value types**: + +- `AbsoluteDate` (in the format `YYYY-MM-DD`) +- `RelativeDate` (in the format ``, where sign is `+`, `-`, or omitted, + digit is an integer, and `unit` is one of `d` (days), `w` (weeks), `m` (months) or `y` (years)) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Additional details**: + +- For the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all issues due in a week: + + ```plaintext + due < 1w + ``` + +- List all issues that were overdue as of January 1, 2025: + + ```plaintext + due < 2025-01-01 + ``` + +- List all issues that are due today (but not due yesterday or tomorrow): + + ```plaintext + due = today() + ``` + +- List all issues that have been overdue in the last 1 month: + + ```plaintext + due > -1m and due < today() + ``` + +## Environment + +**Field name**: `environment` + +**Allowed operators**: `=` + +**Allowed value types**: `String` + +**Allowed in columns of a GLQL view**: No + +**Supported for object types**: `MergeRequest` + +**Examples**: + +- List all merge requests that have been deployed to environment `production`: + + ```plaintext + environment = "production" + ``` + +## Group + +**Field name**: `group` + +**Allowed operators**: `=` + +**Allowed value types**: `String` + +**Allowed in columns of a GLQL view**: No + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Additional details**: + +- Only one group can be queried at a time. +- The `group` cannot be used together with the `project` field. +- If omitted when using inside a GLQL view in a group object (like an epic), `group` is assumed to + be the current group. +- Using the `group` field queries all objects in that group, all its subgroups, and child projects. + +**Examples**: + +- List all issues in the `gitlab-org` group and any of its subgroups: + + ```plaintext + group = "gitlab-org" + ``` + +- List all Tasks in the `gitlab-org` group and any of its subgroups: + + ```plaintext + group = "gitlab-org" and type = Task + ``` + +## Health status + +**Field name**: `health` + +**Allowed operators**: `=` + +**Allowed value types**: + +- `StringEnum` (one of `"needs attention"`, `"at risk"` or `"on track"`) +- `Nullable` (either of `null`, `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Examples**: + +- List all issues that don't have a health status set: + + ```plaintext + health = any + ``` + +- List all issues where the health status is "needs attention": + + ```plaintext + health = "needs attention" + ``` + +## ID + +**Field name**: `id` + +**Allowed operators**: `=`, `in` + +**Allowed value types**: + +- `Number` (only positive integers) +- `List` (containing `Number` values) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Examples**: + +- List issue with ID `123`: + + ```plaintext + id = 123 + ``` + +- List issues with IDs `1`, `2`, or `3`: + + ```plaintext + id in (1, 2, 3) + ``` + +- List all merge requests with IDs `1`, `2`, or `3`: + + ```plaintext + type = MergeRequest and id in (1, 2, 3) + ``` + +## Iteration + +**Field name**: `iteration` + +**Allowed operators**: `=`, `in`, `!=` + +**Allowed value types**: + +- `Number` (only positive integers) +- `Iteration` (for example, `*iteration:123456`) +- `List` (containing `Number` or `Iteration` values) +- `Enum` (only `current` is supported) +- `Nullable` (either of `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Additional details**: + +- Because an issue can have only one iteration, the `=` operator cannot be used with `List` type for the `iteration` field. +- The `in` operator is not supported for `MergeRequest` types. + +**Examples**: + +- List all issues with iteration ID `123456` (using a number in the query): + + ```plaintext + iteration = 123456 + ``` + +- List all issues that are a part of iterations `123` or `456` (using numbers): + + ```plaintext + iteration in (123, 456) + ``` + +- List all issues with iteration ID `123456` (using iteration syntax): + + ```plaintext + iteration = *iteration:123456 + ``` + +- List all issues that are a part of iterations `123` or `456` (using iteration syntax): + + ```plaintext + iteration in (*iteration:123, *iteration:456) + ``` + +- List all issues in the current iteration + + ```plaintext + iteration = current + ``` + +## Labels + +**Field name**: `label` + +**Allowed operators**: `=`, `in`, `!=` + +**Allowed value types**: + +- `String` +- `Label` (for example, `~bug`, `~"team::planning"`) +- `List` (containing `String` or `Label` values) +- `Nullable` (either of `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Additional details**: + +- Scoped labels, or labels containing spaces must be wrapped in quotes. +- The `in` operator is not supported for `MergeRequest` types. + +**Examples**: + +- List all issues with label `~bug`: + + ```plaintext + label = ~bug + ``` + +- List all issues not having label `~"workflow::in progress"`: + + ```plaintext + label != ~"workflow::in progress" + ``` + +- List all issues with labels `~bug` and `~"team::planning"`: + + ```plaintext + label = (~bug, ~"team::planning") + ``` + +- List all issues with labels `~bug` or `~feature`: + + ```plaintext + label in (~bug, ~feature) + ``` + +- List all issues where the labels include neither of `~bug` or `~feature`: + + ```plaintext + label != (~bug, ~feature) + ``` + +- List all issues where none of the scoped labels apply, with scope `workflow::`: + + ```plaintext + label != ~"workflow::*" + ``` + +- List all merge requests with labels `~bug` and `~"team::planning"` + + ```plaintext + type = MergeRequest and label = (~bug, ~"team::planning") + ``` + +## Merged at + +**Field name**: `merged` + +**Allowed operators**: `=`, `>`, `<` + +**Allowed value types**: + +- `AbsoluteDate` (in the format `YYYY-MM-DD`) +- `RelativeDate` (in the format ``, where sign is `+`, `-`, or omitted, + digit is an integer, and `unit` is one of `d` (days), `w` (weeks), `m` (months) or `y` (years)) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: `MergeRequest` + +**Additional details**: + +- For the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all merge requests that have been merged in the last 6 months: + + ```plaintext + type = MergeRequest and merged > -6m + ``` + +- List all merge requests that have been merged in the month of January 2025: + + ```plaintext + type = MergeRequest and merged > 2025-01-01 and merged < 2025-01-31 + ``` + +## Merged by user + +**Field name**: `merger` + +**Allowed operators**: `=` + +**Allowed value types**: + +- `String` +- `User` (for example, `@username`) +- `List` (containing `String` or `User` values) +- `Nullable` (either of `null`, `none`, or `any`) + +**Allowed in columns of a GLQL view**: No + +**Supported for object types**: `MergeRequest` + +**Examples**: + +- List all merge requests merged by the current user: + + ```plaintext + type = MergeRequest and merger = currentUser() + ``` + +## Milestone + +**Field name**: `milestone` + +**Allowed operators**: `=`, `in`, `!=` + +**Allowed value types**: + +- `String` +- `Milestone` (for example, `%Backlog`, `%"Awaiting Further Demand"`) +- `List` (containing `String` or `Milestone` values) +- `Nullable` (either of `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Additional details**: + +- Milestones containing spaces must be wrapped in quotes (`"`). +- Because an issue can have only one milestone, the `=` operator cannot be used with `List` type for the `milestone` field. +- The `in` operator is not supported for `MergeRequest` types. + +**Examples**: + +- List all issues with milestone `%Backlog`: + + ```plaintext + milestone = %Backlog + ``` + +- List all issues with milestones `%17.7` or `%17.8`: + + ```plaintext + milestone in (%17.7, %17.8) + ``` + +- List all issues in an upcoming milestone: + + ```plaintext + milestone = upcoming + ``` + +- List all issues in a current milestone: + + ```plaintext + milestone = started + ``` + +- List all issues where the milestone is neither of `%17.7` or `%17.8`: + + ```plaintext + milestone != (%17.7, %17.8) + ``` + +## Project + +**Field name**: `project` + +**Allowed operators**: `=` + +**Allowed value types**: `String` + +**Allowed in columns of a GLQL view**: No + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Additional details**: + +- Only one project can be queried at a time. +- The `project` field cannot be used together with the `group` field. +- If omitted when using inside a GLQL view, `project` is assumed to be the current project. + +**Examples**: + +- List all issues and work items in the `gitlab-org/gitlab` project: + + ```plaintext + project = "gitlab-org/gitlab" + ``` + +## Reviewers + +**Field name**: `reviewer` + +**Allowed operators**: `=`, `!=` + +**Allowed value types**: + +- `String` +- `User` (for example, `@username`) +- `List` (containing `String` or `User` values) +- `Nullable` (either of `null`, `none`, or `any`) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: `MergeRequest` + +**Examples**: + +- List all merge requests reviewed by current user and `@johndoe` + + ```plaintext + type = MergeRequest and reviwer = (currentUser(), @johndoe) + ``` + +## State + +**Field name**: `state` + +**Allowed operators**: `=` + +**Allowed in columns of a GLQL view**: Yes + +**Allowed value types**: + +- `Enum` + - For issue and work item types, one of `opened`, `closed`, or `all` + - For `MergeRequest` types, one of `opened`, `closed`, `merged`, or `all` + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequest` + +**Additional details**: + +- The `state` field does not support the `!=` operator. + +**Examples**: + +- List all closed issues: + + ```plaintext + state = closed + ``` + +- List all open issues: + + ```plaintext + state = opened + ``` + +- List all issues regardless of their state (also the default): + + ```plaintext + state = all + ``` + +- List all merged merge requests: + + ```plaintext + type = MergeRequest and state = merged + ``` + +## Updated at + +**Field name**: `updated` + +**Allowed operators**: `=`, `>`, `<` + +**Allowed value types**: + +- `AbsoluteDate` (in the format `YYYY-MM-DD`) +- `RelativeDate` (in the format ``, where sign is `+`, `-`, or omitted, + digit is an integer, and `unit` is one of `d` (days), `w` (weeks), `m` (months) or `y` (years)) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` +- `MergeRequests` + +**Additional details**: + +- For the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all issues that haven't been edited in the last 1 month: + + ```plaintext + updated < -1m + ``` + +- List all issues that were edited today: + + ```plaintext + updated = today() + ``` + +- List all open MRs that haven't been edited in the last 1 week: + + ```plaintext + type = MergeRequest and state = opened and updated < -1w + ``` + +## Weight + +**Field name**: `weight` + +**Allowed operators**: `=`, `!=` + +**Allowed value types**: + +- `Number` (only positive integers) + +**Allowed in columns of a GLQL view**: Yes + +**Supported for object types**: + +- `Issue` +- Work item types like `Task` or `Objective` + +**Additional details**: + +- Comparison operators `<` and `>` cannot be used. + +**Examples**: + +- List all issues with weight 5: + + ```plaintext + weight = 5 + ``` + +- List all issues with weight not 5: + + ```plaintext + weight != 5 + ``` diff --git a/doc/user/glql/functions.md b/doc/user/glql/functions.md new file mode 100644 index 0000000000000000000000000000000000000000..fbf46920eb540d025239483ec9e4fef731a4bcdb --- /dev/null +++ b/doc/user/glql/functions.md @@ -0,0 +1,142 @@ +--- +stage: Plan +group: Knowledge +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GLQL functions + +DETAILS: +**Tier:** Free, Premium, Ultimate +**Offering:** GitLab.com, GitLab Self-Managed +**Status:** Experiment + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default. +> - Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects. +> - `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6. + +FLAG: +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. + +Use functions with [GitLab Query Language (GLQL)](index.md) to create dynamic queries. + +## Functions inside query + +To make a query context-specific, use functions inside a [query](index.md#query-syntax), for example, +by filtering by a current user or a date. + +### Current user + +**Function name**: `currentUser` + +**Parameters**: None + +**Syntax**: `currentUser()` + +**Description**: Evaluates to the current authenticated user. + +**Additional details**: + +- Using this function in a query makes the query fail for users who are not authenticated. + +**Examples**: + +- List all issues where the current authenticated user is the assignee: + + ```plaintext + assignee = currentUser() + ``` + +- List all merge requests where the current authenticated user is the assignee but not the author: + + ```plaintext + type = MergeRequest and assignee = currentUser() and author != currentUser() + ``` + +### Today + +**Function name**: `today` + +**Parameters**: None + +**Syntax**: `today()` + +**Description**: Evaluates to today's date at 00:00 in the user's time zone. + +**Additional details**: + +- When used with the `=` operator, the time range is considered from 00:00 to 23:59 in the user's time zone. + +**Examples**: + +- List all issues created today: + + ```plaintext + created = today() + ``` + +- List all merge requests merged today: + + ```plaintext + type = MergeRequest and merged = today() + ``` + +## Functions in GLQL views + +To derive a new column from an existing field of a [GLQL view](index.md#glql-views), include +functions in the `fields` parameter. + +### Extract labels into a new column + +**Function name**: `labels` + +**Parameters**: One or more `String` values + +**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 regular `labels` column, if you choose to display that column as well. + +**Additional details**: + +- By default, this function looks for an exact match to the label name. + A wildcard character (`*`) in the string to match any character. +- A minimum of 1 and maximum of 100 label names can be passed to the `labels` function. +- Label names passed to this function are case-insensitive. For example, `Deliverable` and `deliverable` are equivalent. + +**Examples**: + +- Include all `workflow` scoped labels in the column: + + ```plaintext + labels("workflow::*") + ``` + +- Include labels `Deliverable`, `Stretch`, and `Spike`: + + ```plaintext + labels("Deliverable", "Stretch", "Spike") + ``` + +- Include all labels like `backend`, `frontend`, and others that end with `end`: + + ```plaintext + labels("*end") + ``` + +To include the `labels` function in a GLQL view: + +````markdown +```glql +display: list +fields: title, health, due, labels("workflow::*"), labels +limit: 5 +query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true +``` +```` diff --git a/doc/user/glql/img/glql_table_v17_5.png b/doc/user/glql/img/glql_table_v17_5.png deleted file mode 100644 index 026d2a5e741e837abb33907fde32920de0cfd3ea..0000000000000000000000000000000000000000 Binary files a/doc/user/glql/img/glql_table_v17_5.png and /dev/null differ diff --git a/doc/user/glql/img/glql_table_v17_8.png b/doc/user/glql/img/glql_table_v17_8.png new file mode 100644 index 0000000000000000000000000000000000000000..ceb6b5ed3a6e962470af6e942b72468e2424c5ff Binary files /dev/null and b/doc/user/glql/img/glql_table_v17_8.png differ diff --git a/doc/user/glql/index.md b/doc/user/glql/index.md index 7919209025ed52738a358ad6cc0555448fb43c3d..4335e26541b0587be26f4a6e755b6afed4e39e9a 100644 --- a/doc/user/glql/index.md +++ b/doc/user/glql/index.md @@ -20,206 +20,134 @@ 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. +GitLab Query Language (GLQL) is an [experimental](../../policy/development_stages_support.md) 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. -This feature is an [experiment](../../policy/development_stages_support.md). -To test it: +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](https://gitlab.com/groups/gitlab-org/-/epics/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"`. +Share your feedback in [epic 14939](https://gitlab.com/groups/gitlab-org/-/epics/14939). -## Supported areas +## Query syntax -GLQL blocks are rendered in the following areas: +The query syntax consists primarily of logical expressions. These expressions follow the +syntax of ` and ...`. -- 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](../group/epics/epic_work_items.md)) and work item comments +### Fields -### Supported objects to query +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`. -GLQL can only query issues under a project or group. +For a full list of supported fields, supported operators, and value types, see [GLQL fields](fields.md). -## Syntax +### Operators -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/508956) in GitLab 17.7: Configuring the presentation layer using YAML front matter is deprecated. +**Comparison operators:** -The syntax of GLQL is a superset of YAML that consists of: +| 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 | **{dotted-circle}** No | +| `<` | Less than | **{dotted-circle}** No | -- The `query` parameter: Expressions joined together with a logical operator, such as `AND`. -- Parameters related to the presentation layer, like `display`, `limit`, `fields`. +**Logical operators**: Only `and` is supported. +`or` is indirectly supported for some fields by using the `in` comparison operator. -A GLQL block is defined in Markdown as a code block, similar to other code blocks like Mermaid. +### Values -For example: +Values can include: -> Display a table of first 5 open issues assigned to the authenticated user in `gitlab-org/gitlab`. -> Display columns `title`, `state`, `health`, `description`, `epic`, `milestone`, `weight`, and `updated`. - -````markdown -```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: +- Strings +- Numbers +- Relative dates (like `-1d`, `2w`, `-6m`, or `1y`) +- Absolute dates (in `YYYY-MM-DD` format, like `2025-01-01`) +- Functions (like `currentUser()` for user fields or `today()` for dates) +- Enum values (like `upcoming` or `started` for milestones) +- Booleans (`true` or `false`) +- Nullable values (like `null`, `none`, or `any`) +- 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: `,`) -![A table listing issues assigned to the current user](img/glql_table_v17_5.png) +## GLQL views -### Query syntax +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/508956) in GitLab 17.7: Configuring the presentation layer using YAML front matter is deprecated. -GLQL syntax consists primarily of logical expressions. -These expressions follow the syntax of ` [< | > | = | != | in] [AND] ...`. +A view created with GLQL is a display representation of a query that executes to +fetch the desired results. -**Field names** include `assignee`, `author`, `label`, and `milestone`. -For a full list of supported fields, see the table at the bottom of this section. +### Supported areas -**Comparison operators**: +Views can be embedded in the following areas: -| 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 | **{dotted-circle}** No | -| `<` | Less than | **{dotted-circle}** No | +- Group and project wikis +- Descriptions and comments of: + - Epics + - Issues + - Merge requests + - Work items (tasks, OKRs, epics [with the new look](../group/epics/epic_work_items.md)) -**Logical operators**: Only `AND` is supported. -`OR` is indirectly supported for some fields by using the `IN` comparison operator. +### Syntax -**Values**: Values can include: +The syntax of views is a superset of YAML that consists of: -- Strings -- Numbers -- Dates (relative or absolute) -- Functions (like `currentUser()` for assignee or `today()` for dates) -- Special tokens (like `upcoming` or `started` for milestones) +- The `query` parameter: Expressions joined together with a logical operator, such as `and`. +- Parameters related to the presentation layer, like `display`, `limit`, or `fields`. -The following table lists all supported fields and their value types: +A GLQL view is defined in Markdown as a code block, similar to other code blocks like Mermaid. -| Field | Operators | Values | Examples | -| ------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------- | -------- | -| `assignee`
`author` | `=`
`!=`
`in` | `String`
`Collection`
`currentUser()`
`any`
`none` | `assignee = "foobar"`
`assignee in ("foobar", "baz")`
`author = currentUser()`
`author = any`
`assignee = none` | -| `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` | `=`
`!=` | `String`
`any`
`none`
`started`
`upcoming` | `milestone = "17.4"`
`milestone = "Backlog"`
`milestone != none` | -| `iteration`
`cadence` | `=`
`!=` | `String`
`any`
`none`
`current` | `iteration = 123`
`cadence = 123`
`cadence = 123 and iteration = current` | -| `label` | `=`
`!=`
`in` | `String`
`Collection`
`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` | +For example: -#### Query shorthand syntax +> Display a table of first 5 open issues assigned to the authenticated user in `gitlab-org/gitlab`. +> Display columns `title`, `state`, `health`, `description`, `epic`, `milestone`, `weight`, and `updated`. -When querying multiple labels and assignees, you can also use the shorthand syntax to simplify the query. +````yaml +```glql +display: table +fields: title, state, health, epic, milestone, weight, updated +limit: 5 +query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true +``` +```` -For example: +This query should render a table like the one below: -| 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"` | +![A table listing issues assigned to the current user](img/glql_table_v17_8.png) -### Presentation syntax +#### Presentation syntax Aside from the `query` parameter, you can configure presentation details for your GLQL query using some more parameters. -Three parameters are supported: - -| 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. | - -Supported fields to display: - -- `assignees` -- `author` -- `closed` -- `created` -- `description` -- `due` -- `health` -- `iteration` -- `cadence` -- `labels` -- `milestone` -- `state` -- `title` -- `type` -- `updated` -- `weight` +Supported parameters: -For example: +| 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](fields.md). All fields allowed in columns of a GLQL view are supported. | -> Display first five issues assigned to current user in the `gitlab-org/gitlab` project as a list, -> displaying fields `title`, `health`, and `due`. +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`: -````markdown +````yaml ```glql ---- display: list fields: title, health, due limit: 5 ---- -project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true +query: 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 regular `labels` 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` and `deliverable` 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 all `workflow` scoped labels in the column. - - `labels("Deliverable", "Stretch", "Spike")`: Include labels `Deliverable`, `Stretch`, and `Spike`. - - `labels("*end")`: Include all labels like `backend`, `frontend`, and others that end with `end`. - - To include the function in the query, follow this example: - - ````markdown - ```glql - display: list - fields: title, health, due, labels("workflow::*"), labels - limit: 5 - query: project = "gitlab-org/gitlab" AND assignee = currentUser() AND opened = true - ``` - ```` - -## Known issues - -For a full list of known issues, see [epic 14437 "GitLab Query Language (GLQL) Strategy"](https://gitlab.com/groups/gitlab-org/-/epics/14437). +To create dynamically generated columns, use functions in the `fields` parameters in views. +For a full list, see [Functions in GLQL views](functions.md#functions-in-glql-views).