└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [![Trajecta](https://img.shields.io/badge/Sponsored%20by-Trajecta-blue?style=flat-square)](https://trajecta.app) 4 | 5 | This cheatsheet provides a handy reference guide for writing queries using 6 | **Dataview Query Language** (**DQL**) in the [dataview][dataview] plugin for 7 | [Obsidian.md][obsidian] note-taking app. 8 | 9 | # How to use this 10 | 11 | I recommend copying this file and including it in your Obsidian vault for easy 12 | reference. In this way, you can access the cheatsheet by pulling up the file 13 | or searching in your vault for a specific command. 14 | 15 | Star and fork this repository to see updates and pull them when more examples 16 | are added or the list of commands is expanded. 17 | 18 | # Table of Contents 19 | 20 | - [Query Commands](#query-cheatsheet) 21 | - [LIST](#list) 22 | - [Simple List](#simple-list) 23 | - [Table](#table) 24 | - [Data Commands](#data-commands) 25 | - [FROM](#from) 26 | - [Tags](#tags) 27 | - [Single Files](#single-files) 28 | - [Folders](#folders) 29 | - [Excluding Notes](#excluding-notes) 30 | - [Excluding notes with a specific tag](#excluding-notes-with-a-specific-tag) 31 | - [Excluding notes from a specific folder](#excluding-notes-from-a-specific-folder) 32 | - [Chaining Resources](#chaining-resources) 33 | - [AND operator](#and) 34 | - [OR operator](#or) 35 | - [WHERE](#where) 36 | - [WHERE property is NOT empty](#where-property-is-not-empty) 37 | - [WHERE property is equal to something](#where-property-is-equal-to-something) 38 | - [SORT](#sort) 39 | - [GROUP BY](#group-by) 40 | - [GROUP BY category](#group-by-category) 41 | - [FLATTEN](#flatten) 42 | - [Multiple properties displayed in its own row](#multiple-properties-displayed-in-its-own-row) 43 | - [Limit results in query](#limit-results-in-query) 44 | - [Extras](#extras) 45 | - [Bool property to custom display value](#bool-property-to-custom-display-value) 46 | - [Metadata Reference](#metadata-reference) 47 | - [JSON](#json) 48 | - [YAML](#yaml) 49 | 50 | # Query Cheatsheet 51 | 52 | ## LIST 53 | 54 | ### Simple List 55 | 56 | ```sql 57 | LIST 58 | FROM 59 | 60 | ``` 61 | 62 | Example 63 | 64 | ```sql 65 | LIST 66 | FROM 67 | #library 68 | ``` 69 | 70 | ## Table 71 | 72 | ```sql 73 | TABLE 74 | Title 75 | Author 76 | FROM 77 | #library 78 | ``` 79 | 80 | [Back to Contents](#table-of-contents) 81 | 82 | # Data Commands 83 | 84 | - [FROM](#from) 85 | - [WHERE](#where) 86 | - [SORT](#sort) 87 | - [GROUP BY](#group-by) 88 | - [FLATTEN](#flatten) 89 | - [LIMIT](#limit) 90 | 91 | ## FROM 92 | Selecting from different sources such as; 93 | 94 | ### Tags 95 | 96 | `FROM #tag` 97 | 98 | Example 99 | 100 | ```sql 101 | TABLE 102 | file.cday as "Created Date" 103 | FROM 104 | #my-tag 105 | ``` 106 | ### Single Files 107 | 108 | `FROM "path/to/file-name"` 109 | 110 | Example 111 | 112 | ```sql 113 | TABLE 114 | file.cday as "Created Date" 115 | FROM 116 | "TopFolder/SubFolder/my-file-name" 117 | ``` 118 | ### Folders 119 | 120 | `FROM "folder-name"` 121 | 122 | Example 123 | 124 | ```sql 125 | TABLE 126 | file.cday as "Created Date" 127 | FROM 128 | "my-folder-name" 129 | ``` 130 | 131 | ### Excluding Notes 132 | 133 | #### Excluding notes with a specific tag 134 | 135 | `!#tag-name` 136 | 137 | Example 138 | 139 | ```sql 140 | TABLE 141 | Title, 142 | Rating, 143 | Seen, 144 | SeenDate as "Seen on" 145 | FROM 146 | #movie AND !#template 147 | ``` 148 | 149 | The above example will return all notes with a tag `#movie` but exclude notes 150 | with a tag `#template`. This is handy if you have a note with pre-populated 151 | tags but it's only used as a template so you don't want to see it in your 152 | table view. 153 | 154 | #### Excluding notes from a specific folder 155 | 156 | `FROM #tag AND !"FolderName"` 157 | 158 | Example 159 | 160 | ```sql 161 | TABLE 162 | Title, 163 | Rating, 164 | Seen, 165 | SeenDate as "Seen on" 166 | FROM 167 | #movie AND !"TemplatesFolder" 168 | ``` 169 | 170 | By including `!"FolderName"` we specify that we do not want to return any 171 | matches if the are located in the specified folder. 172 | 173 | ### Chaining Resources 174 | 175 | You can fine tune query parameters utilizing the `AND` and `OR` operators 176 | 177 | #### AND 178 | The `AND` operator queries notes that meet all criteria included in the query: 179 | 180 | ```sql 181 | TABLE 182 | Title, 183 | Author, 184 | Publication 185 | FROM 186 | "Books" AND "Magazines" 187 | ``` 188 | 189 | Using in conjunction with exclusion: 190 | 191 | ```sql 192 | TABLE 193 | Title, 194 | Author, 195 | Publication 196 | FROM 197 | "Books" AND "Books/assets" 198 | ``` 199 | 200 | #### OR 201 | The `OR` operator queries notes that meet any of the provided criteria: 202 | 203 | ```sql 204 | TABLE 205 | Title, 206 | Author, 207 | Publication 208 | FROM 209 | #horror OR #comedy 210 | ``` 211 | 212 | Using in conjunction with exclusion: 213 | 214 | ```sql 215 | TABLE 216 | Title 217 | Author 218 | Publication 219 | FROM 220 | #horror OR #comedy AND !"Books/assets" 221 | ``` 222 | 223 | [Back to Contents](#table-of-contents) 224 | 225 | ## WHERE 226 | Examples of queries containing WHERE clause. 227 | 228 | ### WHERE property is NOT empty 229 | 230 | ```sql 231 | WHERE 232 | 233 | ``` 234 | 235 | Example 236 | 237 | ```sql 238 | TABLE 239 | file.cday as "Created", 240 | Category 241 | FROM 242 | #books 243 | SORT 244 | file.cday 245 | WHERE 246 | Category 247 | ``` 248 | 249 | The above example ensures to show only results where the meta-data 'Category' is not empty. 250 | 251 | ### WHERE property is equal to something 252 | 253 | ```sql 254 | WHERE 255 | = "my-value" 256 | ``` 257 | 258 | ```sql 259 | WHERE 260 | = 123 261 | ``` 262 | 263 | Examples 264 | 265 | ```sql 266 | LIST 267 | WHERE 268 | category = "my-value" 269 | ``` 270 | 271 | ```sql 272 | LIST 273 | WHERE 274 | digitProperty = 123 275 | ``` 276 | 277 | [Back to Contents](#table-of-contents) 278 | 279 | ## SORT 280 | Dataview offers simple ways to sort results. The most simplistic is by some 281 | property in ascending (asc) or descending (desc) order: 282 | 283 | ```sql 284 | TABLE 285 | Title, 286 | Author, 287 | Published, 288 | Year 289 | FROM 290 | #library 291 | SORT 292 | Year asc 293 | ``` 294 | 295 | This should serve well for most use-cases. More complex sorting mechanisms 296 | will added here at a later time. 297 | 298 | [Back to Contents](#table-of-contents) 299 | 300 | ## GROUP BY 301 | The simplest method is to group by some property included in your frontmatter: 302 | 303 | ```sql 304 | GROUP BY 305 | 306 | ``` 307 | 308 | Group by category in a table: 309 | 310 | ```sql 311 | TABLE 312 | rows.file.name as "File" 313 | WHERE 314 | category 315 | GROUP BY 316 | category 317 | ``` 318 | 319 | Group by category in a list: 320 | 321 | ```sql 322 | LIST 323 | rows.file.name 324 | WHERE 325 | category = "first-category" 326 | GROUP BY 327 | category 328 | ``` 329 | 330 | NOTE: When using `GROUP BY`, the structure of the results changes. Instead of 331 | directly accessing `file.name`, you must use the `rows` property to access the 332 | file properties within each group. This is because results are now grouped 333 | into rows based on the `GROUP BY` field. 334 | 335 | [Back to Contents](#table-of-contents) 336 | 337 | ## FLATTEN 338 | Use `FLATTEN` to display multiple properties in a single row 339 | 340 | ```sql 341 | FLATTEN 342 | 343 | ``` 344 | 345 | Code example: 346 | 347 | ```sql 348 | TABLE 349 | Title, 350 | Action 351 | FLATTEN 352 | Action 353 | ``` 354 | 355 | Result example: 356 | 357 | | File Name | Created | Action | 358 | | --------- | ------- | ------------- | 359 | | Note 1 | July | Action name 1 | 360 | | Note 1 | July | Action name 2 | 361 | | Note 2 | August | My Action 123 | 362 | | Note 2 | August | Hello World | 363 | 364 | [Back to Contents](#table-of-contents) 365 | 366 | ## LIMIT 367 | You can limit the results in a query: 368 | 369 | ```sql 370 | LIMIT 371 | 372 | ``` 373 | 374 | Example: 375 | 376 | ```sql 377 | TABLE 378 | Title, 379 | Rating 380 | WHERE 381 | Rating > 3 382 | LIMIT 383 | 10 384 | ``` 385 | 386 | ## Extras 387 | 388 | ### Bool property to custom display value 389 | Dataview provides options on how to display various forms of data. For 390 | example, Booleans can be displayed as Yes/No instead of True/False: 391 | 392 | ```js 393 | CHOICE(, "Yes", "No") as "custom-name" 394 | ``` 395 | 396 | Example 397 | 398 | ```sql 399 | TABLE 400 | Author as "Author", 401 | choice(read, "Yes", "No") as "Read", 402 | FROM 403 | "Books" 404 | ``` 405 | 406 | [Back to Contents](#table-of-contents) 407 | 408 | # Metadata Reference 409 | 410 | Obsidian allows YAML and JSON for metadata. 411 | 412 | ## JSON 413 | 414 | JSON 415 | 416 | ``` 417 | { 418 | "Author": "Author Name", 419 | "Genre": "Fiction", 420 | "DateRead": "2022-06-01", 421 | "Read": false, 422 | "Tags": [ 423 | "Mind-blowing", 424 | "Interesting", 425 | "Science" 426 | ] 427 | } 428 | ``` 429 | 430 | ## YAML 431 | 432 | YAML 433 | 434 | ``` 435 | Author: Author Name 436 | Genre: Fiction 437 | DateRead: '2022-06-01' 438 | Read: false 439 | Tags: 440 | - Mind-blowing 441 | - Interesting 442 | - Science 443 | ``` 444 | 445 | 446 | [obsidian]: https://obsidian.md 447 | [dataview]: https://github.com/blacksmithgu/obsidian-dataview 448 | [trajecta]: https://trajecta.app 449 | 450 | --- 451 | 452 | --------------------------------------------------------------------------------