Explaining Queries - Tasks User Guide

# Explaining Queries ## Overview: the 'explain' instruction > [!released] 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. - If there is a [[Global Filter|global filter]] enabled, it is included in the explanation. - This often explains why tasks are missing from results. - If there is a [[Global Query|global query]] enabled, it too is included in the explanation. - Any [[query file defaults]]-generated instructions are listed (since Tasks 7.15.0). - Any [[Grouping|'group by']] instructions are listed (since Tasks 5.4.0). - Any [[Sorting|'sort by']] instructions are listed (since Tasks 5.4.0). ## Examples ### Dates in filters are expanded For example, when the following text is placed in a tasks query block:  ```text starts after 2 years ago scheduled after 1 week ago due before tomorrow explain ```  the results begin with the following, on `2022-10-21`:  ```text 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. ### Regular Expressions are explained > [!released] > Introduced in Tasks 4.3.0. For example, when the following [[Regular Expressions|regular expression]] is placed in a tasks query block:  ```text explain path regex matches /^Root/Sub-Folder/Sample File\.md/i ```  the results begin with the following:  ```text Explanation of this Tasks code block query: path regex matches /^Root/Sub-Folder/Sample File\.md/i => using regex: '^Root\/Sub-Folder\/Sample File\.md' with flag 'i' ```  ### Boolean combinations are displayed For example, when the following text is placed in a tasks query block:  ```text explain not done (due before tomorrow) AND (is recurring) ```  the results begin with the following, on `2022-10-21`:  ```text Explanation of this Tasks code block query: not done => status type is TODO or IN_PROGRESS or ON_HOLD (due before tomorrow) AND (is recurring) => AND (All of): due before tomorrow => 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, even when using [[Line Continuations]] to improve readability. With `explain`, the interpreted logic is easily visible. For example, when the following text is placed in a tasks query block:  ```text 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`:  ```text 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) => ( (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 ```  ## Advanced Examples ### Global Query is displayed > [!released] The Global Query setting was added in Tasks 3.5.0. For example, with this [[Global Query|global query]]:  ```text limit 50 heading includes tasks ```  and when the following text is placed in a tasks query block:  ```text not done due next week explain ```  the results begin with the following, on `2022-10-21`:  ```text Explanation of the global query: heading includes tasks At most 50 tasks. Explanation of this Tasks code block query: not done => status type is TODO or IN_PROGRESS or ON_HOLD due next week => due date is between: 2022-10-24 (Monday 24th October 2022) and 2022-10-30 (Sunday 30th October 2022) inclusive ```  ### Query File Defaults are displayed > [!released] > The [[Query File Defaults]] facility was introduced in Tasks 7.15.0. > [!info]- What are Query File Defaults? > You can use [[Query File Defaults]] facility to modify Tasks searches, by adding certain pre-defined property value's the query file's frontmatter. > > For example, setting `TQ_short_mode` to `true` makes Tasks insert the following line at the start of the query: > > ```text > short mode > ``` Consider this Markdown note:  ````text --- TQ_extra_instructions: |- folder includes {{query.file.folder}} not done TQ_short_mode: true TQ_show_tree: true --- ```tasks explain ``` ````  The Tasks results begin would the following:  ```text Explanation of the Query File Defaults (from properties/frontmatter in the query's file): folder includes {{query.file.folder}} => folder includes Test Data/ not done => status type is TODO or IN_PROGRESS or ON_HOLD short mode show tree Explanation of this Tasks code block query: No filters supplied. All tasks will match the query. ```  ### Placeholder values are expanded > [!released] > Placeholders were introduced in Tasks 4.7.0. For example, when the following query with [[Query Properties]] in [[Placeholders|placeholders]] is placed in a tasks query block in the file `some/sample/file path.md`:  ```text explain path includes {{query.file.path}} path includes {{query.file.pathWithoutExtension}} root includes {{query.file.root}} folder includes {{query.file.folder}} filename includes {{query.file.filename}} filename includes {{query.file.filenameWithoutExtension}} description includes Some Cryptic String {{! Inline comments are removed before search }} ```  the results begin with the following:  ```text Explanation of this Tasks code block query: path includes {{query.file.path}} => path includes some/sample/file path.md path includes {{query.file.pathWithoutExtension}} => path includes some/sample/file path root includes {{query.file.root}} => root includes some/ folder includes {{query.file.folder}} => folder includes some/sample/ filename includes {{query.file.filename}} => filename includes file path.md filename includes {{query.file.filenameWithoutExtension}} => filename includes file path description includes Some Cryptic String {{! Inline comments are removed before search }} => description includes Some Cryptic String ```  ## 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](https://help.obsidian.md/How+to/Add+custom+styles#Use+Themes+and+or+CSS+snippets), we can change the appearance of the explanation block. For example, [this CSS snippet](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/resources/sample_vaults/Tasks-Demo/.obsidian/snippets/tasks-plugin-explain-text-blue.css) `tasks-plugin-explain-text-blue.css` makes the explanation block text blue:  ```css /* Make the Tasks plugin's 'explain' output stand out in blue */ .plugin-tasks-query-explanation { color: var(--color-blue); } ```  ## Support Before creating a new bug report or feature request about explaining queries, please check existing items to avoid duplicates. You do not need to search manually: the links below are already filtered to the label `"scope: explain"`. - Check both Open and Closed items. - If you find an existing item, support it there instead of adding a `+1` comment. See [[About Support and Help#How to support an existing request|How to support an existing request]]. | Type | Open | Closed | Notes | | --- | --- | --- | --- | | Issues | [Open](https://github.com/obsidian-tasks-group/obsidian-tasks/issues?q=is%3Aopen%20label%3A%22scope%3A+explain%22%20is%3Aissue%20) | [Closed](https://github.com/obsidian-tasks-group/obsidian-tasks/issues?q=is%3Aclosed%20label%3A%22scope%3A+explain%22%20is%3Aissue%20) | bug reports and feature requests | | Discussions | [Open](https://github.com/obsidian-tasks-group/obsidian-tasks/discussions/categories/ideas-any-new-feature-requests-go-in-issues-please?discussions_q=is%3Aopen+label%3A%22scope%3A+explain%22+category%3A%22Ideas%3A+Any+New+Feature+Requests+go+in+Issues+please%22+sort%3Atop) | [Closed](https://github.com/obsidian-tasks-group/obsidian-tasks/discussions/categories/ideas-any-new-feature-requests-go-in-issues-please?discussions_q=is%3Aclosed+label%3A%22scope%3A+explain%22+category%3A%22Ideas%3A+Any+New+Feature+Requests+go+in+Issues+please%22+sort%3Atop) | older feature discussions from before late 2022 | If you do not find an existing item in Issues or Discussions, see [[About Support and Help]] for how to report a bug or request a feature.