### Install org-roam-ql Package

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Install the org-roam-ql package using either straight.el or package.el.

```emacs-lisp
;; Using straight.el
(straight-use-package 'org-roam-ql)

;; Using package.el
;; M-x package-install RET org-roam-ql
```

--------------------------------

### Install org-roam-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Install org-roam-ql with optional org-ql integration. Ensure org-roam is loaded first.

```emacs-lisp
(use-package org-roam-ql
  :after org-roam
  :bind ((:map org-roam-mode-map
          ("v" . org-roam-ql-buffer-dispatch))))

;; Optional: org-ql integration
(use-package org-roam-ql-ql
  :after (org-roam-ql org-ql)
  :config (org-roam-ql-ql-init))
```

--------------------------------

### Install org-roam-ql with straight.el or quelpa

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

Example Emacs Lisp configuration for installing org-roam-ql using straight.el or quelpa. It also configures keybindings for org-roam-ql's transient and minibuffer interactions.

```emacs-lisp
(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))))
```

--------------------------------

### Setup Org-Roam-QL QL Package

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Configures the org-roam-ql-ql package using use-package. Includes optional setup for org-super-agenda and initialization of the QL integration.

```emacs-lisp
(use-package org-roam-ql-ql
  :after (org-roam-ql org-ql)
  :init
  ;; Optional: org-super-agenda for grouping
  (require 'org-super-agenda nil t)
  :config
  (org-roam-ql-ql-init))
```

--------------------------------

### Correct Query Syntax Examples

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Corrected syntax examples for org-roam-ql-nodes, demonstrating proper usage with arguments and combined predicates.

```emacs-lisp
;; Correct syntax
(org-roam-ql-nodes '(todo "TODO"))
(org-roam-ql-nodes '(and (tags "work") (todo "TODO")))
```

--------------------------------

### Multi-Step Workflow Example

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Demonstrates a typical workflow involving switching between org-roam-ql, org-ql-view, and agenda views. This example shows how to initiate a search, view it in org-ql, and then convert it to an agenda view.

```emacs-lisp
;; Start with org-roam-ql search for all tags
(org-roam-ql-search '(tags "project"))

;; Press 'v' then 'Q' to see in org-ql-view
;; In org-ql-view, can further filter with org-ql predicates

;; Press 'v' then 'R' to switch to agenda view
;; Now can use org-agenda actions on the results
```

--------------------------------

### Interactive Search Refinement Setup

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Initiates a search that allows for interactive refinement of the query, filters, and sorting within the buffer. This is a setup function.

```emacs-lisp
(defun interactive-refine-search (initial-query)
  "Start search and allow interactive refinement"
  (org-roam-ql-search initial-query "Refinable Search")
  
  ;; In buffer, user presses 'v' and modifies:
  ;; - Query (q)
  ;; - Filter (F)
  ;; - Sort (s)
  ;; - Refresh (r)
  
  ;; Each modification updates results
  nil)

;; Setup
(interactive-refine-search '(tags "explore"))
```

--------------------------------

### Example Org-Roam-QL Node Query

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

Demonstrates how to use org-roam-ql-nodes with a combination of predicates to filter nodes.

```emacs-lisp
(org-roam-ql-nodes '(and (todo "TODO") (tags "tag1" "tag2") "*org-roam*"))
```

--------------------------------

### Bookmark Structure Example

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

This example demonstrates the structure of an Org-Roam-QL bookmark, which stores query context including the query itself, display title, sort order, kind, and filter.

```emacs-lisp
((query . (tags "important"))
  (title . "Important Items")
  (sort . "deadline")
  (kind . nodes)
  (filter . (todo "TODO"))
  (handler . org-roam-ql--bookmark-open))
```

--------------------------------

### Dynamic Block Parameters Example

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

This example shows how to define parameters for the `org-dblock-write:org-roam-ql` function using a plist format, specifying query, columns, sorting, and other options.

```emacs-lisp
(:query (todo "TODO")
  :columns (title tags)
  :sort "deadline"
  :take 10
  :no-link t)
```

--------------------------------

### Querying Nodes with SQL-like Syntax

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

This example demonstrates how to use `org-roam-ql-nodes` with a list of parameters that can be passed to `org-roam-db-query` to select nodes based on a condition.

```emacs-lisp
(org-roam-ql-nodes '([:select [id] :from nodes :where (= todo "TODO")]))
```

--------------------------------

### Configure org-roam-ql-ql Extension

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

Configuration for the org-roam-ql-ql extension, showing installation methods for straight.el and quelpa, and basic initialization. Ensure org-ql and org-roam-ql are loaded before this.

```emacs-lisp
(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))
```

--------------------------------

### Org-Roam-QL Preview Function Examples

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

Demonstrates how to define custom preview functions for Org-Roam-QL buffers. These functions determine the content displayed for each node.

```emacs-lisp
;; Show node content
(lambda (node _query)
  (save-excursion
    (org-roam-with-file (org-roam-node-file node) t
      (goto-char (org-roam-node-point node))
      (org-get-entry))))
```

