When will rethinkdb return a cursor

Question

I notice that r.table('xxx') not always return a cursor but also sometimes just return docs directly

1. Is the cursor client side implementation only or there are some special things server did to perform queries associate with a cursor?

2. If it has somethings related to server, what is it and when will I receive a cursor

For example I specify result offset and size with skip and limit in the query. Will server return a cursor or just result docs?

Answer 1

A driver returns a cursor when the query returns a stream.

Basically when the server produces a stream (a sequence that is lazily computed), the driver will return a cursor. As you fetch rows from the cursor, the server will compute more elements in the sequence.

For example, when you run r.table('xxx'), you will get back a cursor. The server will load the documents from disk as you request them with the driver.

In the JavaScript driver, when a query return an array, the driver will sneak an object that mimics the cursor interface between the arrray itself and Array.prototype. So if query.run(...) returns a sequence, you can just do

query.run(connection).then(function(result) {
    return result.toArray()
}).then(function(result) {
    // do something with result
}).error(function(err) {
    // handle err
})

Basically if you don't want to think if you are getting back a cursor or an array, you can just consider that it's a cursor.

You can read more about stream/cursor here:
http://www.rethinkdb.com/docs/data-types/