| org-roam-ql | | |
| org-roam-ql-ql | | |
This package provides an interface to easily query and display results from your org-roam database.
You can query org-roam with org-roam-ql-search. The results are displayed in an org-roam-like buffer. org-roam-ql also comes with a transient that can be used to modify the results viewed. The transient can be activated with v. You can modify the title (t), view kind (k), query (q), filter (F), sort (s) and specify whether the query should be evaluated against the current in-buffer results or against the whole org-roam database (i). Refreshing the buffer (r) will display the updated results.
The transient is available in the org-roam buffer as well, which allows you to start a query from the results in the org-roam buffer. You also can view the results in an agenda-like buffer (S). When entering a query in any interactive function of org-roam-ql, it also has completion-at-point. org-roam-ql buffers support bookmarks (set with bookmark-set). For convenience, the transient has a shortcut for that (b).
org-roam-ql can be installed from MELPA or with other package management tools like quelpa and straight
Example configuration:
(use-package org-roam-ql
;; If using straight
:straight (org-roam-ql :type git :host github :repo "ahmed-shariff/org-roam-ql"
:files (:defaults (:exclude "org-roam-ql-ql.el")))
;; If using quelpa
:quelpa (org-roam-ql :fetcher github :repo "ahmed-shariff/org-roam-ql"
:files (:defaults (:exclude "org-roam-ql-ql.el")))
;; Simple configuration
:after (org-roam)
:bind ((:map org-roam-mode-map
;; Have org-roam-ql's transient available in org-roam-mode buffers
("v" . org-roam-ql-buffer-dispatch)
:map minibuffer-mode-map
;; Be able to add titles in queries while in minibuffer.
;; This is similar to `org-roam-node-insert', but adds
;; only title as a string.
("C-c n i" . org-roam-ql-insert-node-title))))org-roam-ql-search (SOURCE-OR-QUERY &optional TITLE FILTER SORT-FN PREVIEW-FN)- This is an interactive command that creates a
org-roam-qlbuffer with the nodes of the correspondingSOURCE-OR-QUERYwithTITLE.FILTERis an additional query which further filters the nodes displayed. Anorg-roam-qlbuffer is functionally similar to theorg-roam-buffer, but allows displaying any list of nodes (see screen-shots above). When called interactively, it will prompt for theSOURCE-OR-QUERYandTITLE. Note that when entering queries interactively either inorg-roam-ql-searchor in the transient, you can get completion-at-point withtab.SORT-FNis used for sorting the results. It can be a string name of a registered sort function or a predicate function that can be used to sort the nodes (should take two nodes as input and return a non-nil value if the first node should be before the second). By default the following sort function are registered:file-mtime,file-atime,deadline,scheduled,point,level,file-title,fileandtitle. Each corresponds to the respective slot of an org-roam-node. It is possible to register new sort functions withorg-roam-ql-register-sort-fn. These registered functions will also appear as options for completion in the transient.PREVIEW-FNis a function used to generate the preview content on theorg-roam-ql-modebuffer. See Custom preview function for org-roam-ql buffer for more information on what this value can be. IfPREVIEW-FNis nil, the value oforg-roam-ql-preview-functionwill be used. If it is non-nil, this argument will be set as the buffer local value fororg-roam-ql-preview-functionin the correspondingorg-roam-ql-modebuffer. - org-roam-ql-search-backlinks (SOURCE-OR-QUERY &optional TITLE FILTER SORT-FN PREVIEW-FN)
- This is similar to
org-roam-ql-search, but displays nodes that have a backlink to any of the nodesSOURCE-OR-QUERYresolves to. You can switch between the results of callingorg-roam-ql-searchandorg-roam-ql-search-backlinkswithkin the transient dispatch. org-roam-ql-nodes (SOURCE-OR-QUERY)- Given a
SOURCE-OR-QUERY, return a list of nodes. org-roam-ql-agenda-block (QUERY)- Meant to be used in
org-agenda-custom-commandsas a user-defined function. Insert items from processingQUERY(which is aSOURCE-OR-QUERY) into the current buffer. QUERY is the `match’ item in the custom command form. Currently this doesn’t respect agenda restrictions. Example:(setq org-agenda-custom-commands ("cr" "Node a" org-roam-ql-agenda-block '(title "Node a")))
org-roam-ql-nodes-files (SOURCE-OR-QUERY)- Given a
SOURCE-OR-QUERY, returns a list of files for the nodes. Can be used inorg-agenda-custom-commands. Example:(setq org-agenda-custom-commands ("cr" "todo nodes" todo "TODO" ((org-agenda-files (org-roam-ql-nodes-files '(title "Node"))))))
org-roam-ql-add-saved-query (NAME DOCSTRING QUERY)- Stores valid QUERY with
NAMEandDOCSTRING. TheNAMEcan be used as a query in place of any otherSOURCE-OR-QUERY.NAMEcan be a string or a symbol. org-roam-ql-register-dblock-column- Register a new column to use with dblock. When
IDENTIFIERis seen in:columnsof the org-roam-ql dblock (see Org dynamic block),FNwill be called with one parameter, an org-roam-node. - org-roam-backlinks-section-with-ql-filter
- Same as
org-roam-backlinks-section, but will respect a filter in aorg-roambuffer. See Filtering org-roam buffers. - org-roam-reflinks-section-with-ql-filter
- Same as
org-roam-reflinks-section, but will respect a filter in aorg-roambuffer. See Filtering org-roam buffers.
- A list of
org-roam-nodes - This should be self-explanatory.
- A list of parameters that can be passed to
org-roam-db-query - It should be a list of the form
(QUERY ARG1 ARG2...). The result of callingorg-roam-db-querywith these parameters should return a list of records where the first element is the ID of a corresponding node. For example:(org-roam-ql-nodes '([:select [id] :from nodes :where (= todo \"TODO\")]))
- A SQL statement
- A SQL statement (a string starting with “select”)
- Saved query name
- Name of a saved query (see
org-roam-ql-add-saved-query). This can be string or a symbol. Note that the name of the saved query is always stored as a symbol. If a string is passed, it gets interned into a symbol before looking up the query. The returned nodes will be a result of executing the query represented by the name. - Bookmark name
- Name of a bookmark of a org-roam-ql-buffer. This matched against the name given when
bookmark-setis called from a org-roam-ql-buffer. - Buffer name
- A buffer or buffer-name of a
org-roambuffer, aorg-roam-qlbuffer or an agenda-like buffer displaying a list of org-roam nodes. - Function
- A function that returns a list of
org-roam-nodes - A
QUERY - This is a predicate, similar to the predicates in org-ql. Returns all nodes that pass for the given predicate. For example, consider the following call to
org-roam-ql-nodes:(org-roam-ql-nodes '(and (todo "TODO") (tags "tag1" "tag2") "*org-roam*"))
In the above example, the result would contain any nodes whose todo state is
TODO, have tags “tag1” and “tag2” and are in the org-roam buffer. The following are predicates available by default in org-roam-ql:or (SOURCE-OR-QUERY1 SOURCE-OR-QUERY2 ...)- Tests if a node matches/contained-in any of the
SOURCE-OR-QUERY’s. and (SOURCE-OR-QUERY1 SOURCE-OR-QUERY2 ...)- Similar to
or, but should satisfy all predicates or contained in all the results ofSOURCE-OR-QUERY’s. not (SOURCE-OR-QUERY)- Tests if a node doesn’t match the result or not contained in the result of
SOURCE-OR-QUERY. file (MATCH &optional EXACT USE-REGEXP)- Test if nodes file name matches
MATCH. IfEXACTis non-nil, the file slot should be an exact match toMATCH. By default, this uses sql LIKE, but ifUSE-REGEXPis non-nil, thenMATCHwill be treated as a regex and regex matching will be used. Note the slotfileof an org-roam-node would contain the absolute path. file-title (MATCH &optional EXACT USE-REGEXP)- Similar to
file, tests thefile-titleslot of a node. id (ID)- Tests if the
IDof a node is a match to the value passed. level= (LEVEL)- Tests if the
levelof a node is equal toLEVEL. level< (LEVEL)- Tests if the
levelof a node is less thanLEVEL. level> (LEVEL)- Tests if the
levelof a node is greater thanLEVEL. level<> (LEVEL)- Tests if the
levelof a node is not equal toLEVEL. point= (POINT)- Tests if the
pointof a node is equal toPOINT. point< (POINT)- Tests if the
pointof a node is less thanPOINT. point> (POINT)- Tests if the
pointof a node is greater thanPOINT. point<> (POINT)- Tests if the
pointof a node is not equal toPOINT. todo (MATCH &optional EXACT USE-REGEXP)- Similar to
file, tests the todo state of a node. priority (MATCH &optional EXACT USE-REGEXP)- Similar to
file, tests the priority of a node. scheduled (COMPARISON TIME-STRING)- Compares the
scheduledof the node withTIME-STAMPbased onCOMPARISON.TIME-STAMPis any valid value for org date-time prompt.COMPARISONis either<or>. Example:(scheduled > "-3w") scheduled-is-after (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes withscheduleafterTIME-STRING.scheduled-is-before (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes withschedulebeforeTIME-STRING.deadline (COMPARISON TIME-STRING)- Same as
scheduled, tests thedeadlineof a node. deadline-is-after (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes withdeadlineafterTIME-STRING.deadline-is-before (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes withdeadlinebeforeTIME-STRING.title (MATCH &optional EXACT USE-REGEXP)- Similar to
file, tests the title of a node. Note this, this only considers thetitle, and not any of thealiases. aliases (MATCH &optional EXACT USE-REGEXP)- Similar to
file, tests the aliases of a node. title-or-alias (MATCH &optional EXACT)- Similar to
file, tests bothtitleandaliasesof a node. If notEXACTwill always use regex matching. properties (PROP PROP-VAL)- Tests if the value of the property of a node PROP is a match to PROP-VAL. PROP-VAL can be a regular expression.
tags (TAG1 TAG2 ...)- Tests if the tags of a node have TAG1, TAG2, etc.
refs (MATCH &optional EXACT USE-REGEXP)- Similar to
file, tests the nodes refs slot. backlink-to (SOURCE-OR-QUERY &key (TYPE "id") (COMBINE :or))- Tests if the node has a backlink to any of the nodes from resolving
SOURCE-OR-QUERY.TYPEspecifies the link type. IfTYPEis nil, it will match to all types of links.COMBINEcan be :and or :or. IfCOMBINEis:and, return only nodes that have backward links to all results ofSOURCE-OR-QUERY; if:or, return nodes that have backward links to any of them. For example, the query(backlink-to (title "Node") :type nil :combine :and)will match to all types of backlinks and return nodes that have backlinks to all the nodes(title "Node")resolve to. backlink-from (SOURCE-OR-QUERY &key (TYPE "id") (COMBINE :or))- Similar to
backlink-to, tests if there are any backlinks from (aka forward links) the resulting nodes fromSOURCE-OR-QUERY. in-buffer (BUFFER-NAME)- This is similar to passing a buffer-name as
SOURCE-OR-QUERY. Tests if a node is in the org-roam buffer namedBUFFER-NAME. nodes-list (NODES-LIST)- This is similar to passing a list of nodes as
SOURCE-OR-QUERY. Tests if a node is in theNODES-LIST. function (FUNC)- This is similar to passing a function as
SOURCE-OR-QUERY. Tests if the node is in the result of executing the functionFUNC. funcall (FUNC)- Tests a node with the function
FUNC, which takes an org-roam node as parameter. Test passes if the function returns non-nil. file-atime (COMPARISON TIME-STRING)- Same as
scheduled, tests thefile-atimeof a node. file-atime-is-after (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes wherefile-atimeis afterTIME-STRING.file-atime-is-before (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes wherefile-atimeis beforeTIME-STRING.file-mtime (COMPARISON TIME-STRING)- Same as
scheduled, tests thefile-mtimeof a node. file-mtime-is-after (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes wherefile-mtimeis afterTIME-STRING.file-mtime-is-before (TIME-STRING)TIME-STRINGis the same asscheduled. This filters for nodes wherefile-mtimeis beforeTIME-STRING.
There are two ways to add a new predicate to org-roam-ql:
org-roam-ql-defpred (NAME DOCSTRING EXTRACTION-FUNCTION COMPARISON-FUNCTION)- Creates a predicate that can be used as
SOURCE-OR-QUERY. For example, for a predicate defined as follows:(org-roam-ql-defpred sample "A sample predicate" extraction-function comparison-function)When the following predicate is used as
SOURCE-OR-QUERY:(org-roam-ql-nodes '(sample arg1 arg2))It tests each
nodein the whole org-roam database as follows:(apply comparison-function (append (list (funcall extraction-function node)) arg1 arg2))
The
EXTRACTION-FUNCTIONtakes an org-roam-node and returns a value that will be passed as the first parameter toCOMPARISON-FUNCTION. The remainder of the parameters when calling the predicate is passed as remaining parameters toCOMPARISON-FUNCTION. When theCOMPARISON-FUNCTIONreturns a non-nil value, it will be included in the result. org-roam-ql-defexpansion (NAME DOCSTRING EXPANSION-FUNCTION)- Adds an
EXPANSION-FUNCTIONwhich will be identified byNAMEin an org-roam-ql query. TheEXPANSION-FUNCTIONshould take the parameters passed in the query and return values that can be passed toorg-roam-ql-nodes.
org-roam-ql-register-sort-fn (FUNCTION-NAME SORT-FUNCTION)- Registers a sort function which can be used with
org-roam-ql-nodes.FUNCTION-NAMEis the string name used to refer to this function with.SORT-FUNCTIONis a function that takes two org-roam-nodes and return a truth value, which is used to sort, i.e., if non-nil, the first node would be before the second node passed to the function. Uses `seq-sort’. If a sort-function with the given name already exists, it would be overwritten. The following example registers a sort function named “custom-prop” which sorts the values based on the “CUSTOM-PROP” property of a node.(org-roam-ql-register-sort-fn "custom-prop" (lambda (el1 el2) (string< (cdr (assoc "CUSTOM-PROP" (org-roam-node-properties el1))) (cdr (assoc "CUSTOM-PROP" (org-roam-node-properties el2))))))
Similar to org-ql, org-roam-ql also provides a dynamic block. The header parameters are as follows:
:query- A validSOURCE-OR-QUERY:columns- A list of columns to display. Each column name is a:SYM- A symbol. This will be used as the column title. It can be:- A slot name of
org-roam-node. For any function/accessor with a name of the formorg-roam-node-<name>, which takes anorg-roam-nodeas a parameter,<name>can also be used asSYM. For example, if there is a function namedorg-roam-node-short-title,short-titlecan be used as a column name (SYM), this will result in a column with the titleshort-titlewhere the content of each row is the result of calling the respective function. - The identifier used to register a function using
org-roam-ql-register-dblock-column.
- A slot name of
(SYM NAME)- A list where the first element is aSYM(see above) and the second element should be a string NAME. In this case, the NAME will be used as the column title as opposed toSYM.((SYM [NAME]) ARG1 ARG2...)- A list where the first element is similar to the above(SYM NAME)pattern. However, hereNAMEis optional. IfNAMEis not provided,SYMwill be used as the column title. The corresponding function forSYMwill be called with the remainder of the elements in the list (i.e.,ARG1,ARG2, etc.) as arguments after the node. That is, if the corresponding function isFN, it will be called with(apply FN NODE '(ARG1 ARG2 ...)).
:sort- Name of a registered sort functions. Seeorg-roam-ql-searchfor more info on the values for sort functions.:take(optional) - If a positive integer N, take the first N elements, if a negative -N, take the last N nodes.:no-link(optional) - If a non-nil value is set, the first column containing the links will be dropped.
If no-link is not provided as a parameter, the first column is a link to the node. Since it is an id link, it will be a backlink to the node.
Following is an example of a dynamic block and its result.
A few other example of dynamic blocks:
- With custom column titles and sorting based on “deadline”:
#+BEGIN: org-roam-ql :query (todo "DONE") :columns ((title "T") (deadline "D")) :sort "deadline" - Org-roam-ql comes with a custom column `property` which is registered with
org-roam-ql-register-dblock-column. It expects one parameter, the property name. The following uses this column with the custom column title “cat” showing the value of property “CATEGORY”:#+BEGIN: org-roam-ql :query (todo "DONE") :columns (title ((property "cat") "CATEGORY")) - Same as above, without a custom column title for the property column. The title for that column would be “Property”:
#+BEGIN: org-roam-ql :query (todo "DONE") :columns (title ((property) "CATEGORY")) - A custom column can be added using
org-roam-ql-register-dblock-column:(defun my/org-roam-ql-dblock-category-column (node) (alist-get "CATEGORY" (org-roam-node-properties node) nil nil #'string-equal)) (org-roam-ql-register-dblock-column 'cat #'my/org-roam-ql-dblock-category-column)
The above can be used as follows:
#+BEGIN: org-roam-ql :query (todo "DONE") :columns (title cat)
org-roam-ql buffers visualize the node itself. This is unlike org-roam buffers, which visualize relationships (like backlinks or refs). To allow better customization, org-roam-ql has the following customizable variables. These are mostly similar to the org-roam counterparts:
org-roam-ql-preview-function- This differs from the
org-roamcounterpart. The preview function used to generate the content of a node preview in anorg-roam-ql-modebuffer. Before calling this, the point will be set toorg-roam-node-point. It will be called with two arguments: (1) the corresponding node, and (2) the source-or-query of the corresponding buffer. See Valid values for SOURCE-OR-QUERY for what the value of source-or-query can be. By default, it callsorg-roam-preview-function. Note that this can be set locally to the buffer and will be used to generate the preview when the buffer is refreshed. The value set for this variable can also be overridden by passing it as a parameter toorg-roam-ql-searchwhen called programmatically; in this case, the preview function passed as an argument is set as the buffer-local value for this variable. Return a string to display the node, ornilto omit it entirely, including its heading. An empty string ("") still displays the heading. The preview runs before the heading function. Omitted nodes are also excluded when the results buffer is used as a source or within-buffer. org-roam-ql-heading-function- The function used to generate the heading of a node in `org-roam-ql-mode’ buffer. Similar to
org-roam-ql-preview-functionabove, the point will be set to the point of the node and will be called with two parameters: (1) the node, and (2) the source-or-query. org-roam-ql-buffer-prerender-functions- Hook run after initializing buffer-local render state and before resolving the query. A non-nil
PREVIEW-FNargument is saved asorg-roam-ql-preview-functionbefore this hook runs, even when there are no results. Hook functions can change that buffer-local value to select the preview function used for the current render and later refreshes. org-roam-ql-buffer-postrender-functions- Hook run after rendering all result sections. Both render hooks accept no arguments and run with the results buffer as the current buffer, on initial rendering and every refresh, including empty results. Both default to nil.
org-roam-ql-preview-postprocess-functions- A list of functions to postprocess the preview content. This defaults to
org-roam-preview-postprocess-functions. Each function takes the preview string and returns the post-processed string. Functions run in list order, only while the current content is a string. If a postprocessor returnsnil, remaining postprocessors are skipped and the section remains with an empty preview. If the preview function itself returnsnil, the node is omitted and no postprocessors run.
See M-x customize-group RET org-roam-ql for more customization options.
org-roam-ql comes with two alternate functions that can be used with org-roam-mode-sections:
(setq org-roam-mode-sections
'(org-roam-backlinks-section-with-ql-filter
org-roam-reflinks-section-with-ql-filter))When these sections are configured in org-roam-mode-sections, using F in org-roam-ql-buffer-dispatch (bound to v in org-roam buffers) lets you specify an org-roam-ql query that will be used to filter the backlinks/reflinks displayed in the respective sections. After setting a filter, refresh the buffer for it to take effect.
Optionally, org-roam-ql results can be visualized with org-ql, available through the extension org-roam-ql-ql (naming things is hard!!). This also can be installed from MELPA or with other package management tools like quelpa and straight.
(use-package org-roam-ql-ql
;; If using straight
:straight (org-roam-ql-ql :type git :host github :repo "ahmed-shariff/org-roam-ql"
:files (:defaults (:exclude "org-roam-ql.el")))
;; If using quelpa
:quelpa (org-roam-ql-ql :fetcher github :repo "ahmed-shariff/org-roam-ql"
:files (:defaults (:exclude "org-roam-ql.el")))
;; Simple config
:after (org-ql org-roam-ql)
:config
(org-roam-ql-ql-init))Note that org-ql works only with org entries, i.e., `heading nodes`. Hence, if there are any file nodes in the result, they will not be displayed. To make that clear, when org-roam-ql results are displayed in an org-ql-view buffer, a warning is added to the end mentioning how many file nodes were in the result. If the extension is loaded, you may view the org-roam-ql results with Q from the org-roam-ql transient. An org-ql-view can be viewed in an org-roam-like buffer with R from the org-ql-view transient.
The wiki has additional tips and tricks, like using org-roam-ql to filter completion candidates in minibuffer.



