diff --git a/README.org b/README.org
index 0ff4d89..741e745 100644
--- a/README.org
+++ b/README.org
@@ -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
 
+**** 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~
 
 /Arguments:/ ~(buffers-or-files query &key action narrow sort)~
diff --git a/org-ql.info b/org-ql.info
index 5c9bb45..519f605 100644
--- a/org-ql.info
+++ b/org-ql.info
@@ -607,7 +607,20 @@ File: README.info,  Node: Listing / acting-on results,  Prev: Agenda-like views,
 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)’
 
@@ -667,7 +680,7 @@ File: README.info,  Node: Listing / acting-on results,  Prev: Agenda-like views,
             '(todo "WAITING"))
           ;; => ((headline (:raw-value "Visit the moon" ...) ...) ...)
 
-  2. Function: ‘org-ql-query’
+  3. Function: ‘org-ql-query’
 
      _Arguments:_ ‘(&key (select 'element-with-markers) from where
      order-by narrow)’
@@ -712,7 +725,7 @@ File: README.info,  Node: Listing / acting-on results,  Prev: Agenda-like views,
             :where '(todo "WAITING"))
           ;; => ((headline (:raw-value "Visit the moon" ...) ...) ...)
 
-  3. Macro: ‘org-ql’
+  4. Macro: ‘org-ql’
 
      _Arguments:_ ‘(buffers-or-files query &key sort narrow markers
      action)’
@@ -1336,33 +1349,33 @@ Node: Date/time predicates17145
 Node: Functions / Macros19800
 Node: Agenda-like views20055
 Node: Listing / acting-on results21460
-Node: Dynamic block26062
-Node: Links28760
-Node: Tips29447
-Node: Changelog29765
-Node: 05-pre30449
-Node: 04931688
-Node: 04831966
-Node: 04732313
-Node: 04632708
-Node: 04533108
-Node: 04433467
-Node: 04333824
-Node: 04234019
-Node: 04134178
-Node: 0434419
-Node: 03238352
-Node: 03138731
-Node: 0338928
-Node: 02341903
-Node: 02242131
-Node: 02142399
-Node: 0242598
-Node: 0146633
-Node: Notes46734
-Node: Comparison with Org Agenda searches46896
-Node: org-sidebar47768
-Node: License48047
+Node: Dynamic block26655
+Node: Links29353
+Node: Tips30040
+Node: Changelog30358
+Node: 05-pre31042
+Node: 04932281
+Node: 04832559
+Node: 04732906
+Node: 04633301
+Node: 04533701
+Node: 04434060
+Node: 04334417
+Node: 04234612
+Node: 04134771
+Node: 0435012
+Node: 03238945
+Node: 03139324
+Node: 0339521
+Node: 02342496
+Node: 02242724
+Node: 02142992
+Node: 0243191
+Node: 0147226
+Node: Notes47327
+Node: Comparison with Org Agenda searches47489
+Node: org-sidebar48361
+Node: License48640
 
 End Tag Table