```emacs-lisp
;; Show minimal info
(lambda (node _query)
  (format "Title: %s\nTags: %s\nTODO: %s"
          (org-roam-node-title node)
          (string-join (org-roam-node-tags node) ", ")
          (or (org-roam-node-todo node) "—")))
```

--------------------------------

### Org-Roam-QL Heading Function Examples

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

Examples of custom heading functions for Org-Roam-QL buffers. These functions format the section titles, potentially including faces and properties.

```emacs-lisp
;; Just the title
(lambda (node _)
  (propertize (org-roam-node-title node)
              'face 'org-roam-title))
```

```emacs-lisp
;; Title with TODO state and tags
(lambda (node _)
  (concat (when-let (todo (org-roam-node-todo node))
            (concat (propertize todo 'face 'org-todo) " "))
          (propertize (org-roam-node-title node)
                      'face 'org-roam-title)
          (when-let (tags (org-roam-node-tags node))
            (concat " " (string-join tags ":")))))
```

--------------------------------

### SOURCE-OR-QUERY Type Examples

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

Illustrates various forms for specifying node sources or queries, including query expressions, SQL strings, and saved query names.

```emacs-lisp
;; Query expression
'(and (todo "TODO") (tags "urgent"))
```

```emacs-lisp
;; Saved query (symbol)
'my-important-tasks
```

```emacs-lisp
;; SQL string
"select id from nodes where todo = 'DONE' order by deadline"
```

```emacs-lisp
;; DB parameters
'([:select [id] :from nodes :where (> deadline $s1)]
  "2024-12-25")
```

```emacs-lisp
;; Buffer reference
"*org-roam: My Node*"
(get-buffer "myresults")
```

```emacs-lisp
;; Node list
(list node1 node2)
node1
```

```emacs-lisp
;; Function
(lambda () (org-roam-node-list))
```

--------------------------------

### Invalid Query Syntax Examples

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Examples of incorrect query syntax for org-roam-ql-nodes, including mismatched parentheses, invalid operators, wrong data types, and missing arguments.

```emacs-lisp
(org-roam-ql-nodes '(todo))          ; Missing argument to 'todo'
(org-roam-ql-nodes '(undefined-pred "text"))  ; Unknown predicate
(org-roam-ql-nodes (list))           ; Empty list is invalid
(org-roam-ql-nodes "not-a-query")    ; String not starting with "select"
```

--------------------------------

### Query Syntax: Simple Predicates

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Examples of simple predicates for filtering nodes by TODO state, tags, title, file, priority, and ID.

```emacs-lisp
(todo "TODO")                 ; TODO state
(todo "DONE")
(tags "urgent")               ; Has tag
(title "Meeting")             ; Title contains
(file "projects")             ; File path contains
(priority "A")                ; Priority
(id "abc123"))                 ; Exact ID
```

--------------------------------

### Bind Org-Roam-QL Buffer Dispatch to a Key

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-core.md

Example of binding the `org-roam-ql-buffer-dispatch` function to a key in `org-roam-mode-map`. This enables launching the transient interface with a single key press.

```emacs-lisp
;; Bind to a key
(define-key org-roam-mode-map "v" 'org-roam-ql-buffer-dispatch)

;; Usage: press 'v' to open transient, then select option
```

--------------------------------

### Example 'backlink-to' Usage

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

Finds nodes with backlinks of any type to nodes titled 'Node', requiring backlinks to all such nodes.

```emacs-lisp
(backlink-to (title "Node") :type nil :combine :and)
```

--------------------------------

### Project Review Query

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Start a project review by searching for nodes tagged 'active-project'. You can then switch to agenda view for GTD actions.

```emacs-lisp
;; Start with project tag
(org-roam-ql-search '(tags "active-project"))
;; Use transient to set filter, sort, etc.
;; Press 'S' to switch to agenda view for GTD actions

```

--------------------------------

### Query Syntax: Complex Examples

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Combine various predicates and operators to construct complex queries for specific use cases.

```emacs-lisp
;; Active work items
(and (todo "TODO")
     (tags "work")
     (not (tags "archived")))

;; Recently modified high-priority items
(and (priority "A")
     (file-mtime-is-after "-1w")
     (todo "TODO"))

;; Nodes linking to Project Alpha but not archived
(and (backlink-to (title "Project Alpha"))
     (not (tags "archived")))
```

--------------------------------

### Configure Org Agenda with Org-Roam-QL Blocks

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-core.md

Example configuration for `org-agenda-custom-commands` to include org-roam-ql agenda blocks. This allows viewing specific reports or project notes directly in the agenda.

```emacs-lisp
;; In org-agenda-custom-commands
(setq org-agenda-custom-commands
      '( ("r" "Reports and Project Notes"
         ((org-roam-ql-agenda-block '(tags "report"))
          (org-roam-ql-agenda-block '(tags "project"))))))

;; Usage: press 'r' to see agenda with custom blocks
```

--------------------------------

### Function Returning List of Nodes

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Correct examples of functions passed to org-roam-ql-nodes that successfully return a list of org-roam-nodes.

```emacs-lisp
(org-roam-ql-nodes (lambda () (org-roam-node-list)))  ; Correct
(org-roam-ql-nodes (lambda () (list node1 node2)))    ; Correct
```

