MarkLogic Server 11.0 Product Documentation

JavaScript Reference Guide — Chapter 2

Node and Document API

MarkLogic APIs often return or expect nodes and/or documents. To make it easy to use these APIs in JavaScript, MarkLogic has added the built-in Node and Document objects. These are objects but they are not part of the global object. This section describes the interface for these objects and includes the following parts:

• Node Object
• Document Object

baseURI

valueOf()

nodeType

ELEMENT_NODE

1

ATTRIBUTE_NODE

2

TEXT_NODE

3

PROCESSING_INSTRUCTION_NODE

7

COMMENT_NODE

8

DOCUMENT_NODE

9

BINARY_NODE

13

NULL_NODE

14

BOOLEAN_NODE

15

NUMBER_NODE

16

ARRAY_NODE

17

OBJECT_NODE

18

toObject()

xpath(String   XPathExpression,
  Object NamespaceBindings)

// assume a document created as follows:
declareUpdate();
xdmp.documentInsert("/my/doc.xml", fn.head(xdmp.unquote(
  '<bar:foo xmlns:bar="bar"><bar:hello><bar:goodbye \n\
     attr="attr value">bye</bar:goodbye>\n\
  </bar:hello>\n\
</bar:foo>')));

// Use the Node.xpath method on the document node:
const node = cts.doc("/my/doc.xml");
node.xpath("//bar:goodbye/@attr", {"bar":"bar"});

// Running in Query Console displays the following value (as an
// attribute node): "attr value" 

documentFormat

BINARY

"BINARY"

JSON

"JSON"

TEXT

"TEXT"

XML

"XML"

root

XML DOM APIs

MarkLogic implements XML DOM APIs to provide read-only access to XML nodes. This section describes these APIs and includes the following parts:

• Node Object for XML Nodes
• Document Object for Document Nodes
• NodeBuilder API
• Element
• Attr
• CharacterData and Subtypes
• TypeInfo
• NamedNodeMap
• NodeList

childNodes

firstChild

lastChild

localname

namespaceURI

nextSibling

nodeName

nodeValue

ownerDocument

parentNode

prefixSibling

hasChildNodes()

hasAttributes()

attributes

baseURI

textContent

isSameNode(
  Node other)

isEqualNode(
  Node other)

insertBefore(
  Node newChild,
  Node refChild)

replaceChild(
  Node newChild,
  Node oldChild)

removeChild(
  Node oldChild)

appendChildNodes(
  Node newChild)

normalize()

documentElement

documentURI

getElementsByTagName(
  String tagname)

getElementsByTagNameNS(
  String namespaceURI,
  localname)

getElementById(
  String elementId)

importNode(
  Node importedNode, 
  Boolean deep)

normalizeDocument()

addAttribute(String name,
  String value,
  [String URI])

addComment(String text)

addDocument(String text,
  [String URI]))

addDocument(
  Function content,
  [String URI]))

const x = new NodeBuilder();
const b = x.addDocument(
  function(builder){
    builder.addElement("foo", 
      "some stuff")});
b.toNode().root;
=>
<foo>some stuff</foo>

addElement(String name,
  String text,
  [String URI])

addElement(String name,
  Function content,
  [String URI])

const x = new NodeBuilder();
const b = x.addElement("foo", 
  function(builder){
    builder.addText("some stuff")});
b.toNode();
=>
<foo>some stuff</foo>

addNode(Node node)

addProcessingInstruction(
  String target,
  String text)

addText(String value)

addBinary(String hex)

addNumber(Number val)

addBoolean(Boolean val)

addNull()

endDocument()

endElement()

startDocument([String URI])

startElement(String name,
  [String URI])

toNode()

const x = new NodeBuilder();
x.startDocument();
x.startElement("foo", "bar");
x.addText("text in bar");
x.endElement();
x.endDocument();
const newNode = x.toNode();
newNode;
// returns a document node with the following serialization:
// <?xml version="1.0" encoding="UTF-8"?>
// <foo xmlns="bar">text in bar</foo>

