Find Issues by Their Files (JQL)
File Field is fully searchable in Advanced search (JQL). You can filter issues by how many files are attached, what type they are, their file name, and their category — and each of these works like a built-in Jira field: it shows up in the JQL editor's suggestions, in saved filters and boards, and in automation conditions.
What you can search
A File Field exposes four search dimensions. Each answers a practical question about the files on an issue:
| Search on | Answers | Type | Operators |
|---|---|---|---|
FileCount | Is anything attached? How many? | number | = != > >= < <= |
FileType | Is there a PDF / image / spreadsheet? | list | = != in not in |
FileName | Is there a file named like this? | text | ~ !~ |
Categories | Is there a file labeled Contract / Invoice? | list | = != in not in |
FileCount is always recorded — it's 0 when the field has no files — so it's the natural way to find issues that are missing a required document. FileType and Categories are lists, so a single issue can match several values at once (an issue with a PDF and an image matches both).
The JQL editor suggests the field's four search dimensions as you type
How a query looks
Every query follows the same pattern:
"Field name".Dimension operator value
The examples below use the default name File Field. If your administrator named the field something else, use that name instead — and wrap any name that contains spaces in quotes, for example "Signed Contract".FileCount > 0.
The dot after the field name matters — you're searching a specific dimension ("File Field".FileCount), not the field as a whole. Quoting the whole expression works too, so "File Field.Categories" = Contract and "File Field".Categories = Contract are equivalent.
For example, this query lists issues in a project that have fewer than three files attached:
project = FILE AND "File Field".FileCount < 3
A query and its results — the matching issues, with the field's files shown as a column
Common searches
Missing or complete evidence
Use FileCount to find issues that are missing a required document — for example, every open issue in a project with no file attached, a ready-made "missing evidence" audit:
project = COMP AND statusCategory != Done AND "File Field".FileCount = 0
By file type
FileType groups files into broad families, so you write PDF instead of application/pdf, and every image lands under a single Image value:
"File Field".FileType = "PDF"
The available families are:
| Value | Covers |
|---|---|
PDF | .pdf files |
Image | .png, .jpg, .jpeg, .gif, .webp and other images |
Word | Word documents — .docx, .doc |
Spreadsheet | Excel spreadsheets — .xlsx, .xls |
CSV | .csv files |
Text | plain text .txt files |
Archive | .zip archives |
Other | anything not recognized above |
By file name
FileName matches on the words in a file's name:
"File Field".FileName ~ "invoice"
By category
If the field uses categories, search by the category name:
"File Field".Categories = "Contract"
Use in filters, boards, and automation
Anything you can search, you can reuse:
- Saved filters and boards — save any of these queries as a filter to power a board, a dashboard gadget, or a column in a list view.
- Jira automation — the same expressions work as JQL conditions in automation rules. A common one: when an issue moves to Done and
FileCount = 0, block the transition or add a comment about the missing document.
A File Field JQL condition in an automation rule — catching issues moved to Done with no file attached
Good to know
- File-name search matches whole words.
FileName ~ "report"matches a file calledreport.pdf, but won't findreportinside a longer word. Search for complete words from the file name. - Older issues index after the field is saved again. Issues whose File Field hasn't been touched since these searches were turned on start matching
FileCountandFileTypequeries once the field is edited and saved again. FileCountis always set. It's0when nothing is attached, which is exactly what makes it reliable for finding issues with no proof on file.
What's next?
- Classify Files with Categories — label files so you can filter by document type
- Attach, Download & Delete Files — the everyday end-user experience
- FAQ — limits, permissions, and common questions