--------------------------------

### Dynamic Block Missing Query or Columns

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

An example of an org-roam-ql dynamic block that is missing the required :query and :columns parameters.

```org
#+BEGIN: org-roam-ql
:columns (title tags)
#+END
```

--------------------------------

### Get Files from Query

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Retrieve files associated with nodes matching a query, useful for org-agenda-files.

```emacs-lisp
;; Useful for org-agenda-files
(org-roam-ql-nodes-files '(tags "project"))

;; Use with agenda
(setq org-agenda-files (org-roam-ql-nodes-files '(tags "active")))

```

--------------------------------

### Display org-roam-ql results in agenda views

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/README.md

Configures custom agenda commands to display Org-Roam-QL results. This example shows how to create an agenda view named 'Review' that lists nodes tagged 'project'.

```emacs-lisp
(setq org-agenda-custom-commands
      '(("r" "Review" (org-roam-ql-agenda-block '(tags "project")))))
```

--------------------------------

### Using Anonymous Sort Function

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Example of directly providing an anonymous lambda function as a sort function to org-roam-ql-nodes.

```emacs-lisp
(org-roam-ql-nodes '(tags "work")
  (lambda (n1 n2) (string< (org-roam-node-title n1)
                           (org-roam-node-title n2))))
```

--------------------------------

### Find and Filter Work Items with Org-Roam-QL

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Starts a search for work items using tags and allows further filtering in org-ql-view. Press 'v' then 'Q' to open in org-ql-view.

```emacs-lisp
;; Start
(org-roam-ql-search '(tags "work"))
;; Press 'v' then 'Q' to open in org-ql-view
;; Further filter with org-ql predicates like:
;; (heading "Meeting") → shows meetings in work nodes
```

--------------------------------

### Get File Paths for Nodes in Org-roam-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-core.md

Retrieve a list of unique file paths for nodes matching a given query. Can be integrated with org-agenda-custom-commands.

```emacs-lisp
;; Get files for nodes with a specific tag
(org-roam-ql-nodes-files '(tags "book-notes"))

;; Use with org-agenda-custom-commands
(setq org-agenda-custom-commands
      '(("cr" "Project TODO items" 
         todo "TODO"
         ((org-agenda-files
          (org-roam-ql-nodes-files '(tags "project")))))))

```

--------------------------------

### Optimize Slow Org-Roam-QL Queries

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

For slow queries, simplify the query structure by combining conditions logically or using SQL directly for complex operations. This example shows simplifying nested `and`/`or` conditions.

```emacs-lisp
;; Slow
(org-roam-ql-nodes '(and (or (todo "TODO") (todo "WAIT"))
                          (or (tags "a") (tags "b") (tags "c"))
                          (not (file-mtime-is-before "2020-01-01"))))
```

```emacs-lisp
;; Faster - combine conditions differently
(org-roam-ql-nodes '(and (todo "TODO")
                         (tags "a")))
```

```emacs-lisp
(org-roam-ql-nodes "select id from nodes where todo = 'TODO' limit 100")
```

```emacs-lisp
;; Slower - regex on all nodes
(org-roam-ql-nodes '(title ".*pattern.*" nil t))
```

```emacs-lisp
;; Faster - SQL LIKE
(org-roam-ql-nodes '(title "pattern"))
```

```emacs-lisp
;; Filter first, then sort
(org-roam-ql-nodes '(todo "TODO") "deadline")
;; Rather than sorting all nodes then filtering
```

--------------------------------

### View Archived Items by Date with Org-QL

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Constructs an Org-QL search to find archived items before a specific date. This example demonstrates using org-roam-query predicates within org-ql-search.

```emacs-lisp
;; Start with org-ql-view
(org-ql-search (org-roam-directory)
  '(and (org-roam-query (tags "archived"))
        (org-roam-query (file-mtime-is-before "2024-01-01"))))
```

--------------------------------

### Org-Roam-QL Dynamic Block Column Registration

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

Examples of registering custom column functions for Org-Roam-QL dynamic blocks. These functions define how data is displayed in columns.

```emacs-lisp
;; Simple column
(org-roam-ql-register-dblock-column 'file-size
  (lambda (node)
    (file-size-human-readable
     (file-attribute-size
      (file-attributes (org-roam-node-file node))))))
```

```emacs-lisp
;; Column with parameter
(org-roam-ql-register-dblock-column 'property-value
  (lambda (node prop-name)
    (alist-get (upcase prop-name)
               (org-roam-node-properties node)
               "—"
               nil
               #'string-equal)))
```

```emacs-lisp
;; Use in dblock
;; #+BEGIN: org-roam-ql :query (tags "test")
;;   :columns (title (property-value "CATEGORY") file-size)
;; #+END
```

--------------------------------

### Reference-based Filtering with Backlinks and Refs

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Navigate relationships between items using 'backlink-from' and 'refs' predicates. Examples include finding nodes documented in a specific paper, all references used in a project, and orphaned notes.

