jiri/org-ql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: Explain how caching works

Browse source 
Fixes #132.  Thanks to Mikhail Skorzhinskii (@mskorzhinskiy) for
suggesting.
This commit is contained in:
Adam Porter 2020-11-20 08:13:15 -06:00
parent f8a531f2be
commit e4fb1cce2e
2 changed files with 49 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

6
README.org
View file

@ -299,6 +299,12 @@ The variable =org-ql-block-header= may be bound to a string to use as the block
*** Listing / acting-on results *** Listing / acting-on results
**** Caching
Org QL uses a per-buffer cache to speed up subsequent searches. It's keyed on query expressions, which means that, for the same query in the same buffer, if the buffer has not been modified since the last time the query was run, the cached result will be returned, and the query will not be evaluated in that buffer again.
Therefore, since query expressions are not guaranteed to be evaluated when these functions are called, they should be free of side effects. Any side effects should be done in the action expression instead.
**** Function: ~org-ql-select~ **** Function: ~org-ql-select~
/Arguments:/ ~(buffers-or-files query &key action narrow sort)~ /Arguments:/ ~(buffers-or-files query &key action narrow sort)~

73
org-ql.info
View file

@ -607,7 +607,20 @@ File: README.info, Node: Listing / acting-on results, Prev: Agenda-like views,
4.3.2 Listing / acting-on results 4.3.2 Listing / acting-on results
--------------------------------- ---------------------------------
1. Function: ‘org-ql-select’ 1. Caching
Org QL uses a per-buffer cache to speed up subsequent searches.
It’s keyed on query expressions, which means that, for the same
query in the same buffer, if the buffer has not been modified since
the last time the query was run, the cached result will be
returned, and the query will not be evaluated in that buffer again.
Therefore, since query expressions are not guaranteed to be
evaluated when these functions are called, they should be free of
side effects. Any side effects should be done in the action
expression instead.
2. Function: ‘org-ql-select’
_Arguments:_ ‘(buffers-or-files query &key action narrow sort)’ _Arguments:_ ‘(buffers-or-files query &key action narrow sort)’
@ -667,7 +680,7 @@ File: README.info, Node: Listing / acting-on results, Prev: Agenda-like views,
'(todo "WAITING")) '(todo "WAITING"))
;; => ((headline (:raw-value "Visit the moon" ...) ...) ...) ;; => ((headline (:raw-value "Visit the moon" ...) ...) ...)
2. Function: ‘org-ql-query’ 3. Function: ‘org-ql-query’
_Arguments:_ ‘(&key (select 'element-with-markers) from where _Arguments:_ ‘(&key (select 'element-with-markers) from where
order-by narrow)’ order-by narrow)’
@ -712,7 +725,7 @@ File: README.info, Node: Listing / acting-on results, Prev: Agenda-like views,
:where '(todo "WAITING")) :where '(todo "WAITING"))
;; => ((headline (:raw-value "Visit the moon" ...) ...) ...) ;; => ((headline (:raw-value "Visit the moon" ...) ...) ...)
3. Macro: ‘org-ql’ 4. Macro: ‘org-ql’
_Arguments:_ ‘(buffers-or-files query &key sort narrow markers _Arguments:_ ‘(buffers-or-files query &key sort narrow markers
action)’ action)’
@ -1336,33 +1349,33 @@ Node: Date/time predicates17145
Node: Functions / Macros19800 Node: Functions / Macros19800
Node: Agenda-like views20055 Node: Agenda-like views20055
Node: Listing / acting-on results21460 Node: Listing / acting-on results21460
Node: Dynamic block26062 Node: Dynamic block26655
Node: Links28760 Node: Links29353
Node: Tips29447 Node: Tips30040
Node: Changelog29765 Node: Changelog30358
Node: 05-pre30449 Node: 05-pre31042
Node: 04931688 Node: 04932281
Node: 04831966 Node: 04832559
Node: 04732313 Node: 04732906
Node: 04632708 Node: 04633301
Node: 04533108 Node: 04533701
Node: 04433467 Node: 04434060
Node: 04333824 Node: 04334417
Node: 04234019 Node: 04234612
Node: 04134178 Node: 04134771
Node: 0434419 Node: 0435012
Node: 03238352 Node: 03238945
Node: 03138731 Node: 03139324
Node: 0338928 Node: 0339521
Node: 02341903 Node: 02342496
Node: 02242131 Node: 02242724
Node: 02142399 Node: 02142992
Node: 0242598 Node: 0243191
Node: 0146633 Node: 0147226
Node: Notes46734 Node: Notes47327
Node: Comparison with Org Agenda searches46896 Node: Comparison with Org Agenda searches47489
Node: org-sidebar47768 Node: org-sidebar48361
Node: License48047 Node: License48640
 
End Tag Table End Tag Table