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 a pre-configured preset for your filter
Each rule is broken down as follows:
The field (blue) on which the filter is applied
The operator (green) 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 up to 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 editing filters, the top-left counter will indicate how many records are returned by these filters:
If the count is zero or low, it means the filters are too restrictive.
If the count is too close to the total number of records, it means the filters are probably not restrictive enough
Available operators for each type of field
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 fewer 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 dates range from July 1st, 2022, inclusive, to July 31st, 2022, inclusive. |
Current |
| Returns items whose due date is between the first day and the last day of the current month. |
Previous |
| 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 |
| 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 look up your username in each connected application and automatically filter results 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 look up 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. |
Contains |
| Returns items whose authors contain the string “john.doe”. |
Contains all of |
| Returns items whose authors contain the 2 strings “john.doe” and "jane.doe". It may contain additional strings
|
Contains any of |
| Returns items whose authors contain at least one of the strings “john.doe” and "jane.doe". It may contain additional strings such as
|
Contains exactly |
| Returns items whose authors contain exactly and only the strings “john.doe” and "jane.doe".
|
Does not contain |
| Returns all items whose authors exclude the string “john.doe”. |
Does not contain all of |
| Returns items whose authors exclude the 2 strings “john.doe” and "jane.doe".
|
Does not contain any of |
| Returns items whose authors exclude at least one of the strings “john.doe”, "jane.doe".
|
Does not contain exactly |
| Returns items whose authors exclude exactly and only the strings “john.doe”, and "jane.doe".
|
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”. |
equals any of |
| Returns items whose title is “My issue” or "My PR". |
equals none of |
| Returns items whose title is not “My issue” or "My PR". |
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".
|
~(regex) |
| Returns all items whose labels match (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".
|
!~(regex) |
| Returns all items whose labels do not match (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 item on ASSIGNEES). |
Length = |
| Return items that have exactly 1 assignee (i.e., records that have exactly 1 list-item on the 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 fewer 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 item on ASSIGNEES). |
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.