JQL Builder – Advanced Search — User guide
JQL Builder turns Jira's search language (JQL) into a form. Fill in the fields you care about and the app writes the JQL for you. You can see the query as you build it, check it, preview the results, and open it in Jira's own search.
Opening the app
- Apps in Jira's sidebar → JQL Builder – Advanced Search (under Your apps),
- the Jira command palette (
Ctrl/⌘ + K) → type JQL Builder, or - from Jira's own issue search: Apps → Open in JQL Builder, which brings the search's query with it.
The app needs no setup: install it and every user on the site can use it. Each user's saved and recent searches are private to them.
Building a search
- Fill in fields. The form is grouped into Common fields, Other fields and Custom fields; click a section title to expand or collapse it. Use Find a field (status, assignee…) to jump to a field by name. If the filter hides fields you have filled in, a line above the form says how many — they are still part of the query.
- Pick an operator for a row (for example
=,IN,~,IS EMPTY,WAS,CHANGED). The app remembers the operator you last used per field. - Choose how rows combine with Match: — all conditions (AND) or any condition (OR).
- Watch the JQL: line above the form. It updates as you type. Copy JQL in the row under it copies the query, for a board filter, a dashboard or an automation rule.
- Press Search to open the query in Jira's search, or Reset to start again. Reset says Form cleared. with an Undo button, in case you pressed it by mistake; the offer lasts until you next change the form.
To go straight to one work item, type its key (for example PROJ-1) in the
Work item key box at the top and press Go.
Per-row extras:
- Me sets a user field to
currentUser()— whoever runs the search, so a saved or shared search finds each person's own work items. - NOT excludes: the row then finds work items that do not match its
condition (in JQL,
NOT ( … )). - The More options button (three dots) shows the row's helper controls: date presets (Today, −7d, −30d …), date offsets, date functions, text-match modes and value browsers.
- The star pins a field so it appears under Pinned fields at the top.
- The cross clears the row.
- Suggestions appear as you type in fields such as labels, versions, sprints, custom select fields and work-item keys.
Query options holds the sort order (Sort by:, with an optional second key) and the linked-work-item condition builder.
Custom fields
Choose + Add custom field and pick any custom field on your site. It gets its own row with the operators that field type supports. Remove takes the row out of the form without changing the field in Jira.
Writing JQL directly
Choose Edit JQL to type or paste JQL yourself. Validate JQL checks it against your site, and Beautify JQL reformats it over several lines.
To leave the editor, Load into form fills the fields from your JQL (and says what, if anything, the form could not hold), while Cancel goes back to the query the fields build and discards what you typed — with an Undo to bring it back.
Hints
A Hint — line under the query points out JQL that runs but probably does
not do what you meant — for example that assignee != jsmith also leaves out
unassigned work items, or that a text search with no project scans every
project you can see. Hints never block anything; they disappear once the query
changes.
Checking results before you search
- Preview count shows roughly how many work items match, with a badge for how broad that is (no matches, focused, moderate, broad, very broad).
- Preview results shows the matching work items in a table (sortable columns, export as CSV, Markdown or an Automation JQL snippet, each with a Copy button) and an Analyze tab with a breakdown chart and a created-vs-resolved line per week. Its header says how many work items are loaded, and of roughly how many once you have pressed Preview count. A line under the table adds up Story Points, estimates and time spent over the loaded rows. Rows per page sets how many work items each Load more fetches; the table shows up to 50 at a time, and clicking a column header sorts the ones on screen. If you change the query while it is open, the table stays and says the results are for the previous query; Refresh runs the new one.
- If Jira refuses the query — a field or value that does not exist on your site — both previews say so in Jira's own words, the reason appears under the JQL: line as JQL error — …, and Search stays disabled until you change the query.
Starting points
- Templates offers ready-made searches such as My open work items or Unassigned in active sprints, followed by your site's own (marked Site, published by a Jira administrator) and your own custom templates. Loading one fills in the form; if it replaced a search you had, Undo brings that back.
- Import Jira filter loads a Jira filter, or a Jira search URL, into the form. Your own and starred filters are listed; type part of a name to search every filter shared with you.
Saving and sharing
The More menu has:
| Action | What it does |
|---|---|
| Search in new tab | Runs the search in a new browser tab, so the builder stays open in this one. |
| Save search | Saves the form under a name (up to 20 per user). Saving under a name you already used replaces that search — the dialog says so first. Mark a saved search as a template to list it under Templates (both the menu and the tab). In Edit JQL mode your JQL is loaded into the form first; if the form cannot hold all of it, nothing is saved and a message says why. |
| Save as Jira filter | Creates a normal Jira filter owned by you, shared with only you, everyone signed in, or a project (Share with). Using the name of a filter you already own replaces that filter's query instead — its sharing, subscriptions and boards are kept. |
| Import Jira filter | Loads a filter into the form (see above). |
| Export / Import config | Copies the whole form as text, or loads one someone sent you. |
| Back up saved searches | Copies all your saved searches as one piece of text. Paste it into Export / Import config (here or on another site) and press Restore searches: searches whose names you already use are skipped, never replaced. |
| Share JQL link | Gives a Jira search link for the current query. |
| Share full form link | Gives a link that opens this app with the same form filled in. |
| Explain JQL | Describes the current query in plain English — and, if Jira has already refused it, lists Jira's errors above the description. |
After you load a saved search (or save one), a line above the JQL says Editing saved search with its name, and whether the form has Unsaved changes. Update writes the form back to that search; Save as… saves a copy under a new name.
JQL & History opens a panel with the JQL tools and three tabs:
- Saved — your saved searches. Load fills the form, Run opens a search in Jira's issue navigator without loading it, Rename changes its name without touching the search itself, and Make template / Untemplate with Edit tags list it under Templates or take it off.
- Recent — your last 10 searches. Run one again, load it back into the form, save it, or clear the history.
- Templates — the built-in, site and custom templates in one table.
On a dashboard
Add the JQL Builder – Search overview gadget to a Jira dashboard to show a query's approximate count, how broad it is, and a pie or bar breakdown by status, assignee, priority or type. In the gadget's settings, type JQL or start from one of your saved searches; Save checks the query with Jira first.
Site templates (Jira administrators)
Jira settings → Apps → JQL Builder – Site templates lists the templates
everyone on the site sees. Add one with a name, optional description and tags,
and its JQL (Check JQL asks Jira whether it is valid). Write
currentUser() rather than naming a person — templates that name someone are
refused, as they are shared with everyone.
Settings
The ⚙ Settings menu has:
- Active fields only shows just the rows you have filled in.
- Compact view tightens the spacing.
- Show unsupported fields appears only when some fields don't exist on your site, for example Jira Service Management fields on a Jira-only site. Those fields are hidden by default.
- Language shows the app in another of its 26 languages. By default it follows the language of your Jira profile; changing it reloads the page and keeps your form. JQL itself (keywords, functions, operators) is never translated.
Permissions and privacy
The app acts as you. It sees only the projects and work items you can already see in Jira, and it changes Jira only when you choose Save as Jira filter. It sends no data outside Atlassian. See PRIVACY.md for what is stored and for how long.
Troubleshooting
| Symptom | Why / what to do |
|---|---|
| Search is disabled | Nothing is filled in yet, or Jira reported an error in the JQL — shown under the JQL: line. The message next to the button says which. |
| Count unavailable | Jira won't count queries with no conditions (for example, only a sort order). Add a condition. |
| A field is missing | It doesn't exist on your site. Turn on Show unsupported fields to see it anyway. |
| A custom field is missing from + Add custom field | Jira lists only custom fields that are on at least one screen. Ask your Jira admin to add the field to a screen. |
Support
Questions, bug reports, feature requests and data requests go to support@kashukov.com. Support hours are Monday–Friday, 9:00–18:00 GMT+2.
To get an answer faster, include:
- what you did and what happened instead, with a screenshot if you can;
- the JQL from the JQL: line, if the problem is about a search;
- your browser, and the language JQL Builder is shown in.
You can also ask and browse answers on the Atlassian Community — the link is on the app's Marketplace listing.