JIRA Query Language (JQL) for Technical Writers - vishdocs/My-Portfolio GitHub Wiki
1. Fields
Fields in JQL refer to the issue properties you can query. In this example, Filter, Component, and key are fields.
- Filter: Refers to the saved filter in Jira (in this case, filter ID 54467).
- Component: Refers to the issue component (e.g., Clearing, FX, etc.).
- key: Refers to the issue key (e.g., CAL-490160 or APL-7322).
2. Operators
Operators specify the comparison between the field and the value. These are essential in forming conditions.
- =: Equality operator. The left-hand side must equal the right-hand side.
- in: Checks if a field's value is one of the specified options.
- AND: Combines two or more conditions so that both must be true.
- ORDER BY: Used to sort the results.
3. Reserved Characters and Words
Certain symbols and words are reserved for specific functionalities in JQL.
- Parentheses (): Used to group values together in conditions. Example: (Clearing, FX, XVA, "FXOptions")
- Quotes "": Used for multi-word terms or special characters. Example: "FXOptions"
- ASC: Sorts results in ascending order.
- DESC: Sorts results in descending order.
4. Term Modifiers
Term modifiers refine searches and enhance precision.
- AND: Requires both conditions to be true.
- in: Allows checking if a field contains one or more values from a defined set. Example: Component in (Clearing, FX, XVA)
5. Functions
There are no direct functions in this example, but Filter = 54467 implies referencing a saved filter functionally.
Summary
| Component | Explanation |
|---|---|
| Fields | - Filter: A predefined search or query saved in Jira.- Component: The area or section within a project.- key: The unique issue identifier. |
| Operators | - =: Equality comparison.- in: Checks if a field matches any value from a set.- AND: Combines conditions.- ORDER BY: Sorts results. |
| Reserved Characters | - () for grouping.- "" for multi-word values.- ASC and DESC for sorting orders. |
| Term Modifiers | - AND: Requires both conditions to be true.- in: Checks for any match from a list of values. |
| Functions | No explicit functions available in this example. |
| Word Stemming | No automatic word stemming is applied. |
| Indicator | Meaning | Description |
|---|---|---|
| Green Tick | Valid Query | - The query is syntactically correct.- Jira successfully parsed the query and it is ready to be executed. |
| Red Error Message | Invalid Query | - There is a syntax or logical error in the query.- Jira cannot process the query until the error is fixed. |
| Warning Icon | Potential Issue (but still valid) | - The query is valid but may not return the expected results.- It often indicates suboptimal use of the query (e.g., deprecated fields or inefficient conditions). |
Detailed Explanation JQL: A simple query in JQL (also known as a “clause”) consists of a field, followed by an operator, followed by one or more values or functions. Fields: Criteria that you use to filter and search for issues.
| Assignee |
|---|
| Affected version |
| Attachments |
| Comment |
| Component |
| Created |
| Creator |
| Description |
| Due |
| Epic link |
| Filter |
| Fix version |
| Issue key |
| Labels |
| Last viewed |
| Priority |
| Project |
| Reporter |
| Resolved |
| Sprint |
| Status |
| Summary |
| Text |
| Time spent |
| Voter |
| Watcher |
| Custom field |
Operators: Used to refine searches by defining relationships between fields and their values.
| = |
|---|
| > |
| >= |
| ~ |
| in |
| is |
| was |
| was in |
| changed |
| != |
| < |
| <= |
| !~ |
| not in |
| is not |
| was not |
| was not in |
Functions: Reusable chunks of logic to simplify querying, such as pulling filters or dates. In this case, there are no direct functions, but Filter = 54467 implies referencing a saved filter functionally.
| startOfDay()/Week/Month/Year | Time |
|---|---|
| endOfDay()/Week/Month/Year | Time |
| lastLogin() | Time |
| now() | Time |
| currentLogin() | Time |
| currentUser() | People |
| membersOf() | People |
| issueHistory() | Issue |
| openSprints() | Issue |
| watchedIssues() | Issue |
| myApproval() | Issue |
| myPending() | Issue |
Reserved Characters:
| space (" ") | Represents a space character (" ") |
|---|---|
| + | Addition operator |
| . | Decimal point or object property access |
| , | Comma, used for separation |
| ; | Semicolon, used to separate statements |
| ? | Question mark |
| ` | ` |
| * | Multiplication operator or wildcard |
| / | Division operator |
| % | Modulus operator |
| ^ | Exponentiation operator |
| $ | Represents end of a string or currency |
| # | Hash or comment symbol |
| @ | At symbol, often used in email addresses or annotations |
| [ | Opening square bracket |
| ] | Closing square bracket |
Reserved words:
| a |
|---|
| and |
| are |
| as |
| at |
| be |
| but |
| by |
| for |
| if |
| in |
| into |
| is |
| it |
| no |
| not |
| of |
| on |
| or |
| s |
| such |
| t |
| that |
| the |
| their |
| then |
| there |
| these |
| they |
| this |
| to |
| was |
| will |
| with |
Term modifiers: Refine search terms further, allowing you to control how terms are matched in queries.
| Wildcard search | Replace single character with ? | e.g. te?t |
|---|---|---|
| Wildcard search | Replace multiple characters with * | e.g. win* |
| Proximity search | Add ~ and a number to the end of a phrase in quotes | e.g. text ~ '"Atlassian jira"~10' |
| Fuzzy search | Add ~ to the end of a single term | e.g. roam~ |
| Boost term | Add ^ with a boost factor (a number) to the end of a search term | e.g. atlassian^4 jira |
To Learn more, Refer visit Atlassian Site