```emacs-lisp
;; Find all nodes that are documented in a specific paper
(org-roam-ql-nodes
 '(backlink-from (refs "arxiv:2024.12345")))

;; Find all references used in a project
(org-roam-ql-nodes
 '(and (backlink-to (tags "project-alpha"))
       (refs)))

;; Find orphaned notes (no backlinks or references)
(org-roam-ql-nodes
 '(and (not (backlink-from))
       (not (refs))))
```

--------------------------------

### Correct Argument Count for `org-roam-ql-nodes`

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

When `org-roam-ql-nodes` reports a 'Wrong number of arguments' or SQL syntax error, ensure the number of arguments provided matches the expected count. This example shows correcting a query with too many arguments.

```emacs-lisp
(org-roam-ql-nodes '([:select id :from nodes :where (= todo $s1)]))  ; Missing arg
```

```emacs-lisp
(org-roam-ql-nodes '([:select id :from nodes] "arg1" "arg2"))  ; Too many args
```

```emacs-lisp
(org-roam-ql-nodes '([:select id :from nodes :where (= todo $s1)] "TODO"))
```

--------------------------------

### Org-roam-ql Dynamic Block with Custom Columns and Sorting

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

Example of an org-roam-ql dynamic block that queries for DONE todos, displays custom 'title' and 'deadline' columns, and sorts by 'deadline'.

```org
#+BEGIN: org-roam-ql :query (todo "DONE") :columns ((title "T") (deadline "D")) :sort "deadline"
#+END:
```

--------------------------------

### Hierarchical Filtering with Level and Backlink Predicates

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Filter nodes based on their heading level and parent-child relationships. This example finds top-level project nodes with unfinished sub-tasks and also demonstrates finding deeply nested todos.

```emacs-lisp
;; Find top-level project nodes with unfinished sub-tasks
(org-roam-ql-nodes
 '(and (level= 1)
       (tags "project")
       (backlink-from (and (todo "TODO") (level> 1)))))

;; Find deeply nested todos only
(org-roam-ql-nodes
 '(and (todo "TODO")
       (level> 2)
       (tags "detail")))
```

--------------------------------

### Temporal Queries for Time-Based Filtering

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Perform complex time-based filtering using date predicates like 'deadline', 'deadline-is-before', 'deadline-is-after', 'file-mtime-is-after', and 'file-atime-is-after'. Examples include finding overdue items, this week's deadlines, and recently modified high-priority items.

```emacs-lisp
;; Overdue items
(org-roam-ql-nodes
 '(and (deadline < "today")
       (todo "TODO")))

;; This week's deadlines
(org-roam-ql-nodes
 '(and (deadline-is-before "+1w")
       (deadline-is-after "today")))

;; Recently modified high-priority items
(org-roam-ql-nodes
 '(and (priority "A")
       (or (file-mtime-is-after "-3d")
           (file-atime-is-after "-1d"))))
```

--------------------------------

### Initialize Org-roam-ql-ql Integration

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/configuration.md

Sets up the integration between org-roam-ql and org-ql for seamless switching between their respective views.

```emacs-lisp
(use-package org-roam-ql-ql
  :after (org-roam-ql org-ql)
  :config
  (org-roam-ql-ql-init))
```

--------------------------------

### Get Nodes Programmatically

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Retrieve a list of nodes that match a query without displaying them. Supports sorting.

```emacs-lisp
;; Return list of nodes (no display)
(org-roam-ql-nodes '(todo "TODO"))
```

```emacs-lisp
;; With sorting
(org-roam-ql-nodes '(tags "work") "title")
```

--------------------------------

### org-roam-ql-ql-init

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Initializes the integration between org-roam-ql and org-ql. This function adds advice to `org-ql-view-refresh`, extends transient menus for buffer conversion, and registers the `org-roam-query` predicate for org-ql.

```APIDOC
## org-roam-ql-ql-init

### Description
Initialize org-roam-ql integration with org-ql.

### Method
(org-roam-ql-ql-init)

### Return Type
nil

### Effects

1. Adds advice to `org-ql-view-refresh` to sync org-roam-ql queries
2. Extends `org-roam-ql-buffer-dispatch` transient with org-ql viewing option
3. Extends `org-ql-view-dispatch` transient with org-roam buffer conversion
4. Registers `org-roam-query` predicate for org-ql

### Prerequisites

- `org-ql` package version 0.8.2+
- `org-roam-ql` loaded
- Called after both packages are available

### Example

```emacs-lisp
(use-package org-roam-ql-ql
  :after (org-roam-ql org-ql)
  :config
  (org-roam-ql-ql-init))
```
```

--------------------------------

### Valid Link Predicate Combine Option

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Example of using a valid :combine option (:or) with the 'backlink-to' predicate in org-roam-ql.

```emacs-lisp
(org-roam-ql-nodes '(backlink-to (tags "work") :combine :or))
```

--------------------------------

### Initialize org-ql integration for org-roam-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/README.md

Initializes the Org-QL integration for Org-Roam-QL, enabling the use of 'Q' to view results in org-ql-view buffers.

```emacs-lisp
(org-roam-ql-ql-init)
```

--------------------------------

### Invalid Link Predicate Combine Option

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Example of an invalid :combine option (:not) used with the 'backlink-to' predicate in org-roam-ql.

