Explaining Queries
Table of contents
Overview: the ‘explain’ instruction
Introduced in Tasks 1.19.0.
The explain
instruction adds some extra output at the start of the search results, when tasks blocks are viewed in Live Preview and Reading modes.
This has a number of benefits:
- It is easy to understand date-based-filters:
- Any dates in filters are expanded, to show the actual dates used in the search.
- Boolean query logic is clearer.
- Combinations of queries (via
AND
,OR
,NOT
etc) can be seen more clearly.
- Combinations of queries (via
- If there is a global filter enabled, it is included in the explanation.
- This often explains why tasks are missing from results.
Examples
Dates in filters are expanded
For example, when the following text is placed in a tasks query block:
starts after 2 years ago
scheduled after 1 week ago
due before tomorrow
explain
the results begin with the following, on 2022-10-21
:
Explanation of this Tasks code block query:
starts after 2 years ago =>
start date is after 2020-10-21 (Wednesday 21st October 2020) OR no start date
scheduled after 1 week ago =>
scheduled date is after 2022-10-14 (Friday 14th October 2022)
due before tomorrow =>
due date is before 2022-10-22 (Saturday 22nd October 2022)
Note how it shows the dates being searched for very clearly, including the day of the week.
It also shows that starts
searches also match tasks with not start date.
Boolean combinations are displayed
For example, when the following text is placed in a tasks query block:
explain
not done
(due before tomorrow) AND (is recurring)
the results begin with the following, on 2022-10-21
:
Explanation of this Tasks code block query:
not done
(due before tomorrow) AND (is recurring) =>
AND (All of):
due date is before 2022-10-22 (Saturday 22nd October 2022)
is recurring
More complex combinations are displayed
With complex Boolean combinations of filters, it is easy to get parentheses in the wrong place. With explain
, the interpreted logic is easily visible.
For example, when the following text is placed in a tasks query block:
explain
( (description includes 1) AND (description includes 2) AND (description includes 3) ) OR ( (description includes 5) AND (description includes 6) AND (description includes 7) ) AND NOT (description includes 7)
the results begin with the following, on 2022-10-21
:
Explanation of this Tasks code block query:
( (description includes 1) AND (description includes 2) AND (description includes 3) ) OR ( (description includes 5) AND (description includes 6) AND (description includes 7) ) AND NOT (description includes 7) =>
OR (At least one of):
AND (All of):
description includes 1
description includes 2
description includes 3
AND (All of):
AND (All of):
description includes 5
description includes 6
description includes 7
NOT:
description includes 7
Styling explain results
Default style
For readability, explanations are shown in a fixed-width font (a PRE
block), and if the text is too wide for the screen a horizontal scrollbar is shown. Otherwise, testing showed that the explanations would be unusable on small-screen devices.
Customizing the results
Using a CSS snippet in Obsidian, we can change the appearance of the explanation block.
For example, this CSS snippet tasks-plugin-explain-text-blue.css
makes the explanation block text blue:
/* Make the Tasks plugin's 'explain' output stand out in blue */
.plugin-tasks-query-explanation {
color: var(--color-blue);
}