Wrap Up

We now have some basic understanding:

1 1. ReQL always starts with `r`.\n2 2. ReQL is tie to your language depend on language driver.\n3 3. Default database\n4 3. Find an document by its primary\n5 4. Access table data and filter data by some condition\n6 5. Access nested field\n

\n\n

We will learn more about advanced query in other chapter. For now, let’s move on\nand try to write some data into RethinkDB.

",{"_235":236,"_43":44,"_47":48,"_45":46,"_65":66,"_237":238,"_275":233},"previewContent","

\n 1. Welcome\n
- \n Introduction\n
- \n Why learn RethinkDB?\n
- \n Feedback\n
- \n Credit\n
\n
\n 2. Getting to know RethinkDB\n
- \n Getting Started\n
  - \n The Ports\n
  - \n The dashboard\n
  \n
- \n RethinkDB object\n
- \n Durability\n
- \n Atomicity\n
- \n Command line tool\n
  - \n import\n
  - \n export\n
  - \n dump\n
  - \n restore\n
  \n
- \n Import sample data\n
\n
\n 3. Reading Data Basic\n
- \n Getting to Know ReQL\n
- \n Drivers\n
  - \n Using drivers\n
  - \n Default database\n
  - \n Repl\n
  \n
- \n Data Type\n
  - \n Basic data type\n
  - \n Composite data type\n
  - \n Sorting data\n
  \n
- \n Selecting data\n
  - \n Select the whole table\n
  - \n Select a single document by its primary key\n
  - \n Select many documents by value of fields\n
  - \n r.row\n
  - \n Pagination data\n
  - \n Access Nested field\n
  \n
- \n Wrap Up\n
\n

1. Welcome

\n\n

Introduction

\n\n

Welcome to my readers. I appreciate your purchase. This will help me continue\nimproving the book content.

\n\n

Before we go into the technical details, I have something to say.

\n\n

Firstly, I’m not a RethinkDB expert at all. I’m just an average guy who loves\nprogramming and new technologies. To me, RethinkDB is a pleasure to use.\nHowever, due to its age, there are not many books and documents about it comparing to other\ndatabase systems. While the RethinkDB cocumentation and API is very good, it can be hard to know \nwhere to start. So this guide is for all those in mind who are unsure about taking the plunge into\nRethinkDB as something totally new. I hope this helps them ease into the learning process.

\n\n

The purpose of this book is to organize the concepts of RethinkDB in order to help you to\nread and understand the RethinkDB API directly. Upon finishing the book, you will have a foundational\nknowledge in which to extend your knowledge with many other RethinkDB videos and blog posts out on the \nInternet.

\n\n

Secondly, I’m a fan of Mixu’s¹ writing style². I won’t cover\ndeeply things like installing RethinkDB, fine-tuning, extra function parameters, and so on. \nThose topics are covered very well on RethinkDB’s documention itself. What I want you to take away from this book\nis a good grasp on RethinkDB usage in practice. and how to apply commands in real scenarios.

\n\n

Third, I’m not fluent in English. If you find any mistakes, you can report the\nissue on repository or email me directly.

\n\n

Fourth, RethinkDB is changing so fast that things in this book may not reflect\nits current state. Once again, I’d be very grateful for any errata you may point out, via my email or Github. \nSince this is a LeanPub book, once I update you may download it again free of charge.

\n\n

And finally, due to my limited knowledge with RethinkDB, I want to keep this book short and straight to the point. \nExpect a book of around 200 pages. My goal is for this to be a book that you can pick up, read on the train while riding to work and after a week you can sit down and actually start your first RethinkDB project without hesitation.

\n\n

http://blog.mixu.net/↩\n
http://blog.mixu.net/2012/07/26/writing-about-technical-topics-like-its-2012/↩\n

\n\n\n

Why learn RethinkDB?

\n\n

RethinkDB is mind-blowing to me. I like the beauty and nature of ReQL which is\nbuilt into the language. It is also very developer friendly with its own\nadministrator UI. RethinkDB is very easy to learn, because its query language is\nnatural to how we think when constructing a query. We can easily tell what ReQL will do\nand what is the execution order of the query.

\n\n

Take this SQL query:

\n\n

1 SELECT * FROM users WHERE name=\"Vinh\" ORDER BY id DESC LIMIT 10,100\n

\n\n\n\n

This query is passed as a string and occaisionally you may sometimes forget the ordering or syntax. \nWill we put **ORDER** before or after **LIMIT**? Where the WHERE clause should appear?\nWe also can’t be certain if an index will be used. Because SQL is a string, the order\nof execution is defined by the syntax. Memorizing that syntax is essential.

\n\n

Compare this with ReQL (RethinkDB Query Language):

\n\n

1 r.table('users').getAll('vinh', {index: 'name'}).order_by(r.desc(id)).limit(10)\n

\n\n\n\n

We can easily ascertain (or ‘grok’) immediately what will result from this query, \nand the order of execution is clear to us. This is because the methods are chained, one after another,\nfrom left too right. ReQL was designed with the intention of a very clear API but without the\nambiguity that comes with an ORM.

\n\n

We can also see that it will use an index **name** when finding data. The way\nthe query is constructed, feels similiar to jQuery if you are a front-end\ndeveloper who never works with databases. Or if you are a functional programming person,\nyou probably see the similarity immediately.

\n\n

If the above example hasn’t convinced you, then check this out:

\n\n

1 SELECT *\n2 FROM foods as f\n3 INNER JOIN compounds_foods as c ON c.food_id=f.id\n4 WHERE f.id IN (10, 20)\n5 ORDER By f.id DESC, c.id ASC\n

\n\n\n\n

The same query represented as ReQL would look like this:

\n\n