```emacs-lisp
(org-roam-ql-nodes '(backlink-to (tags "work") :combine :not))
```

--------------------------------

### Initialize org-roam-ql Integration with org-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Call this function to enable the integration between org-roam-ql and org-ql. Ensure both packages are loaded and available before calling.

```emacs-lisp
(org-roam-ql-ql-init)
```

```emacs-lisp
(use-package org-roam-ql-ql
  :after (org-roam-ql org-ql)
  :config
  (org-roam-ql-ql-init))
```

--------------------------------

### Configure org-roam-ql with Dependencies

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Configure org-roam-ql to use its required dependencies like org-roam, transient, dash, s, and magit-section.

```emacs-lisp
(use-package org-roam-ql
  :requires (org-roam transient dash s magit-section)
  ;; ... rest of config
  )
```

--------------------------------

### Invalid Time Comparison Operator Errors

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Examples of using invalid operators (=, <>) with time comparison predicates in org-roam-ql.

```emacs-lisp
(org-roam-ql-nodes '(scheduled = "2024-01-01"))  ; = is invalid
(org-roam-ql-nodes '(deadline "<>" "2024-01-01"))  ; <> is invalid
```

--------------------------------

### Query Syntax: String Matching Options

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Demonstrates different string matching behaviors for queries: default LIKE, case-insensitive exact match, and regex.

```emacs-lisp
(title "text")                ; SQL LIKE match (default)
(title "text" t)              ; Exact case-insensitive match
(title "^T.*" nil t)          ; Regex match
```

--------------------------------

### org-roam-ql-ql-init

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-sorting-customization.md

Initializes the integration between org-roam-ql and org-ql. This function sets up necessary hooks and predicates to enable org-roam-ql queries within the org-ql framework, enhancing query capabilities.

```APIDOC
## org-ql-init

### Description
Initialize integration between org-roam-ql and org-ql.

### Method
(org-roam-ql-ql-init)

### Requirements
`org-ql` package must be installed

### Effects
- Adds advice to `org-ql-view-refresh` to handle org-roam-ql queries
- Adds transient suffixes for switching between buffer views
- Enables `org-roam-query` predicate in org-ql

### Example
```emacs-lisp
(use-package org-roam-ql-ql
  :after (org-roam-ql org-ql)
  :config
  (org-roam-ql-ql-init))
```
```

--------------------------------

### Use Custom Columns in Dynamic Blocks

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/configuration.md

Example of how to use registered custom columns within an org-roam-ql dynamic block.

```org
#+BEGIN: org-roam-ql
:query (tags "article")
:columns (title status ((property "AUTHOR")))
:sort "title"
#+END
```

--------------------------------

### Function Returning Non-List Error

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Examples where a function passed as source-or-query to org-roam-ql-nodes does not return a list of org-roam-nodes, leading to an error.

```emacs-lisp
(org-roam-ql-nodes (lambda () "wrong return value"))
(org-roam-ql-nodes (lambda () (org-roam-node-list nil)))  ; Returns something else
```

--------------------------------

### Create Bookmarks in Org-Roam-QL Buffers

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

To ensure bookmarks correctly restore views, create them only within Org-Roam-QL buffers using `bookmark-set`. Bookmarks created in other buffer types may not function as expected.

```emacs-lisp
(bookmark-set)
```

--------------------------------

### Using a Custom Registered Column in Org-roam-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/README.org

Example of an org-roam-ql dynamic block utilizing the custom 'cat' column, which displays the 'CATEGORY' property.

```org
#+BEGIN: org-roam-ql :query (todo "DONE") :columns (title cat)
#+END:
```

--------------------------------

### Initialize Org-Roam-QL QL

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Ensures that Org-Roam-QL's QL integration is initialized. Call this function before using Org-Roam-QL predicates in Org-QL.

```emacs-lisp
;; In initialization
(org-roam-ql-ql-init)
```

--------------------------------

### Registering and Using Custom Predicate

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Demonstrates how to define and register a custom predicate using `org-roam-ql-defpred` and then use it in a query.

```emacs-lisp
(org-roam-ql-defpred my-pred "docs"
  (lambda (n) (org-roam-node-title n))
  (lambda (v arg) (string-match arg v)))

(org-roam-ql-nodes '(my-pred "pattern"))
```

--------------------------------

### Registering and Using Custom Sort Function

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Shows how to register a custom sort function using `org-roam-ql-register-sort-fn` and then use it.

```emacs-lisp
(org-roam-ql-register-sort-fn "my-sort"
  (lambda (n1 n2) (string< (org-roam-node-title n1)
                           (org-roam-node-title n2))))
```

--------------------------------

### Buffer-Specific Customization

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Configure Org-Roam-QL settings like preview functions and postrender hooks on a per-buffer basis. This enables different behaviors for different search contexts.