tagName

getAttribute(String name)

getAttributeNode(String name)

getAttributeNS(
  String namespace,
  String name)

getAttributeNode(String name)

getAttributeNodeNS(
  String namespaceURI,
  String localname)

getElementsByTagName(
  String tagname)

getElementsByTagNameNS(
  String namespaceURI,
  String localname)

hasAttribute(String name)

hasAttributeNS(
  String namespaceURI,
  String localname)

schemaTypeInfo

setAttribute(String name,
  String value)

removeAttribute(String name)

setAttributeNode(Attr newAttr)

removeAttributeNode(
  Attr newAttr)

setAttributeNS(
  String namespaceURI,
  String localname)

removeAttributeNS(
  String namespaceURI,
  String localname)

setIdAttribute(
  String name,
  Boolean isId)

setIdAttributeNS(
  String namespaceURI,
  String localname,
  Boolean isId)

setIdAttributeNode(
  Attr idAttr,
  Boolean isId)

name

specified

value

ownerElement

isId

schemaTypeInfo

data

length

substringData(Number offset,
  Number count)

isElementContentWhitespace

wholeText

target

appendData(String arg)

insertData(Number offset,
  Number count)

deleteData(Number offset,
  Number count)

replaceData(Number offset,
  Number count, 
  String arg)

replaceWholeText(
  String content)

splitText(Number offset)

typeName

typeNamespace

isDerivedFrom(
  String typeNamespace,
  String typeName,
  unsigned long
    derivationMethod)

length

getNamedItem(name)

getNamedItemNS(
  String namespaceURI,
  String localName)

item(Number index)

setNamedItem(Node arg)

removeNamedItem(
  String name)

setNamedItemNS(Node arg)

removeNamedItem(
  String namespaceURI,
  String localname)

length

item(Number index)

Value Object

Value is an object class that wraps MarkLogic XQuery types, enabling you to pass these objects into functions that are designed for those types.

Value supports valueOf and toObject methods for converting the underlying value to its closest native JavaScript value or object. For more details, see Value in the MarkLogic Server-Side JavaScript Function Reference.

Any builtin function whose signature indicates an XML atomic return type such as xs.date, xs.int, or xs.string returns a Value object. A function whose signature indicates a native JavaScript type such as number, boolean, or string returns a simple, native value.

For example, the fn.currentDate builtin function returns a Value representing an xs:date, and its return type in the MarkLogic Server-Side JavaScript Function Reference is xs.date. It returns a Value object that contains an XQuery xs:date value. This enables you to pass the result to date-specific functions such as xdmp.weekFromDate.

Similarly, lexicon functions such as cts.values, cts.words, and cts.geospatialBoxes return a Sequence of Value objects rather than native JavaScript objects in order to preserve type and support passing the Sequence items to cts.frequency.

See the following topics for more details:

• Example: xs:date as Value
• Comparison to Native JavaScript Values
• Example: Comparison between a Value and a Number

xdmp.daynameFromDate(xs.date('1997-07-20'));

fn.currentDate() instanceof Value

xdmp.daynameFromDate(fn.currentDate());

typeof fn.currentDate();                           // object
Object.prototype.toString.call(fn.currentDate());  // [object xs.date]

someDecimalValue == 1

const mlValues = cts.values(cts.pathReference('/my/int/property'));

fn.head(mlValues) == 10;             // true
fn.head(mlValues) === 10;            // false
fn.head(mlValues).valueOf() === 10;  // true
mlValues.toArray().includes(10);     // false
mlValues.toArray().indexOf(10);      // -1 (no match)
fn.head(mlValues) instanceof Value;  // true
typeof fn.head(mlValues);            // 'object'
typeof fn.head(mlValues).valueOf();  // 'number'

Accessing JSON Nodes

When you store JSON in a MarkLogic database, it is stored as a document node with a JSON node child. You can access JSON documents stored in the database with fn.doc, or with any other function that returns a document. You have direct read-only access to the JSON nodes through the native JavaScript properties, including get a named property, querying for the existence of a named property, and enumerate all available named properties.

