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 or Add a rule group.
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 |
> |
| Returns items that have strictly more than 1000 lines changed. |
>= |
| Returns items that have 1000 lines or more changed . |
< |
| Returns items that have strictly less than 1000 lines changed. |
<= |
| Returns items that have 1000 lines or less changed. |
= |
| Returns items that have exactly 1000 lines changed. |
!= |
| 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) |
| Returns items whose due date is exactly on July 1st, 2022. |
Is not (date) |
| Returns all items except those whose due date is exactly on July 1st, 2022. |
Before (date) |
| Returns items whose due date is strictly before July 1st, 2022 (i.e. date is not included in the range). |
After (date) |
| Returns items whose due date is strictly after July 1st, 2022 (i.e. date is not included in the range). |
Within (date) |
| Returns items whose due date is ranging from July 1st, 2022 included to July 31st, 2022 included. |
Current |
| Returns items whose due date is between the first day and last day of the current month. |
Last |
| Returns items whose due date is included in the last 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 last hour, day, week, month, quarter and year. |
Next |
| 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) |
| 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) |
| Returns all items whose due date is after 2 months ago (i.e. about 60 days ago). |
Is empty |
| Returns all items that have no closure date (i.e. items that are not closed). |
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 |
| 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 |
| 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. |
= |
| Returns items whose author is john.doe. N.B. users can write any custom user name for advanced filtering. |
Is null |
| Returns all items that have not been merged by anyone. |
Is not null |
| Returns all items that have been merged by someone. |
~ (regex) |
| Returns all items whose author matches (PCRE regex) the string “doe”.
Regex expressions can be tested using https://regex101.com/r/dX8cN8/1 |
!= |
| Returns all items whose author is not equal to “john.doe”. |
!~ (regex) |
| Returns all items whose author does not match (PCRE regex) the string “doe”.
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 |
= |
| Returns items whose title matches exactly the string “My Title”. |
Is null |
| Returns all items whose body is not populated. |
Is not null |
| Returns all items whose body is populated. |
~ (regex) |
| Returns all items whose title matches (PCRE regex) the string “fix”.
Regex expressions can be tested using https://regex101.com/r/dX8cN8/1 |
!= |
| Returns all items that are not equal to “My Title”. |
!~ (regex) |
| Returns all items whose URL does not match (PCRE regex) the string “github.com/my-project”.
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 |
| Returns items whose labels contain the string “bug”. |
Contains all of |
| Returns items whose labels contain the 3 strings “bug”, "defect" and "improvement". It may contain additional strings
|
Contains any of |
| Returns items whose labels contain at least one of the strings “bug”, "defect" and "improvement". It may contain additional strings such as
|
Contains exactly |
| Returns items whose labels contain exactly and only the strings “bug”, "defect" and "improvement".
|
~(regrex) |
| Returns all items whose labels matches (PCRE regex) the string “bug”.
Regex expressions can be tested using https://regex101.com/r/dX8cN8/1 |
Does not contain |
| Returns all items whose labels exclude the string “bug”. |
Does not contain all of |
| Returns items whose labels exclude the 2 strings “bug” and "defect".
|
Does not contain any of |
| Returns items whose labels exclude at least one of the strings “bug”, "defect".
|
Does not contain exactly |
| Returns items whose labels exclude exactly and only the strings “bug”, "defect" and "improvement".
|
!~(regrex) |
| Returns all items whose labels does not matche (PCRE regex) the string “bug”.
Regex expressions can be tested using https://regex101.com/r/dX8cN8/1 |
Length > |
| Return items that have strictly more than 1 assignee (i.e. records that have at least 2 list-items on ASSIGNEES). |
Length >= |
| Return items that have 1 or more assignees (i.e. records that have at least 1 list-items on ASSIGNEES). |
Length = |
| Return items that have exactly 1 assignee (i.e. records that have exactly 1 list-item on field ASSIGNEES). |
Length < |
| Return items that have strictly less than 2 assignees (i.e. records that have 0 or 1 list-items on ASSIGNEES). |
Length <= |
| Return items that have 2 or less assignees (i.e. records that have at most 2 list-items on ASSIGNEES). |
Length != |
| 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.