Cloudant Fundamentals 6/10

June 12, 2018 | Glynn Bird | Fundamentals Node.js

In the previous two posts we saw how how the command-line tool curl is all that is required to do basic read and write operations with Cloudant, and how two API calls can be used for bulk commands.

In this post we’ll look at equivalent tasks using programmatic means.

You don’t need a special library to work with Cloudant - just something capbable of making HTTP requests. The libraries do help, however, with authentication and parameter encoding. There are three officially supported libraries for three programming languages:

For these examples I’m going to use the cloudant-quickstart library that makes it very easy for you to get started with Cloudant. It is installed by simply typing npm install cloudant-quickstart into your terminal.

You can copy the following code snippets into either:

  1. a Node “REPL” (just type node on the command line)
  2. a Jupyter notebook using the pixiedust_node library
  3. a text file

Connect to the database

First we need a URL containing our Cloudant credentials and to start up the library:

const url = 'https://username:password@hostname.cloudant.com/newdb'
const cqs = require('cloudant-quickstart')
const db = cqs(url)

Create a the database

Creating a database is as simple as calling the create function:

db.create().then(console.log)
// { ok: true }

Creating documents

Let’s say we want to add an array of documents to our database:

var docs = [
    {"name": "Ferris Bueller", "actor": "Matthew Broderick", "dob": "1962-03-21"},
    {"name": "Sloane Peterson", "actor": "Mia Sara", "dob": "1967-06-19"},
    {"name": "Cameron Frye", "actor": "Alan Ruck", "dob": "1956-07-01"}
 ] 

The insert document can be used to write them to the database:

db.insert(docs).then(console.log)
// { ok: true, success: 3, failed: 0 }

The same goes for single documents:

var newdoc = { name: "Ed Rooney", actor: "Jeffrey Jones", dob: "1946-09-28"}
db.insert(newdoc).then(console.log)
// { ok: true, _id: '95b51f94118ae2d852393c63edacf462' }

Reading documents

Documents can be read back singly by specifying the id of the document you want:

db.get('95b51f94118ae2d852393c63edacf462').then(console.log)
// { _id: '95b51f94118ae2d852393c63edacf462',
//  name: 'Ed Rooney',
//  actor: 'Jeffrey Jones',
//  dob: '1946-09-28' }

You may also specify a list of ids:

const ids = ['95b51f94118ae2d852393c63edacf462', 'c30959f23a9feb3abbfd40e7e848fde4']
db.get(ids).then(console.log)
// [ {...}, {...} ]

or ask for all the documents:

db.all().then(console.log)

Updating documents

The cloudant-quickstart library allows documents to be updated without worrying about revision tokens: just pass in the new document body and the library will figure it out:

var modified_doc = { 
  _id: "95b51f94118ae2d852393c63edacf462",
  name: "Edward Rooney", 
  actor: "Jeffrey Jones", 
  dob: "1946-09-28"
}
db.update(modified_doc).then(console.log)

The library will even allow you to make incremental updates to documents by passing the document id, an object containing the changes and true (to indicate that the updates are to merged in) as three parameters to the update function:

var mods = {
  actor: "Jeffrey Duncan Jones",
  residence: "Los Angeles, CA"
}
// update actor field and add residence field
db.update("95b51f94118ae2d852393c63edacf462", mods, true).then(console.log)
// { ok: true }

Deleting a document

A documents can be removed from the database by passing an id delete function:

db.delete("95b51f94118ae2d852393c63edacf462").then(console.log)
// { ok: true }

Where did the rev token go?

The cloudant-quickstart library hides the rev token from you. The rev token is a tricky concept for new starters, so this library abstracts it from you so that you can get on with building something quickly. In a production environment, you will have to get to grips with revision tokens, but for now we can sit back and relax.

Next time

In the next post we’ll look at querying data.