If you want to convert a JavaScript object to a JSON node, you can call xdmp.toJson on the JavaScript object and it will return a JSON node.

For more details about JSON nodes and documents, see Working With JSON in the Application Developer's Guide.

Sequence

A Sequence is a JavaScript Iterable object that represents a set of values. Many MarkLogic functions that return multiple values do so in Server-Side JavaScript by returning a Sequence. An iterable is a JavaScript object which returns an iterator object from the @@iterator method.

You can iterate over the values in a Sequence using a for..of loop. For example:

for (const doc of fn.collection('/my/coll')) {
  // do something with doc
}

If you want to extract just the first (or only) item in a Sequence without iteration, use fn.head. For example, the xdmp.unquote function returns a Sequence, but in many cases it is a Sequence containing only one item, so you could extract that single result with code like the following:

const node = fn.head(xdmp.unquote('<data>some xml</data>'))

You can create your own Sequence object from an array, an array-like, or another iterable using Sequence.from. For example, the following code snippet creates a Sequence from an array:

const mySeq = Sequence.from([1,2,3,4]);

Use fn.count to count the number of items in a Sequence. For example:

const mySeq = Sequence.from([1,2,3,4]);
fn.count(mySeq);       // returns 4

For more details, see Sequence Object in the MarkLogic Server-Side JavaScript Function Reference.

ValueIterator

This interface is deprecated. As of MarkLogic 9, no MarkLogic functions return a ValueIterator or accept a ValueIterator as input. Use the guidelines in this section to transition your code to Sequence.

Code that manipulates ValueIterator results as described in the following table will continue to work transparently when the return type is Sequence.

const uris = cts.uris('/');
for (const u of uris) {
  // do something with u
}

const uris = cts.uris('/');
uris.next.value();
uris.next.value();
...

fn.head(
  cts.uris('/')
);

cts.uris('/').next().value

fn.count(
  cts.uris('/')
);

cts.uris('/').count

Code that depends on the ValueIterator properties and methods next, count, and clone cannot used with a Sequence value.

You can use the instanceof operator to create code that behaves differently, depending on whether you are working with a ValueIterator or a Sequence. No MarkLogic 8 functions will return a Sequence, so you can be certain that code will not execute in MarkLogic 8.

For example, the following code uses ValueIterator.clone to preserve a set of values across iteration in MarkLogic 8, but skips the unnecessary cloning when the result type becomes Sequence.

const results = cts.uris('/', ['limit=10']);
const clone = {};
if (uris instanceof ValueIterator) {
  // iterator destructive, so clone to preserve orig
  clone = results.clone();
} else if (results instanceof Sequence) {
  // iteration is not destructive, no clone needed
  clone = results;
}
for (const val of clone) {
  // do something with val
}

JavaScript instanceof Operator

The JavaScript instanceof operator is available to test MarkLogic types (in addition to JavaScript types). For example, the following returns true:

const a = Sequence.from(["saab", "alfa romeo", "tesla"]);
a instanceof Sequence;
// returns true

Similarly, the following are some other examples of using instaceof with MarkLogic and JavaScript object types.

An xs.date object type:

const a = fn.currentDate();
a instanceof xs.date;
// returns true

Not an xs.date object type:

const a = fn.currentDate().toObject();
a instanceof xs.date;
// returns false

A JavaScript Date object type:

const a = fn.currentDate().toObject();
a instanceof Date;
// returns true

You can test for any of the following MarkLogic object types using instanceof:

• Value (all MarkLogic Object types are subtypes of Value)
• xs.anyAtomicType
• cts.query (and all of its subtypes--the subtypes are also instance of cts.query)
• ArrayNode
• BinaryNode
• BooleanNode
• ObjectNode
• XMLNode
• Document
• Node
• NodeBuilder
• Attr
• CharacterData
• Comment
• Sequence
• Text
• Element
• ProcessingInstruction
• XMLDocument
• ValueIterator

