Command syntax

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)