Using filters
Tom Azernour avatar
Written by Tom Azernour
Updated this week

Where to configure filters?

All Keypup insights support one or multiple levels of filtering:


Charts, KPIs and Reports

Configure filters from the Configure Filter button on the right while configuring your insight.

Cards feed

By design, this type of insight is built through filters. Enter some rules and the list of displayed cards will automatically filter itself.


Boards

Boards support two levels of filtering:

  • Global filtering (available from the top right) that applies to all cards in all columns

  • Column-level filtering (available by clicking on a specific column) only applies to the chosen column


How does filtering work?

Add rules

No matter the type of insights, filtering is always done the same way:

You can

  • Add a rule: Add a single rule to your insight

  • Add a rule group: Create a group to categorize related filters (read more here)

  • Add a quick rule: Select pre-configured presets for your filters to get started in a click

Each rule is broken down as follows:

  • The field (blue) on which the filter is applied

  • The operator (green) that specifies how the field should be filtered

  • The filtering value (purple) that the field must satisfy through the operator.

Each type of field (text, date etc..) will provide a different set of bespoke operators. Clicking on the operator dropdown will display all available operators.

Read this article to learn more about possible matches.


Dealing with combinators

Individual rules and groups of rules are chained together via AND / OR combinators.

E.g. condition1 AND condition2 AND condition3

E.g. condition1 OR condition2

All the rules within a group - including the top-level group - must be chained together using the same combinator.

E.g. condition1 AND condition2 AND condition3 is valid.

E.g. condition1 AND condition2 OR condition3 is NOT valid.

In order to write this last example, we would have to introduce a group that explicitly specifies in what order the different combinators apply. The two examples below are valid ways of rewriting the above example - but have different meanings:

E.g. condition1 AND (condition2 OR condition3), in which case condition 1 is considered WITH condition2 OR condition3.

E.g. (condition1 AND condition2) OR condition3, in which case condition1 WITH condition2 is considered, or condition3 alone.

Sort and hierarchize your rules

Groupings allow you to nest or regroup rules that belong together. You can recognize rule groups through their indentation from the headblock. Your filter can go 4 levels deep (3 nested subgroups).

Rules and groups can be reordered by dragging & dropping the handle on the left, and can be deleted from the trash icon on the right.

You can always refer to the SQL-like query at the top of the filtering section to get an overview of your filtering logic.

Apply filters

When customizing a filter set, the counter below the title is here to help

  • If the counter shows zero, it could be a sign that the filters are incorrect or too restrictive.

  • If the counter is equal to the number of records, it's probably a sign that the filter is not effective enough.


Filter fields depending on their type

The list of filtering operators depends on the type (text, date, etc.) of the selected field.

The section below lists all available operators - grouped by field type - along with usage examples.

Number fields

Description: Number fields are numerical values, such as 15 or 5.2.

Field examples: lines_added, required_approval_count (see data dictionary for a complete list)

Available matchers and operators:

Operators

Example

Description

>

LINES CHANGED > 1000

Returns items that have strictly more than 1000 lines changed.

>=

LINES CHANGED >= 1000

Returns items that have 1000 lines or more changed .

<

LINES CHANGED < 1000

Returns items that have strictly less than 1000 lines changed.

<=

LINES CHANGED <= 1000

Returns items that have 1000 lines or less changed.

=

LINES CHANGED = 1000

Returns items that have exactly 1000 lines changed.

!=

LINES CHANGED != 1000

Returns all items except those that have exactly 1000 lines changed.

Date fields

Description: Date fields contain date and time information, such as July 9th at 15:48. Using dynamic date filters like before/after/within allows building dynamic reports that update themselves over time (e.g. weekly reports).

Field examples: created_at, due_on, updated_at, merged_at (see data dictionary for a complete list)

Available matchers and operators:

Operator

Example

Description

Is (date)

CLOSED AT Is (date) 07/01/2022

Returns items whose due date is exactly on July 1st, 2022.

Is not (date)

CLOSED AT Is not (date) 07/01/2022

Returns all items except those whose due date is exactly on July 1st, 2022.

Before (date)

CLOSED AT Before (date) 07/01/2022

Returns items whose due date is strictly before July 1st, 2022 (i.e. date is not included in the range).

After (date)

CLOSED AT After (date) 07/01/2022

Returns items whose due date is strictly after July 1st, 2022 (i.e. date is not included in the range).

Within (date)

CLOSED AT Within (date) 07/01/2022 AND 07/31/2022

Returns items whose due date is ranging from July 1st, 2022 included to July 31st, 2022 included.

Current

CLOSED AT Current MONTH

Returns items whose due date is between the first day and last day of the current month.

N.B. The same logic applies to the current hour, day, week, month, quarter and year.

Previous

CLOSED AT previous 2 QUARTERS

Returns items whose due date is included in the previous 2 quarters, excluding the current quarter (i.e. if the filter is done in July 2022, the range includes Q1 & Q2 2022).

