The Node.js Client API in 5 Minutes

Aries Yuwono

Last updated October 13, 2015

Documents

The basic unit of organization in MarkLogic is a Document and the Node.js Client API enables you to store and search documents. The Node.js API supports documents encoded in JSON like:

{
    name: 'Asahi Draft Beer',
    brewer: {
        name: 'Asahi',
        country: 'Japan'
    },
    calories: 41,
    alcohol:  '5.21'
}

and XML like

<beer>
    <name>Asahi Draft Beer</name>
    <brewer>
        <name>Asahi</name>
        <country>Japan</country>
    </brewer>
    <calories>41</calories>
    <alcohol>5.21</alcohol>
</beer>

The set of JSON keys, objects, and arrays, or XML elements and attributes you use in your documents is up to you. MarkLogic does not require adherence to any schemas.

MarkLogic also supports documents encoded in binary form or plain text as well. We refer to this encoding (JSON, XML, text, or binary) as the document's Format.

URIs

A document's URI is a key that you choose when you insert a document into the database. Each document has a unique URI. You use this URI to retrieve or refer to the document later. Typically document URIs begin with a slash like /beer.

Beyond the URI, MarkLogic maintains some additional metadata associated with each document.

Organization

How does MarkLogic organize documents in the database? Logically, MarkLogic provides two concepts: Collections and Directories. You can think of collections as unordered sets. If you have a notion of tag as well, that may help. Collections can hold multiple documents and documents can belong to multiple collections.

Directories are similar in concept to the notion of directories or folders in file systems. They are hierarchical and membership is implicit based on the path syntax of URIs.

API Basics

Ok, so that's what is stored in MarkLogic. What does the API look like? The first step whenever you want to interact with MarkLogic is to get a DatabaseClient instance. Note that this tutorial uses admin/admin for the username and password; for a real deployment, you'd want a more secure password.

var marklogic = require('marklogic');
var db = marklogic.createDatabaseClient({
      host: 'localhost', 
      port: '8000', 
      user: 'admin', 
      password: 'admin', 
      authType: 'DIGEST'
});

You can connect as a different user, to a different port, and a different database. (See the Getting Started with the Node Client API for project setup).

CRUD

Yep, that's Create, Read, Update, and Delete. We use the term "Insert" instead of "Create" but that doesn't keep us from saying CRUD for fun. MarkLogic provides a simple Node.js API for CRUD.

The first step is to use our DatabaseClient instance (db) to write a document by calling the write() method:

db.documents.write({
  uri: '/afternoon-drink',
  contentType: 'application/json',
  content: {
    name: 'Iced Mocha',
    size: 'Grand',
    tasty: true
  }
}).result(function(response) {
  console.log(JSON.stringify(response, null, 2));
});

The result will be:

{
  "documents": [
    {
      "uri": "/afternoon-drink",
      "contentType": null
    }
  ]
}

To get the document back, call the read() method:

db.documents.read({uris: '/afternoon-drink'}).result(…)

Updating (replacing) the document works exactly the same as creating a document: use the write() method.

To delete the document, call the remove() method:

db.documents.remove('/afternoon-drink').result(…)

Search

Beyond basic retrieval by URI, MarkLogic provides extremely robust support for search-style queries. Results can be sorted by relevance or by a scalar. Result items can be paged (viewing a small number at a time), returned documents can be snippeted (showing a short content blurb containing the matching terms) and highlighted (to perhaps bold the matching word occurrences).

When executing a search you can choose to retrieve a simple description of the matching documents, or fetch the documents as well, for the sake of efficiency to avoid repeated calls. If you fetch the documents as part of the search, you can request the same subsetting and transformation occur as for singular document retrievals.

Ok, that sounds cool. Let's move on to some sample code.

To execute any kind of query, call a document instance's query() method and construct the query using queryBuilder instance qb():

var qb = marklogic.queryBuilder;
db.documents.query(
  qb.where(…)

String Query

To run a search that retrieves documents with the word, "delicious":

db.documents.query(
  qb.where(
    qb.term('delicious')
  )).result(…)

If you only want documents with this word that are in your drinks collection, you can do:

db.documents.query(
  qb.where(
    qb.and(
      qb.collection('drinks'),
      qb.term('delicious')
    )
  )).result(…)

For more examples, see Getting Started with the Node Client API.

Contents