Before inserting documents into the database, we must create a table to hold our data. We can do this using the tableCreate() command that takes the table name as an argument. Let's create a table called people by running the following query:

r.db('test').tableCreate('people')

This query assumes you have a database called test and creates the people table within this database. If the query is successful, you will get an output similar to this:

{
  "config_changes":[
    {
      "new_val":{
        "db":"test",
        "durability":"hard",
        "id":"a29447ca-1587-4b8c-86db-a7b3d5198519",
        "name":"people",
        "primary_key":"id",
        "shards":[
          {
            "primary_replica":"rethinkdb1",
            "replicas":[
              "rethinkdb1"
            ]
          }
        ],
        "write_acks":"majority"
      },
      "old_val":null
    }
  ],
  "tables_created":1
}

This is a great deal of information! If you look closely at the output, you can deduce that RethinkDB acknowledges the creation of the table, assigns an ID to it, and sets the primary key attribute to ID. The other data gives us information on the shard where the table resides and other sharding info. We will look at this closely in the next chapter. For now, what interests us is that RethinkDB has created a new table for us in the database.

We can now proceed with the insertion of our first document in the people table. Inserts are the basic method for adding documents to a table and can be achieved by using the insert() command. This command takes a JSON document as input. Building on from the JSON example, we built in the previous sections. Let's add a document to the table by running the following query:

r.db('test').table('people').insert({
  "name":"Alex",
  "surname":"Jones",
  "yearOfBirth":1990,
  "email":"[email protected]",
  "address":{
    "street":"23, St. John's Street",
    "city":"London",
    "postcode":"EC1V4PY"
  },
  "interests":[
    "programming",
    "football",
    "cars"
  ]
}
)

This will create a new UUID as the primary key, and it will add the provided JSON document to the "people" table. If you run the query from the Data Explorer section of the web interface, you will get an output similar to this:

If the query has succeeded, the resulting JSON object will have zero errors and one inserted document. As you can see from the screenshot, RethinkDB has generated c4cad21f-edf2-4ae1-8269-73dce5ff8bff as the primary key for our document.

Using the primary key, we can check if the document has actually been saved in the table by querying the database by a primary key. We can do this using the get() command:

r.db('test').table('people').get("c4cad21f-edf2-4ae1-8269-73dce5ff8bff")

If the document has been saved correctly, the get() query will return the original document, confirming that it is present in the table:

Batch inserts

The insert() command is simple to use; however, if you find yourself in a situation where you insert multiple documents, then running one insert command after the other can be a tedious task. Batch inserts allow you to insert multiple JSON documents into the database with just one query.

Tip

Sending dozens or even hundreds of documents at a time can make inserts significantly faster, so keep this in mind when you insert multiple documents.

To execute a batch insert, just pass an array to the insert() command instead of a single document such as this:

r.db('test').table('people').insert([{document1}, {document2}])

The following screenshot illustrates the process of inserting two documents in just one query:

As usual, we can look at the resulting output to check if the query succeeded:

{
  "deleted":0,
  "errors":0,
  "generated_keys":[
    "083d0878-808b-4ebf-abee-8e99e0adc3b5",
    "f1664276-1aad-4998-8240-410a82883115"
  ],
  "inserted":2,
  "replaced":0,
  "skipped":0,
  "unchanged":0
}

This confirms that two documents have been inserted, two primary keys have been generated by the database, and there are no errors. Congratulations! If you've been following the instructions steps by step, you will now have three documents inside the table. The next section will be all about reading data from the database.