> ## Documentation Index
> Fetch the complete documentation index at: https://collabase.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Collabase documentation. Interface labels are quoted in English, as they appear in the product.
> Features marked Enterprise need the Collabase Enterprise Edition licence.

# Filters and query language

> Write precise queries for work items and pages in the Collabase Query Language, save them as personal filters, and run them again with one click.

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 <Tooltip tip="The query syntax of Collabase, for example dueDate < today() AND author = currentUser()." cta="Glossary" href="/docs/glossary#cql">Collabase Query Language (CQL)</Tooltip>, and save it under a name. Run it again from **My Filters** whenever you need the current answer.

<h2 id="build">
  Build a query
</h2>

<Steps>
  <Step title="Open the Search page">
    Open the [Search page](/docs/concepts/search#search-page) and pick the kind of object to search, for example work items or pages.
  </Step>

  <Step title="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 |
  </Step>

  <Step title="Run it">
    Click **Search**. The results appear in the table below.
  </Step>
</Steps>

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.

<Note>
  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](/docs/concepts/search#search-page).
</Note>

<h2 id="syntax">
  Query syntax
</h2>

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.

```text theme={"dark"}
priority = "High" AND status != "Done"
(priority = "High" OR priority = "Highest") AND author = currentUser()
```

<h3 id="fields">
  Fields
</h3>

| 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.

<Warning>
  The assignee field is `author`, not `assignee`. A query with `assignee = …` returns **Unknown field**.
</Warning>

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.

<h3 id="operators">
  Operators
</h3>

| 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 …**.

<h3 id="relative-values">
  Dates and the current user
</h3>

| 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 |

```text theme={"dark"}
dueDate < today() AND author = currentUser()
updated >= -7d
```

<h3 id="functions">
  Functions for work items
</h3>

| 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 |

```text theme={"dark"}
isOverdue() AND status != "Done" AND hasNoAssignee()
```

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

<h3 id="order-by">
  Sort the results
</h3>

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

```text theme={"dark"}
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 …**.

<h2 id="save">
  Save a search as a filter
</h2>

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Find it again">
    The filter opens from **My Filters**, and from the **Filters** sidebar when you star it.
  </Step>
</Steps>

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**.

<h2 id="my-filters">
  Use your filters
</h2>

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](/docs/concepts/share-filters). To take the results into a spreadsheet, [export them as CSV](/docs/concepts/export-results).

<h2 id="troubleshooting">
  Troubleshooting
</h2>

| Message | Cause | What to do |
| - | - | - |
| **Unknown field** | The field name is not in the [field list](#fields), for example `assignee` | Use `author` for the assignee |
| **Operator not supported for field …** | The operator does not fit the field type | See [Operators](#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](#order-by) |

## Related

<CardGroup cols={2}>
  <Card title="Search" icon="search" href="/docs/concepts/search">
    Header search and the Search page.
  </Card>

  <Card title="Share a filter" icon="share" href="/docs/concepts/share-filters">
    Let people, groups, a Space or a project use your filter.
  </Card>

  <Card title="Subscribe to a filter" icon="bell" href="/docs/concepts/subscribe-to-filters">
    Get the results of a filter by email.
  </Card>

  <Card title="Work Items table" icon="table" href="/docs/projects/list-view">
    Search, filter and edit many work items of one project.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.