Update _index.md

content/en/docs/API/Read Consistency/_index.md

@@ -43,6 +43,8 @@ If you decide to deploy [read-only nodes](/docs/clustering/read-only-nodes/) how
 #### freshness_strict
 As explained above `freshness` just checks that that the node has been in contact with the Leader within the specified time. If you also want the node to check that the data it last received is not out-of-date by (at most) the `freshness` interval, you should also add the `freshness_strict` flag as a query parameter. **Note that this check works by comparing timestamps generated by the Leader to those generated by the node receiving the read request**. Any clock skew between the nodes may therefore affect the correctness of the data returned by the node. You are responsible for controlling the amount of clock skew across your rqlite cluster.
 
+ See the examples at the end of this page to learn how to control _freshness_.
+
 ## Which should I use?
 _Weak_ is almost certainly sufficient for your application, and is the default read consistency level. Unless your cluster Leader is continually changing while you're actually executing queries there will be never be any difference between _weak_ and _strong_ -- but using _strong_ will result in much slower queries, which is not what most people want.
 
@@ -58,6 +60,11 @@ Examples of enabling each read consistency level for a simple query is shown bel
 # waits for a response from the Leader. Same as weak.
 curl -G 'localhost:4001/db/query' --data-urlencode 'q=SELECT * FROM foo'
 
+# The read request will be served by the node if it believes it is the Leader,
+# otherwise it wil forward the request to the Leader. This is the default if
+# no read consistency is specified.
+curl -G 'localhost:4001/db/query?level=weak' --data-urlencode 'q=SELECT * FROM foo'
+
 # Query the node, telling it simply to read the SQLite database directly.
 # No guarantees on how old the data is. In fact, the node may not even be
 # connected to the cluster. Provides the fastest possible query response.
@@ -66,7 +73,8 @@ curl -G 'localhost:4001/db/query?level=none' --data-urlencode 'q=SELECT * FROM f
 # Query the node, telling it simply to read the SQLite database directly.
 # The read request will be successful only if the node last heard from the
 # Leader no more than 1 second ago. This provides very fast reads, but sets
-# an upper bound of 1 second on how old the returned data is.
+# an upper bound of 1 second on how long the node may have been disconnected
+# from the cluster.
 curl -G 'localhost:4001/db/query?level=none&freshness=1s' --data-urlencode 'q=SELECT * FROM foo'
 
 # Query the node, telling it simply to read the SQLite database directly.
@@ -76,12 +84,10 @@ curl -G 'localhost:4001/db/query?level=none&freshness=1s' --data-urlencode 'q=SE
 # node's local clock.
 curl -G 'localhost:4001/db/query?level=none&freshness=1s&freshness_strict' --data-urlencode 'q=SELECT * FROM foo'
 
-# The read request will be served by the node if it believes it is the Leader,
-# otherwise it wil forward the request to the Leader.
-curl -G 'localhost:4001/db/query?level=weak' --data-urlencode 'q=SELECT * FROM foo'
-
-# The read request will be successful only if the node maintained cluster
-# leadership during the entirety of query processing. Zero chance of stale reads
-# but query processing will be relatively slow.
+# The read request will be processed by the Leader and will be successful
+# only if the Leader maintained leadership during the entirety of query
+# processing. Zero chance of stale reads but query processing will be
+# relatively slow. If the node receiving the query is not the the Leader,
+# the request will be transparently forwarded to the Leader.
 curl -G 'localhost:4001/db/query?level=strong' --data-urlencode 'q=SELECT * FROM foo'
 ```