N.B. The same logic applies to the previous hour, day, week, month, quarter and year.

Next

CLOSED AT next 3 DAYS

Returns items whose due date is included in the next 3 days, excluding the current day (i.e. if the filter is done on Monday 1st, the range includes Tuesday 2nd to Thursday 4th).

N.B. The same logic applies to the next hour, day, week, month, quarter and year.

Before (from/ago)

CLOSED AT before 72 HOURS FROM NOW

Returns all items whose due date is before 72 hours from now.

N.B. The same logic applies to hours, days, weeks, months, quarters and years.

After (from/ago)

CLOSED AT after 2 MONTHS AGO

Returns all items whose due date is after 2 months ago (i.e. about 60 days ago).

N.B. The same logic applies to hours, days, weeks, months, quarters and years.

Is empty

CLOSED AT is empty

Returns all items that have no closure date (i.e. items that are not closed).

Is not empty

CLOSED AT is not empty

Returns all items that have a closure date (i.e. items whose close date field is populated).

User fields

Description: User fields are text fields referring to a username. This type of field supports the special is me and is user operators, which allow you to filter records based on Keypup users and simplify cross-app filtering (see each operator below).

Field examples: author, merged_by, reviewers (see data dictionary for a complete list)

Available matchers and operators:

Operator

Example

Description

Is me

AUTHOR is me

Returns items whose author I am.

This special operator uses your Keypup account and your connected identities (e.g. GitHub, JIRA) to lookup what your username is in each connected application and automatically filter based on these.

E.g. If your username is jdoe in GitHub and john.doe in JIRA, then using author is me is equivalent to doing author = jdoe OR author = john.doe.

Is user

AUTHOR is john.doe

Returns items whose author is John Doe.

This special operator uses the Keypup account of the selected user and their connected identities (e.g. GitHub, JIRA) to lookup what their username is in each connected application and automatically filter based on these.

E.g. If John’s username is jdoe in GitHub and john.doe in JIRA, then using author is John is equivalent to doing author = jdoe OR author = john.doe.

=

AUTHOR = john.doe

Returns items whose author is john.doe.

N.B. users can write any custom user name for advanced filtering.

Is null

MERGED BY is null

Returns all items that have not been merged by anyone.

Is not null

MERGED BY not null

Returns all items that have been merged by someone.

~ (regex)

AUTHOR ~ doe

Returns all items whose author matches (PCRE regex) the string “doe”.

  • “jdoe”, “john.doe”, “johnny doe” would all match “doe”.

  • “Jdo”, “john.dewey”, “johnny ohm” would not match “doe”.

Regex expressions can be tested using https://regex101.com/r/dX8cN8/1

!=

AUTHOR != john.doe

Returns all items whose author is not equal to “john.doe”.

!~ (regex)

AUTHOR !~ doe

Returns all items whose author does not match (PCRE regex) the string “doe”.

  • “jdoe”, “john.doe”, “johnny doe” would all match “doe”, and would not be displayed.

  • “Jdo”, “john.dewey”, “johnny ohm” would not match “doe”, and would not be displayed.


Regex expressions can be tested using https://regex101.com/r/dX8cN8/1



Text fields

Description: Text fields are string values that can be matched or partially matched using equality or regex (regular expression) operators.

Field examples: body, title, URL (see data dictionary for a complete list)

Available matchers and operators:

Operator

Example

Description

=

TITLE = My Title

Returns items whose title matches exactly the string “My Title”.

Is null

BODY is null

Returns all items whose body is not populated.

Is not null

BODY is not null

Returns all items whose body is populated.

~ (regex)

TITLE ~ fix

Returns all items whose title matches (PCRE regex) the string “fix”.

  • “Fixes this item”, “Quick fix” would all match “fix”.
    ​​

Regex expressions can be tested using https://regex101.com/r/dX8cN8/1

!=

TITLE != My Title

Returns all items that are not equal to “My Title”.

!~ (regex)

URL !~ github.com/my-project

Returns all items whose URL does not match (PCRE regex) the string “github.com/my-project”.

  • “github.com/my-project-name”, “github.com/my-project/repo” would not be displayed.

  • “my-project”, “github.com” and “foobar” would be displayed.

Regex expressions can be tested using https://regex101.com/r/dX8cN8/1

List fields

Description: List fields are arrays of text items, such as [“emma”, “bob”, “jenny”].

Field examples: assignees, labels, reviewers (see data dictionary for a complete list)

Available matchers and operators:

Operator

Example

Description

Contains

LABELS contains bug

Returns items whose labels contain the string “bug”.

Contains all of

LABELS contains all of bug, defect, improvement

Returns items whose labels contain the 3 strings “bug”, "defect" and "improvement". It may contain additional strings

  • An item labeled "bug", "defect", "improvement", "documentation" would match

  • An item labeled "bug", "improvement", "documentation" would NOT match

Contains any of

LABELS contains any of bug, defect, improvement

