Let me try to address some of these questions here, before figuring out how to improve the tutorial.
`r`: is the top level ReQL namespace that gives you access to the functions defined
r.db('name'): is accessing the 'test' database. RethinkDB supports multiple databases. You can specify which one to use on a per connection basis or for each query.
The 'test' database is a default database (in principle it's similar to MySQL's test database). Being the default also means that you don't need to use `.db('test')` in each query.
`run`: ReQL allows chaining multiple functions together. Basically creating a query is a bit like using a builder pattern. These chained ops are all sent to the server and executed on the database. There is a single roundtrip. Basically `run` tells the query builder: "now it's your time to do something for me".
As side comments
1. initially we added much more details about each query, but we ended up with quite a bit of text compared to short queries. We thought it would be more intuitive the reduce the description part and provide links to the API. It looks like that wasn't the best solution.
2. we chose to have the query pre-typed instead of having it part of the description only as we assumed mostly everyone would just copy paste it. Assumption proved incorrect!
Thanks a lot!
alex @ rethinkdb