Filters and query language

A filter is a saved search. You build the search on the Search page, either with simple filters or by writing a query in the , and save it under a name. Run it again from My Filters whenever you need the current answer.

Build a query

Open the Search page

Open the Search page and pick the kind of object to search, for example work items or pages.

Choose how to write the query

The page has two modes:

Mode	How it works
Filters	Click Add filter, pick a field, how to compare it and a value. Every filter must match
Query	Write the query as text. The editor suggests fields, comparisons and values as you type and underlines what is wrong

Run it

Click Search. The results appear in the table below.

The two modes show the same filter. A query with OR, NOT, groups, ORDER BY or a function cannot be shown as simple filters, so it stays in Query mode.

A query searches the kind of object you picked: work items, pages, projects, portfolios, Registry objects and test management objects. The field tables below cover work items and pages. The fields of the other kinds are listed on the Search page.

Query syntax

A condition has the form field operator value. Combine conditions with AND, OR and NOT, and group them with parentheses. Text values go in quotes.

priority = "High" AND status != "Done"
(priority = "High" OR priority = "Highest") AND author = currentUser()

Fields

Field	Work items	Pages	Meaning
`title`	Yes	Yes	The title
`content`		Yes	The page body
`status`	Yes	Yes	Work items: the status name. Pages: `PUBLISHED`, `DRAFT` or `ARCHIVED`
`priority`	Yes		The priority
`taskType`	Yes		The work item type, for example `"Bug"`
`author`	Yes	Yes	Work items: the assignee. Pages: the author
`createdBy`	Yes		Who created the work item
`label`	Yes	Yes	Labels
`sprint`	Yes		The cycle
`storyPoints`	Yes		The story point estimate
`parent`	Yes		The key of the parent, for example `"ABC-1"`
`space`	Yes	Yes	The Space, by its short name in the address
`startDate`, `dueDate`	Yes		Scheduled dates
`created`, `updated`	Yes	Yes	Creation and last change

Words without a field search the title and key of work items, or the title and content of pages.

The assignee field is author, not assignee. A query with assignee = … returns Unknown field.

Use names, not IDs. Write a person’s name or email for author, a status name for status, the type name for taskType. If a name matches several people, the query matches all of them.

Operators

Operator	Meaning	Example
`=`, `!=`	Equals, does not equal. On a date, `=` matches the whole day	`status = "In Progress"`
`>`, `>=`, `<`, `<=`	Greater or less than, for numbers and dates	`storyPoints >= 5`
`~`, `!~`	Contains, does not contain (text)	`title ~ "invoice"`
`~"text"`, `~"text"`	Starts with, ends with	`title ~ "Onboard*"`
`IN (…)`, `NOT IN (…)`	Any of several values	`status IN ("To Do", "In Progress")`
`IS EMPTY`, `IS NOT EMPTY`	The field has no value, or any value	`dueDate IS EMPTY`

Which operators a field accepts depends on its type. Text fields take ~ but not IN. Choice and people fields take IN but not ~. label takes only IN, NOT IN, IS EMPTY and IS NOT EMPTY, so write label IN ("urgent"). space takes only = and !=. A wrong combination shows Operator not supported for field ….

Dates and the current user

Value	Meaning
`-7d`, `-2w`, `-3m`, `-1y`	Days, weeks, months or years before today. Without the minus, after today. No space between number and unit
`today()`	The start of today
`now()`	This moment
`startOfWeek()`, `endOfWeek()`	Monday and the end of the current week
`currentUser()`	You

dueDate < today() AND author = currentUser()
updated >= -7d

Functions for work items

Function	Matches work items that
`isOverdue()`	Have a due date in the past, whatever their status
`hasNoAssignee()`	Have nobody assigned
`hasNoLabel()`	Have no label
`isTopLevel()`	Are not a sub-item
`isSubWorkItem()`	Are a sub-item
`hasChildren()`	Have at least one sub-item
`hasStartAndDueDates()`	Have both a start and a due date

isOverdue() AND status != "Done" AND hasNoAssignee()

isOverdue() also matches finished work items, so combine it with a status condition.

Sort the results

End the query with ORDER BY, a field and ASC (the default) or DESC. Separate several fields with commas.

status = "In Progress" ORDER BY priority DESC, dueDate ASC

Work items sort by title, priority, storyPoints, dueDate, startDate, created, updated, status and author. Pages sort by title, created, updated and space. Other fields show Cannot sort by ….

Save a search as a filter

Build the search

On the Search page, choose a kind of object and add filters, or switch to Query mode and write a query. A query that has an error cannot be saved.

Save it

Click Save filter. Enter a name, and a description if you like, and click Save. The query, the type, the sort order and the columns are saved as they are on the page.

Find it again

The filter opens from My Filters, and from the Filters sidebar when you star it.

An open filter shows its name. When you change the query, the filter shows Unsaved changes:

Button	What it does
Save	Overwrites the filter with what is on the page. Only the owner and people who may edit it see it
Save as…	Saves what is on the page as a new filter and leaves the original as it was

If someone else saved the filter after you opened it, Save does not overwrite their work. You choose Reload to take their version, or Save as a copy to keep your changes. A filter you open from a link, and that is not shared with you, shows This filter is not available.

Use your filters

Open Filters from the app drawer. The sidebar lists your starred filters. View all filters opens My Filters.

Tab	Shows
Mine	The filters you own
Shared with me	Filters others shared with you, directly, through a group, a Space, a project or with everyone
Favorites	The filters you starred
All I can see	All of the above

Each row shows the owner, how the filter is shared and when it changed. A filter whose owner was removed shows (deleted user) as its owner.

Action	How
Run a filter	Click its name
Find a filter	Search filters by name…
Mark a favorite	The star icon (Favorite). The star is yours alone, also on a filter someone shared
Delete a filter	Delete, then confirm. Only the owner deletes a filter. This cannot be undone

To give others the same filter, share it. To take the results into a spreadsheet, export them as CSV.

Troubleshooting

Message	Cause	What to do
Unknown field	The field name is not in the field list, for example `assignee`	Use `author` for the assignee
Operator not supported for field …	The operator does not fit the field type	See Operators
Unknown function …()	A work item function used for pages	Functions work for work items only
Cannot sort by …	The field cannot be used in `ORDER BY`	Use one of the sortable fields

Search

Header search and the Search page.

Share a filter

Let people, groups, a Space or a project use your filter.

Subscribe to a filter

Get the results of a filter by email.

Work Items table

Search, filter and edit many work items of one project.

Core concepts

Apps

Filters and query language

Build a query

Query syntax

Fields

Operators

Dates and the current user

Functions for work items

Sort the results

Save a search as a filter

Use your filters

Troubleshooting

Search

Share a filter

Subscribe to a filter

Work Items table

​Build a query

​Query syntax

​Fields

​Operators

​Dates and the current user

​Functions for work items

​Sort the results

​Save a search as a filter

​Use your filters

​Troubleshooting

​Related

Search

Share a filter

Subscribe to a filter

Work Items table

Build a query

Query syntax

Fields

Operators

Dates and the current user

Functions for work items

Sort the results

Save a search as a filter

Use your filters

Troubleshooting

Related