The following is an example using an XML document:

// assume "/one.xml" has content <name>value</name>
const a = fn.head(fn.doc("/one.xml")).root;
const b = fn.head(a.xpath("./text()"));
b instanceof Text;
// returns true

The following is an example using a JSON document:

// Assume "/car.json" has the content:
// {"car":"The fast electric car drove down the highway."}
const res = new Array();
const a = fn.head(fn.doc("/car.json"));
res.push(a instanceof Document);
const b = a.root;
res.push(b instanceof ObjectNode);
res;
// returns [true, true]

Similarly, you can test for any XML type. Note that the XML types in JavaScript have a dot (.) instead of a colon (:) between the namespace and the type name. For example, xs.integer, xs.string, and so on.

JavaScript Error API

When errors and exceptions are thrown in a Server-Side JavaScript program, a stack is thrown and can be caught using a standard JavaScript try/catch block. For details about each individual error message, see the Messages and Codes Reference Guide. This section includes the following parts:

• JavaScript Error Properties and Functions
• JavaScript stackFrame Properties
• JavaScript try/catch Example

code

data

message

name

retryable

stack

stackFrame

toString()

line

column

operation

uri

language

isEval

variables

contextItem

contextPosition

try{ xdmp.documentInsert("/foo.json", {"foo": "bar"} ); }
catch (err) { err.toString(); }