```emacs-lisp
;; After creating org-roam-ql search
(defun setup-custom-orq-buffer (source query)
  "Create org-roam-ql buffer with custom settings"
  (let* ((buffer-name (format "*orq: %s*" query))
         (inhibit-read-only t))
    (org-roam-ql-search source query)
    
    ;; Customize this buffer
    (with-current-buffer buffer-name
      ;; Custom preview
      (setq-local org-roam-ql-preview-function
                  (lambda (node _) 
                    (format "Title: %s\nID: %s" 
                            (org-roam-node-title node)
                            (org-roam-node-id node))))
      
      ;; Custom postrender hook
      (add-hook 'org-roam-ql-buffer-postrender-functions
                (lambda () 
                  (goto-char (point-min))
                  (insert (format "Query: %S\n\n" query)))
                nil t))))

;; Use
(setup-custom-orq-buffer '(tags "project") "Active Projects")
```

--------------------------------

### Dynamic Buffer Updates via Advice

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Automatically refresh Org-Roam-QL buffers when the Org-Roam database changes. This uses `advice-add` to hook into the `org-roam-db-sync` function.

```emacs-lisp
;; Auto-refresh when org-roam database changes
(defun watch-db-and-refresh ()
  "Refresh all org-roam-ql buffers when DB changes"
  (advice-add 'org-roam-db-sync :after
    (lambda (&rest _) 
      (dolist (buf (buffer-list))
        (with-current-buffer buf
          (when (derived-mode-p 'org-roam-ql-mode)
            (org-roam-ql-refresh-buffer)))))))

;; Setup
(watch-db-and-refresh)
```

--------------------------------

### Invalid Sort Function Usage

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Examples of incorrect usage of sort functions with org-roam-ql-nodes, including unregistered names and functions with incorrect argument counts.

```emacs-lisp
(org-roam-ql-nodes '(tags "work") "invalid-sort")
(org-roam-ql-nodes '(tags "work") (lambda (a b c) "too many args"))
```

--------------------------------

### Org-ql Integration

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

View org-roam-ql results in org-ql or use org-roam-query predicate directly with org-ql-search.

```emacs-lisp
;; After org-roam-ql-ql-init:

;; View org-roam-ql results in org-ql
;; Press 'v' then 'Q' in org-roam-ql buffer

;; Or use org-roam-query predicate directly
(org-ql-search (org-roam-directory)
  '(org-roam-query (tags "project")))

```

--------------------------------

### Configure Org-roam-mode Sections

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/configuration.md

Integrates filtered backlinks and reflinks into org-roam-mode sections using org-roam-ql.

```emacs-lisp
(setq org-roam-mode-sections
      '(org-roam-backlinks-section-with-ql-filter
        org-roam-reflinks-section-with-ql-filter))
```

--------------------------------

### Define and Use Saved Queries

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/configuration.md

Pre-define commonly used queries for quick access. Use 'org-roam-ql-add-saved-query' to define and 'org-roam-ql-search' to execute them.

```emacs-lisp
;; Todo items
(org-roam-ql-add-saved-query 'my-todos
  "All active TODO items"
  '(and (todo "TODO")
        (not (tags "archived"))))

;; Recent changes
(org-roam-ql-add-saved-query 'recent
  "Files modified in last week"
  '(file-mtime-is-after "-1w"))

;; Project-specific
(org-roam-ql-add-saved-query 'project-alpha
  "All items for Project Alpha"
  '(or (tags "project-alpha")
       (title "Alpha")))

;; Use them
(org-roam-ql-search 'my-todos)
(org-roam-ql-search 'recent)
```

--------------------------------

### Get Nodes as List

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/README.md

Retrieves a list of org-roam nodes matching the specified query without displaying them in a buffer. Useful for programmatic access to node data.

```emacs-lisp
(org-roam-ql-nodes '(tags "work"))
```

--------------------------------

### Clearing Org QL Cache and Re-querying

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Demonstrates how to manually clear the org-roam-ql cache and then execute a query, useful when results appear stale.

```emacs-lisp
(org-roam-ql-clear-cache)
(org-roam-ql-nodes '(tags "test"))
```

--------------------------------

### Basic and Combined Predicates

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-predicates.md

Demonstrates the use of basic predicates and how to combine them using logical operators like 'and', 'or', and 'not' for sophisticated filtering.

```emacs-lisp
;; Basic predicate
(todo "TODO")
```

```emacs-lisp
;; Combining predicates with 'and'
(and (todo "TODO") (tags "urgent"))
```

```emacs-lisp
;; Combining predicates with 'or'
(or (tags "work") (tags "personal"))
```

```emacs-lisp
;; Negating with 'not'
(not (todo "DONE"))
```

```emacs-lisp
;; Complex combinations
(and (or (todo "TODO") (todo "WAITING"))
     (not (tags "archived")))
```

--------------------------------

### Syncing Database and Clearing Cache

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

Shows the process of ensuring the org-roam database is synchronized and then clearing the org-roam-ql cache to ensure fresh results.

```emacs-lisp
(org-roam-db-sync)
(org-roam-ql-clear-cache)
```

--------------------------------

### Emacs Lisp Sorting Functions for Org-Roam Nodes

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/types.md

Examples of lambda functions used for sorting Org-Roam nodes by title, custom properties, or a combination of TODO status and title.

```emacs-lisp
;; Sort by title
(lambda (n1 n2)
  (string< (org-roam-node-title n1)
           (org-roam-node-title n2)))
```

