New API for parsing JQL queries in Jira Cloud

Hi everyone,

We’ve just released a new API in Jira Cloud: Parse JQL query.

As the name suggests, it can parse a JQL query and return its abstract syntax tree. We believe it will be useful if you need to do any kind of analysis or processing of JQL queries.

10 Likes

Hello Krzysztof,
thanks a lot for providing the JQL parse API! It is very helpful and will replace some of our own parsing we’ve done in the past.

However, the “orderBy” property of the response doesn’t seem to be correct in some cases. For example, the default ordering of priority and date fields (created/updated) is DESC, yet if I send a request with a JQL of “ORDER BY priority” the “orderBy” property reports a direction of “asc”. However, when showing issues within the /issues/ browser in Jira Cloud (or using the /rest/api/2/search API), “ORDER BY priority” is the same as “ORDER BY priority DESC”.

Could the JQL parse API be enhanced to reflect the same ordering as the issue browser and the /rest/api/2/search API?

Thanks for your feedback, @ben2. The parser currently always returns DESC by default, even if no ordering was provided in the original query. This is actually wrong, it should not return any direction in this case.

It would be good if the parser could return the correct direction, even for the default case (rather than omitting it entirely). Our use case is that we want to allow ordering of columns in a list of issues. We’d like to show the arrow (pointing up or down) on the column the list is sorted on. The JQL for the list of issues is given by the user and might not include the direction (ASC/DESC), so we have to know that the default direction for fields like priority is DESC, and for fields like assignee is ASC. We’d rather ask the JQL parser API for the actual direction than having to remember all the special cases where the default direction is DESC in our code.

I get what you’re saying, but I’m afraid this is out of scope of the parser. It’s supposed to return a syntax tree of the query, not information on how to interpret it.

It should be easy enough to hardcode the default directions in your app. Or you can compare the actual results for each column and figure out the direction on the fly. That would save you an additional network call to the parser API.

Good to know, thanks a lot for your swift response!

Comparing the actual results is an interesting idea, but might not always be possible, e.g. if all results have the same priority which isn’t that uncommon. But probably hardcoding is good enough for now, it seems to affect only a few fields (e.g. custom date fields seem to be ASC by default and only created/updated/duedate are DESC by default). I’ll keep digging :slight_smile:

Hi @kkercz, would it be possible to add in some information about the type of a field reference? E.g. for this query “assignee = ‘Jon Bevan’ AND project = FOO” we would get the following response?

    "structure": {
        "where": {
          "clauses": [
            {
              "field": {
                "name": "assignee",
                "type": "user"
              },
              "operator": "=",
              "operand": {
                "value": "Jon Bevan"
              }
            },
            {
              "field": {
                "name": "project",
                "type": "project"
              },
              "operator": "=",
              "operand": {
                "value": "FOO"
              }
            }
          ],
          "operator": "and"
        }
      }

That seems to be redundant, since you can get the type of each field with the /rest/api/2/field API. For example, this is what’s returned for “assignee”:

  {
    "id": "assignee",
    "key": "assignee",
    "name": "Assignee",
    "custom": false,
    "orderable": true,
    "navigable": true,
    "searchable": true,
    "clauseNames": [
      "assignee"
    ],
    "schema": {
      "type": "user",
      "system": "assignee"
    }
  }

You can see that the type is user.