Add above and below

api/collection-above.md

@@ -0,0 +1,44 @@
+---
+layout: api
+title: Collection.above()
+---
+
+# Method
+
+{% apibody %}
+Collection.above(integer | object[, "closed" | "open"])
+{% endapibody %}
+
+# Description
+
+Restrict the range of results returned to values that sort above a given value.
+
+The `above` method may be called with either a key-value pair to match against (e.g., `{name: "agatha"}` or an integer (an `id` value to look up). The second optional parameter must be the string `"closed"` or `"open"`, indicating that the specified value will be included (closed) or excluded (open) from the result set. The default is excluded (open): `above(10)` will return documents with `id` values higher than (but not equal to) 10.
+
+Values in key-value pairs may be numbers, strings, or even arrays or objects; non-numeric values will be sorted lexicographically, and strings are sorted by UTF-8 codepoint. (Read about [Sorting order][so] and [ReQL data types][dt] in general.)
+
+[so]: https://rethinkdb.com/docs/data-types/#sorting-order
+[dt]: https://rethinkdb.com/docs/data-types/
+
+The `above` method is often used in conjunction with [order][cor], but it may appear after any Horizon method with the exception of [find][cfi] and [limit][cli]. (However, `limit` may appear after `above`.)
+
+```
+// get all messages with an ID over 100, sorted
+messages.order("id").above({id: 100});
+
+// the same as above, but using the integer shorthand for ID
+messages.order("id").above(100);
+
+// get all messages with an ID between 101 and 200, sorted
+messages.order("id").below(200).above(100);
+
+// get all users with a reputation score of 50 or over, unsorted
+users.above({reputation: 50}, "closed");
+```
+
+Also see: [Collection.below][cbe]
+
+[cor]: /api/collection-order/
+[cfi]: /api/collection-find/
+[cli]: /api/collection-limit/
+[cbe]: /api/collection-below/

api/collection-below.md

@@ -0,0 +1,41 @@
+---
+layout: api
+title: Collection.below()
+---
+
+# Method
+
+{% apibody %}
+Collection.below(integer | object[, "closed" | "open"])
+{% endapibody %}
+
+# Description
+
+Restrict the range of results returned to values that sort below a given value.
+
+The `below` method may be called with either a key-value pair to match against (e.g., `{name: "agatha"}` or an integer (an `id` value to look up). The second optional parameter must be the string `"closed"` or `"open"`, indicating that the specified value will be included (closed) or excluded (open) from the result set. The default is excluded (open): `below(10)` will return documents with `id` values lower than (but not equal to) 10.
+
+Values in key-value pairs may be numbers, strings, or even arrays or objects; non-numeric values will be sorted lexicographically, and strings are sorted by UTF-8 codepoint. (Read about [Sorting order][so] and [ReQL data types][dt] in general.)
+
+[so]: https://rethinkdb.com/docs/data-types/#sorting-order
+[dt]: https://rethinkdb.com/docs/data-types/
+
+The `below` method may _only_ be used after [order][cor], although other methods may be used after it.
+
+```
+// get all messages with an ID below 100, sorted
+messages.order("id").below({id: 100});
+
+// the same as above, but using the integer shorthand for ID
+messages.order("id").below(100);
+
+// get all messages with an ID between 101 and 200, sorted
+messages.order("id").below(200).above(100);
+
+// get all users with a reputation score of 50 or below, sorted
+users.order("reputation").below({reputation: 50}, "closed");
+```
+
+Also see: [Collection.below][cbe]
+
+[cor]: /api/collection-order/

api/collection.md

@@ -43,6 +43,10 @@ messages.order("id").findAll({from: "bob"});
 
 **[Collection.findAll][cfa]:** retrieve multiple objects from a collection.
 
+**[Collection.above][cab]:** limit a query's results to documents based on keys above a certain value.
+
+**[Collection.below][cbe]:** limit a query's results to documents based on keys below a certain value.
+
 **[Collection.limit][cli]:** limit a query's results to a certain number of documents.
 
 **[Collection.order][cor]:** order a query's results based on a given field.
@@ -73,3 +77,5 @@ messages.order("id").findAll({from: "bob"});
 [cup]: /api/collection-upsert/
 [cwa]: /api/collection-watch/
 [cfe]: /api/collection-fetch/
+[cab]: /api/collection-above/
+[cbe]: /api/collection-below/