Returns items whose labels contain at least one of the strings “bug”, "defect" and "improvement". It may contain additional strings such as

  • An item labeled "bug", "documentation" would match

  • An item labeled "documentation","critical" would NOT match

Contains exactly

LABELS contains exactly bug, defect, improvement

Returns items whose labels contain exactly and only the strings “bug”, "defect" and "improvement".

  • An item labeled "bug", "defect", "improvement" would match

  • An item labeled "bug", "defect", "improvement", "documentation" would NOT match

~(regrex)

LABELS ~ bug

Returns all items whose labels matches (PCRE regex) the string “bug”.

  • An item labeled "bugfix", "fixing issue" would match

  • An item labeled "fixing issue" would NOT match
    ​​

Regex expressions can be tested using https://regex101.com/r/dX8cN8/1

Does not contain

LABELS does not contains bug

Returns all items whose labels exclude the string “bug”.

Does not contain all of

LABELS does not contain all of bug, defect

Returns items whose labels exclude the 2 strings “bug” and "defect".

  • An item labeled "bug", "improvement", "documentation" would match

  • An item labeled "bug", "defect", "documentation" would NOT match

Does not contain any of

LABELS does not contain any of bug, defect

Returns items whose labels exclude at least one of the strings “bug”, "defect".

  • An item labeled "improvement", "documentation" would match

  • An item labeled "documentation","defect" would NOT match

Does not contain exactly

LABELS does not contain exactly bug, defect

Returns items whose labels exclude exactly and only the strings “bug”, "defect" and "improvement".

  • An item labeled "bug", "improvement" would match

  • An item labeled "bug", "defect", "improvement" would NOT match

!~(regrex)

LABELS !~ bug

Returns all items whose labels does not matche (PCRE regex) the string “bug”.

  • An item labeled "fix", "enhancement" would match

  • An item labeled "bugfix", "documentation" would NOT match
    ​​

Regex expressions can be tested using https://regex101.com/r/dX8cN8/1

Length >

ASSIGNEES > 1

Return items that have strictly more than 1 assignee (i.e. records that have at least 2 list-items on ASSIGNEES).

Length >=

ASSIGNEES >=1

Return items that have 1 or more assignees (i.e. records that have at least 1 list-items on ASSIGNEES).

Length =

ASSIGNEES = 1

Return items that have exactly 1 assignee (i.e. records that have exactly 1 list-item on field ASSIGNEES).

Length <

ASSIGNEES < 2

Return items that have strictly less than 2 assignees (i.e. records that have 0 or 1 list-items on ASSIGNEES).

Length <=

ASSIGNEES <= 2

Return items that have 2 or less assignees (i.e. records that have at most 2 list-items on ASSIGNEES).

Length !=

ASSIGNEES != 0

Return all items that have assignees (i.e. records that have at least 1 list-items on ASSIGNEES).


Filters examples & tips

Our Data dictionaries are the best place to understand the type and use of each field.

E.g. 1

"Select all items I - as author - have created after June 1st and for which the due date is June 18th

E.g. 2

Select all items whose type is Pull Request AND the state is "Open OR Merged".

In this example we use "equals any of" to specify multiple possible values on the State field via an OR combinator.

E.g. 3

“Select all items where the title starts with ‘Ability’ (case sensitive)”

In this example (?c) makes the filtering search case-sensitive, and ^ specifies that the match must be done at the beginning of the string.

E.g. 4

“Select all items where the title ends with "setup"

The character $ specifies that the match must be done at the end of the string.

E.g. 5

“Select all Open items where the Labels contain at least the string “bug” OR “bugs”, and that were created this year and whose due date was passed more than 30 days ago.

The example above selects items whose state is open and matches de defined labels. Two datetime filters are added to narrow down items to the specified dates.

Tips & best practices

ProTip 1: Do not hardcode users in filters

Unless you have a very specific use case in mind we recommend not adding any filter related to a specific user (E.g. author = “bob”). You should ensure the insight filters make sense at a Team level and user level.

ProTip 2: Use relative time filters instead of hardcoded dates

Using relative time filters is a good way of ensuring your dashboards remain dynamic. On the contrary, using hardcoded dates would require you to frequently update your dashboards to ensure that the definitions stay up to date.

ProTip 3: Use relative time filters instead of hardcoded dates

Board columns are stateless and are not aware of the filters configured in other columns. If an item matches the filters of two columns, it will appear in these two columns.

It is best to ensure your column filters are mutually exclusive if what you are looking for is a progressive board (items move from left to right).

There are cases though where having overlapping columns can be beneficial. Let's consider the case of two columns called Todo and Todo (Urgent):

  • Todo: Displays all issues currently assigned

  • Todo (Urgent): Display all issues currently assigned and have the label "urgent"

By doing so, not only will you have visibility on Todo and Todo (Urgent) issues but having the two columns side by side will also provide a visual indication of the proportion of urgent issues amongst todo issues.

Did this answer your question?