TQL For JQL Users

For users of Jira who are familiar with JQL, for the most part you should find TQL fairly similar - but there are some key differences which can trip up new users, which we list here to help users transition between querying in the two products.

Why is it different

When developing TQL we looked at JQL and took the parts which suited Enterprise Tester as a product, but we had a number of additional key features we wished to develop such as aggregations, sub-selects (because of relationships and other complex queries that Enterprise Tester users want to compose). Or where the underlying mechanics of the applications differ (for example Enterprise Tester uses Guid's and a hierarchical structure for organising data which contrasts with the use of integer ID's in Jira and a flatter data structure, where you are primarily querying on a single type of entity "Issues").

Our main aim was to make the core experience of writing Terminal Expressions (or what JQL calls Terminal clauses) largely the same, one of our primary goals was to ensure that jira users don't need to learn an entirely new query language to start becoming productive in TQL.

Differences

Lists of values (IN)

Within JQL parentheses (round brackets) are used when writing a query to match a list of values:

Assignee in (joeb, janed)

In TQL, we use square brackets for lists:

AssignedTo IN [joeb, janed]

We had a number of reasons for this choice, but it largely came down to:

  • Readability (especially when using functions in the values list, or sub-selects)
  • Avoiding confusion when writing complex aggregated queries (which use functions and round parentheses heavily)
  • Familiarity to developers used to working with languages that support arrays.

IN/NOT IN statements within TQL also (in some cases) support sub-selects e.g.:

EntityType = Requirement AND Relationships IN { RelatedToEntityType = Script }

Which again does not use parentheses to keep sub-selects seperate from lists of values or groups of terminal expressions.

Empty/Null

We support the JQL statements:

Field is empty

And:

Field is null

But TQL does not currently support:

Field = empty

And:

Field = null

In these cases empty and null will be treated as string values.

String Encoding

The rules for encoding/escaping strings in TQL are not exactly the same as JQL, TQL follows the JSON standard for string encoding currently. This means we do use backslash escaping, but that the following characters can be escaped through the use of a backslash:

  • " (quotation mark)
  • \ (back slash)
  • / (forward slash
  • \b (back space)
  • \f (form feed)
  • \r (carriage return)
  • \t (tab)
  • \uXXXX (hex code, where XXXX is hexadecimal)

Unquoted Values

In TQL the following characters are allowed in unquoted values, where an unquoted value is a single-word value which you don't need to surround in single (') or double (") quotes.

  • Letters (A-Z, a-z)
  • Digits (0-9)
  • Underscores (_)
  • Dashes (-)
  • Period (.)
  • Colon (:)
  • At sign (@)
  • Percent sign (%)
  • Hash (#)

Within JQL some of the above characters are reserved - Period (.), Percent (%), Hash (#) and the at sign (@) - which means when translating queries from TQL to JQL, those values would need to be quoted to be valid values.

Reserved Words

JQL has a relatively small set of reserved words. Enterprise Tester on the other hand has a relatively large set of reserved words, and we prevent custom fields from being named in a way that would conflict with those Reserved words.

The list of reserved words can be viewed from the Admin -> Search -> Indexing -> Reserved Words screen.

Also in Enterprise Tester we don't differentiate between in-built fields and custom fields when it comes to naming - you reference custom fields in queries only by name, never by their unique ID (so there is no support for the JQL style custom field naming e.g. cf[10301]).

Filter

The Filter field in JQL is called "Query" within Enterprise Tester, see the the Query field topic for more details.

Aggregations

In TQL a query can be prefixed with one or more aggregation functions followed by a WHERE statement - when the query includes aggregation functions, it's results view will switch from a grid to a tree, as there is no limit to how deeply nested the set of aggregation functions may be.

Aggregation/Summary query support in Enterprise Tester is an exciting feature of Enterprise Tester 4.0, and is the underlying technology which drives the new dashboard portlet graphs.

See the Aggregations Topic for more details.

  • No labels