=> catches the following error 
( because it is missing the declareUpdate() call )
XDMP-UPDATEFUNCTIONFROMQUERY: xdmp:eval("// query

  try{ xdmp.documentInsert("/foo.json", {&q...", ()) 
  -- Cannot apply an update function from a query

JavaScript console Object

MarkLogic implements a console object, which contains functions to do things that log output to ErrorLog.txt in the MarkLogic data directory. The following are the console functions:

• console.assert
• console.debug
• console.dir
• console.error
• console.log
• console.trace
• console.warn

JavaScript Duration and Date Arithmetic and Comparison Methods

XQuery has operators that allow you to perform date math on duration typed data to do things like subtract durations to return dateTime values. In Server-Side JavaScript, you can get data returned in the various dateTime duration types and use the duration methods to add, subtract, multiply, divide and compare those durations. This section describes these duration arithmetic and comparison methods and includes the following parts:

• Arithmetic Methods on Durations
• Arithmetic Methods on Duration, Dates, and Times
• Comparison Methods on Duration, Date, and Time Values

add(xs.yearMonthDuration)

subtract(xs.yearMonthDuration)

multiply(Number)

divide(Number)

divide(xs.yearMonthDuration)

const v1 = xs.yearMonthDuration("P3Y7M");
const v2 = xs.yearMonthDuration("P1Y4M");

const r = {
"v1 + v2" : v1.add(v2),
"v1 - v2" : v1.subtract(v2),
"v1 * 2" : v1.multiply(2),
"v1 / 2" : v1.divide(2),
"v1 / v2" : v1.divide(v2)
};
r;

/*
returns:
{"v1 + v2":"P4Y11M", 
 "v1 - v2":"P2Y3M", 
 "v1 * 2":"P7Y2M", 
 "v1 / 2":"P1Y10M", 
 "v1 / v2":2.6875}
*/

add(xs.dayTimeDuration)

subtract(xs.dayTimeDuration)

multiply(Number)

divide(Number)

divide(xs.dayTimeDuration)

const v1 = xs.dayTimeDuration("P5DT4H");
const v2 = xs.dayTimeDuration("P1DT1H");

const r = {
"v1 + v2" : v1.add(v2),
"v1 - v2" : v1.subtract(v2),
"v1 * 2" : v1.multiply(2),
"v1 / 2" : v1.divide(2),
"v1 / v2" : v1.divide(v2)
};
r;

/*
returns:
{"v1 + v2":"P6DT5H", 
 "v1 - v2":"P4DT3H", 
 "v1 * 2":"P10DT8H", 
 "v1 / 2":"P2DT14H", 
 "v1 / v2":4.96}
*/

add(xs.dayTimeDuration)

add(xs.yearMonthDuration)

subtract(xs.dateTime)

subtract(xs.dayTimeDuration)

subtract(xs.dayTimeDuration)

const v1 = xs.dateTime(xs.date('2013-08-15'), xs.time('12:30:45-05:00'))
const v2 = xs.dateTime(xs.date('2012-04-01'), xs.time('01:10:25-02:00'))
const v3 = xs.yearMonthDuration("P3Y3M")
const v4 = xs.dayTimeDuration("PT1H")

const r = {
"v1 + v3" : v1.add(v3),
"v1 + v4" : v1.add(v4),
"v1 - v2" : v1.subtract(v2),
"v1 - v3" : v1.subtract(v3),
"v1 - v4" : v1.subtract(v4)
};
r;

/*
returns:
{"v1 + v3":"2016-11-15T12:30:45-05:00", 
 "v1 + v4":"2013-08-15T13:30:45-05:00", 
 "v1 - v2":"P501DT14H20M20S", 
 "v1 - v3":"2010-05-15T12:30:45-05:00", 
 "v1 - v4":"2013-08-15T11:30:45-05:00"}
*/

add(xs.dayTimeDuration)

add(xs.yearMonthDuration)

subtract(xs.date)

subtract(xs.dayTimeDuration)

subtract(xs.dayTimeDuration)

const v1 = xs.date('2013-08-15')
const v2 = xs.date('2012-04-01')
const v3 = xs.yearMonthDuration("P3Y3M")
const v4 = xs.dayTimeDuration("P1DT3H")

const r = {
"v1 + v3" : v1.add(v3),
"v1 + v4" : v1.add(v4),
"v1 - v2" : v1.subtract(v2),
"v1 - v3" : v1.subtract(v3),
"v1 - v4" : v1.subtract(v4)
};
r;

/*
returns:
{"v1 + v3":"2016-11-15", 
 "v1 + v4":"2013-08-16", 
 "v1 - v2":"P501D", 
 "v1 - v3":"2010-05-15", 
 "v1 - v4":"2013-08-13"}
*/

add(xs.dayTimeDuration)

subtract(xs.time)

subtract(xs.dayTimeDuration)

const v1 = xs.time('12:30:45-05:00')
const v2 = xs.time('01:10:25-02:00')
const v3 = xs.dayTimeDuration("PT1H")

const r = {
"v1 + v3" : v1.add(v3),
"v1 - v2" : v1.subtract(v2),
"v1 - v3" : v1.subtract(v3)
};
r;

/*
returns:
{"v1 + v3":"13:30:45-05:00", 
 "v1 - v2":"PT14H20M20S", 
 "v1 - v3":"11:30:45-05:00"}
*/

lt(xs.yearMonthDuration)

le(xs.yearMonthDuration)

gt(xs.yearMonthDuration)

ge(xs.yearMonthDuration)

eq(xs.yearMonthDuration)

ne(xs.yearMonthDuration)

const v1 = xs.yearMonthDuration("P3Y7M");
const v2 = xs.yearMonthDuration("P1Y4M");

const r = {
"v1 lt v2" : v1.lt(v2),
"v1 le v2" : v1.le(v2),
"v1 gt v2" : v1.gt(v2),
"v1 ge v2" : v1.ge(v2),
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 lt v2":false, 
 "v1 le v2":false, 
 "v1 gt v2":true, 
 "v1 ge v2":true, 
 "v1 eq v2":false, 
 "v1 ne v2":true}
*/

lt(xs.dayTimeDuration)

le(xs.dayTimeDuration)

gt(xs.dayTimeDuration)

ge(xs.dayTimeDuration)

eq(xs.dayTimeDuration)

ne(xs.dayTimeDuration)

const v1 = xs.dayTimeDuration("P5DT4H");
const v2 = xs.dayTimeDuration("P1DT1H");

const r = {
"v1 lt v2" : v1.lt(v2),
"v1 le v2" : v1.le(v2),
"v1 gt v2" : v1.gt(v2),
"v1 ge v2" : v1.ge(v2),
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 lt v2":false, 
 "v1 le v2":false, 
 "v1 gt v2":true, 
 "v1 ge v2":true, 
 "v1 eq v2":false, 
 "v1 ne v2":true}
*/

lt(xs.dateTime)

le(xs.dateTime)

gt(xs.dateTime)

ge(xs.dateTime)

eq(xs.dateTime)

ne(xs.dateTime)

const v1 = xs.dateTime(xs.date('2013-08-15'), xs.time('12:30:45-05:00'))
const v2 = xs.dateTime(xs.date('2012-04-01'), xs.time('01:10:25-02:00'))

const r = {
"v1 lt v2" : v1.lt(v2),
"v1 le v2" : v1.le(v2),
"v1 gt v2" : v1.gt(v2),
"v1 ge v2" : v1.ge(v2),
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 lt v2":false, 
 "v1 le v2":false, 
 "v1 gt v2":true, 
 "v1 ge v2":true, 
 "v1 eq v2":false, 
 "v1 ne v2":true}
*/

lt(xs.date)

le(xs.date)

gt(xs.date)

ge(xs.date)

eq(xs.date)

ne(xs.date)

const v1 = xs.date('2013-08-15');
const v2 = xs.date('2012-04-01');

const r = {
"v1 lt v2" : v1.lt(v2),
"v1 le v2" : v1.le(v2),
"v1 gt v2" : v1.gt(v2),
"v1 ge v2" : v1.ge(v2),
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 lt v2":false, 
 "v1 le v2":false, 
 "v1 gt v2":true, 
 "v1 ge v2":true, 
 "v1 eq v2":false, 
 "v1 ne v2":true}
*/

lt(xs.time)

le(xs.time)

gt(xs.time)

ge(xs.time)

eq(xs.time)

ne(xs.time)

const v1 = xs.time('12:30:45-05:00');
const v2 = xs.time('01:10:25-02:00');

const r = {
"v1 lt v2" : v1.lt(v2),
"v1 le v2" : v1.le(v2),
"v1 gt v2" : v1.gt(v2),
"v1 ge v2" : v1.ge(v2),
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 lt v2":false, 
 "v1 le v2":false, 
 "v1 gt v2":true, 
 "v1 ge v2":true, 
 "v1 eq v2":false, 
 "v1 ne v2":true}
*/

eq(xs.gYearMonth)

ne(xs.gYearMonth)

const v1 = xs.gYearMonth('2013-08');
const v2 = xs.gYearMonth('2012-04');

const r = {
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 eq v2":false, 
 "v1 ne v2":true}
*/

eq(xs.gYear)

ne(xs.gYear)

const v1 = xs.gYear('2013');
const v2 = xs.gYear('2012');

const r = {
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 eq v2":false, 
 "v1 ne v2":true}
*/

eq(xs.xs.gMonthDay)

ne(xs.xs.gMonthDay)

const v1 = xs.gMonthDay('--08-20');
const v2 = xs.gMonthDay('--04-14');

const r = {
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 eq v2":false, 
 "v1 ne v2":true}
*/

eq(xs.gMonth)

ne(xs.gMonth)

const v1 = xs.gMonth('--08');
const v2 = xs.gMonth('--04');

const r = {
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 eq v2":false, 
 "v1 ne v2":true}
*/

eq(xs.gDay)

ne(xs.gDay)

const v1 = xs.gDay('---08');
const v2 = xs.gDay('---04');

const r = {
"v1 eq v2" : v1.eq(v2),
"v1 ne v2" : v1.ne(v2)
};
r;

/*
returns:
{"v1 eq v2":false, 
 "v1 ne v2":true}
*/

MarkLogic JavaScript Functions

There are a large number of MarkLogic built-in functions available in JavaScript. In general, most functions available in XQuery have siblings that are available in JavaScript. For details on the MarkLogic functions available in JavaScript, see JavaScript Functions and Constructors.