JavaScript ReQL command reference
Looking for documentation for a community driver?
Find the project page for your driver for specific ReQL documentation.
Accessing ReQL
r
r → r
The top-level ReQL namespace.
Example: Set up your top-level namespace.
var r = require('rethinkdb');
Read more about this command →
connect
r.connect([options, ]callback) r.connect([host, ]callback) r.connect([options]) → promise r.connect([host]) → promise
Create a new connection to the database server. Accepts the following options:
-
host: the host to connect to (defaultlocalhost). -
port: the port to connect on (default28015). -
db: the default database (defaulttest). -
user: the user account to connect as (defaultadmin). -
password: the password for the user account to connect as (default'', empty). -
timeout: timeout period in seconds for the connection to be opened (default20). -
ssl: a hash of options to support SSL connections (defaultnull). Currently, there is only one option available, and if thessloption is specified, this key is required:-
ca: a list of Node.jsBufferobjects containing SSL CA certificates.
-
If the connection cannot be established, a ReqlDriverError will be passed to the callback instead of a connection.
Example: Open a connection using the default host and port, specifying the default database.
r.connect({
db: 'marvel'
}, function(err, conn) {
// ...
});
If no callback is provided, a promise will be returned.
var promise = r.connect({db: 'marvel'});
Read more about this command →
close
conn.close([{noreplyWait: true}, ]callback)
conn.close([{noreplyWait: true}]) → promise
Close an open connection. If no callback is provided, a promise will be returned.
Example: Close an open connection, waiting for noreply writes to finish.
conn.close(function(err) { if (err) throw err; })
Read more about this command →
reconnect
conn.reconnect([{noreplyWait: true}, ]callback)
conn.reconnect([{noreplyWait: true}]) → promise
Close and reopen a connection. If no callback is provided, a promise will be returned.
Example: Cancel outstanding requests/queries that are no longer needed.
conn.reconnect({noreplyWait: false}, function(error, connection) { ... })
Read more about this command →
use
conn.use(dbName)
Change the default database on this connection.
Example: Change the default database so that we don’t need to specify the database when referencing a table.
conn.use('marvel')
r.table('heroes').run(conn, ...) // refers to r.db('marvel').table('heroes')
Read more about this command →
run
query.run(conn[, options], callback) query.run(conn[, options]) → promise
Run a query on a connection. The callback will get either an error, a single JSON result, or a cursor, depending on the query.
Example: Run a query on the connection conn and log each row in the result to the console.
r.table('marvel').run(conn, function(err, cursor) {
cursor.each(console.log);
})
Read more about this command →
changes
stream.changes([options]) → stream singleSelection.changes([options]) → stream
Turn a query into a changefeed, an infinite stream of objects representing changes to the query’s results as they occur. A changefeed may return changes to a table or an individual document (a “point” changefeed). Commands such as filter or map may be used before the changes command to transform or filter the output, and many commands that operate on sequences can be chained after changes.
Example: Subscribe to the changes on a table.
Start monitoring the changefeed in one client:
r.table('games').changes().run(conn, function(err, cursor) {
cursor.each(console.log);
});
As these queries are performed in a second client, the first client would receive and print the following objects:
> r.table('games').insert({id: 1}).run(conn, callback);
{old_val: null, new_val: {id: 1}}
> r.table('games').get(1).update({player1: 'Bob'}).run(conn, callback);
{old_val: {id: 1}, new_val: {id: 1, player1: 'Bob'}}
> r.table('games').get(1).replace({id: 1, player1: 'Bob', player2: 'Alice'}).run(conn, callback);
{old_val: {id: 1, player1: 'Bob'},
new_val: {id: 1, player1: 'Bob', player2: 'Alice'}}
> r.table('games').get(1).delete().run(conn, callback)
{old_val: {id: 1, player1: 'Bob', player2: 'Alice'}, new_val: null}
> r.tableDrop('games').run(conn, callback);
ReqlRuntimeError: Changefeed aborted (table unavailable)
Read more about this command →
noreplyWait
conn.noreplyWait(callback) conn.noreplyWait() → promise
noreplyWait ensures that previous queries with the noreply flag have been processed by the server. Note that this guarantee only applies to queries run on the given connection.
If no callback is provided, a promise will be returned.
Example: We have previously run queries with the noreply argument set to true. Now wait until the server has processed them.
conn.noreplyWait(function(err) { ... })
Read more about this command →
server
conn.server(callback) conn.server() → promise
Return information about the server being used by a connection.
Example: Return server information.
conn.server(callback);
// Result passed to callback
{
"id": "404bef53-4b2c-433f-9184-bc3f7bda4a15",
"name": "amadeus",
"proxy": false
}
If no callback is provided, a promise will be returned.
Read more about this command →
EventEmitter (connection)
connection.addListener(event, listener) connection.on(event, listener) connection.once(event, listener) connection.removeListener(event, listener) connection.removeAllListeners([event]) connection.setMaxListeners(n) connection.listeners(event) connection.emit(event, [arg1], [arg2], [...])
Connections implement the same interface as Node’s [EventEmitter][ee]. This allows you to listen for changes in connection state.
Example: Monitor the connection state with events.
r.connect({}, function(err, conn) {
if (err) throw err;
conn.addListener('error', function(e) {
processNetworkError(e);
});
conn.addListener('close', function() {
cleanup();
});
runQueries(conn);
});
Cursors
next
cursor.next(callback) array.next(callback) cursor.next() → promise array.next() → promise
Get the next element in the cursor.
Example: Retrieve the next element.
cursor.next(function(err, row) {
if (err) throw err;
processRow(row);
});
Read more about this command →
each
cursor.each(callback[, onFinishedCallback]) array.each(callback[, onFinishedCallback]) feed.each(callback)
Lazily iterate over the result set one element at a time. The second callback is optional and is called when the iteration stops (when there are no more rows or when the callback returns false).
Example: Let’s process all the elements!
cursor.each(function(err, row) {
if (err) throw err;
processRow(row);
});
Read more about this command →
eachAsync
sequence.eachAsync(function[, errorFunction]) → promise
Lazily iterate over a cursor, array, or feed one element at a time. eachAsync always returns a promise that will be resolved once all rows are returned.
Example: Process all the elements in a stream, using then and catch for handling the end of the stream and any errors. Note that iteration may be stopped in the first callback (rowProcess) by returning any non-Promise value.
cursor.eachAsync(function (row) {
var ok = processRowData(row);
if (!ok) {
throw new Error('Bad row: ' + row);
}
}).then(function () {
console.log('done processing');
}).catch(function (error) {
console.log('Error:', error.message);
});
Read more about this command →
toArray
cursor.toArray(callback) array.toArray(callback) cursor.toArray() → promise array.toArray() → promise
Retrieve all results and pass them as an array to the given callback.
Example: For small result sets it may be more convenient to process them at once as an array.
cursor.toArray(function(err, results) {
if (err) throw err;
processResults(results);
});
Read more about this command →
close
cursor.close([callback]) cursor.close() → promise
Close a cursor. Closing a cursor cancels the corresponding query and frees the memory associated with the open request.
Example: Close a cursor.
cursor.close(function (err) {
if (err) {
console.log("An error occurred on cursor close");
}
});
Read more about this command →
EventEmitter (cursor)
cursor.addListener(event, listener) cursor.on(event, listener) cursor.once(event, listener) cursor.removeListener(event, listener) cursor.removeAllListeners([event]) cursor.setMaxListeners(n) cursor.listeners(event) cursor.emit(event, [arg1], [arg2], [...])
Cursors and feeds implement the same interface as Node’s EventEmitter.
Example: Broadcast all messages with socket.io.
r.table("messages").orderBy({index: "date"}).run(conn, function(err, cursor) {
if (err) {
// Handle error
return
}
cursor.on("error", function(error) {
// Handle error
})
cursor.on("data", function(message) {
socket.broadcast.emit("message", message)
})
});
Manipulating databases
dbCreate
r.dbCreate(dbName) → object
Create a database. A RethinkDB database is a collection of tables, similar to relational databases.
Example: Create a database named ‘superheroes’.
> r.dbCreate('superheroes').run(conn, callback);
// Result passed to callback
{
"config_changes": [
{
"new_val": {
"id": "e4689cfc-e903-4532-a0e6-2d6797a43f07",
"name": "superheroes"
},
"old_val": null
}
],
"dbs_created": 1
}
Read more about this command →
dbDrop
r.dbDrop(dbName) → object
Drop a database. The database, all its tables, and corresponding data will be deleted.
Example: Drop a database named ‘superheroes’.
> r.dbDrop('superheroes').run(conn, callback);
// Result passed to callback
{
"config_changes": [
{
"old_val": {
"id": "e4689cfc-e903-4532-a0e6-2d6797a43f07",
"name": "superheroes"
},
"new_val": null
}
],
"tables_dropped": 3,
"dbs_dropped": 1
}
Read more about this command →
dbList
r.dbList() → array
List all database names in the system. The result is a list of strings.
Example: List all databases.
r.dbList().run(conn, callback)
Manipulating tables
tableCreate
db.tableCreate(tableName[, options]) → object r.tableCreate(tableName[, options]) → object
Create a table. A RethinkDB table is a collection of JSON documents.
Example: Create a table named ‘dc_universe’ with the default settings.
> r.db('heroes').tableCreate('dc_universe').run(conn, callback);
// Result passed to callback
{
"config_changes": [
{
"new_val": {
"db": "test",
"durability": "hard",
"id": "20ea60d4-3b76-4817-8828-98a236df0297",
"name": "dc_universe",
"primary_key": "id",
"shards": [
{
"primary_replica": "rethinkdb_srv1",
"replicas": [
"rethinkdb_srv1",
"rethinkdb_srv2"
]
}
],
"write_acks": "majority"
},
"old_val": null
}
],
"tables_created": 1
}
Read more about this command →
tableDrop
db.tableDrop(tableName) → object
Drop a table from a database. The table and all its data will be deleted.
Example: Drop a table named ‘dc_universe’.
> r.db('test').tableDrop('dc_universe').run(conn, callback);
// Result passed to callback
{
"config_changes": [
{
"old_val": {
"db": "test",
"durability": "hard",
"id": "20ea60d4-3b76-4817-8828-98a236df0297",
"name": "dc_universe",
"primary_key": "id",
"shards": [
{
"primary_replica": "rethinkdb_srv1",
"replicas": [
"rethinkdb_srv1",
"rethinkdb_srv2"
]
}
],
"write_acks": "majority"
},
"new_val": null
}
],
"tables_dropped": 1
}
Read more about this command →
tableList
db.tableList() → array
List all table names in a database. The result is a list of strings.
Example: List all tables of the ‘test’ database.
r.db('test').tableList().run(conn, callback)
Read more about this command →
indexCreate
table.indexCreate(indexName[, indexFunction][, {multi: false, geo: false}]) → object
Create a new secondary index on a table. Secondary indexes improve the speed of many read queries at the slight cost of increased storage space and decreased write performance. For more information about secondary indexes, read the article “Using secondary indexes in RethinkDB.”
Example: Create a simple index based on the field postId.
r.table('comments').indexCreate('postId').run(conn, callback)
Read more about this command →
indexDrop
table.indexDrop(indexName) → object
Delete a previously created secondary index of this table.
Example: Drop a secondary index named ‘code_name’.
r.table('dc').indexDrop('code_name').run(conn, callback)
Read more about this command →
indexList
table.indexList() → array
List all the secondary indexes of this table.
Example: List the available secondary indexes for this table.
r.table('marvel').indexList().run(conn, callback)
Read more about this command →
indexRename
table.indexRename(oldIndexName, newIndexName[, {overwrite: false}]) → object
Rename an existing secondary index on a table. If the optional argument overwrite is specified as true, a previously existing index with the new name will be deleted and the index will be renamed. If overwrite is false (the default) an error will be raised if the new index name already exists.
Example: Rename an index on the comments table.
r.table('comments').indexRename('postId', 'messageId').run(conn, callback)
Read more about this command →
indexStatus
table.indexStatus([, index...]) → array
Get the status of the specified indexes on this table, or the status of all indexes on this table if no indexes are specified.
Example: Get the status of all the indexes on test:
r.table('test').indexStatus().run(conn, callback)
Read more about this command →
indexWait
table.indexWait([, index...]) → array
Wait for the specified indexes on this table to be ready, or for all indexes on this table to be ready if no indexes are specified.
Example: Wait for all indexes on the table test to be ready:
r.table('test').indexWait().run(conn, callback)
Read more about this command →
setWriteHook
table.setWriteHook(function | binary | null) → object
Sets the write hook on a table or overwrites it if one already exists.
The function can be an anonymous function with the signature (context: object, oldVal: object, newVal: object) -> object or a binary representation obtained from the function field of getWriteHook. The function must be deterministic, and so cannot use a subquery or the r.js command.
Read more about this command →
getWriteHook
table.getWriteHook() → null/object
Gets the write hook of this table. If a write hook exists, the result is an object of the following form:
{
"function": <binary>,
"query": "setWriteHook(function(_var1, _var2, _var3) { return ...; })",
}
Writing data
insert
table.insert(object | [object1, object2, ...][, {durability: "hard", returnChanges: false, conflict: "error"}]) → object
Insert documents into a table. Accepts a single document or an array of documents.
Example: Insert a document into the table posts.
r.table("posts").insert({
id: 1,
title: "Lorem ipsum",
content: "Dolor sit amet"
}).run(conn, callback)
Read more about this command →
update
table.update(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false}]) → object
selection.update(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false}]) → object
singleSelection.update(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false}]) → object
Update JSON documents in a table. Accepts a JSON document, a ReQL expression, or a combination of the two.
Example: Update the status of the post with id of 1 to published.
r.table("posts").get(1).update({status: "published"}).run(conn, callback)
Read more about this command →
replace
table.replace(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false}]) → object
selection.replace(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false}]) → object
singleSelection.replace(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false}]) → object
Replace documents in a table. Accepts a JSON document or a ReQL expression, and replaces the original document with the new one. The new document must have the same primary key as the original document.
Example: Replace the document with the primary key 1.
r.table("posts").get(1).replace({
id: 1,
title: "Lorem ipsum",
content: "Aleas jacta est",
status: "draft"
}).run(conn, callback)
Read more about this command →
delete
table.delete([{durability: "hard", returnChanges: false}]) → object
selection.delete([{durability: "hard", returnChanges: false}]) → object
singleSelection.delete([{durability: "hard", returnChanges: false}]) → object
Delete one or more documents from a table.
Example: Delete a single document from the table comments.
r.table("comments").get("7eab9e63-73f1-4f33-8ce4-95cbea626f59").delete().run(conn, callback)
Read more about this command →
sync
table.sync() → object
sync ensures that writes on a given table are written to permanent storage. Queries that specify soft durability ({durability: 'soft'}) do not give such guarantees, so sync can be used to ensure the state of these queries. A call to sync does not return until all previous writes to the table are persisted.
Example: After having updated multiple heroes with soft durability, we now want to wait until these changes are persisted.
r.table('marvel').sync().run(conn, callback)
Selecting data
db
r.db(dbName) → db
Reference a database.
Example: Explicitly specify a database for a query.
r.db('heroes').table('marvel').run(conn, callback)
Read more about this command →
table
db.table(name[, {readMode: 'single', identifierFormat: 'name'}]) → table
Return all documents in a table. Other commands may be chained after table to return a subset of documents (such as get and filter) or perform further processing.
Example: Return all documents in the table ‘marvel’ of the default database.
r.table('marvel').run(conn, callback)
Read more about this command →
get
table.get(key) → singleRowSelection
Get a document by primary key.
Example: Find a document by UUID.
r.table('posts').get('a9849eef-7176-4411-935b-79a6e3c56a74').run(conn, callback);
Read more about this command →
getAll
table.getAll([key, key2...], [, {index:'id'}]) → selection
Get all documents where the given value matches the value of the requested index.
Example: Secondary index keys are not guaranteed to be unique so we cannot query via get when using a secondary index.
r.table('marvel').getAll('man_of_steel', {index:'code_name'}).run(conn, callback)
Read more about this command →
between
table.between(lowerKey, upperKey[, options]) → table_slice table_slice.between(lowerKey, upperKey[, options]) → table_slice
Get all documents between two keys. Accepts three optional arguments: index, leftBound, and rightBound. 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). leftBound or rightBound may be set to open or closed to indicate whether or not to include that endpoint of the range (by default, leftBound is closed and rightBound is open).
Example: Find all users with primary key >= 10 and < 20 (a normal half-open interval).
r.table('marvel').between(10, 20).run(conn, callback);
Read more about this command →
filter
selection.filter(predicate_function[, {default: false}]) → selection
stream.filter(predicate_function[, {default: false}]) → stream
array.filter(predicate_function[, {default: false}]) → array
Return all the elements in a sequence for which the given predicate is true. The return value of filter will be the same as the input (sequence, stream, or array). Documents can be filtered in a variety of ways—ranges, nested values, boolean conditions, and the results of anonymous functions.
Example: Get all users who are 30 years old.
r.table('users').filter({age: 30}).run(conn, callback);
The predicate {age: 30} selects documents in the users table with an age field whose value is 30. Documents with an age field set to any other value or with no age field present are skipped.
Joins
innerJoin
sequence.innerJoin(otherSequence, predicate_function) → stream array.innerJoin(otherSequence, predicate_function) → array
Returns an inner join of two sequences.
Example: Return a list of all matchups between Marvel and DC heroes in which the DC hero could beat the Marvel hero in a fight.
r.table('marvel').innerJoin(r.table('dc'), function(marvelRow, dcRow) {
return marvelRow('strength').lt(dcRow('strength'))
}).zip().run(conn, callback)
Read more about this command →
outerJoin
sequence.outerJoin(otherSequence, predicate_function) → stream array.outerJoin(otherSequence, predicate_function) → array
Returns a left outer join of two sequences. The returned sequence represents a union of the left-hand sequence and the right-hand sequence: all documents in the left-hand sequence will be returned, each matched with a document in the right-hand sequence if one satisfies the predicate condition. In most cases, you will want to follow the join with zip to combine the left and right results.
Example: Return a list of all Marvel heroes, paired with any DC heroes who could beat them in a fight.
r.table('marvel').outerJoin(r.table('dc'), function(marvelRow, dcRow) {
return marvelRow('strength').lt(dcRow('strength'))
}).run(conn, callback)
(Compare this to an innerJoin with the same inputs and predicate, which would return a list only of the matchups in which the DC hero has the higher strength.)
Read more about this command →
eqJoin
sequence.eqJoin(leftField, rightTable[, {index: 'id', ordered: false}]) → sequence
sequence.eqJoin(function, rightTable[, {index: 'id', ordered: false}]) → sequence
Join tables using a field or function on the left-hand sequence matching primary keys or secondary indexes on the right-hand table. eqJoin is more efficient than other ReQL join types, and operates much faster. Documents in the result set consist of pairs of left-hand and right-hand documents, matched when the field on the left-hand side exists and is non-null and an entry with that field’s value exists in the specified index on the right-hand side.
Example: Match players with the games they’ve played against one another.
Join these tables using gameId on the player table and id on the games table:
r.table('players').eqJoin('gameId', r.table('games')).run(conn, callback)
This will return a result set such as the following:
[
{
"left" : { "gameId" : 3, "id" : 2, "player" : "Agatha" },
"right" : { "id" : 3, "field" : "Bucklebury" }
},
{
"left" : { "gameId" : 2, "id" : 3, "player" : "Fred" },
"right" : { "id" : 2, "field" : "Rushock Bog" }
},
...
]
Read more about this command →
zip
stream.zip() → stream array.zip() → array
Used to ‘zip’ up the result of a join by merging the ‘right’ fields into ‘left’ fields of each member of the sequence.
Example: ‘zips up’ the sequence by merging the left and right fields produced by a join.
r.table('marvel').eqJoin('main_dc_collaborator', r.table('dc'))
.zip().run(conn, callback)
Transformations
map
sequence1.map([sequence2, ...], function) → stream array1.map([array2, ...], function) → array r.map(sequence1[, sequence2, ...], function) → stream r.map(array1[, array2, ...], function) → array
Transform each element of one or more sequences by applying a mapping function to them. If map is run with two or more sequences, it will iterate for as many items as there are in the shortest sequence.
Example: Return the first five squares.
r.expr([1, 2, 3, 4, 5]).map(function (val) {
return val.mul(val);
}).run(conn, callback);
// Result passed to callback
[1, 4, 9, 16, 25]
Read more about this command →
withFields
sequence.withFields([selector1, selector2...]) → stream array.withFields([selector1, selector2...]) → array
Plucks one or more attributes from a sequence of objects, filtering out any objects in the sequence that do not have the specified fields. Functionally, this is identical to hasFields followed by pluck on a sequence.
Example: Get a list of users and their posts, excluding any users who have not made any posts.
Existing table structure:
[
{ 'id': 1, 'user': 'bob', 'email': '[email protected]', 'posts': [ 1, 4, 5 ] },
{ 'id': 2, 'user': 'george', 'email': '[email protected]' },
{ 'id': 3, 'user': 'jane', 'email': '[email protected]', 'posts': [ 2, 3, 6 ] }
]
Command and output:
> r.table('users').withFields('id', 'user', 'posts').run(conn, callback)
// Result passed to callback
[
{ 'id': 1, 'user': 'bob', 'posts': [ 1, 4, 5 ] },
{ 'id': 3, 'user': 'jane', 'posts': [ 2, 3, 6 ] }
]
Read more about this command →
concatMap
stream.concatMap(function) → stream array.concatMap(function) → array
Concatenate one or more elements into a single sequence using a mapping function.
Example: Construct a sequence of all monsters defeated by Marvel heroes. The field “defeatedMonsters” is an array of one or more monster names.
r.table('marvel').concatMap(function(hero) {
return hero('defeatedMonsters')
}).run(conn, callback)
Read more about this command →
orderBy
table.orderBy([key | function...], {index: index_name}) → table_slice
selection.orderBy(key | function[, ...]) → selection<array>
sequence.orderBy(key | function[, ...]) → array
Sort the sequence by document values of the given key(s). To specify the ordering, wrap the attribute with either r.asc or r.desc (defaults to ascending).
Example: Order all the posts using the index date.
r.table('posts').orderBy({index: 'date'}).run(conn, callback);
Read more about this command →
skip
sequence.skip(n) → stream array.skip(n) → array
Skip a number of elements from the head of the sequence.
Example: Here in conjunction with orderBy we choose to ignore the most successful heroes.
r.table('marvel').orderBy('successMetric').skip(10).run(conn, callback)
Read more about this command →
limit
sequence.limit(n) → stream array.limit(n) → array
End the sequence after the given number of elements.
Example: Only so many can fit in our Pantheon of heroes.
r.table('marvel').orderBy('belovedness').limit(10).run(conn, callback)
Read more about this command →
slice
selection.slice(startOffset[, endOffset, {leftBound:'closed', rightBound:'open'}]) → selection
stream.slice(startOffset[, endOffset, {leftBound:'closed', rightBound:'open'}]) → stream
array.slice(startOffset[, endOffset, {leftBound:'closed', rightBound:'open'}]) → array
binary.slice(startOffset[, endOffset, {leftBound:'closed', rightBound:'open'}]) → binary
string.slice(startOffset[, endOffset, {leftBound:'closed', rightBound:'open'}]) → string
Return the elements of a sequence within the specified range.
Example: Return the fourth, fifth and sixth youngest players. (The youngest player is at index 0, so those are elements 3–5.)
r.table('players').orderBy({index: 'age'}).slice(3,6).run(conn, callback);
Read more about this command →
nth
sequence.nth(index) → object selection.nth(index) → selection<object>
Get the nth element of a sequence, counting from zero. If the argument is negative, count from the last element.
Example: Select the second element in the array.
r.expr([1,2,3]).nth(1).run(conn, callback)
r.expr([1,2,3])(1).run(conn, callback)
Read more about this command →
offsetsOf
sequence.offsetsOf(datum | predicate_function) → array
Get the indexes of an element in a sequence. If the argument is a predicate, get the indexes of all elements matching it.
Example: Find the position of the letter ‘c’.
r.expr(['a','b','c']).offsetsOf('c').run(conn, callback)
Read more about this command →
isEmpty
sequence.isEmpty() → bool
Test if a sequence is empty.
Example: Are there any documents in the marvel table?
r.table('marvel').isEmpty().run(conn, callback)
Read more about this command →
union
stream.union(sequence[, sequence, ...][, {interleave: true}]) → stream
array.union(sequence[, sequence, ...][, {interleave: true}]) → array
r.union(stream, sequence[, sequence, ...][, {interleave: true}]) → stream
r.union(array, sequence[, sequence, ...][, {interleave: true}]) → array
Merge two or more sequences.
Example: Construct a stream of all heroes.
r.table('marvel').union(r.table('dc')).run(conn, callback);
Read more about this command →
sample
sequence.sample(number) → selection stream.sample(number) → array array.sample(number) → array
Select a given number of elements from a sequence with uniform random distribution. Selection is done without replacement.
Example: Select 3 random heroes.
r.table('marvel').sample(3).run(conn, callback)
Aggregation
group
sequence.group(field | function..., [{index: <indexname>, multi: false}]) → grouped_stream
r.group(sequence, field | function..., [{index: <indexname>, multi: false}]) → grouped_stream
Takes a stream and partitions it into multiple groups based on the fields or functions provided.
Example: Group games by player.
> r.table('games').group('player').run(conn, callback)
// Result passed to callback
[
{
group: "Alice",
reduction: [
{id: 5, player: "Alice", points: 7, type: "free"},
{id: 12, player: "Alice", points: 2, type: "free"}
]
},
{
group: "Bob",
reduction: [
{id: 2, player: "Bob", points: 15, type: "ranked"},
{id: 11, player: "Bob", points: 10, type: "free"}
]
}
]
Read more about this command →
ungroup
grouped_stream.ungroup() → array grouped_data.ungroup() → array
Takes a grouped stream or grouped data and turns it into an array of objects representing the groups. Any commands chained after ungroup will operate on this array, rather than operating on each group individually. This is useful if you want to e.g. order the groups by the value of their reduction.
Example: What is the maximum number of points scored by each player, with the highest scorers first?
r.table('games')
.group('player').max('points')('points')
.ungroup().orderBy(r.desc('reduction')).run(conn, callback)
Read more about this command →
reduce
sequence.reduce(function) → value r.reduce(sequence, function) → value
Produce a single value from a sequence through repeated application of a reduction function.
Example: Return the number of documents in the table posts.
r.table("posts").map(function(doc) {
return 1;
}).reduce(function(left, right) {
return left.add(right);
}).default(0).run(conn, callback);
A shorter way to execute this query is to use count.
Read more about this command →
fold
sequence.fold(base, function) → value
sequence.fold(base, function, {emit: function[, finalEmit: function]}) → sequence
Apply a function to a sequence in order, maintaining state via an accumulator. The fold command returns either a single value or a new sequence.
Example: Concatenate words from a list.
r.table('words').orderBy('id').fold('', function (acc, word) {
return acc.add(r.branch(acc.eq(''), '', ', ')).add(word);
}).run(conn, callback);
(This example could be implemented with reduce, but fold will preserve the order when words is a RethinkDB table or other stream, which is not guaranteed with reduce.)
Read more about this command →
count
sequence.count([value | predicate_function]) → number binary.count() → number string.count() → number object.count() → number r.count(sequence | binary | string | object[, predicate_function]) → number
Counts the number of elements in a sequence or key/value pairs in an object, or returns the size of a string or binary object.
Example: Count the number of users.
r.table('users').count().run(conn, callback);
Read more about this command →
sum
sequence.sum([field | function]) → number r.sum(sequence, [field | function]) → number
Sums all the elements of a sequence. If called with a field name, sums all the values of that field in the sequence, skipping elements of the sequence that lack that field. If called with a function, calls that function on every element of the sequence and sums the results, skipping elements of the sequence where that function returns null or a non-existence error.
Example: What’s 3 + 5 + 7?
r.expr([3, 5, 7]).sum().run(conn, callback)
Read more about this command →
avg
sequence.avg([field | function]) → number r.avg(sequence, [field | function]) → number
Averages all the elements of a sequence. If called with a field name, averages all the values of that field in the sequence, skipping elements of the sequence that lack that field. If called with a function, calls that function on every element of the sequence and averages the results, skipping elements of the sequence where that function returns null or a non-existence error.
Example: What’s the average of 3, 5, and 7?
r.expr([3, 5, 7]).avg().run(conn, callback)
Read more about this command →
min
sequence.min(field | function) → element
sequence.min({index: <indexname>}) → element
r.min(sequence, field | function) → element
r.min(sequence, {index: <indexname>}) → element
Finds the minimum element of a sequence.
Example: Return the minimum value in the list [3, 5, 7].
r.expr([3, 5, 7]).min().run(conn, callback);
Read more about this command →
max
sequence.max(field | function) → element
sequence.max({index: <indexname>}) → element
r.max(sequence, field | function) → element
r.max(sequence, {index: <indexname>}) → element
Finds the maximum element of a sequence.
Example: Return the maximum value in the list [3, 5, 7].
r.expr([3, 5, 7]).max().run(conn, callback);
Read more about this command →
distinct
sequence.distinct() → array
table.distinct([{index: <indexname>}]) → stream
r.distinct(sequence) → array
r.distinct(table, [{index: <indexname>}]) → stream
Removes duplicates from elements in a sequence.
Example: Which unique villains have been vanquished by Marvel heroes?
r.table('marvel').concatMap(function(hero) {
return hero('villainList')
}).distinct().run(conn, callback)
Read more about this command →
contains
sequence.contains([value | predicate_function, ...]) → bool r.contains(sequence, [value | predicate_function, ...]) → bool
When called with values, returns true if a sequence contains all the specified values. When called with predicate functions, returns true if for each predicate there exists at least one element of the stream where that predicate returns true.
Example: Has Iron Man ever fought Superman?
r.table('marvel').get('ironman')('opponents').contains('superman').run(conn, callback);
Document manipulation
row
r.row → value
Returns the currently visited document.
Example: Get all users whose age is greater than 5.
r.table('users').filter(r.row('age').gt(5)).run(conn, callback)
Read more about this command →
pluck
sequence.pluck([selector1, selector2...]) → stream array.pluck([selector1, selector2...]) → array object.pluck([selector1, selector2...]) → object singleSelection.pluck([selector1, selector2...]) → object
Plucks out one or more attributes from either an object or a sequence of objects (projection).
Example: We just need information about IronMan’s reactor and not the rest of the document.
r.table('marvel').get('IronMan').pluck('reactorState', 'reactorPower').run(conn, callback)
Read more about this command →
without
sequence.without([selector1, selector2...]) → stream array.without([selector1, selector2...]) → array singleSelection.without([selector1, selector2...]) → object object.without([selector1, selector2...]) → object
The opposite of pluck; takes an object or a sequence of objects, and returns them with the specified paths removed.
Example: Since we don’t need it for this computation we’ll save bandwidth and leave out the list of IronMan’s romantic conquests.
r.table('marvel').get('IronMan').without('personalVictoriesList').run(conn, callback)
Read more about this command →
merge
singleSelection.merge([object | function, object | function, ...]) → object object.merge([object | function, object | function, ...]) → object sequence.merge([object | function, object | function, ...]) → stream array.merge([object | function, object | function, ...]) → array
Merge two or more objects together to construct a new object with properties from all. When there is a conflict between field names, preference is given to fields in the rightmost object in the argument list. merge also accepts a subquery function that returns an object, which will be used similarly to a map function.
Example: Equip Thor for battle.
r.table('marvel').get('thor').merge(
r.table('equipment').get('hammer'),
r.table('equipment').get('pimento_sandwich')
).run(conn, callback)
Read more about this command →
append
array.append(value) → array
Append a value to an array.
Example: Retrieve Iron Man’s equipment list with the addition of some new boots.
r.table('marvel').get('IronMan')('equipment').append('newBoots').run(conn, callback)
Read more about this command →
prepend
array.prepend(value) → array
Prepend a value to an array.
Example: Retrieve Iron Man’s equipment list with the addition of some new boots.
r.table('marvel').get('IronMan')('equipment').prepend('newBoots').run(conn, callback)
Read more about this command →
difference
array.difference(array) → array
Remove the elements of one array from another array.
Example: Retrieve Iron Man’s equipment list without boots.
r.table('marvel').get('IronMan')('equipment')
.difference(['Boots'])
.run(conn, callback)
Read more about this command →
setInsert
array.setInsert(value) → array
Add a value to an array and return it as a set (an array with distinct values).
Example: Retrieve Iron Man’s equipment list with the addition of some new boots.
r.table('marvel').get('IronMan')('equipment').setInsert('newBoots').run(conn, callback)
Read more about this command →
setUnion
array.setUnion(array) → array
Add a several values to an array and return it as a set (an array with distinct values).
Example: Retrieve Iron Man’s equipment list with the addition of some new boots and an arc reactor.
r.table('marvel').get('IronMan')('equipment').setUnion(['newBoots', 'arc_reactor']).run(conn, callback)
Read more about this command →
setIntersection
array.setIntersection(array) → array
Intersect two arrays returning values that occur in both of them as a set (an array with distinct values).
Example: Check which pieces of equipment Iron Man has from a fixed list.
r.table('marvel').get('IronMan')('equipment').setIntersection(['newBoots', 'arc_reactor']).run(conn, callback)
Read more about this command →
setDifference
array.setDifference(array) → array
Remove the elements of one array from another and return them as a set (an array with distinct values).
Example: Check which pieces of equipment Iron Man has, excluding a fixed list.
r.table('marvel').get('IronMan')('equipment').setDifference(['newBoots', 'arc_reactor']).run(conn, callback)
Read more about this command →
() (bracket)
sequence(attr) → sequence singleSelection(attr) → value object(attr) → value array(index) → value
Get a single field from an object. If called on a sequence, gets that field from every object in the sequence, skipping objects that lack it.
Example: What was Iron Man’s first appearance in a comic?
r.table('marvel').get('IronMan')('firstAppearance').run(conn, callback)
Read more about this command →
getField
sequence.getField(attr) → sequence singleSelection.getField(attr) → value object.getField(attr) → value
Get a single field from an object. If called on a sequence, gets that field from every object in the sequence, skipping objects that lack it.
Example: What was Iron Man’s first appearance in a comic?
r.table('marvel').get('IronMan').getField('firstAppearance').run(conn, callback)
Read more about this command →
hasFields
sequence.hasFields([selector1, selector2...]) → stream array.hasFields([selector1, selector2...]) → array object.hasFields([selector1, selector2...]) → boolean
Test if an object has one or more fields. An object has a field if it has that key and the key has a non-null value. For instance, the object {'a': 1,'b': 2,'c': null} has the fields a and b.
Example: Return the players who have won games.
r.table('players').hasFields('games_won').run(conn, callback)
Read more about this command →
insertAt
array.insertAt(offset, value) → array
Insert a value in to an array at a given index. Returns the modified array.
Example: Hulk decides to join the avengers.
r.expr(["Iron Man", "Spider-Man"]).insertAt(1, "Hulk").run(conn, callback)
Read more about this command →
spliceAt
array.spliceAt(offset, array) → array
Insert several values in to an array at a given index. Returns the modified array.
Example: Hulk and Thor decide to join the avengers.
r.expr(["Iron Man", "Spider-Man"]).spliceAt(1, ["Hulk", "Thor"]).run(conn, callback)
Read more about this command →
deleteAt
array.deleteAt(offset [,endOffset]) → array
Remove one or more elements from an array at a given index. Returns the modified array. (Note: deleteAt operates on arrays, not documents; to delete documents, see the delete command.)
Example: Delete the second element of an array.
> r(['a','b','c','d','e','f']).deleteAt(1).run(conn, callback)
// result passed to callback
['a', 'c', 'd', 'e', 'f']
Read more about this command →
changeAt
array.changeAt(offset, value) → array
Change a value in an array at a given index. Returns the modified array.
Example: Bruce Banner hulks out.
r.expr(["Iron Man", "Bruce", "Spider-Man"]).changeAt(1, "Hulk").run(conn, callback)
Read more about this command →
keys
singleSelection.keys() → array object.keys() → array
Return an array containing all of an object’s keys. Note that the keys will be sorted as described in ReQL data types (for strings, lexicographically).
Example: Get all the keys from a table row.
// row: { id: 1, mail: "[email protected]", name: "fred" }
r.table('users').get(1).keys().run(conn, callback);
// Result passed to callback
[ "id", "mail", "name" ]
Read more about this command →
values
singleSelection.values() → array object.values() → array
Return an array containing all of an object’s values. values() guarantees the values will come out in the same order as keys.
Example: Get all of the values from a table row.
// row: { id: 1, mail: "[email protected]", name: "fred" }
r.table('users').get(1).values().run(conn, callback);
// Result passed to callback
[ 1, "[email protected]", "fred" ]
Read more about this command →
literal
r.literal(object) → special
Replace an object in a field instead of merging it with an existing object in a merge or update operation. Using literal with no arguments in a merge or update operation will remove the corresponding field.
Example: Replace one nested document with another rather than merging the fields.
r.table('users').get(1).update({ data: r.literal({ age: 19, job: 'Engineer' }) }).run(conn, callback)
// Result passed to callback
{
"id": 1,
"name": "Alice",
"data": {
"age": 19,
"job": "Engineer"
}
}
Read more about this command →
object
r.object([key, value,]...) → object
Creates an object from a list of key-value pairs, where the keys must be strings. r.object(A, B, C, D) is equivalent to r.expr([[A, B], [C, D]]).coerceTo('OBJECT').
Example: Create a simple object.
r.object('id', 5, 'data', ['foo', 'bar']).run(conn, callback)
Result:
{data: ["foo", "bar"], id: 5}
String manipulation
match
string.match(regexp) → null/object
Matches against a regular expression. If there is a match, returns an object with the fields:
-
str: The matched string -
start: The matched string’s start -
end: The matched string’s end -
groups: The capture groups defined with parentheses
If no match is found, returns null.
Example: Get all users whose name starts with “A”. Because null evaluates to false in filter, you can just use the result of match for the predicate.
r.table('users').filter(function(doc){
return doc('name').match("^A")
}).run(conn, callback)
Read more about this command →
split
string.split([separator, [max_splits]]) → array
Splits a string into substrings. Splits on whitespace when called with no arguments. When called with a separator, splits on that separator. When called with a separator and a maximum number of splits, splits on that separator at most max_splits times. (Can be called with null as the separator if you want to split on whitespace while still specifying max_splits.)
Example: Split on whitespace.
r.expr("foo bar bax").split().run(conn, callback)
Result:
["foo", "bar", "bax"]
Read more about this command →
upcase
string.upcase() → string
Uppercases a string.
Example:
r.expr("Sentence about LaTeX.").upcase().run(conn, callback)
Result:
"SENTENCE ABOUT LATEX."
Note: upcase and downcase only affect ASCII characters.
Read more about this command →
downcase
string.downcase() → string
Lowercases a string.
Example:
r.expr("Sentence about LaTeX.").downcase().run(conn, callback)
Result:
"sentence about latex."
Note: upcase and downcase only affect ASCII characters.
Math and logic
add
value.add(value[, value, ...]) → value time.add(number[, number, ...]) → time
Sum two or more numbers, or concatenate two or more strings or arrays.
Example: It’s as easy as 2 + 2 = 4.
> r.expr(2).add(2).run(conn, callback)
// result passed to callback
4
Read more about this command →
sub
number.sub(number[, number, ...]) → number time.sub(number[, number, ...]) → time time.sub(time) → number
Subtract two numbers.
Example: It’s as easy as 2 - 2 = 0.
r.expr(2).sub(2).run(conn, callback)
Read more about this command →
mul
number.mul(number[, number, ...]) → number array.mul(number[, number, ...]) → array
Multiply two numbers, or make a periodic array.
Example: It’s as easy as 2 * 2 = 4.
r.expr(2).mul(2).run(conn, callback)
Read more about this command →
div
number.div(number[, number ...]) → number
Divide two numbers.
Example: It’s as easy as 2 / 2 = 1.
r.expr(2).div(2).run(conn, callback)
Read more about this command →
mod
number.mod(number) → number
Example: It’s as easy as 2 % 2 = 0.
r.expr(2).mod(2).run(conn, callback)
Read more about this command →
and
bool.and([bool, bool, ...]) → bool r.and([bool, bool, ...]) → bool
Compute the logical “and” of one or more values.
Example: Return whether both a and b evaluate to true.
var a = true, b = false;
r.expr(a).and(b).run(conn, callback);
// result passed to callback
false
Read more about this command →
or
bool.or([bool, bool, ...]) → bool r.or([bool, bool, ...]) → bool
Compute the logical “or” of one or more values.
Example: Return whether either a or b evaluate to true.
var a = true, b = false;
r.expr(a).or(b).run(conn, callback);
// result passed to callback
true
Read more about this command →
eq
value.eq(value[, value, ...]) → bool
Test if two or more values are equal.
Example: See if a user’s role field is set to administrator.
r.table('users').get(1)('role').eq('administrator').run(conn, callback);
Read more about this command →
ne
value.ne(value[, value, ...]) → bool
Test if two or more values are not equal.
Example: See if a user’s role field is not set to administrator.
r.table('users').get(1)('role').ne('administrator').run(conn, callback);
Read more about this command →
gt
value.gt(value[, value, ...]) → bool
Compare values, testing if the left-hand value is greater than the right-hand.
Example: Test if a player has scored more than 10 points.
r.table('players').get(1)('score').gt(10).run(conn, callback);
Read more about this command →
ge
value.ge(value[, value, ...]) → bool
Compare values, testing if the left-hand value is greater than or equal to the right-hand.
Example: Test if a player has scored 10 points or more.
r.table('players').get(1)('score').ge(10).run(conn, callback);
Read more about this command →
lt
value.lt(value[, value, ...]) → bool
Compare values, testing if the left-hand value is less than the right-hand.
Example: Test if a player has scored less than 10 points.
r.table('players').get(1)('score').lt(10).run(conn, callback);
Read more about this command →
le
value.le(value[, value, ...]) → bool
Compare values, testing if the left-hand value is less than or equal to the right-hand.
Example: Test if a player has scored 10 points or less.
r.table('players').get(1)('score').le(10).run(conn, callback);
Read more about this command →
not
bool.not() → bool not(bool) → bool
Compute the logical inverse (not) of an expression.
Example: Not true is false.
r(true).not().run(conn, callback)
r.not(true).run(conn, callback)
These evaluate to false.
Read more about this command →
bitAnd
r.bitAnd(number) → number r.bitAnd(number[, number, ...]) → number
Compute the arithmetic “and” of one or more values. bitAnd takes one or more arguments.
Example: Compute the arithmetic “and” of 6 and 4
r.expr(6).bitAnd(4).run(conn)
Read more about this command →
bitOr
r.bitOr(number) → number r.bitOr(number[, number, ...]) → number
Compute the arithmetic “or” of one or more values. bitOr takes one or more arguments.
Example: Compute the arithmetic “or” of 6 and 4
r.expr(6).bitOr(4).run(conn)
Read more about this command →
bitXor
r.bitXor(number) → number r.bitXor(number[, number, ...]) → number
Compute the arithmetic “and” of one or more values. bitXor takes one or more arguments.
Example: Compute the arithmetic “and” of 6 and 4
r.expr(6).bitXor(4).run(conn)
Read more about this command →
bitNot
r.bitNot() → number
Compute the arithmetic inverse (not) of an expression. bitNot takes no arguments.
Example: Negate the arithmetice expression
r.expr(15).bitNot().run(conn)
Read more about this command →
bitSal
r.bitSal(number) → number r.bitSal(number[, number, ...]) → number
Compute the left arithmetic shift (left logical shift) of one or more values. bitSal takes one or more arguments.
Example: Compute the left arithmetic shift of 5 and 4
r.expr(5).bitSal(4).run(conn)
Read more about this command →
bitSar
r.bitSar(number) → number r.bitSar(number[, number, ...]) → number
Compute the right arithmetic shift of one or more values. bitSar takes one or more arguments.
Example: Compute the right arithmetic shift of 32 and 3
r.expr(32).bitSar(3).run(conn)
Read more about this command →
random
r.random() → number
r.random(number[, number], {float: true}) → number
r.random(integer[, integer]) → integer
Generate a random number between given (or implied) bounds. random takes zero, one or two arguments.
Example: Generate a random number in the range [0,1)
r.random().run(conn, callback)
Read more about this command →
round
r.round(number) → number number.round() → number
Rounds the given value to the nearest whole integer.
Example: Round 12.345 to the nearest integer.
r.round(12.345).run(conn, callback);
// Result passed to callback
12.0
The round command can also be chained after an expression.
Read more about this command →
ceil
r.ceil(number) → number number.ceil() → number
Rounds the given value up, returning the smallest integer value greater than or equal to the given value (the value’s ceiling).
Example: Return the ceiling of 12.345.
r.ceil(12.345).run(conn, callback);
// Result passed to callback
13.0
The ceil command can also be chained after an expression.
Read more about this command →
floor
r.floor(number) → number number.floor() → number
Rounds the given value down, returning the largest integer value less than or equal to the given value (the value’s floor).
Example: Return the floor of 12.345.
r.floor(12.345).run(conn, callback);
// Result passed to callback
12.0
The floor command can also be chained after an expression.
Dates and times
now
r.now() → time
Return a time object representing the current time in UTC. The command now() is computed once when the server receives the query, so multiple instances of r.now() will always return the same time inside a query.
Example: Add a new user with the time at which he subscribed.
r.table("users").insert({
name: "John",
subscription_date: r.now()
}).run(conn, callback)
Read more about this command →
time
r.time(year, month, day[, hour, minute, second], timezone) → time
Create a time object for a specific time.
Example: Update the birthdate of the user “John” to November 3rd, 1986 UTC.
r.table("user").get("John").update({birthdate: r.time(1986, 11, 3, 'Z')}).run(conn, callback)
Read more about this command →
epochTime
r.epochTime(number) → time
Create a time object based on seconds since epoch. The first argument is a double and will be rounded to three decimal places (millisecond-precision).
Example: Update the birthdate of the user “John” to November 3rd, 1986.
r.table("user").get("John").update({birthdate: r.epochTime(531360000)}).run(conn, callback)
Read more about this command →
ISO8601
r.ISO8601(string[, {defaultTimezone:''}]) → time
Create a time object based on an ISO 8601 date-time string (e.g. ‘2013-01-01T01:01:01+00:00’). RethinkDB supports all valid ISO 8601 formats except for week dates. Read more about the ISO 8601 format at Wikipedia.
Example: Update the time of John’s birth.
r.table("user").get("John").update({birth: r.ISO8601('1986-11-03T08:30:00-07:00')}).run(conn, callback)
Read more about this command →
inTimezone
time.inTimezone(timezone) → time
Return a new time object with a different timezone. While the time stays the same, the results returned by methods such as hours() will change since they take the timezone into account. The timezone argument has to be of the ISO 8601 format.
Example: Hour of the day in San Francisco (UTC/GMT -8, without daylight saving time).
r.now().inTimezone('-08:00').hours().run(conn, callback)
Read more about this command →
timezone
time.timezone() → string
Return the timezone of the time object.
Example: Return all the users in the “-07:00” timezone.
r.table("users").filter( function(user) {
return user("subscriptionDate").timezone().eq("-07:00")
})
Read more about this command →
during
time.during(startTime, endTime[, {leftBound: "closed", rightBound: "open"}]) → bool
Return whether a time is between two other times.
Example: Retrieve all the posts that were posted between December 1st, 2013 (inclusive) and December 10th, 2013 (exclusive).
r.table("posts").filter(
r.row('date').during(r.time(2013, 12, 1, "Z"), r.time(2013, 12, 10, "Z"))
).run(conn, callback)
Read more about this command →
date
time.date() → time
Return a new time object only based on the day, month and year (ie. the same day at 00:00).
Example: Retrieve all the users whose birthday is today.
r.table("users").filter(function(user) {
return user("birthdate").date().eq(r.now().date())
}).run(conn, callback)
Read more about this command →
timeOfDay
time.timeOfDay() → number
Return the number of seconds elapsed since the beginning of the day stored in the time object.
Example: Retrieve posts that were submitted before noon.
r.table("posts").filter(
r.row("date").timeOfDay().le(12*60*60)
).run(conn, callback)
Read more about this command →
year
time.year() → number
Return the year of a time object.
Example: Retrieve all the users born in 1986.
r.table("users").filter(function(user) {
return user("birthdate").year().eq(1986)
}).run(conn, callback)
Read more about this command →
month
time.month() → number
Return the month of a time object as a number between 1 and 12. For your convenience, the terms r.january, r.february etc. are defined and map to the appropriate integer.
Example: Retrieve all the users who were born in November.
r.table("users").filter(
r.row("birthdate").month().eq(11)
)
Read more about this command →
day
time.day() → number
Return the day of a time object as a number between 1 and 31.
Example: Return the users born on the 24th of any month.
r.table("users").filter(
r.row("birthdate").day().eq(24)
).run(conn, callback)
Read more about this command →
dayOfWeek
time.dayOfWeek() → number
Return the day of week of a time object as a number between 1 and 7 (following ISO 8601 standard). For your convenience, the terms r.monday, r.tuesday etc. are defined and map to the appropriate integer.
Example: Return today’s day of week.
r.now().dayOfWeek().run(conn, callback)
Read more about this command →
dayOfYear
time.dayOfYear() → number
Return the day of the year of a time object as a number between 1 and 366 (following ISO 8601 standard).
Example: Retrieve all the users who were born the first day of a year.
r.table("users").filter(
r.row("birthdate").dayOfYear().eq(1)
)
Read more about this command →
hours
time.hours() → number
Return the hour in a time object as a number between 0 and 23.
Example: Return all the posts submitted after midnight and before 4am.
r.table("posts").filter(function(post) {
return post("date").hours().lt(4)
})
Read more about this command →
minutes
time.minutes() → number
Return the minute in a time object as a number between 0 and 59.
Example: Return all the posts submitted during the first 10 minutes of every hour.
r.table("posts").filter(function(post) {
return post("date").minutes().lt(10)
})
Read more about this command →
seconds
time.seconds() → number
Return the seconds in a time object as a number between 0 and 59.999 (double precision).
Example: Return the post submitted during the first 30 seconds of every minute.
r.table("posts").filter(function(post) {
return post("date").seconds().lt(30)
})
Read more about this command →
toISO8601
time.toISO8601() → string
Convert a time object to a string in ISO 8601 format.
Example: Return the current ISO 8601 time.
r.now().toISO8601().run(conn, callback)
// Result passed to callback
"2015-04-20T18:37:52.690+00:00"
Read more about this command →
toEpochTime
time.toEpochTime() → number
Convert a time object to its epoch time.
Example: Return the current time in seconds since the Unix Epoch with millisecond-precision.
r.now().toEpochTime()
Control structures
args
r.args(array) → special
r.args is a special term that’s used to splice an array of arguments into another term. This is useful when you want to call a variadic term such as getAll with a set of arguments produced at runtime.
Example: Get Alice and Bob from the table people.
r.table('people').getAll('Alice', 'Bob').run(conn, callback)
// or
r.table('people').getAll(r.args(['Alice', 'Bob'])).run(conn, callback)
Read more about this command →
binary
r.binary(data) → binary
Encapsulate binary data within a query.
Example: Save an avatar image to a existing user record.
var fs = require('fs');
fs.readFile('./defaultAvatar.png', function (err, avatarImage) {
if (err) {
// Handle error
}
else {
r.table('users').get(100).update({
avatar: avatarImage
})
}
});
Read more about this command →
do
any.do(function) → any r.do([args]*, function) → any any.do(expr) → any r.do([args]*, expr) → any
Call an anonymous function using return values from other ReQL commands or queries as arguments.
Example: Compute a golfer’s net score for a game.
r.table('players').get('f19b5f16-ef14-468f-bd48-e194761df255').do(
function (player) {
return player('gross_score').sub(player('course_handicap'));
}
).run(conn, callback);
Read more about this command →
branch
r.branch(test, true_action[, test2, test2_action, ...], false_action) → any test.branch(true_action[, test2, test2_action, ...], false_action) → any
Perform a branching conditional equivalent to if-then-else.
The branch command takes 2n+1 arguments: pairs of conditional expressions and commands to be executed if the conditionals return any value but false or null (i.e., “truthy” values), with a final “else” command to be evaluated if all of the conditionals are false or null.
Example: Test the value of x.
var x = 10;
r.branch(r.expr(x).gt(5), 'big', 'small').run(conn, callback);
// Result passed to callback
"big"
Read more about this command →
forEach
sequence.forEach(write_function) → object
Loop over a sequence, evaluating the given write query for each element.
Example: Now that our heroes have defeated their villains, we can safely remove them from the villain table.
r.table('marvel').forEach(function(hero) {
return r.table('villains').get(hero('villainDefeated')).delete()
}).run(conn, callback)
Read more about this command →
range
r.range() → stream r.range([startValue, ]endValue) → stream
Generate a stream of sequential integers in a specified range.
Example: Return a four-element range of [0, 1, 2, 3].
> r.range(4).run(conn, callback)
// result returned to callback
[0, 1, 2, 3]
Read more about this command →
error
r.error(message) → error
Throw a runtime error. If called with no arguments inside the second argument to default, re-throw the current error.
Example: Iron Man can’t possibly have lost a battle:
r.table('marvel').get('IronMan').do(function(ironman) {
return r.branch(ironman('victories').lt(ironman('battles')),
r.error('impossible code path'),
ironman)
}).run(conn, callback)
Read more about this command →
default
value.default(default_value | function) → any sequence.default(default_value | function) → any
Provide a default value in case of non-existence errors. The default command evaluates its first argument (the value it’s chained to). If that argument returns null or a non-existence error is thrown in evaluation, then default returns its second argument. The second argument is usually a default value, but it can be a function that returns a value.
Example: Retrieve the titles and authors of the table posts. In the case where the author field is missing or null, we want to retrieve the string Anonymous.
r.table("posts").map(function (post) {
return {
title: post("title"),
author: post("author").default("Anonymous")
}
}).run(conn, callback);
Read more about this command →
expr
r.expr(value) → value
Construct a ReQL JSON object from a native object.
Example: Objects wrapped with expr can then be manipulated by ReQL API functions.
r.expr({a:'b'}).merge({b:[1,2,3]}).run(conn, callback)
Read more about this command →
js
r.js(jsString[, {timeout: <number>}]) → value
Create a javascript expression.
Example: Concatenate two strings using JavaScript.
r.js("'str1' + 'str2'").run(conn, callback)
Read more about this command →
coerceTo
sequence.coerceTo('array') → array
value.coerceTo('string') → string
string.coerceTo('number') → number
array.coerceTo('object') → object
sequence.coerceTo('object') → object
object.coerceTo('array') → array
binary.coerceTo('string') → string
string.coerceTo('binary') → binary
Convert a value of one type into another.
Example: Coerce a stream to an array to store its output in a field. (A stream cannot be stored in a field directly.)
r.table('posts').map(function (post) {
return post.merge({ comments: r.table('comments').getAll(post('id'), {index: 'postId'}).coerceTo('array')});
}).run(conn, callback)
Read more about this command →
typeOf
any.typeOf() → string
Gets the type of a ReQL query’s return value.
Example: Get the type of a string.
r.expr("foo").typeOf().run(conn, callback);
// Result passed to callback
"STRING"
Read more about this command →
info
any.info() → object r.info(any) → object
Get information about a ReQL value.
Example: Get information about a table such as primary key, or cache size.
r.table('marvel').info().run(conn, callback)
Read more about this command →
json
r.json(json_string) → value
Parse a JSON string on the server.
Example: Send an array to the server.
r.json("[1,2,3]").run(conn, callback)
Read more about this command →
toJsonString, toJSON
value.toJsonString() → string value.toJSON() → string
Convert a ReQL value or object to a JSON string. You may use either toJsonString or toJSON.
Example: Get a ReQL document as a JSON string.
> r.table('hero').get(1).toJSON()
// result returned to callback
'{"id": 1, "name": "Batman", "city": "Gotham", "powers": ["martial arts", "cinematic entrances"]}'
Read more about this command →
http
r.http(url[, options]) → value r.http(url[, options]) → stream
Retrieve data from the specified URL over HTTP. The return type depends on the resultFormat option, which checks the Content-Type of the response by default. Make sure that you never use this command for user provided URLs.
Example: Perform an HTTP GET and store the result in a table.
r.table('posts').insert(r.http('http://httpbin.org/get')).run(conn, callback)
Read more about this command →
uuid
r.uuid([string]) → string
Return a UUID (universally unique identifier), a string that can be used as a unique ID. If a string is passed to uuid as an argument, the UUID will be deterministic, derived from the string’s SHA-1 hash.
Example: Generate a UUID.
> r.uuid().run(conn, callback)
// result returned to callback
"27961a0e-f4e8-4eb3-bf95-c5203e1d87b9"
Geospatial commands
circle
r.circle([longitude, latitude], radius[, {numVertices: 32, geoSystem: 'WGS84', unit: 'm', fill: true}]) → geometry
r.circle(point, radius[, {numVertices: 32, geoSystem: 'WGS84', unit: 'm', fill: true}]) → geometry
Construct a circular line or polygon. A circle in RethinkDB is a polygon or line approximating a circle of a given radius around a given center, consisting of a specified number of vertices (default 32).
Example: Define a circle.
r.table('geo').insert({
id: 300,
name: 'Hayes Valley',
neighborhood: r.circle([-122.423246,37.779388], 1000)
}).run(conn, callback);
Read more about this command →
distance
geometry.distance(geometry[, {geoSystem: 'WGS84', unit: 'm'}]) → number
r.distance(geometry, geometry[, {geoSystem: 'WGS84', unit: 'm'}]) → number
Compute the distance between a point and another geometry object. At least one of the geometry objects specified must be a point.
Example: Compute the distance between two points on the Earth in kilometers.
var point1 = r.point(-122.423246,37.779388);
var point2 = r.point(-117.220406,32.719464);
r.distance(point1, point2, {unit: 'km'}).run(conn, callback);
// result returned to callback
734.1252496021841
Read more about this command →
fill
line.fill() → polygon
Convert a Line object into a Polygon object. If the last point does not specify the same coordinates as the first point, polygon will close the polygon by connecting them.
Example: Create a line object and then convert it to a polygon.
r.table('geo').insert({
id: 201,
rectangle: r.line(
[-122.423246,37.779388],
[-122.423246,37.329898],
[-121.886420,37.329898],
[-121.886420,37.779388]
)
}).run(conn, callback);
r.table('geo').get(201).update({
rectangle: r.row('rectangle').fill()
}, {nonAtomic: true}).run(conn, callback);
Read more about this command →
geojson
r.geojson(geojson) → geometry
Convert a GeoJSON object to a ReQL geometry object.
Example: Convert a GeoJSON object to a ReQL geometry object.
var geoJson = {
'type': 'Point',
'coordinates': [ -122.423246, 37.779388 ]
};
r.table('geo').insert({
id: 'sfo',
name: 'San Francisco',
location: r.geojson(geoJson)
}).run(conn, callback);
Read more about this command →
toGeojson
geometry.toGeojson() → object
Convert a ReQL geometry object to a GeoJSON object.
Example: Convert a ReQL geometry object to a GeoJSON object.
r.table('geo').get('sfo')('location').toGeojson.run(conn, callback);
// result passed to callback
{
'type': 'Point',
'coordinates': [ -122.423246, 37.779388 ]
}
Read more about this command →
getIntersecting
table.getIntersecting(geometry, {index: 'indexname'}) → selection<stream>
Get all documents where the given geometry object intersects the geometry object of the requested geospatial index.
Example: Which of the locations in a list of parks intersect circle1?
var circle1 = r.circle([-117.220406,32.719464], 10, {unit: 'mi'});
r.table('parks').getIntersecting(circle1, {index: 'area'}).run(conn, callback);
Read more about this command →
getNearest
table.getNearest(point, {index: 'indexname'[, maxResults: 100, maxDist: 100000, unit: 'm', geoSystem: 'WGS84']}) → array
Return a list of documents closest to a specified point based on a geospatial index, sorted in order of increasing distance.
Example: Return a list of the closest 25 enemy hideouts to the secret base.
var secretBase = r.point(-122.422876,37.777128);
r.table('hideouts').getNearest(secretBase,
{index: 'location', maxResults: 25}
).run(conn, callback)
Read more about this command →
includes
sequence.includes(geometry) → sequence geometry.includes(geometry) → bool
Tests whether a geometry object is completely contained within another. When applied to a sequence of geometry objects, includes acts as a filter, returning a sequence of objects from the sequence that include the argument.
Example: Is point2 included within a 2000-meter circle around point1?
var point1 = r.point(-117.220406,32.719464);
var point2 = r.point(-117.206201,32.725186);
r.circle(point1, 2000).includes(point2).run(conn, callback);
// result returned to callback
true
Read more about this command →
intersects
sequence.intersects(geometry) → sequence geometry.intersects(geometry) → bool r.intersects(sequence, geometry) → sequence r.intersects(geometry, geometry) → bool
Tests whether two geometry objects intersect with one another. When applied to a sequence of geometry objects, intersects acts as a filter, returning a sequence of objects from the sequence that intersect with the argument.
Example: Is point2 within a 2000-meter circle around point1?
var point1 = r.point(-117.220406,32.719464);
var point2 = r.point(-117.206201,32.725186);
r.circle(point1, 2000).intersects(point2).run(conn, callback);
// result returned to callback
true
Read more about this command →
line
r.line([lon1, lat1], [lon2, lat2], ...) → line r.line(point1, point2, ...) → line
Construct a geometry object of type Line. The line can be specified in one of two ways:
- Two or more two-item arrays, specifying latitude and longitude numbers of the line’s vertices;
- Two or more Point objects specifying the line’s vertices.
Example: Define a line.
r.table('geo').insert({
id: 101,
route: r.line([-122.423246,37.779388], [-121.886420,37.329898])
}).run(conn, callback);
Read more about this command →
point
r.point(longitude, latitude) → point
Construct a geometry object of type Point. The point is specified by two floating point numbers, the longitude (−180 to 180) and latitude (−90 to 90) of the point on a perfect sphere. See Geospatial support for more information on ReQL’s coordinate system.
Example: Define a point.
r.table('geo').insert({
id: 1,
name: 'San Francisco',
location: r.point(-122.423246,37.779388)
}).run(conn, callback);
Read more about this command →
polygon
r.polygon([lon1, lat1], [lon2, lat2], [lon3, lat3], ...) → polygon r.polygon(point1, point2, point3, ...) → polygon
Construct a geometry object of type Polygon. The Polygon can be specified in one of two ways:
- Three or more two-item arrays, specifying latitude and longitude numbers of the polygon’s vertices;
- Three or more Point objects specifying the polygon’s vertices.
Example: Define a polygon.
r.table('geo').insert({
id: 101,
rectangle: r.polygon(
[-122.423246,37.779388],
[-122.423246,37.329898],
[-121.886420,37.329898],
[-121.886420,37.779388]
)
}).run(conn, callback);
Read more about this command →
polygonSub
polygon1.polygonSub(polygon2) → polygon
Use polygon2 to “punch out” a hole in polygon1. polygon2 must be completely contained within polygon1 and must have no holes itself (it must not be the output of polygonSub itself).
Example: Define a polygon with a hole punched in it.
var outerPolygon = r.polygon(
[-122.4,37.7],
[-122.4,37.3],
[-121.8,37.3],
[-121.8,37.7]
);
var innerPolygon = r.polygon(
[-122.3,37.4],
[-122.3,37.6],
[-122.0,37.6],
[-122.0,37.4]
);
outerPolygon.polygonSub(innerPolygon).run(conn, callback);
Administration
grant
r.grant("username", {permission: bool[, ...]}) → object
db.grant("username", {permission: bool[, ...]}) → object
table.grant("username", {permission: bool[, ...]}) → object
Grant or deny access permissions for a user account, globally or on a per-database or per-table basis.
Example: Grant the chatapp user account read and write permissions on the users database.
r.db('users').grant('chatapp', {read: true, write: true}).run(conn, callback);
// Result passed to callback
{
"granted": 1,
"permissions_changes": [
{
"new_val": { "read": true, "write": true },
"old_val": { null }
}
]
Read more about this command →
config
table.config() → selection<object> database.config() → selection<object>
Query (read and/or update) the configurations for individual tables or databases.
Example: Get the configuration for the users table.
> r.table('users').config().run(conn, callback);
Read more about this command →
rebalance
table.rebalance() → object database.rebalance() → object
Rebalances the shards of a table. When called on a database, all the tables in that database will be rebalanced.
Example: Rebalance a table.
> r.table('superheroes').rebalance().run(conn, callback);
Read more about this command →
reconfigure
table.reconfigure({shards: <s>, replicas: <r>[, primaryReplicaTag: <t>, dryRun: false, nonvotingReplicaTags: null}]) → object
database.reconfigure({shards: <s>, replicas: <r>[, primaryReplicaTag: <t>, dryRun: false, nonvotingReplicaTags: null}]) → object
table.reconfigure(emergencyRepair: <option>, dryRun: false) → object
Reconfigure a table’s sharding and replication.
Example: Reconfigure a table.
> r.table('superheroes').reconfigure({shards: 2, replicas: 1}).run(conn, callback);
Read more about this command →
status
table.status() → selection<object>
Return the status of a table.
Example: Get a table’s status.
> r.table('superheroes').status().run(conn, callback);
Read more about this command →
wait
table.wait([{waitFor: 'all_replicas_ready', timeout: <sec>}]) → object
database.wait([{waitFor: 'all_replicas_ready', timeout: <sec>}]) → object
r.wait(table | database, [{waitFor: 'all_replicas_ready', timeout: <sec>}]) → object
Wait for a table or all the tables in a database to be ready. A table may be temporarily unavailable after creation, rebalancing or reconfiguring. The wait command blocks until the given table (or database) is fully up to date.
Example: Wait on a table to be ready.
> r.table('superheroes').wait().run(conn, callback);
// Result passed to callback
{ "ready": 1 }
© RethinkDB contributors
Licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
https://rethinkdb.com/api/javascript/