1 r.db(\"food\")\n2   .table(\"foodbase\")\n3   .filter(function (food) {\n4     return r.expr([10, 20]).contains(food(\"id\"))\n5   })\n6   .eqJoin(\"id\", r.db(\"foodbase\").table(\"compound_foods\"), {index: \"food_id\"})\n

\n\n\n\n

Even if you are not completely familar with the syntax, you can guess what is going to happen. \nIn ReQL, we are taking the foodbase database, and table foods, and filtering them and \nfiltering the result with another table called compound_foods. Within the filter, we pass \nan anonymous function which determines if the “id” field of document is contained in the array \n[10, 20]. If it is either 10 or 20 then we join the results with the compound_foods \ntable based on the id field and use an index to efficiently search. \nThe query looks like a chain of API call and the order of execution is clear to the reader.

\n\n

RethinkDB really makes me rethink how we work with database. I don’t\nhave to write a query in a language that I don’t like. As well, I’m no longer forced\nto use a syntax that I don’t like because I have no choice. And further, if something does\ngo wrong, I don’t have to slowly tear apart the entire string to find out which clause has\nthe issue. The resulting error from a ReQL query allows me to more precisely determine the cause of \nerror.

\n\n

Furthermore, RethinkDB is explicit. Later on, you will also learn that in RethinkDB you\nhave to explicitly tell it to do some not-very-safe operations. Such as when a\nnon-atomic update is required, you clearly set a flag to do it. RethinkDB by default has sensible\nand conservative settings as a database should to help you avoid shooting yourself in the foot.

\n\n

In my opinion, RethinkDB forces us to understand what we are doing. Everything is\nexposed on the query. No magic, no “why did this query fail on production but\nwork as expected on my local machine”, no hidden surprises.

\n\n

In Vietnamese culture, we usually follow a rule of three in demonstrations before we conclude. \nBeing Vietnamese, let me end by showing you this third example.

\n\n

Do you understand the query below?

\n\n

1 r\n2   .db('foodbase')\n3   .table('foods')\n4   .filter(r.row('created_at').year().eq(2011))\n

\n\n\n\n

This query finds all foods which were inserted in the year 2011. I\ncannot even provide an equivalent SQL example, because it just cannot be as beautiful\nand concise as the above query.

\n\n

Feedback

\n\n

I appreciate all of your feedbacks to improve this book. Below is my handle on internet:

\n\n

twitter: http://twitter.com/kureikain\n
email: kurei@axcoto.com\n
twitter book hashtag: #simplyrethinkdb

\n\n

Credit

\n\n

Sample dataset: foodb.ca/foods\n
Book cover: Design by my friend, aresta.co helps to create the cover for this book

\n\n

2. Getting to know RethinkDB

\n\n

Let’s warm up with some RethinkDB concepts, ideas and tools. In this chapter, thing\nmay a bit confuse because sometime to understand concept A, you need to\nunderstand B. To understand B, you need C, which is based on A. So plese\nuse your feeling and don’t hestitate to do some quick lookup on offical\ndocs to clear thing out a bit.

\n\n

From now on, we will use term ReQL to mean anything related to RethinkDB\nquery language, or query API.

\n\n

Getting Started

\n\n

It’s not uncommon to see someone write an interactive shell in browser for\nevaluation purpose such as mongly, tryRedis. This isn’t applied for RethinkDB\nbecause it comes with an excellent editor where you can type code and run it.

\n\n

Install RethinkDB by downloading package for your platform http://rethinkdb.com/docs/install/.\nRun it after installing.

\n\n

The Ports

\n\n

By default, RethinkDB runs on 3 ports

\n\n

8080: this is the web user interface of RethinkDB or the dashboard. You can query\nthe data, check performance and server status on that UI.
28015: this is the client drive port. All client drive will connect to RethinkDB\nthrough this port. If you remember in previous chapter, we used a tcpdump\ncommand to listen on this port to capture data send over it.
29015: this is intracluster port; different RethinkDB node in a cluster communicates\nwith eath others via this port

\n\n

The dashboard

\n\n

Open your browser at http://127.0.0.1:8080 and welcome RethinkDB. You can play\naround to see what you have:

\n\n

Navigate to the Explorer tab, you can type the command from there. Let’s start\nwith

\n\n

1 r.dbList()\n

\n\n\n\n

Run it and you can see a list of database.

\n\n

RethinkDB object

\n\n

Similar to traditonal database system, we also have database in RethinkDB. A\ndatabase contains many tables. Each table contains your JSON document. Those\nJSON document can contains any fields. A table doesn’t force a schema for those\nfields.

\n\n

A JSON document is similar to a row in MySQL. Each of field in the document is\nsimilar to column in MySQL. When I say JSON document, I mean an JSON object\nwith fields, not a single number, an array or a string. However, each field\ncan content whatever JSON data type.

\n\n

More than that, the same field can accept whatever data type. On same table,\ntwo document can contains diferent data type for same field.

\n\n

Durability

\n\n

You will see an option/argument call durability *durability appear a lot\nin many option of ReQL. Because it’s so common and it’s very important, I\nwant to address it here. Durability accepts value of ‘soft’ or ‘hard’.

\n\n

soft: means the writes will be acknowledge by server immdediately and data will be flushed to disk in\nbackground.
hard: The opposite of soft. The default behaviour is to acknowledge after data is written to disk.\nTherefore, when you don’t need the data to be consitent, such as\nwriting a cache, or an important log, you should set durability to soft in order to\nincrease speed

\n\n

Atomicity

\n\n

According to RethinkDB docs [^atomic], write atomicity is supported on a per-document basis. So when you write to a single document, it’s either succesfully or nothing orrcur instead of updating a couple field and leaving your data in a bad shape. Furthermore, RethinkDB guarantees that any combination of operation can be executed in a single document will be write atomically.

\n\n

However, it does comes with a limit. To quote RethinkDB doc, Operations that cannot be proven deterministic cannot update the document in an atomic way. That being said, the unpredictable value won’t be atomic. Eg, randome value, operation run by using JavaScript expression other than ReQL, or values which are fetched from somewhere else. RethinkDB will throw an error instead of silently do it or ignore. You can choose to set a flag for writing data in non-atomic way.

\n\n

Multiple document writing isn’t atomic.

\n\n

[^atomic] http://www.rethinkdb.com/docs/architecture/#how-does-the-atomicity-model-work

\n\n

Command line tool

\n\n

Besides the dashboard, RethinkDB gives us some command line utility to\ninteractive with it. Some of them are:

\n\n

import
export
dump
restore

\n\n

import

\n\n

In the spirit of giving users the dashboard, RethinkDB also gives us some sample data.\nYou can download the data in file input_polls and country_stats at \nhttps://github.com/rethinkdb/rethinkdb/tree/next/demos/election and import them into\ntest database

\n\n

1 rethinkdb import -c localhost:28015 --table test.input_polls --pkey uuid -f inpu\\\n2 t_polls.json --format json\n3 rethinkdb import -c localhost:28015 --table test.county_stats --pkey uuid -f cou\\\n4 nty_stats.json --format json\n

\n\n\n\n

Notice the --table argument, we are passing the table name in format of\ndatabase_name.*table_name”. In our case, we import the data into two tables:\ninput_polls and county_stats inside database test.

\n\n

Basically you can easily import any file contains a valid JSON document.

\n\n

export

\n\n

export exports your database into many JSON files, each file is a table. The\nJSON file can be import using above import command.

\n\n

dump

\n\n

dump will just export whole of data of a cluster, it’s similar to an export\ncommand, then follow by gzip to compress all JSON output file. Syntax is as\neasy as.

\n\n

1 rethinkdb dump -c 127.0.0.1:28015\n

\n\n\n\n

Here is an example output when I run this command:

\n\n

 1 rethinkdb dump -c 127.0.0.1:28015\n 2 NOTE: 'rethinkdb-dump' saves data and secondary indexes, but does *not* save\n 3  cluster metadata.  You will need to recreate your cluster setup yourself after\n 4  you run 'rethinkdb-restore'.\n 5 Exporting to directory...\n 6 [========================================] 100%\n 7 764509 rows exported from 9 tables, with 21 secondary indexes\n 8   Done (157 seconds)\n 9 Zipping export directory...\n10   Done (5 seconds)\n

\n\n\n\n

The dump result is a gzip file whose name is in format rethinkdb_dump_{timestamp}.tar.gz\nIt’s very useful when you want to try out something and get back your original data. \nNote it here because you will need it later.

\n\n

restore

\n\n

Once we got the dump file with dump command. We can restore with:

\n\n

1 rethinkdb restore -c 127.0.0.1:28015 rethinkdb_dump_DATE_TIME.tar.gz\n

\n\n\n\n

Import sample data

\n\n

It’s much nicer to work with real and fun data than boring data. I found a very\nuseful dataset call FooDB¹. It’s a data about food constituents,\nchemistry and biolog. To quote their about page:

\n\n

\n
What is FooDB\nFooDB is the worldâ€™s largest and most comprehensive resource on food constituents, chemistry and biology. \nIt provides information on both macronutrients and micronutrients, including many of the constituents that give foods their flavor, color, taste, texture and aroma
\n

\n\n

I import their data into RethinkDB, and generate some sample tables such as\nusers table. At the end, I used the dump command to generate sample data\nwhich you can download using below links²

\n\n

https://www.dropbox.com/s/dy48el02j9p4b2g/simplyrethink_dump_2015-08-11T22%3A15%3A51.tar.gz?dl=0.\nOnce you download it, you can import this sample dataset:

\n\n

1 rethinkdb restore -c 127.0.0.1:28015 simplyrethink_dump_2015-08-11T22:15:51.tar.\\\n2 gz\n

\n\n\n\n

The output looks like this:

\n\n

 1 Unzipping archive file...\n 2   Done (1 seconds)\n 3 Importing from directory...\n 4 [                                        ]   0%\n 5 [                                        ]   0%\n 6 [                                        ]   0%\n 7 [                                        ]   0%\n 8 [========================================] 100%\n 9 764509 rows imported in 9 tables\n10   Done (2166 seconds)\n

\n\n\n\n

Once this processing is done, you should have a database call foodb which\ncontains the data we play throught the book. At any point, if you messed up\ndata, you can always restore from this sample data. Also, I encourage to back\nup data if you build many interesting data to experiment yourself.

\n\n

http://foodb.ca/about↩\n
https://www.dropbox.com/s/dy48el02j9p4b2g/simplyrethink_dump_2015-08-11T22%3A15%3A51.tar.gz?dl=0↩\n

\n\n\n

3. Reading Data Basic

\n\n

If you are lazy(just like me) and skip straigh to this chapter, please go back to\nthe end of previous chapter to import sample dataset. Once you did it, let’s start.\nOh, before we start, let me tell you this, sometime if you see an ... it\nmeans, we have more data returning, but I cannot paste them all into the book. I\nused ... to denote for more data available.

\n\n

Getting to Know ReQL

\n\n

RethinkDB uses a special syntax call ReQL to interact with the data. ReQL is\nchainable. You start with a database, chain to table, and chain to other API to\nget what you want, in a way very natural. Type this into data explorer:

\n\n

1 r.db(\"foodb\").table('flavors').filter({'flavor_group': 'fruity'})\n

\n\n\n\n

You should see some interesting data now.

\n\n\n

\"Result — Result of filter command by flavor_group

\n\n\n

Don’t worry about the syntax, just look at it again and even without any\nknowledge you know what it does and easily remember it. A way, for me, to\nunderstand ReQL is that every command return an object which share some API\nwhich we can call those API as if method of an object.

\n\n

ReQL is particular binding to your language. Though, of course, they will look \nfamiliar between different language to maintain consitent look and feel. But, \nthey are different. Those querie are constructed by making function call of your\nlanguage, not by concat SQL String, or not by special JSON object like MongoDB.\nTherefore, it feel very natualy to write ReQL, as if the data we manipulate\nis an object or data type in our language. But everything comes with a trade\noff. On the downside, we have to accept differences of ReQL betweens many\nlanguage. No matter how hard we try, different language has different syntax,\nespecially when it comes to anonymous function.

\n\n

What is r? r is like a special namespace which is all RethinkDB is exposed \nvia it. It’s just a normal variable in your language, or a namespace, a package\nname, a module. Think of r like $ of jQuery. If you don’t like r, assign\nanother variable to it is possible.

\n\n

We will call all method of r, or of any method of return resulted from other\nmethod are command for now. Think of it like a method in jQuery world.

\n\n

Here is example, with this HTML structure:

\n\n

1 <div class=\"db\">\n2   <div class=\"table\" data-type=\"anime\">Haru River</div>\n3   <div class=\"table\" data-type=\"anime\">Bakasara</div>\n4   <div class=\"table\" data-type=\"movie\">James Bond</div>\n5 </div>\n

\n\n\n\n

To filter only anime movie, we can use this jQuery:

\n\n

1 $('.db').find('.table').filter('[data-type=\"anime\"]')\n

\n\n\n\n

If we have a database call db, and a table call table, with 3 records:

\n\n

1 {type: 'anime', title: 'Haru River'}\n2 {type: 'anime', title: 'Bakasara'}\n3 {type: 'movie', title: 'James Bond'}\n

\n\n\n\n

The equavilent ReQL use to find only anime is:

\n\n

1 r.db('db').table('table').filter({type: 'anime'})\n

\n\n\n\n

Notice how similar the structure between them? Because of those concept, I find\nReQL is easy to learn. If you can write jQuery, you can write ReQL.

\n\n

Another way to understand is considering ReQL like the pipe on Linux, you select the data, \npassing into another command:

\n\n

1 $ cd db; ls -la table/* | grep 'type: anime'\n

\n\n\n\n

Drivers

\n\n

This section deep down a bit on how the drivers work, you can skip if you are\nnot interested in how RethinkDB driver works at low level. But I really hope you keep reading it.\nLet’s start.

\n\n

ReQL is binded to your language. Therefore, the API is implemented totally by\nthe driver itself. You won’t work directly with RethinkDB server. You write the\nquery using the API of driver, the driver will built it into a real query to send\nto server, receive data, parse it to return data as a native data of your\nlanguage.

\n\n

Internaly, all client driver will turn the query that you write in driver language\ninto an AST tree, then serialize them as JSON and send to server.

\n\n

If you curious, you can fire up tcpdump and watch the raw query in JSON

\n\n

1 tcpdump -nl -w - -i lo0 -c 500 port 28015|strings\n

\n\n\n\n

An example of what above tcpdump return when I run those command(in Ruby):

\n\n

1 r.db(\"foodb\").table(\"users\").with_fields(\"address\").run\n

\n\n\n\n

Once I ran this command, I see this via tcpdump:

\n\n

[1,[96,[[15,[[14,[“foodb”]],”users”]],”address”]],{}]

\n\n

So basically, the whole query is turned into a special JSON object by client\ndriver. If you would like to dig deeper, the above query is actually translate\nin to this:

\n\n

[QUERY_START, [WITH_FIELDS, [[TABLE, [[DB, [“foodb”]],”users”]],”address”]],{}]

\n\n

Each of numbers is equivalent to a command in RethinkDB. Those number is\npredefined in RethinkDB. So basically, whatever you write using client driver\nAPI will be turn into an JSON array. Each of element often takes this form:

\n\n

1 COMMAND, [Argument Array], {Option object}\n

\n\n\n\n

It’s similar to a function call when we have function name, follow by its argument and the last is an option object.

\n\n

You can quickly sense a downside is that each of driver have different API to\nconstruct query. When you come to another language, you may feel very strange.\nThe driver hide the real query behinds its API. It’s kind of similar to how you\nuse an ORM in SQL world to avoid writing raw SQL string. But it’s different\nbecause the ORM usually has its own API to turn query into raw query string,\nwhich in turns send to server using another driver with that database protocol.\nHere, we are having power of an ORM, but happen at driver level, because\nRethinkDB protocol is a powerful JSON protocol to help model query\nlike function call, with argument and follow by parameter. In fact, ReQL is\nmodeled after functional languages like Lisp or Hashkell.

\n\n

If you would like to know more about ReQL at lower level, you should read more\nin official documents

\n\n

Using drivers

\n\n

RethinkDB supports 3 official drives:

\n\n

Ruby
NodeJS
Python

\n\n

These support all driver specifications.\nThe community drives such as Go, PHP probably won’t support them all, if you\nused a different language and find something isn’t right, it is probably not\nyour fault.

\n\n

All ReQL starts with r, its top level module to expose its public API. In\nNodeJS, we can use

\n\n

1 var r = require('rethinkdb')\n

\n\n\n\n

or Ruby

\n\n

1 require 'rethinkdb'\n2 include RethinkDB::Shortcuts\n3 puts r.inspect\n

\n\n\n\n

or in Go Lang

\n\n

1 import (\n2   r \"github.com/dancannon/gorethink\"\n3 )\n

\n\n\n\n

Once we constructed ReQL with r, we have to call run method to execute it. The\ncommand will be submit to an active database connection. The database connection\ncan be establish with connect.

\n\n

1 var r = require('rethinkdb')\n2 var connection = r.connect({\n3   host: '127.0.0.1', \n4   port: '28015', \n5   db: 'test'\n6 }, function (err, conn) {\n7   r.db('db').table('table').filter({type: 'anime'})\n8 })\n

\n\n\n\n

When creating the connection with r.connect, you can pass an db parameter to\nspecify a default database to work on once connecting succesfully. It’s similar\nto the current database of MySQL. Without setting this parameter, RethinkDB\nassumes test as default database.

\n\n

To understand more about difference of API in different language, let looks at\nGo Lang driver¹

\n\n

Notice that we don’t have any host, or database parameter now. They are\nAddressand Database in Go Lang driver. Therefore, by using an un-official\nlanguage, the API will be totally different with official API.

\n\n

That’s how beautiful it is because each language has its own design philosophy.\nSuch as in Go lang, we cannot have a lower case field of a struct and expect it \npublicly available to outside. Using names such as host or db for connection\noption is impossible in Go lang.

\n\n

Default database

\n\n

Similar to MySQL, when you can issue use database_name to switch to another\ndatabase. We can do that in RethinkDB by calling use command on a connection\nobject.

\n\n

1 connection.use('another_db')\n

\n\n\n\n

In this small book, most of the time, we will use Data Exploer. Therefore \nwe can use r without initialization and calling run method. Data Exploer\nwill do that for us. Just keep in mind when you write code, you have to connect,\nand explicitly call run to, obviously, run the query.

\n\n

Note that you don’t have to switch to another database to access its table, you\ncan just call r.db('another_db') before building query.

\n\n

Repl

\n\n

Repl means read-eval-print loop. To avoid burden of manually call run and passing\nconnection object. Some driver offers a repl to help call run without any parameter.

\n\n

Such as in Ruby:

\n\n

1 r.connect(:db => 'marvel').repl\n2 r.table(\"test\").run\n

\n\n\n\n

JavaScript doesn’t have a repl. I think because we can already used the Data Explorer.

\n\n

\nhttps://github.com/dancannon/gorethink\n
var connection *r.Session
\n\n
connection, err := r.Connect(r.ConnectOpts{\n Address: “localhost:28015”,\n Database: “test”,\n})
\n\n
if err != nil {\n log.Fatalln(err.Error())\n}↩
\n

\n\n\n

Data Type

\n\n

Why do we have to discuss about data type? We use dynamic language and we almost dicuss about\nRuby and JavaScript most of time. But understanding data type allow us to read API document better.\nIt helps us to understand why we can can r.table.insert but we cannot call like r.table.filter().insert.\nAren’t we still selecting data from table, so we should be able to insert data to it?

\n\n

Data type helps us know that we can only call some method on some of data type

\n\n

Each ReQL method can be call on one or many above data types. Take update command, when you browser the API\ndocument, you see

\n\n

1 table.update(json | expr[, {durability: \"hard\", returnVals: false, nonAtomic: fa\\\n2 lse}]) → object\n3 \n4 selection.update(json | expr[, {durability: \"hard\", returnVals: false, nonAtomic\\\n5 : false}]) → object\n6 \n7 singleSelection.update(json | expr[, {durability: \"hard\", returnVals: false, non\\\n8 Atomic: false}]) → object\n

\n\n\n\n

It means the command can be invoked on a table, or selection (eg: first 30\nelement of tables), or a single selection - a document is an example of single\nselection. The behaviour maybe different based on data type, even the\ncommand is same.

\n\n

In RethinkDB, we have several data types. We will focus into those 2 kind for\nnow:

\n\n

Basic data type
Composite data type

\n\n

Basic data type

\n\n

These are usually the native data type in your language too:

\n\n

 1 * Number: any real numbers. RethinkDB uses double precision (64-bit) floating po\\\n 2 int numbers internally\n 3 * String\n 4 * Time: This is native RethinkDB date time type. However, they will be converted\\\n 5  automatically to your native data type in your language by the driver.\n 6 * Boolean: True/False \n 7 * Null: Depend on your language, it can be nil, null,..    \n 8 * Object: any valid JSON object. In JavaScript, it will be a normal object. In R\\\n 9 uby, it can be a hash.\n10 * Array: any valid JSON array.\n

\n\n\n\n

The data type of a field or column can be change. If you assign a number to a\nfield, you can still assign an value with different data type to that same\nfield. So we don’t have a static schema for tables.

\n\n

We have a very useful command to get the type of any vaue. It’s typeOf.\nExample:

\n\n

 1 r.db('foodb').table('foods')\n 2   .typeOf()\n 3 //=>\n 4 \"TABLE\"\n 5 \n 6 r.db('foodb').table('foods')\n 7   .filter(r.row(\"name\").match('A^'))\n 8   .typeOf()\n 9 //=>\n10 \"SELECTION<STREAM>\"\n

\n\n\n\n

It’s seems not very important to understand about data type at first. I really\nhope you should invest some time to use it frequently to understand the data\ntype of a value.

\n\n

To give a story. In MariaDB10.0/MySQL5.6, when data type doesn’t match, an index may not be used.\nLet’s say you have a field name with type VARCHAR(255) when you define it,\nthen you create an index on that column. Query on that column with exact data\ntype will make index kicked in. Let’s come back MySQL a bit.

\n\n

First I insert below records.

\n\n

1 INSERT INTO foods(name) VALUES(\"100\");\n2 Query OK, 1 row affected, 1 warning (0.00 sec)\n

\n\n\n\n

Below query will use index:

\n\n

 1 MariaDB [food]> EXPLAIN SELECT * FROM foods WHERE name=\"100\";\n 2 +------+-------------+-------+-------+---------------------+--------------------\\\n 3 -+---------+-------+------+-------+\n 4 | id   | select_type | table | type  | possible_keys       | key                \\\n 5  | key_len | ref   | rows | Extra |\n 6 +------+-------------+-------+-------+---------------------+--------------------\\\n 7 -+---------+-------+------+-------+\n 8 |    1 | SIMPLE      | foods | const | index_foods_on_name | index_foods_on_name\\\n 9  | 257     | const |    1 |       |\n10 +------+-------------+-------+-------+---------------------+--------------------\\\n11 -+---------+-------+------+-------+\n

\n\n\n\n

But this query won’t:

\n\n

 1 EXPLAIN select * from foods where name = 9;\n 2 MariaDB [food]> EXPLAIN SELECT * FROM foods WHERE name=100;\n 3 +------+-------------+-------+------+---------------------+------+---------+----\\\n 4 --+------+-------------+\n 5 | id   | select_type | table | type | possible_keys       | key  | key_len | ref\\\n 6  | rows | Extra       |\n 7 +------+-------------+-------+------+---------------------+------+---------+----\\\n 8 --+------+-------------+\n 9 |    1 | SIMPLE      | foods | ALL  | index_foods_on_name | NULL | NULL    | NUL\\\n10 L |  890 | Using where |\n11 +------+-------------+-------+------+---------------------+------+---------+----\\\n12 --+------+-------------+\n13 1 row in set (0.00 sec)\n

\n\n\n\n

When we pass string ‘9’, the index is used. When we pass number 9, the index\nisn’t used.

\n\n

Of if you have a date time column and you passing time as string, the index\nwon’t kicked in either.

\n\n

The lesson here is we aboslutely should understand about data type.

\n\n

Composite data type

\n\n

We have 3 composite data types.

\n\n

Streams

\n\n

:are list or array, but they’re loaded in a lazy fashion. Instead of returning\na whole array at once, meaning all data are read into memory, a cursor is return.\nA cursor is a pointer into the result set. We can loop over cursor to read data\nwhen we need. Imagine instead of an array, and loop over it, you know iterate\nover the cursor to get next value. It allows you to iterator over a data set\nwithout building an entire array in memory. It’s equivalent to PHP iterator, or\nRuby iterator, or JavaScript iterator. Stream allows us access current element\nand keep track of current position so\nthat we can, ideally\ncall next() on a cursor to move to next element, until we reach to the end\nof array, it returns nil and iterator can stop. Because of that, we can work\nwith large data set because RethinkDB doesn’t need to load all of data and\nreturn to client. The nature of stream make it read-only, you cannot change\nthe data while iterating over it.

\n\n

Selections

\n\n

:represent subsets of tables, for example, the return values of filter or get.\nThere are two kinds of selections, Selection<Object> and Selection<Stream>,\nwhich behave like objects or streams respectively. The difference between\nselections and objects/streams are that selections are writable –their return values\ncan be passed as inputs to ReQL commands that modify the database. For instance, the\nget command will return a Selection<Object> that could then be passed to an\nupdate or delete command. We can think of selection like an array\nwhere each element keeps an reference back to real document so that we can modify\nthem.

\n\n

Tables

\n\n

:are RethinkDB database tables. They behave like selections. However, they’re writable,\nas you can insert and delete documents in them. ReQL methods that use an index, like getAll,\nare only available on tables. Because index are created on table level.

\n\n

In short, you cannot modify streams, you can update or change value of selection\nbut you cannot remove existed document, or insert new one. Tables allows you\ninsert new document or remove existed one.

\n\n\n\n

Remember data types seems not much important but you should understand them\nwell because it helps us understand the efficient of a query. If a query\nreturns an array, it consumes lot of memory to hold the array.

\n\n

Sorting data

\n\n

When talking about data type, let think of how we sort them. It really doesn’t\nmatter in the order, what is important is the definition of sorting data.

\n\n

Understanding sorting is important in RethinkDB because of its schemaless. The primary key may not\nbe a numeric field, it can be a string. Moreover than that, a field can have\nwhatever data type, how are we going to compare an object to a string when\nsorting.

\n\n

Here is sorting order:

\n\n

Arrays (and strings) sort lexicographically. Objects are coerced to arrays before sorting. Strings are sorted by UTF-8 codepoint and do not support Unicode collations.

\n\n

Mixed sequences of data sort in the following order:

\n\n

arrays
booleans
null
numbers
objects
binary objects
geometry objects
times
strings

\n\n

That mean array < booleans < null < numbers < objects < binary objects < geometry objects < times < strings.

\n\n

Selecting data

\n\n

In this section, we will learn how to get data out of RethinkDB. Most of the\ntime, we will choose a db to work with, and chain into command table.

\n\n

Select the whole table

\n\n

Let’s find all foods. This is same as SELECT * FROM foods in SQL.

\n\n

 1 r.db('foodb').table('foods')\n 2 //=>\n 3 \n 4 [{\n 5     \"created_at\": Wed Feb 09 2011 00: 37: 17 GMT - 08: 00,\n 6     \"creator_id\": null,\n 7     \"description\": null,\n 8     \"food_group\": \"Herbs and Spices\",\n 9     \"food_subgroup\": \"Spices\",\n10     \"food_type\": \"Type 1\",\n11     \"id\": 43,\n12     \"itis_id\": \"29610\",\n13     \"legacy_id\": 46,\n14     \"name\": \"Caraway\",\n15     \"name_scientific\": \"Carum carvi\",\n16     \"picture_content_type\": \"image/jpeg\",\n17     \"picture_file_name\": \"43.jpg\",\n18     \"picture_file_size\": 59897,\n19     \"picture_updated_at\": Fri Apr 20 2012 09: 38: 36 GMT - 07: 00,\n20     \"updated_at\": Fri Apr 20 2012 16: 38: 37 GMT - 07: 00,\n21     \"updater_id\": null,\n22     \"wikipedia_id\": null\n23 }, {\n24     \"created_at\": Wed Feb 09 2011 00: 37: 18 GMT - 08: 00,\n25     \"creator_id\": null,\n26     \"description\": null,\n27     \"food_group\": \"Herbs and Spices\",\n28     \"food_subgroup\": \"Spices\",\n29     \"food_type\": \"Type 1\",\n30     \"id\": 67,\n31     \"itis_id\": \"501839\",\n32     \"legacy_id\": 73,\n33     \"name\": \"Cumin\",\n34     \"name_scientific\": \"Cuminum cyminum\",\n35     \"picture_content_type\": \"image/jpeg\",\n36     \"picture_file_name\": \"67.jpg\",\n37     \"picture_file_size\": 73485,\n38     \"picture_updated_at\": Fri Apr 20 2012 09: 32: 32 GMT - 07: 00,\n39     \"updated_at\": Fri Apr 20 2012 16: 32: 33 GMT - 07: 00,\n40     \"updater_id\": null,\n41     \"wikipedia_id\": null\n42 },\n43 ...\n44 ]\n

\n\n\n\n

You should get back an array of JSON object. By default, the data explorer will\nautomatically paginate it and display a part of data.

\n\n

Typing r.db(db_name) all the time is insane. We can drop it to use r.table()\nwithout calling r.db() if the table is in current selected database. Without \nany indication, the default database is test. On Data Exploer, without a \nr.db command, RethinkDB will use test as default database. Unfortunately we\ncannot set a default database with data exploer¹

\n\n

Counting

\n\n

We can also count the table or any sequence by calling count command.

\n\n

1 r.db('foodb').table('foods').count()\n2 //=>\n3 863\n

\n\n\n\n

Select a single document by its primary key

\n\n

To select a single element, we call get on a table, and passing its primary\nkey value.

\n\n

 1 r.db('foodb').table('foods')\n 2   .get(108)\n 3 //=>\n 4 {\n 5     \"created_at\": Wed Feb 09 2011 00: 37: 20 GMT - 08: 00,\n 6     \"creator_id\": null,\n 7     \"description\": null,\n 8     \"food_group\": \"Herbs and Spices\",\n 9     \"food_subgroup\": \"Herbs\",\n10     \"food_type\": \"Type 1\",\n11     \"id\": 108,\n12     \"itis_id\": \"32565\",\n13     \"legacy_id\": 115,\n14     \"name\": \"Lemon balm\",\n15     \"name_scientific\": \"Melissa officinalis\",\n16     \"picture_content_type\": \"image/jpeg\",\n17     \"picture_file_name\": \"108.jpg\",\n18     \"picture_file_size\": 30057,\n19     \"picture_updated_at\": Fri Apr 20 2012 09: 33: 54 GMT - 07: 00,\n20     \"updated_at\": Fri Apr 20 2012 16: 33: 54 GMT - 07: 00,\n21     \"updater_id\": null,\n22     \"wikipedia_id\": null\n23 }\n

\n\n\n\n

Every document in RethinkDB includes a primary key field, its value is\nunique across cluster and is used to identify the document. The name of primary \nfield is id by default. However, when you create a table, you have an option \nto change name of primary field. We will learn more about it later. Just keep a\nnote here.

\n\n

In RethinkDB, using of incremental primary key isn’t recommended because that’s\nhard in a cluster environment. To make sure\nthe uniqueness of the new value, We have to check in every clusters\nsomehow. RethinkDB team decides² to use an universal unique³ id instead of an\nincremental value.

\n\n

get command returns the whole document. What if we get a single field? Such\nas we only care about name? RethinkDB has a command call bracket for that\npurpose. In Ruby it’s [], and in JavaScript it’s ().

\n\n

We can do this in JavaScript:

\n\n

1 r.db('foodb').table('foods')\n2   .get(108)(\"name\")\n3 //=>\n4 \"Lemon balm\"\n

\n\n\n\n

Or in Ruby

\n\n

1 r.connect.repl\n2 r.db('foodb').table('foods').get(108)[:name].run\n

\n\n\n\n

What special about bracket is that it return a single value of the field.\nThe type of value is same type of value, not a subset of document. We can verify\nthat with typeOf command:

\n\n

1 r.db('foodb').table('foods')\n2   .get(108)\n3   (\"name\")\n4   .typeOf()\n5 //=>\n6 \"STRING\"\n

\n\n\n\n

You can even get nested field with bracket:

\n\n

1 r.db('foodb').table('test')\n2   .get(108)(\"address\")(\"country\")\n

\n\n\n\n

with assumption that the document has address field is an object contains a\nfield name country.

\n\n

If you don’t like the using of bracket, you can use getField(JavaScript) or\nget_field(Ruby) which have same effect:

\n\n

1 r.db('foodb').table('foods')\n2   .get(108)\n3   .getField('name')\n4 //=>\n5 \"Lemon balm\"\n

\n\n\n\n

How about getting a sub set of document, we can use pluck like this:

\n\n

1 r.db('foodb').table('foods')\n2   .get(108)\n3   .pluck(get\"name\", \"id\")\n4 //=>\n5 {\n6   \"id\": 108 ,\n7   \"name\":  \"Lemon balm\"\n8 }\n

\n\n\n\n

pluck probably existed in many standard library of your favourite language.\nThis example shows you how friendly ReQL is.

\n\n

Select many documents by value of fields

\n\n

To select many document based on value of field, We used filter method, and\npassing an object with expected value.

\n\n

Let’s find all food that were inserted into database on 2011, the year I come\nto the US.

\n\n

 1 r.db('foodb').table('foods')\n 2   .filter(r.row('created_at').year().eq(2011))\n 3 //=>Executed in 59ms. 40 rows returned, 40 displayed, more available\n 4 [{\n 5     \"created_at\": Wed Feb 09 2011 00: 37: 17 GMT - 08: 00,\n 6     \"creator_id\": null,\n 7     \"description\": null,\n 8     \"food_group\": \"Herbs and Spices\",\n 9     \"food_subgroup\": \"Spices\",\n10     \"food_type\": \"Type 1\",\n11     \"id\": 43,\n12     \"itis_id\": \"29610\",\n13     \"legacy_id\": 46,\n14     \"name\": \"Caraway\",\n15     \"name_scientific\": \"Carum carvi\",\n16     \"picture_content_type\": \"image/jpeg\",\n17     \"picture_file_name\": \"43.jpg\",\n18     \"picture_file_size\": 59897,\n19     \"picture_updated_at\": Fri Apr 20 2012 09: 38: 36 GMT - 07: 00,\n20     \"updated_at\": Fri Apr 20 2012 16: 38: 37 GMT - 07: 00,\n21     \"updater_id\": null,\n22     \"wikipedia_id\": null\n23 }\n24 ...\n25 ]\n

\n\n\n\n

r.row is new to you, but no worry, it just means current document. We used\nr.row('created_at') to get value of created_at field, similar with how we\nuse bracket on get command to get a single value. Because created_at\nis a datetime value, I get its year with, well, year command, then using eq\nto do an equal compare with 2011. Sound a lot, but above query is really simple\nand exlain itself. Sometimes I feel redundant to explain query but I have to\nwrite this book anyway.

\n\n

We can also pass an filter object to do matching filter:

\n\n

 1 r.db('foodb').table('foods')\n 2   .filter({\n 3     food_type: 'Type 1',\n 4     food_group: 'Fruits'\n 5   })\n 6 //=>\n 7 [\n 8 {\n 9   \"created_at\": Wed Feb 09 2011 00:37:15 GMT-08:00 ,\n10   \"creator_id\": null ,\n11   \"description\": null ,\n12   \"food_group\":  \"Fruits\" ,\n13   \"food_subgroup\":  \"Tropical fruits\" ,\n14   \"food_type\":  \"Type 1\" ,\n15   \"id\": 14 ,\n16   \"itis_id\":  \"18099\" ,\n17   \"legacy_id\": 14 ,\n18   \"name\":  \"Custard apple\" ,\n19   \"name_scientific\":  \"Annona reticulata\" ,\n20   \"picture_content_type\":  \"image/jpeg\" ,\n21   \"picture_file_name\":  \"14.jpg\" ,\n22   \"picture_file_size\": 29242 ,\n23   \"picture_updated_at\": Fri Apr 20 2012 09:30:49 GMT-07:00 ,\n24   \"updated_at\": Fri Apr 20 2012 16:30:49 GMT-07:00 ,\n25   \"updater_id\": null ,\n26   \"wikipedia_id\": null\n27 },...\n28 ]\n

\n\n\n\n

Passing an object will match exactly document with those field and value. In\nother words, passing an object is equal to passing multiple eq command and and\ncommand. Above query can re-write using expression:

\n\n

1 r.db('foodb').table('foods')\n2   .filter(\n3     r.and(\n4       r.row('food_type').eq('Type 1'),\n5       r.row('food_group').eq('Fruits')\n6     )\n7   )\n

\n\n\n\n

The object notation is much cleaner in this case.

\n\n

From a selection of document, We can use pluck to get a subset of documents’s\nfield instead of returning the whole document. Similarly to how we use bracket\nto get a particular field

\n\n

 1 r.db('foodb').table('foods')\n 2   .filter({\n 3     food_type: 'Type 1',\n 4     food_group: 'Fruits'\n 5   })\n 6   .pluck('id', 'name', 'food_subgroup')\n 7 //=>Executed in 70ms. 40 rows returned, 40 displayed, more available\n 8 [\n 9   {\n10   \"food_subgroup\":  \"Berries\" ,\n11   \"id\": 75 ,\n12   \"name\":  \"Black crowberry\"\n13   }, {\n14   \"food_subgroup\":  \"Tropical fruits\" ,\n15   \"id\": 150 ,\n16   \"name\":  \"Guava\"\n17   }, {\n18   \"food_subgroup\":  \"Tropical fruits\" ,\n19   \"id\": 151 ,\n20   \"name\":  \"Pomegranate\"\n21   }, ...\n22 ]\n

\n\n\n\n

By passing a list of field to pluck, we can get only those field.

\n\n

Opposite of pluck is without. We passed a list of fields, and it removes\nthose fiels from document.

\n\n

 1 r.db('foodb').table('foods')\n 2   .filter({\n 3     food_type: 'Type 1',\n 4     food_group: 'Fruits'\n 5   })\n 6   .without(\"created_at\", \"picture_content_type\", 'picture_file_name', 'picture_f\\\n 7 ile_size', 'picture_updated_at')\n 8 //=> Executed in 52ms. 40 rows returned, 40 displayed, more available\n 9 [\n10 {\n11   \"creator_id\": null ,\n12   \"description\": null ,\n13   \"food_group\":  \"Fruits\" ,\n14   \"food_subgroup\":  \"Berries\" ,\n15   \"food_type\":  \"Type 1\" ,\n16   \"id\": 75 ,\n17   \"itis_id\":  \"23743\" ,\n18   \"legacy_id\": 81 ,\n19   \"name\":  \"Black crowberry\" ,\n20   \"name_scientific\":  \"Empetrum nigrum\" ,\n21   \"updated_at\": Fri Apr 20 2012 16:29:43 GMT-07:00 ,\n22   \"updater_id\": null ,\n23   \"wikipedia_id\": null\n24 },...\n25 ]\n

\n\n\n\n

With simple filterting, we can easily pass an filter object as above. But what\nup with complex searching? Such as finding all foods whose name starts with\ncharacter N. As you see at the beginning, we used r.row command to do a\nbit complex query.

\n\n

1 r.db('foodb').table('foods')\n2   .filter(r.row('created_at').year().eq(2011))\n

\n\n\n\n

Let’s dive more into it.

\n\n\n\n

r.row

\n\n

r.row is our swiss army knife. It refers to current visited document.\nLiterally, it’s the document at which RethinkDB is accessing. You can think of\nit like this in a JavScript callback/iterator. Or think of it like current\nelement in an iterator loop. It’s very handy because we can call other ReQL\ncommand on it to achieve our filtering.

\n\n

It somehow feel like jQuery filtering command. For an instance, we write this \nin JavaScript to filter all DOM element whose data-type value is anime.

\n\n

1 $('.db').find('.table').filter(function() {\n2   return $(this).data('type')=='anime'\n3 })\n

\n\n\n\n

In ReQL, using filter with filter object:

\n\n

1 r.db('foodb').table('foods').filter({food_group: 'Fruits'})\n

\n\n\n\n

We can re-write it with r.row

\n\n

1 r.db('foodb').table('foods').filter(r.row('food_group').eq('Fruits'))\n

\n\n\n\n

Breaking it down we have:

\n\n

r.row ⇒ current document
(‘type’) ⇒ get value of field type\n
.eq(‘anime’) ⇒ return true if the value is equal to the argument, anime in this case

\n\n

r.row a RethinkDB object, which we can continue call many method to filter or\nmanipulation it. The expression that we pass into filter is a normal ReQL\nexpression but evaluate to a boolean result. RethinkDB runs it and if the returned value is true, the\ndocument is included into result set. Ideally, any function that returns boolean\nresult can used with filter. Note that the evaluation of filter expression run\non RethinkDB server, therefore they has to be a valid ReQL expression, they\ncannot be any arbitrary language expression. You cannot write:

\n\n

1 r.db('db').table('table').filter(r.row('type') == 'anime')\n

\n\n\n\n

In manner of filter action, we usually execute comparison or some condition to\nbe matched, RethinkDB gives us some kind of those method. You should refer to\nits API for extensive command. Usually, we can use r.row in combine with\npluck or without or bracket command to narrow down data before\ncomparing. Below are some function for that purpose:

\n\n

\neq(value) check equal to value. similar to ==.
\nne(value) check not equal to value. similar to !=.
\nge(value) check greater than or equal value. similar to >=.
\ngt(value) check greater than value. similar to >.
\nle(value) check less than or equal value. similar to <=.
\nlt(value) check less than value. similar to <.
\nadd(value) Sum two numbers, concatenate two strings, or concatenate 2 arrays.
\nsub() Subtract two numbers.

\n\n

Each of above command can be call on different data type. Eg, when you call add\non an array, it will append the element to array. when you call on a string, it\nconcat parameter to the original string. Or calling on a number and they just \ndo arithmetic operation.

\n\n

Run those command in data explorer:

\n\n

 1 r.expr([\"foo\", \"bar\"]).add(['forbar'])\n 2 //=>\n 3 [\n 4   \"foo\" ,\n 5   \"bar\" ,\n 6   \"forbar\"\n 7 ]\n 8 \n 9 r.expr(2).add(10)\n10 //=>\n11 12\n12 \n13 r.expr('foo').add(\"bar\")\n14 //=>\n15 \"foobar\"\n

\n\n\n\n\n\n

You can find more about those document in RethinkDB doc, in group Math and\nlogic⁴.

\n\n

Let’s apply what we learn, by finding al food where its name starts with\ncharacter R and is a tropical fruits.

\n\n

 1 r.db(\"foodb\").table(\"foods\")\n 2   .filter(\n 3       r.row(\"name\").match(\"^R\")\n 4       .and(\n 5         r.row(\"food_subgroup\").eq('Tropical fruits')\n 6       )\n 7   )\n 8 //=>\n 9 {\n10   \"created_at\": Wed Feb 09 2011 00:37:27 GMT-08:00 ,\n11   \"creator_id\": null ,\n12   \"description\": null ,\n13   \"food_group\":  \"Fruits\" ,\n14   \"food_subgroup\":  \"Tropical fruits\" ,\n15   \"food_type\":  \"Type 1\" ,\n16   \"id\": 234 ,\n17   \"itis_id\":  \"506073\" ,\n18   \"legacy_id\": 249 ,\n19   \"name\":  \"Rambutan\" ,\n20   \"name_scientific\":  \"Nephelium lappaceum\" ,\n21   \"picture_content_type\":  \"image/jpeg\" ,\n22   \"picture_file_name\":  \"234.jpg\" ,\n23   \"picture_file_size\": 71055 ,\n24   \"picture_updated_at\": Fri Apr 20 2012 09:43:04 GMT-07:00 ,\n25   \"updated_at\": Fri Apr 20 2012 16:43:05 GMT-07:00 ,\n26   \"updater_id\": null ,\n27   \"wikipedia_id\": null\n28 }\n

\n\n\n\n

Here we are usinbg match with an regular expression ^R means any name starts\nwith R, and using and to do an and operator with other boolean. Other\nboolean is result of getting field food_subgroup and compare with tropical\nfruits.

\n\n

filter seems handy but it’s actually limited. filter didn’t leverage index.\nIt scan and hold all data in memory. Of course, this isn’t scale infinite. Only\n100,000 records can be filter. For anything large than that, we have to use\ngetAll or between which we will learn in chapter 5.

\n\n

Now, let’s try to find all foods which has more than 10 foods document in its\ngroup. We probably think of a simple solution like this: for each of document,\nwe get its food_group and count how many items has that same food group, if\nthe result is greater than 10, we return true, so that it will be included in\nfilter result. We may have duplicate result but let’s try this naieve\nsoltuion:

\n\n

1 r.db('foodb').table('foods')\n2   .filter(\n3     r.db('foodb').table('foods')\n4       .filter(\n5         {food_group: r.row(\"food_group\")}\n6       )\n7       .count()\n8       .gt(10)\n9   )\n

\n\n\n\n

Query looks good but when we run, we get this:

\n\n

1 RqlCompileError: Cannot use r.row in nested queries.  Use functions instead in:\n2 r.db(\"foodb\").table(\"foods\").filter(r.db(\"foodb\").table(\"foods\").filter({food_gr\\\n3 oup:\n4 r.row(\"food_group\")}).count().gt(10))\n

\n\n\n\n

Basically, we have nested query here, and RethinkDB doesn’t know which query\nr.row should belong to, is it parent query, or the sub query? In those case,\nwe have to use filter with function. Let’s move to next chapter.

\n\n

Filter with function

\n\n

Beside passing an ReQL expression, we can also use a function which return true\nor false to filter.

\n\n

Let’s try previous example.

\n\n

1 r.db('foodb').table('foods')\n2   .filter(function (food) {\n3    return r.db('foodb').table('foods').filter({food_group: food(\"food_group\")}).\\\n4 count().gt(10)\n5   })\n

\n\n\n\n

Now, we no longer using r.row, we pass an anonymous function with a single\nparameter(which we can name whatever), when itereating over the table, RethinkDB\ncall this function, and passing current document as its first argument. By using\nfunction, we can still access current document, without using r.row, and\nclearly bind current document to a variable, so that we can access its value and\navoid conflicting. Here, we name our argument food, instead of writing:

\n\n

1 filter({food_group: r.row(\"food_group\")})\n

\n\n\n\n

We will write:

\n\n

1 filter({filter_group: food(\"food_group\")})\n

\n\n\n\n

And we using boolean value, count().gt(10) here, as result of function.\nFilter with function helps us write query with complex logic.

\n\n

Pagination data

\n\n

We rarely want a whole sequence of document, usually we care about a subset of\ndata such as pagination data. In this section, we go over commands: order, limit\nand skip.

\n\n

Order data

\n\n

So far, we only select data and accept default ordering. Let’s control how they\nappear:

\n\n

1 r.db('foodb').table('foods')\n2   .filter(function (food) {\n3    return r.db('foodb').table('foods').filter({food_group:\n

\n\n\n

food(“food_group”)}).count().gt(10)\n })\n .orderBy(“name”)\n //⇒Executed in 5.69s. 821 rows returned\n [\n {\n “created_at”: {\n “$reql_type$”: “TIME”,\n “epoch_time”: 1297240650,\n “timezone”: “-08:00”\n },\n “creator_id”: null,\n “description”: null,\n “food_group”: “Aquatic foods”,\n “food_subgroup”: “Mollusks”,\n “food_type”: “Type 1”,\n “id”: 280,\n “itis_id”: “69493”,\n “legacy_id”: 307,\n “name”: “Abalone”,\n “name_scientific”: “Haliotis”,\n “picture_content_type”: “image/jpeg”,\n “picture_file_name”: “280.jpg”,\n “picture_file_size”: 99231,\n “picture_updated_at”: {\n “$reql_type$”: “TIME”,\n “epoch_time”: 1334940073,\n “timezone”: “-07:00”\n },\n “updated_at”: {\n “$reql_type$”: “TIME”,\n “epoch_time”: 1334965273,\n “timezone”: “-07:00”\n },\n “updater_id”: null,\n “wikipedia_id”: null\n },\n …\n ]

\n\n

We re-used above filter query, but append orderBy(\"name\"). If you notice,\nthe above command run quite long Executed in 5.56s. 821 rows returned and\nall rows are returned instead of a streams as usual. When we are calling\norderBy without specifing an index, it load all data into memory to sort,\nwhich is both of slow and in-efficient. We will learn more about ordering with\nindex in chapter 5. For now, let’s continue with this method because, well, they\nare easy to use, at first :D

\n\n

We can reverse order by applying r.desc command:

\n\n

1 r.db('foodb').table('foods')\n2   .filter(function (food) {\n3     return r.db('foodb').table('foods').filter({food_group: food(\"food_group\")})\\\n4 .count().gt(10)\n5   })\n6   .orderBy(r.desc(\"name\"))\n

\n\n\n\n

We can order on table too, not just filter:

\n\n

1 r.db('foodb').table('foods')\n2   .orderBy(r.desc(\"name\"))\n

\n\n\n\n

We can order by multiple field, at a time

\n\n

1 r.db('foodb').table('foods')\n2   .orderBy(r.desc(\"name\"), r.asc(\"created_at\"))\n

\n\n\n\n

We order by descending order on field name and ascending on field\ncreated_at.

\n\n\n\n

We can combine some document commands with orderBy too. Such as pluck only\nan useful set of fields:

\n\n

 1 r.db('foodb').table('foods')\n 2   .pluck(\"id\", \"name\", \"food_group\")\n 3   .orderBy(r.desc(\"name\"), r.asc(\"created_at\"))\n 4 //=>Executed in 122ms. 863 rows returned\n 5 [\n 6   {\n 7       \"food_group\": \"Milk and milk products\",\n 8       \"id\": 634,\n 9       \"name\": \"Yogurt\"\n10   },\n11   {\n12       \"food_group\": \"Milk and milk products\",\n13       \"id\": 656,\n14       \"name\": \"Ymer\"\n15   },\n16   {\n17       \"food_group\": \"Aquatic foods\",\n18       \"id\": 523,\n19       \"name\": \"Yellowtail amberjack\"\n20   },\n21   ...\n22 ]\n

\n\n\n\n

Limiting data

\n\n

Once we have an ordering sequence, we usually want to select a limit number of\ndocument instead of the whole sequence. We use command limit(n) for this\npurpose. It get n elements from the sequence or array.

\n\n

 1 r.db('foodb').table('foods')\n 2   .pluck(\"id\", \"name\", \"food_group\")\n 3   .orderBy(r.desc(\"name\"), r.asc(\"created_at\"))\n 4   .limit(4)\n 5 //=>Executed in 107ms. 2 rows returned\n 6 [{\n 7     \"food_group\": \"Milk and milk products\",\n 8     \"id\": 634,\n 9     \"name\": \"Yogurt\"\n10 }, {\n11     \"food_group\": \"Milk and milk products\",\n12     \"id\": 656,\n13     \"name\": \"Ymer\"\n14 }, {\n15     \"food_group\": \"Aquatic foods\",\n16     \"id\": 523,\n17     \"name\": \"Yellowtail amberjack\"\n18 }, {\n19     \"food_group\": \"Aquatic foods\",\n20     \"id\": 522,\n21     \"name\": \"Yellowfin tuna\"\n22 }]\n

\n\n\n\n

limit get us a number of document that we want, but it always start from the\nbeginning of sequence. To start selecting data starts from a position, we used\nskip.

\n\n

Skip

\n\n

As its name, skip(n) ignore a number of element from the head of sequence.

\n\n

 1 r.db('foodb').table('foods')\n 2   .pluck(\"id\", \"name\", \"food_group\")\n 3   .orderBy(r.desc(\"name\"), r.asc(\"created_at\"))\n 4   .skip(2)\n 5   .limit(2)\n 6 //=> Executed in 97ms. 2 rows returned\n 7 [{\n 8     \"food_group\": \"Aquatic foods\",\n 9     \"id\": 523,\n10     \"name\": \"Yellowtail amberjack\"\n11 }, {\n12     \"food_group\": \"Aquatic foods\",\n13     \"id\": 522,\n14     \"name\": \"Yellowfin tuna\"\n15 }]\n

\n\n\n\n

Access Nested field

\n\n

As you know, RethinkDB document is a JSON object. Very likely we have two or\nmore level of data structure. So how we can access those nested field, or to\ndrill down the fields.

\n\n

Let’s beging this chapter by creating some sample data. Just copy and paste,\nignore the syntax for now because we save them for chapter 4.

\n\n

First, create table on test db.

\n\n

1 r.tableCreate(\"books\")\n

\n\n\n\n

Then, insert sample data:

\n\n

 1 r.table(\"books\")\n 2   .insert([\n 3         {\n 4             id: 1,\n 5             name: \"Simply RethinkDB\",\n 6             address: {\n 7                 country: {\n 8                     code: \"USA\",\n 9                     name: \"The United State of America\"\n10                 }\n11             },\n12             contact: {\n13                 phone: {\n14                     work: \"408-555-1212\",\n15                     home: \"408-555-1213\",\n16                     cell: \"408-555-1214\"\n17                 },\n18                 email: {\n19                     work: \"bob@smith.com\",\n20                     home: \"bobsmith@gmail.com\",\n21                     other: \"bobbys@moosecall.net\"\n22                 },\n23                 im: {\n24                     skype: \"Bob Smith\",\n25                     aim: \"bobmoose\",\n26                     icq: \"nobodyremembersicqnumbers\"\n27                 }\n28             }\n29         },\n30         {\n31             id: 2,\n32             name: \"TKKG\",\n33             address: {\n34                 country: {\n35                     code: \"GER\",\n36                     name: \"Germany\"\n37                 }\n38             },\n39             contact: {\n40                 phone: {\n41                     work: \"408-111-1212\",\n42                     home: \"408-111-1213\",\n43                     cell: \"408-111-1214\"\n44                 },\n45                 email: {\n46                     work: \"bob@gmail.com\",\n47                     home: \"bobsmith@axcoto.com\",\n48                     other: \"bobbys@axcoto.com\"\n49                 },\n50                 im: {\n51                     skype: \"Jon\",\n52                     aim: \"Jon\",\n53                     icq: \"nooneremembersicqnumbers\"\n54                 }\n55             }\n56         }\n57   ])\n

\n\n\n\n

Depend on your language, you will usually have some way to access nested field,\nby following the nested path. In above example, let’s say we want to access\n*skype im, the path is:

\n\n

contact -> im -> skype

\n\n

Using JavaScript driver, we will use bracket to access field and sub field.

\n\n

1 r.table('books').get(1)('contact')('im')('skype')\n2 //=>\n3 \"Bob Smith\"\n

\n\n\n\n

While as, in Ruby driver, bracket notation is [field]

\n\n

1 r.table('books').get(1)['contact']['im']['skype']\n

\n\n\n\n

We can keep calling bracket to get the final nested field follow the path.\nNot just a single document, we can use bracket on table level too:

\n\n

 1 r.table('books')('address')('country')\n 2 [\n 3 {\n 4   \"code\":  \"GER\" ,\n 5   \"name\":  \"Germany\"\n 6 }, {\n 7   \"code\":  \"USA\" ,\n 8   \"name\":  \"The United State of America\"\n 9 }\n10 ]\n

\n\n\n\n

Or using in combination with filter, on selection:

\n\n

1 r.table('books')\n2   .filter({id: 1})('address')('country')('name')\n3 //=>\n4 \"The United State of America\"\n

\n\n\n\n

Beside using bracket command, we can also using getField if that feel more\nnature:

\n\n

 1 r.table('books')\n 2   .getField('contact')('email')\n 3 //=>\n 4 [\n 5 {\n 6   \"home\": bobsmith@axcoto.com, »\n 7   \"other\": bobbys@axcoto.com, »\n 8   \"work\": bob@gmail.com, »\n 9 }, {\n10   \"home\": bobsmith@gmail.com, »\n11   \"other\": bobbys@moosecall.net, »\n12   \"work\": bob@smith.com, »\n13 }]\n

\n\n\n\n

At the end of the day all you have to remember is to drill down the path with a\nchain of bracket command.

\n\n

https://github.com/rethinkdb/rethinkdb/issues/829↩\n
\nhttp://stackoverflow.com/questions/21020823/unique-integer-counter-in-rethinkdb ↩\n
\nhttp://en.wikipedia.org/wiki/Universally_unique_identifier ↩\n
\nhttp://rethinkdb.com/api/javascript/#mod ↩\n

\n\n\n

Wrap Up

\n\n

We now have some basic understanding:

\n\n

1 1. ReQL always starts with `r`.\n2 2. ReQL is tie to your language depend on language driver.\n3 3. Default database\n4 3. Find an document by its primary\n5 4. Access table data and filter data by some condition\n6 5. Access nested field\n

\n\n\n\n

We will learn more about advanced query in other chapter. For now, let’s move on\nand try to write some data into RethinkDB.

\n\n\n

\n\n","tocStructure",[239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274],{"_80":74,"_43":70,"_71":-5,"_75":76,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":82,"_71":-5,"_75":83,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":88,"_71":-5,"_75":89,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":92,"_71":-5,"_75":93,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":96,"_71":-5,"_75":97,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":74,"_43":100,"_71":-5,"_75":101,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":104,"_71":-5,"_75":105,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":109,"_71":-5,"_75":110,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":114,"_71":-5,"_75":115,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":117,"_71":-5,"_75":118,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":121,"_71":-5,"_75":122,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":125,"_71":-5,"_75":126,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":129,"_71":-5,"_75":130,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":133,"_71":-5,"_75":134,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":136,"_71":-5,"_75":137,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":139,"_71":-5,"_75":140,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":142,"_71":-5,"_75":143,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":145,"_71":-5,"_75":146,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":74,"_43":149,"_71":-5,"_75":150,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":153,"_71":-5,"_75":154,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":157,"_71":-5,"_75":158,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":161,"_71":-5,"_75":162,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":164,"_71":-5,"_75":165,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":167,"_71":-5,"_75":168,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":170,"_71":-5,"_75":171,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":174,"_71":-5,"_75":175,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":177,"_71":-5,"_75":178,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":180,"_71":-5,"_75":181,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":183,"_71":-5,"_75":184,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":187,"_71":-5,"_75":188,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":190,"_71":-5,"_75":191,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":193,"_71":-5,"_75":194,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":196,"_71":-5,"_75":197,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":199,"_71":-5,"_75":200,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":108,"_43":202,"_71":-5,"_75":203,"_73":74,"_111":-5,"_112":-5,"_86":-5},{"_80":81,"_43":205,"_71":-5,"_75":206,"_73":74,"_111":-5,"_112":-5,"_86":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

Wrap Up

Table of Contents

1. Welcome

Introduction

Why learn RethinkDB?

Feedback

Credit

2. Getting to know RethinkDB

Getting Started

The Ports

The dashboard

RethinkDB object

Durability

Atomicity

Command line tool

import

export

dump

restore

Import sample data

3. Reading Data Basic

Getting to Know ReQL

Drivers

Using drivers

Default database

Repl

Data Type

Basic data type

Composite data type

Sorting data

Selecting data

Select the whole table

Counting

Select a single document by its primary key

Select many documents by value of fields

r.row

Filter with function

Pagination data

Order data

Limiting data

Skip

Access Nested field

Wrap Up