← Querykin
DocumentationPrivacyEULASupport

Querykin documentation

Querykin adds seven functions to JQL in Jira Cloud. Use them anywhere Jira takes JQL: the work item search, saved filters, boards, dashboards, automation and exports. There is nothing to set up after installing.

The functions

Arguments that are queries go in double quotes. Inside them, use single quotes: childrenOfQuery("status = 'In Progress'").

childrenOfQuery("query", levels)

Sub-tasks and child work items of everything the query finds. This is how you filter children by a field of their parent.

  • issue in childrenOfQuery("type = Epic AND fixVersion = 2.0"): every story under the epics planned for 2.0.
  • issue in childrenOfQuery("project = MOB AND type = Epic", 2): stories and their sub-tasks.
  • levels is optional: 1 (default) to 5, or "all" for 5.
  • Limit: up to 1,000 parents across all levels. Children are not capped.

parentsOfQuery("query", levels)

Parents of everything the query finds.

  • issue in parentsOfQuery("type = Bug AND priority = Highest")
  • issue in parentsOfQuery("type = Sub-task AND assignee = 5b10ac8d82e05b22cc7d4ef5", "all")
  • Limit: reads up to 5,000 matching work items, returns up to 1,000 parents.

withChildren("scope") and withoutChildren("scope")

Work items in the scope that have (or don't have) at least one sub-task or child.

  • issue in withoutChildren("type = Epic AND statusCategory != Done"): open epics with nothing under them.
  • issue in withChildren("project = WEB AND type = Story")
  • Limit: scopes up to 20,000 work items with up to 10,000 children between them. withChildren returns up to 1,000; withoutChildren is not capped (it can exclude up to 1,000 parents).
  • withoutChildren works with in only; for the opposite use withChildren.

linkedToQuery("query", "link")

Work items linked to anything the query finds.

  • issue in linkedToQuery("project = SUP AND statusCategory != Done"): everything linked to an open support ticket.
  • link is optional. A link type name such as "Relates" means both directions. The wording you see on the work item, such as "is blocked by", "clones" or "is implemented by", means that one direction: linkedToQuery("fixVersion = 3.1", "is implemented by") finds the work items that 3.1 work "is implemented by".
  • Limit: reads links on up to 5,000 matching work items, returns up to 1,000.

blockedByQuery("blockers", "scope") and blockingQuery("blocked", "scope")

  • issue in blockedByQuery(): work still waiting on a blocker that is not done. A blocker that is done no longer counts.
  • issue not in blockedByQuery("", "project = WEB") AND project = WEB AND statusCategory = "To Do": WEB work that is ready to start.
  • issue in blockedByQuery("project = OPS"): work blocked by anything in OPS, done or not.
  • issue in blockingQuery() AND assignee is EMPTY: unassigned work holding others up.
  • Both arguments are optional. The scope narrows the side being returned.
  • They use the link type named "Blocks". A Jira admin can pick another type in Jira settings > Apps > Querykin > Settings.
  • Limit: reads links on up to 5,000 work items that have a blocker (or block something), returns up to 1,000.

Combining and nesting

Put one function inside another's query: issue in childrenOfQuery("issue in blockedByQuery()") finds the children of blocked work.

Functions that depend on who is searching (currentUser(), watchedIssues(), issueHistory() and similar) can't go inside an argument, because Jira shares a function's result with everyone who runs it. Put them outside: issue in childrenOfQuery("type = Epic") AND assignee = currentUser(). Querykin tells you this if you try.

How fresh are results?

Jira stores each function's answer. Querykin refreshes every stored answer a couple of minutes after work items or links change (Jira admins can choose 1, 2, 5 or 15 minutes) and once an hour, so relative dates such as updated >= -1d inside an argument keep moving too. There is no index to build: results are right from the first search after installing.

Limits and what happens at a limit

Jira lets an app function return at most 1,000 values and gives it 25 seconds. When a function would pass a limit, Querykin answers with an error that gives the real count and how to narrow the query. It never returns a partial list without telling you. Narrow with a project, type, fixVersion or date, or split the search into two clauses joined with OR.

Permissions

Querykin reads as the app to work out the answer, then Jira applies each person's own permissions to the final results: nobody sees work items they couldn't see already. Querykin never edits work items, links or fields.

Admin page

Jira settings > Apps > Querykin:

  • Settings: link type for the blocker functions; how soon to refresh after a change.
  • Stored results: every distinct function call used in the last 7 days and what Jira currently uses for it, with Refresh all now.
  • Refreshes: when results were last refreshed, why, how many changed, how long it took.

Apps > Querykin

Every function with examples you can run, and a Try a query box that runs as you.

Subscription

When the subscription or trial ends, the functions answer with a renewal message instead of results, and stored results are replaced with the same message within an hour. Renewing brings real results back on the next refresh.

Support

hello@greatwork.company, or the Great Work help desk. First response within one business day.