ReQL command: between

Command syntax

table.between(lower_key, upper_key[, options]) → table_slice
table_slice.between(lower_key, upper_key[, options]) → table_slice

Description

Get all documents between two keys. Accepts three optional arguments: index, left_bound, and right_bound. If index is set to the name of a secondary index, between will return all documents where that index’s value is in the specified range (it uses the primary key by default). left_bound or right_bound may be set to open or closed to indicate whether or not to include that endpoint of the range (by default, left_bound is closed and right_bound is open).

You may also use the special constants r.minval and r.maxval for boundaries, which represent “less than any index key” and “more than any index key” respectively. For instance, if you use r.minval as the lower key, then between will return all documents whose primary keys (or indexes) are less than the specified upper key.

If you use arrays as indexes (compound indexes), they will be sorted using lexicographical order. Take the following range as an example:

[[1, "c"] ... [5, "e"]]

This range includes all compound keys:

• whose first item is 1 and second item is equal or greater than “c”;
• whose first item is between 1 and 5, regardless of the value of the second item;
• whose first item is 5 and second item is less than or equal to “e”.

Example: Find all users with primary key >= 10 and < 20 (a normal half-open interval).

r.table('marvel').between(10, 20).run(conn)

Example: Find all users with primary key >= 10 and <= 20 (an interval closed on both sides).

r.table('marvel').between(10, 20, :right_bound => 'closed').run(conn)

Example: Find all users with primary key < 20.

r.table('marvel').between(r.minval, 20).run(conn)

Example: Find all users with primary key > 10.

r.table('marvel').between(10, r.maxval, :left_bound => 'open').run(conn)

Example: Between can be used on secondary indexes too. Just pass an optional index argument giving the secondary index to query.

r.table('dc').between('dark_knight', 'man_of_steel',
    :index => 'code_name').run(conn)

Example: Get all users whose full name is between “John Smith” and “Wade Welles.”

r.table("users").between(["Smith", "John"], ["Welles", "Wade"],
    :index => "full_name").run(conn)

Example: Get the top 10 ranked teams in order.

r.table("teams").order_by(:index => "rank").between(1, 11).run(conn)

Note: When between is chained after order_by, both commands must use the same index; between will default to the index order_by is using, so in this example "rank" is automatically being used by between. Trying to specify another index will result in a ReqlRuntimeError.

Example: Subscribe to a changefeed of teams ranked in the top 10.

changes = r.table("teams").between(1, 11, :index => "rank").changes().run(conn)

The between command works with secondary indexes on date fields, but will not work with unindexed date fields. To test whether a date value is between two other dates, use the during command, not between.

Secondary indexes can be used in extremely powerful ways with between and other commands; read the full article on secondary indexes for examples using boolean operations, contains and more.

RethinkDB uses byte-wise ordering for between and does not support Unicode collations; non-ASCII characters will be sorted by UTF-8 codepoint.