Tree queries and search

Tree queries pick rows by where they sit in a hierarchy. This page covers the language, query mode, finding a hierarchy's issues in Jira search, and the workflow rules built on it.

The tree query language

A tree query combines conditions about a row's kind, position and content, and it is not case sensitive.

Combine conditions with not, and and or, in that order of precedence, and group them with parentheses. A relation applies to the condition right after it. Text takes double or single quotes, with \ to escape a quote.

Examples:

A query has at most 2,000 characters and 5 JQL conditions, and nests at most 32 levels deep (parentheses, relations and not each count as a level). When a query doesn't read, the message says what was expected and where. Jira checks each JQL part strictly first, so a misspelled field is an error instead of an empty result.

Where tree queries work

• Find rows: pick Tree query next to the find box. Matches update as you type. See Finding rows.
• Transforms: Keep rows matching a tree query keeps the matches and the rows above them. See Transforms.
• Columns: Matches a query… shows Yes or No for each row.
• Formulas: TQL{leaves} is true on the rows that match. See Formulas.
• Query mode, Jira search and workflow rules, below.

Query mode

Search issues, in the list on the left of the app's page, opens a temporary hierarchy from a query. Nothing is stored. Pick where to search with Search in:

• Jira: type text, issue keys or JQL. Keys become a list of those issues, a JQL query is used as written, and other words are searched as text. An empty box shows the issues you viewed recently. Tick With child issues to bring in their children.
• A hierarchy: pick a hierarchy and type a tree query. The matching rows open with the rows above them.

Select Show to run it. The result shows its first 500 rows and reads 500 more each time you scroll near the end. Columns, views, transforms, export and printing all work on it.

Save as hierarchy… keeps a Jira search as a new hierarchy made of rules, so it stays up to date. You can't save a tree query result this way, because a tree query isn't a rule. Open the hierarchy and use Find rows or a tree query transform instead.

Finding a hierarchy's issues in Jira search

People with Control can turn on Find its issues in Jira search on the Jira search tab of the hierarchy's settings. You can then find its issues anywhere Jira takes JQL, including issue search, filters, boards and dashboards:

issue in treecraftHierarchy(42)
issue in treecraftHierarchy("Product roadmap")
issue not in treecraftHierarchy(42)

The settings show the search by the hierarchy's number, which keeps working after a rename. Search by name works while the name is unique. The search finds the issues the hierarchy holds, whether someone placed them by hand or its rules placed them.

A second argument narrows the search to part of the tree, with a tree query:

issue in treecraftHierarchy(42, "children of key = PLAN-1")

In Jira search, a tree query may use only positions in the tree and issue keys: kinds, top, leaves, level, row, key and the relations. Jira search refuses jql and text conditions. A tree query names at most 50 issue keys, and a hierarchy keeps at most 10 different tree queries for search. People with Control see the tree queries people searched with, on the same tab, and can clear any of them. A saved filter that used a cleared query then says it was cleared.

Jira keeps search results for a while, so a change to the hierarchy can take a few minutes to show in search. A tree query used for the first time finds nothing until its issues are worked out, usually within a minute.

What turning on search reveals

Anyone who can search Jira can use this search, including people who can't open the hierarchy. Jira still shows them only the issues they may browse, but they can tell that those issues are in the hierarchy and where they sit in it, and they can test issue keys they guess with a tree query. They never see the details of issues they can't browse. For this reason search is off until someone with Control turns it on, and the settings say so when you do.

Query troubleshooting

When a search finds less than you expect, open Help and select Query troubleshooting. Pick the hierarchy, type the tree query if there is one, and select Check. The page tells you:

• the search to type in Jira;
• whether search is on for the hierarchy, and whether the tree query reads correctly, with where it stops if it doesn't;
• whether Jira search has used this tree query before, or whether it is new;
• the JQL and issue keys the query uses.

Try it in Jira asks Jira, as you, how many issues it finds. Anyone who can view the hierarchy can use this page. Jira admins and app admins also see how far the search index has come: how many issues the hierarchy holds, how many Jira search finds now, and how many are still to add or remove.

Workflow condition and validator

Jira admins can use a hierarchy in a workflow. Both rules are named Issue is in a hierarchy in Jira's workflow editor:

• The condition shows a transition only for issues in, or not in, the chosen hierarchy. All it does is hide the transition.
• The validator refuses the transition for issues that don't match and shows a message saying so. Add it when you want to enforce the rule.

Only hierarchies with Jira search turned on can be chosen. An optional tree query limits the rule to part of the hierarchy, with the same restrictions as in Jira search: positions and keys only, and at most 50 keys. While a hierarchy's search is off, no issue counts as in it. If someone with Control clears a tree query that a workflow rule uses, the validator refuses its transition until a Jira admin sets it up again. The hierarchy's settings mark such queries as Used by a workflow rule.

Questions about the app? Write to info@plugincraft.ca.