```emacs-lisp
;; Sort by custom property (descending)
(lambda (n1 n2)
  (string> (alist-get "PRIORITY" (org-roam-node-properties n1) "")
           (alist-get "PRIORITY" (org-roam-node-properties n2) "")))
```

```emacs-lisp
;; Multi-key sort: by TODO first, then title
(lambda (n1 n2)
  (let ((t1 (org-roam-node-todo n1))
        (t2 (org-roam-node-todo n2)))
    (if (string= t1 t2)
        (string< (org-roam-node-title n1)
                 (org-roam-node-title n2))
      (string< (or t1 "") (or t2 "")))))
```

--------------------------------

### Override consult-org-roam-node-read with org-roam-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/wiki/Home

This code advises `consult-org-roam-node-read` to use `org-roam-ql` for node selection, enabling dynamic filtering and completion. It leverages `consult--async-pipeline` for asynchronous processing and `consult--read` for interactive input.

```emacs-lisp
(consult-org-ql-setup)
(advice-add #'consult-org-roam-node-read :override #'consult-org-roam-ql)
```

--------------------------------

### Agenda-based Project Review with Org-Roam-QL

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-ql-extension.md

Initiates a search for project items using tags and provides an option to view results in an agenda format. Press 'v' then 'S' for agenda view.

```emacs-lisp
;; Start with org-roam-ql
(org-roam-ql-search '(tags "project"))
;; Press 'v' then 'S' for agenda view
;; Use org-agenda actions on results
```

--------------------------------

### Customize Org-Roam-QL Preview Function

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-sorting-customization.md

Set the org-roam-ql-preview-function to control how preview content is generated in org-roam-ql buffers. The function takes the node and the query as arguments and returns a string.

```emacs-lisp
(defcustom org-roam-ql-preview-function
  #'org-roam-ql-preview-default-function
  ...)
```

```emacs-lisp
;; Show only title and tags
(setq org-roam-ql-preview-function
  (lambda (node _query)
    (format "Title: %s\nTags: %s"
            (org-roam-node-title node)
            (string-join (org-roam-node-tags node) ", "))))

;; Show with file modification time
(setq org-roam-ql-preview-function
  (lambda (node _query)
    (let ((default-preview (funcall org-roam-preview-function)))
      (concat default-preview
              (format "\n\nModified: %s"
                      (org-roam-node-file-mtime node))))))
```

--------------------------------

### org-roam-ql-preview-postprocess-functions

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-sorting-customization.md

A hook for post-processing preview content strings. Useful for truncating or modifying preview text before display.

```APIDOC
## org-roam-ql-preview-postprocess-functions

### Description
Hook for post-processing preview content strings. Takes a preview string and returns a modified string.

### Type
hook

### Function signature
`(fn content) → string`

### Default
Same as `org-roam-preview-postprocess-functions`

### Example
```emacs-lisp
;; Truncate previews to 500 characters
(add-hook 'org-roam-ql-preview-postprocess-functions
  (lambda (s)
    (if (> (length s) 500)
        (concat (substring s 0 500) "...")
      s)))

;; Remove properties before certain keywords
(add-hook 'org-roam-ql-preview-postprocess-functions
  (lambda (s)
    (replace-regexp-in-string "^#\\+.*$" "" s)))
```
```

--------------------------------

### Define Custom Predicate: has-citations

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/ADVANCED_PATTERNS.md

Define a custom predicate to find nodes that include academic citations, such as those starting with 'arxiv:' or 'doi:'. It iterates through the node's references to find matching patterns.

```emacs-lisp
;; Only citation links
(org-roam-ql-defpred has-citations
  "Find nodes with academic citations"
  (lambda (node) (org-roam-node-refs node))
  (lambda (refs)
    (--any-p (or (string-match "^arxiv:" it)
                 (string-match "^doi:" it))
             refs)))

;; Usage
(org-roam-ql-nodes '(has-citations))
```

--------------------------------

### Configure Org-agenda-custom-commands with org-roam-ql-nodes-files

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/configuration.md

Filters agenda items by org-roam queries using `org-roam-ql-nodes-files`.

```emacs-lisp
(setq org-agenda-custom-commands
      '(("w" "Work Agenda"
         todo "TODO"
         ((org-agenda-files
          (org-roam-ql-nodes-files '(tags "work")))))))
```

--------------------------------

### Complex Query: Active Work Items with Deadlines

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/README.md

Example of a complex query combining multiple predicates and logical operators to find active work items that have deadlines within the next month.

```emacs-lisp
;; Active work items with deadlines
(and (todo "TODO")
     (tags "work")
     (deadline-is-before "+1m"))
```

--------------------------------

### Fix Incorrect Number of Arguments in Column Function

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

When a column function in an Org-Roam-QL query is called with the wrong number of arguments, adjust the function call to match its signature. This example shows correcting a column definition.

```org
#+BEGIN: org-roam-ql
:query (tags "test")
:columns (((property) "PROP1" "EXTRA"))
#+END:
```

```org
#+BEGIN: org-roam-ql
:query (tags "test")
:columns (((property "PROP1")))
#+END:
```

