#+TITLE: org-ql examples

* Contents
:PROPERTIES:
:TOC:      this
:END:
  -  [[#find-entries-matching-a-certain-custom_id][Find entries matching a certain CUSTOM_ID]]
  -  [[#show-entries-with-recent-timestamps][Show entries with recent timestamps]]
  -  [[#stuck-projects-block-agenda][Stuck projects block agenda]]
  -  [[#listing-bills-coming-due][Listing bills coming due]]

* Find entries matching a certain =CUSTOM_ID=

Since queries can contain both built-in =org-ql= predicate expressions and arbitrary expressions, they can be combined in useful ways.  This example uses the built-in =property= predicate to quickly locate entries that have the =CUSTOM_ID= property set, and then compares the value of that property to the string =issue=.

#+BEGIN_SRC elisp
  (org-ql-query
    :select #'org-get-heading
    :from "~/org/tickets.org"
    :where '(and (property "CUSTOM_ID")
                 (string-match "issue" (org-entry-get (point) "CUSTOM_ID"))))
#+END_SRC

Using the =property= predicate as the first clause of the two clauses joined with =and= allows =org-ql= to optimize the query by searching through the buffer directly to entries that set the =CUSTOM_ID= property, which is much faster than testing every entry in a buffer.  Also, If the query were only the =string-match= call, it would signal an error on entries that didn't have the property set, because =org-entry-get= would return nil.

* Show entries with recent timestamps

You can also access these views with the command ~org-ql-view~.

#+BEGIN_SRC elisp
  ;; Show entries with any timestamp from last 7 days:
  (org-ql-view-recent-items 7)

  ;; Show entries clocked in last 30 days:
  (org-ql-view-recent-items 30 'clocked)

  ;; Show entries closed in last 30 days:
  (org-ql-view-recent-items 30 'closed)
#+END_SRC

* Stuck projects block agenda

Reddit user =emptymatrix= [[https://www.reddit.com/r/emacs/comments/cnrt2d/orgqlblock_integrates_orgql_into_org_agenda/ewtqez8/][shared]] this example of replacing a traditional =org-stuck-projects= view like:

#+BEGIN_SRC elisp
  (setq org-stuck-projects
        '("+@project/-DONE" ("NEXT") nil "SCHEDULED:"))
#+END_SRC

With this =org-ql-block= agenda view, like:

#+BEGIN_SRC elisp
  (setq org-agenda-custom-commands
        '(("s" "Stuck Projects"
            ((org-ql-block '(and (tags "@project")
                                 (not (done))
                                 (not (descendants (todo "NEXT")))
                                 (not (descendants (scheduled))))
                           ((org-ql-block-header "Stuck Projects")))))))
#+END_SRC

* Listing bills coming due

This uses the example in the readme file, but maps across the elements returned by ~org-ql~ to present a simple list of titles and deadlines.

#+BEGIN_SRC elisp
  (org-ql (org-agenda-files)
    (and (not (done))
         (tags "bills")
         (deadline auto))
    :action (list (substring-no-properties (org-get-heading t t))
                  (org-entry-get (point) "DEADLINE"))
    :sort deadline)
  ;;=> (("Electric bill" "<2018-08-23 Thu +1m>")
  ;;    ("Rent" "<2018-09-01 Sat +1m>"))
#+END_SRC

This could also be put in a script, which could use desktop notifications to remind of bills coming due: [[examples/org-bills-due.el][org-bills-due.el]].

* COMMENT Code                                                     :noexport:
:PROPERTIES:
:TOC:      ignore
:END:

** File-local variables

# Local Variables:
# eval: (require 'org-make-toc)
# before-save-hook: org-make-toc
# End: