RethinkDB

What is RethinkDB?

RethinkDB is the first open-source, scalable JSON database built from the ground up for the realtime web. It inverts the traditional database architecture by exposing an exciting new access model – instead of polling for changes, the developer can tell RethinkDB to continuously push updated query results to applications in realtime. RethinkDB’s realtime push architecture dramatically reduces the time and effort necessary to build scalable realtime apps.

 

When is RethinkDB a good choice?

RethinkDB is a great choice when your applications could benefit from realtime feeds to your data.

The query-response database access model works well on the web because it maps directly to HTTP’s request-response. However, modern applications require sending data directly to the client in realtime. Use cases where companies benefited from RethinkDB’s realtime push architecture include:

  • Collaborative web and mobile apps
  • Streaming analytics apps
  • Multiplayer games
  • Realtime marketplaces
  • Connected devices

For example, when a user changes the position of a button in a collaborative design app, the server has to notify other users that are simultaneously working on the same project. Web browsers support these use cases via WebSockets and long-lived HTTP connections, but adapting database systems to realtime needs still presents a huge engineering challenge.

RethinkDB is the first open-source, scalable database designed specifically to push data to applications in realtime. It dramatically reduces the time and effort necessary to build scalable realtime apps.

RethinkDB pushes JSON to your appsin realtime.

When your app polls for data, it becomes slow, unscalable, and cumbersome to maintain.

RethinkDB is the open-source, scalable database that makes building realtime apps dramatically easier.

Building realtime apps just got easy

  • Reactive web and mobile apps

    Web apps like Google Docs, Trello, and Quora pioneered the realtime experience on the web. With RethinkDB, you can build amazing realtime apps with dramatically less engineering effort.

     

  • What’s in the box?

    Work with your favorite stack

    Query JSON documents with Python, Ruby, Node.js or dozens of other languages. Build modern apps using your favorite web framework, paired with realtime technologies like Socket.io orSignalR.

    Robust architecture

    RethinkDB integrates the latest advances in database technology. It has a modern distributed architecture, a highly-optimized buffer cache, and a state of the art storage engine. All of these components work together to create a robust, scalable, high-performance database.

    Built with love by the open source community

    Developed by a core team of database experts and over 100 contributors from around the world, RethinkDB is shaped by developers like you participating in an open development process.

    Scale your cluster in seconds

    When you’re ready to scale your app, shard and replicate in a few clicks using an intuitive web UI.

    If you need it, a simple API provides precise control over the cluster:

    r.table('games').reconfigure(shards=5, replicas=3)

    Monitor your production cluster with live statistics and complete visibility into running jobs:

    r.db('rethinkdb').table('jobs').changes()

    Learn more go

    Accessing ReQL

    All ReQL queries begin from the top-level module.

    r

    r → r

    The top-level ReQL namespace.

    Example: Set up your top-level namespace.

    var r = require('rethinkdb');
    

    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.

    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')
    

    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 →

    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.

    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) { ... })
    

    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. This allows you to listen for changes in connection state.

    Read more about this command →

    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.

    Example: Let’s process all the elements!

    cursor.each(function(err, row) {
        if (err) throw err;
        processRow(row);
    });
    

    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()

    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()
    

    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][ee].

    Read more about this command →

    Manipulating databases

    dbCreate

    r.dbCreate(dbName) → object

    Create a database. A RethinkDB database is a collection of tables, similar to relational databases.

    If successful, the operation returns an object: {created: 1}. If a database with the same name already exists the operation throws ReqlRuntimeError.

    Note: that you can only use alphanumeric characters and underscores for the database name.

    Example: Create a database named ‘superheroes’.

    r.dbCreate('superheroes').run(conn, callback)
    

    dbDrop

    r.dbDrop(dbName) → object

    Drop a database. The database, all its tables, and corresponding data will be deleted.

    If successful, the operation returns the object {dropped: 1}. If the specified database doesn’t exist aReqlRuntimeError is thrown.

    Example: Drop a database named ‘superheroes’.

    r.dbDrop('superheroes').run(conn, callback)
    

    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]) → objectr.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)
    

    Read more about this command →

    tableDrop

    db.tableDrop(tableName) → object

    Drop a table. 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)
    

    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)
    

    indexCreate

    table.indexCreate(indexName[, indexFunction][, {multi: false, geo: false}]) → object

    Create a new secondary index on a table.

    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)
    

    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)
    

    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 isfalse (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)
    

    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)
    

    Example: Get the status of the timestamp index:

    r.table('test').indexStatus('timestamp').run(conn, callback)
    

    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)
    

    Example: Wait for the index timestamp to be ready:

    r.table('test').indexWait('timestamp').run(conn, callback)
    

    changes

    stream.changes({squash: false, includeStates: false}) → streamsingleSelection.changes({squash: false, includeStates: false}) → stream

    Return a changefeed, an infinite stream of objects representing changes to a query. A changefeed may return changes to a table or an individual document (a “point” changefeed), and document transformation commands such as filter or map may be used before the changes command to affect the output.

    Example: Subscribe to the changes on a table.

    r.table('games').changes().run(conn, function(err, cursor) {
      cursor.each(console.log)
    })
    

    Read more about this command →

    Writing data

    insert

    table.insert(object | [object1, object2, …][, {durability: “hard”, returnChanges: false, conflict: “error”}]) → object

    Insert JSON documents into a table. Accepts a single JSON 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}]) → objectselection.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. You can pass options like returnChanges that will return the old and new values of the row you have modified.

    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}]) → objectselection.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}]) → objectselection.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

    Select all documents in a table. This command can be chained with other commands to do further processing on the data.

    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.

    If no document exists with that primary key, get will return null.

    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_slicetable_slice.between(lowerKey, upperKey[, options]) → table_slice

    Get all documents between two keys. Accepts three optional arguments: index, left_bound, andright_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_boundmay 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).

    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}]) → selectionstream.filter(predicate_function[, {default: false}]) → stream

    array.filter(predicate_function[, {default: false}]) → array

    Get all the documents for which the given predicate is true.

    filter can be called on a sequence, selection, or a field containing an array of elements. The return type is the same as the type on which the function was called on.

    The body of every filter is wrapped in an implicit .default(false), which means that if a non-existence errors is thrown (when you try to access a field that does not exist in a document), RethinkDB will just ignore the document. The default value can be changed by passing an object with a default field. Setting this optional argument to r.error() will cause any non-existence errors to return a ReqlRuntimeError.

    Example: Get all the users that are 30 years old.

    r.table('users').filter({age: 30}).run(conn, callback)
    

    Read more about this command →

    Joins

    These commands allow the combination of multiple sequences into a single sequence

    innerJoin

    sequence.innerJoin(otherSequence, predicate_function) → streamarray.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) → streamarray.outerJoin(otherSequence, predicate_function) → array

    Returns a left outer join of two sequences.

    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)
    

    Read more about this command →

    eqJoin

    sequence.eqJoin(leftField, rightTable[, {index:’id’}]) → sequencesequence.eqJoin(predicate_function, rightTable[, {index:’id’}]) → 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.

    r.table('players').eqJoin('gameId', r.table('games')).run(conn, callback)
    

    Read more about this command →

    zip

    stream.zip() → streamarray.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

    These commands are used to transform data in a sequence.

    map

    sequence1.map([sequence2, …], function) → streamarray1.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…]) → streamarray.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.

    r.table('users').withFields('id', 'username', 'posts').run(conn, callback)
    

    Read more about this command →

    concatMap

    stream.concatMap(function) → streamarray.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_sliceselection.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).

    Sorting without an index requires the server to hold the sequence in memory, and is limited to 100,000 documents (or the setting of the arrayLimit option for run). Sorting with an index can be done on arbitrarily large tables, or after a between command using the same index.

    Example: Order all the posts using the index date.

    r.table('posts').orderBy({index: 'date'}).run(conn, callback)
    

    The index must have been previously created with indexCreate.

    r.table('posts').indexCreate('date').run(conn, callback)
    

    You can also select a descending ordering:

    r.table('posts').orderBy({index: r.desc('date')}).run(conn, callback)
    

    Read more about this command →

    skip

    sequence.skip(n) → streamarray.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)
    

    limit

    sequence.limit(n) → streamarray.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)
    

    slice

    selection.slice(startIndex[, endIndex, {leftBound:’closed’, rightBound:’open’}]) → selectionstream.slice(startIndex[, endIndex, {leftBound:’closed’, rightBound:’open’}]) → stream

    array.slice(startIndex[, endIndex, {leftBound:’closed’, rightBound:’open’}]) → array

    binary.slice(startIndex[, endIndex, {leftBound:’closed’, rightBound:’open’}]) → binary

    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)
    

    nth

    sequence.nth(index) → objectselection.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)
    

    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)
    

    union

    stream.union(sequence[, sequence, …]) → streamarray.union(sequence[, sequence, …]) → array

    Merge two or more sequences. (Note that ordering is not guaranteed by union.)

    Example: Construct a stream of all heroes.

    r.table('marvel').union(r.table('dc')).run(conn, callback);
    

    sample

    sequence.sample(number) → selectionstream.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

    These commands are used to compute smaller values from large sequences.

    group

    sequence.group(field | function…, [{index: <indexname>, multi: false}]) → grouped_stream

    Takes a stream and partitions it into multiple groups based on the fields or functions provided. Commands chained after group will be called on each of these grouped sub-streams, producing grouped data.

    Example: What is each player’s best game?

    r.table('games').group('player').max('points').run(conn, callback)
    

    Read more about this command →

    ungroup

    grouped_stream.ungroup() → arraygrouped_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)
    

    Read more about this command →

    reduce

    sequence.reduce(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)
    }).run(conn, callback);
    

    Read more about this command →

    count

    sequence.count([value | predicate_function]) → numberbinary.count() → number

    Count the number of elements in the sequence. With a single argument, count the number of elements equal to it. If the argument is a function, it is equivalent to calling filter before count.

    Example: Just how many super heroes are there?

    r.table('marvel').count().add(r.table('dc').count()).run(conn, callback)
    

    Read more about this command →

    sum

    sequence.sum([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

    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) → elementsequence.min({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) → elementsequence.max({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() → arraytable.distinct([{index: <indexname>}]) → stream

    Remove duplicate elements from the 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

    Returns whether or not a sequence contains all the specified values, or if functions are provided instead, returns whether or not a sequence contains values matching all the specified functions.

    Example: Has Iron Man ever fought Superman?

    r.table('marvel').get('ironman')('opponents').contains('superman').run(conn, callback)
    

    Read more about this command →

    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…]) → streamarray.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…]) → streamarray.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, …]) → objectobject.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.

    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)
    

    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)
    

    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)
    

    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)
    

    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)
    

    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)
    

    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)
    

    () (bracket)

    sequence(attr) → sequencesingleSelection(attr) → value

    object(attr) → value

    array(index) → value

    Get a single field from an object or a single element from a sequence.

    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) → sequencesingleSelection.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)
    

    hasFields

    sequence.hasFields([selector1, selector2…]) → streamarray.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(index, 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)
    

    spliceAt

    array.spliceAt(index, 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)
    

    deleteAt

    array.deleteAt(index [,endIndex]) → array

    Remove one or more elements from an array at a given index. Returns the modified array.

    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(index, 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)
    

    keys

    singleSelection.keys() → arrayobject.keys() → array

    Return an array containing all of the object’s keys.

    Example: Get all the keys of a row.

    r.table('marvel').get('ironman').keys().run(conn, callback)
    

    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.

    r.table('users').get(1).update({ data: r.literal({ age: 19, job: 'Engineer' }) }).run(conn, callback)
    

    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]]).coerce_to('OBJECT').

    Example: Create a simple object.

    r.object('id', 5, 'data', ['foo', 'bar']).run(conn, callback)
    

    String manipulation

    These commands provide string operators.

    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”.

    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.)

    Mimics the behavior of Python’s string.split in edge cases, except for splitting on the empty string, which instead produces an array of single-character strings.

    Example: Split on whitespace.

    r.expr("foo  bar bax").split().run(conn, callback)
    

    Read more about this command →

    upcase

    string.upcase() → string

    Uppercases a string.

    Example:

    r.expr("Sentence about LaTeX.").upcase().run(conn, callback)
    

    downcase

    string.downcase() → string

    Lowercases a string.

    Example:

    r.expr("Sentence about LaTeX.").downcase().run(conn, callback)
    

    Math and logic

    add

    value.add(value[, value, …]) → valuetime.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)
    

    Read more about this command →

    sub

    number.sub(number[, number, …]) → numbertime.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, …]) → numberarray.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)
    

    mod

    number.mod(number) → number

    Find the remainder when dividing two numbers.

    Example: It’s as easy as 2 % 2 = 0.

    r.expr(2).mod(2).run(conn, callback)
    

    and

    bool.and(bool[, bool, …]) → boolr.and(bool[, bool, …]) → bool

    Compute the logical “and” of two 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
    

    or

    bool.or(bool[, bool, …]) → boolr.or(bool[, bool, …]) → bool

    Compute the logical “or” of two 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
    

    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);
    

    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);
    

    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);
    

    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);
    

    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);
    

    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);
    

    not

    bool.not() → boolnot(bool) → bool

    Compute the logical inverse (not) of an expression.

    not can be called either via method chaining, immediately after an expression that evaluates as a boolean value, or by passing the expression as a parameter to not.

    Example: Not true is false.

    r(true).not().run(conn, callback)
    r.not(true).run(conn, callback)
    

    Read more about this command →

    random

    r.random() → numberr.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) → numbernumber.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);
    
    12.0
    

    ceil

    r.ceil(number) → numbernumber.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);
    
    13.0
    

    floor

    r.floor(number) → numbernumber.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);
    
    12.0
    

    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)
    

    time

    r.time(year, month, day[, hour, minute, second], timezone) → time

    Create a time object for a specific time.

    A few restrictions exist on the arguments:

    • year is an integer between 1400 and 9,999.
    • month is an integer between 1 and 12.
    • day is an integer between 1 and 31.
    • hour is an integer.
    • minutes is an integer.
    • seconds is a double. Its value will be rounded to three decimal places (millisecond-precision).
    • timezone can be 'Z' (for UTC) or a string with the format ±[hh]:[mm].

    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)
    

    epochTime

    r.epochTime(epochTime) → 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)
    

    ISO8601

    r.ISO8601(iso8601Date[, {defaultTimezone:”}]) → time

    Create a time object based on an ISO 8601 date-time string (e.g. ‘2013-01-01T01:01:01+00:00’). We support all valid ISO 8601 formats except for week dates. If you pass an ISO 8601 date-time without a time zone, you must specify the time zone with the defaultTimezone argument. Read more about the ISO 8601 format atWikipedia.

    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)
    

    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)
    

    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")
    })
    

    during

    time.during(startTime, endTime[, options]) → bool

    Return if a time is between two other times (by default, inclusive for the start, exclusive for the end).

    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), r.time(2013, 12, 10))
    ).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)
    

    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)
    

    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)
    

    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)
    

    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)
    )
    

    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)
    })
    

    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)
    })
    

    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)
    })
    

    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"
    

    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.

    This is analogous to using apply in JavaScript.

    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)
    

    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) → anyr.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_branch, false_branch) → any

    If the test expression returns false or null, the false_branch will be evaluated. Otherwise, thetrue_branch will be evaluated.

    The branch command is effectively an if renamed due to language constraints. The type of the result is determined by the type of the branch that gets executed.

    Example: Return heroes and superheroes.

    r.table('marvel').map(
        r.branch(
            r.row('victories').gt(100),
            r.row('name').add(' is a superhero'),
            r.row('name').add(' is a hero')
        )
    ).run(conn, callback)
    

    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)
    

    range

    r.range() → streamr.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)
    
    [0, 1, 2, 3]
    

    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)
    

    default

    value.default(default_value | function) → anysequence.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 ornull, 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’) → arrayvalue.coerceTo(‘string’) → string

    string.coerceTo(‘number’) → number

    array.coerceTo(‘object’) → object

    object.coerceTo(‘array’) → array

    binary.coerceTo(‘string’) → string

    Convert a value of one type into another.

    Example: Coerce a stream to an array.

    r.table('posts').map(function (post) {
        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 value.

    Example: Get the type of a string.

    r.expr("foo").typeOf().run(conn, callback)
    

    info

    any.info() → objectr.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)
    

    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)
    

    toJsonString, toJSON

    value.toJsonString() → stringvalue.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"]}'
    

    http

    r.http(url [, options]) → value

    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.

    Example: Perform a simple HTTP GET request, 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

    Return a UUID (universally unique identifier), a string that can be used as a unique ID.

    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}]) → geometryr.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’}]) → numberr.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’]}) → selection<array>

    Get all documents where the specified geospatial index is within a certain distance of the specified point (default 100 kilometers).

    Example: Return a list of enemy hideouts within 5000 meters of the secret base.

    var secretBase = r.point(-122.422876,37.777128);
    r.table('hideouts').getNearest(secretBase,
        {index: 'location', maxDist: 5000}
    ).run(conn, callback)
    

    Read more about this command →

    includes

    sequence.includes(geometry) → sequencegeometry.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) → sequencegeometry.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, lat1], …) → liner.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 longitude and latitude 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 the latitude (−90 to 90) of the point on a perfect sphere.

    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], …) → polygonr.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 longitude and latitude 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 withinpolygon1 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);
    

    Read more about this command →

    Administration

    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() → objectdatabase.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}]) → objectdatabase.reconfigure({shards: <s>, replicas: <r>[, primaryReplicaTag: <t>, 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: ‘ready_for_writes’, timeout: <sec>}]) → objectdatabase.wait([{waitFor: ‘ready_for_writes’, timeout: <sec>}]) → object

    r.wait([{waitFor: ‘ready_for_writes’, 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 for a table to be ready.

    > r.table('superheroes').wait().run(conn, callback);
    
    
    
    

    Get more help

    We always welcome suggestions on how to improve our documentation, or specific ReQL questions.

     
     Source : https://www.rethinkdb.com
  • Ask Question