--------------------------------

### org-roam-ql-buffer-dispatch

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-core.md

Provides an interactive transient interface for modifying org-roam-ql buffer queries and display settings. Users can interactively change titles, views, queries, filters, sorting, and more.

```APIDOC
## org-roam-ql-buffer-dispatch

### Description
Interactive transient for modifying org-roam-ql buffer queries and display settings. This function provides a user interface to adjust various aspects of the org-roam-ql buffer.

### Method
(org-roam-ql-buffer-dispatch)

### Parameters
None

### Interactive
Yes (Transient)

### Features
- **t** - Edit title
- **k** - Switch between nodes/backlinks view
- **q** - Edit query
- **F** - Set filter
- **s** - Change sort function
- **i** - Toggle between in-buffer and org-roam-db search
- **r** - Refresh buffer
- **S** - Switch to/from agenda view
- **b** - Create bookmark
- **o** - Convert to org-roam-ql mode

### Example
```emacs-lisp
;; Bind to a key
(define-key org-roam-mode-map "v" 'org-roam-ql-buffer-dispatch)

;; Usage: press 'v' to open transient, then select option
```
```

--------------------------------

### Complex Query: Recently Modified Important Items

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/README.md

Example of a complex query to find important items that have been modified within the last week. Demonstrates using priority and file modification time predicates.

```emacs-lisp
;; Recently modified important items
(and (priority "A")
     (file-mtime-is-after "-1w"))
```

--------------------------------

### Export TODO List as Table

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/QUICK_START.md

Use Org mode's BEGIN/END block to export a TODO list with specific columns, sorting, and a limit.

```org
#+BEGIN: org-roam-ql
:query (and (todo "TODO") (deadline))
:columns (title (todo "State") deadline tags)
:sort "deadline"
:take 20
#+END

```

--------------------------------

### Use Parameterized Queries for Custom SQL

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

To avoid 'SELECT must be used with placeholders' errors, use parameterized queries with `org-roam-ql-nodes` instead of embedding literal values directly in the SQL string.

```emacs-lisp
(org-roam-ql-nodes "select id from nodes where todo = 'TODO'")  ; Literal values wrong
```

```emacs-lisp
(org-roam-ql-nodes '([:select [id] :from nodes :where (= todo $s1)] "TODO"))
```

--------------------------------

### Limit Results to Prevent Memory Issues

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/errors-troubleshooting.md

To avoid memory issues caused by large result sets, limit the number of results using `:take` in Org-Roam-QL dblocks or directly in SQL queries. This example demonstrates using `:take`.

```org
#+BEGIN: org-roam-ql
:query (tags "note")
:take 50
#+END:
```

```emacs-lisp
(org-roam-ql-nodes "select id from nodes limit 100")
```

```emacs-lisp
(setq org-roam-ql-preview-function
  (lambda (node _)
    ;; Don't load full content
    (format "Title: %s" (org-roam-node-title node))))
```

--------------------------------

### org-dblock-write:org-roam-ql

Source: https://github.com/ahmed-shariff/org-roam-ql/blob/master/_autodocs/api-reference/org-roam-ql-sorting-customization.md

Defines the syntax for writing org-roam-ql dynamic blocks, enabling users to display nodes in a table format with customizable queries, columns, sorting, and limits.

```APIDOC
## org-dblock-write:org-roam-ql

### Description
Write an org-roam-ql dynamic block to display nodes in a table. Supports custom queries, columns, sorting, and limiting results.

### Syntax
```org
#+BEGIN: org-roam-ql
:query (QUERY-EXPRESSION)
:columns (COLUMN-SPEC ...)
:sort SORT-FUNCTION
:take TAKE-COUNT
:no-link nil
#+END
```

### Parameters
#### Query Parameters
- **:query** (org-roam-ql query) - Required - Query to execute
- **:columns** (list) - Required - Column specifications
- **:sort** (string) - Optional - Registered sort function name
- **:take** (integer) - Optional - Take first N (positive) or last N (negative) nodes
- **:no-link** (boolean) - Optional - If true, don't show ID link in first column

### Column Specifications
1. **Simple slot:** `title` - uses `org-roam-node-title`
2. **Aliased:** `(title "Title")` - custom column header
3. **With arguments:** `((property "CATEGORY") "Category")` - passes arguments to function

### Built-in Columns
- Node slots: `title`, `file`, `level`, `todo`, `priority`, `tags`, etc.
- Accessor functions: Any `org-roam-node-*` function can be used
- Custom registered: Functions registered with `org-roam-ql-register-dblock-column`

### Example
```org
* Query Results

#+BEGIN: org-roam-ql
:query (todo "TODO")
:columns (title (todo "State") (deadline "Due") tags)
:sort "deadline"
:take 20
#+END
```

Output: Table with TODO items sorted by deadline, showing top 20

```org
* Archive Stats

#+BEGIN: org-roam-ql
:query (tags "archived")
:columns (title (file-title "File") (file-mtime "Modified")),
:sort "file-mtime"
:no-link t
#+END
```

Output: Archived items with file names and modification times, no backlink
```