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 four officially supported libraries for four programming languages:

For these examples Iโ€™m going to use the Node.js library.

Connect to the database ๐Ÿ”—

Letโ€™s set up our Cloudant credentials in environment variables:

# the URL of the Cloudant service
export CLOUDANT_URL='https://mycloudantservice.cloudant.com'
# the IAM API key
export CLOUDANT_APIKEY='myapikey'

Then we can include the library and get it set up:

const { CloudantV1 } = require('@ibm-cloud/cloudant')
const client = CloudantV1.newInstance()

Create a the database ๐Ÿ”—

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

await client.putDatabase({
  db: 'mydatabasename',
  partitioned: false
})
// { ok: true }

Creating documents ๐Ÿ”—

Letโ€™s say we want to add an array of documents to our database:

const 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:

await client.postBulkDocs({
  db: 'mydatabasename',
  bulkDocs: { docs: docs }
})
// [ { id: 'a', ok: true, rev: '1-123'}, { id: 'b', ok: true, rev: '1-456'}]

The same goes for single documents:

const newdoc = { name: "Ed Rooney", actor: "Jeffrey Jones", dob: "1946-09-28"}
await client.postDocument({
  db: 'mydatabasename',
  document: newdoc
})
// { ok: true, id: '95b51f94118ae', rev: '1-678' }

Reading documents ๐Ÿ”—

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

await client.getDocument({
  db: 'mydatabasename',
  docId: '95b51f94118ae2d852393c63edacf462'
})
// { _id: '95b51f94118ae2d852393c63edacf462',
//  name: 'Ed Rooney',
//  actor: 'Jeffrey Jones',
//  dob: '1946-09-28' }

You may also fetch a list of ids:

const ids = ['95b51f94118ae2d852393c63edacf462', 'c30959f23a9feb3abbfd40e7e848fde4']
await client.postAllDocs({
  db: 'mydatabasename',
  includeDocs: true,
  keys: ids
})
// [ {...}, {...} ]

or ask for all the documents:

await client.postAllDocs({
  db: 'mydatabasename',
  includeDocs: true
})

Updating documents ๐Ÿ”—

The Node.js library allows documents to be updated by passing a document with its last revision (_rev) in place:

const modifiedDoc = { 
  _id: "95b51f94118ae2d852393c63edacf462",
  _rev: '1-678'
  name: "Edward Rooney", 
  actor: "Jeffrey Duncan Jones",
  residence: "Los Angeles, CA",
  dob: "1946-09-28"
}
await client.postDocument({
  db: 'mydatabasename',
  document: modifiedDoc
})
// { ok: true, rev: '2-456' }

Deleting a document ๐Ÿ”—

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

await client.deleteDocument({
  db: 'mydatabasename',
  docId: '95b51f94118ae2d852393c63edacf462',
  rev: '2-456'
})
// { ok: true, rev: '3-789' }

Next time ๐Ÿ”—

In the next post weโ€™ll look at querying data.