WIXLIB

MarkLogic ServerNode.js Application Developer’sGuide1MarkLogic 10June, 2019Last Revised: 10.0-9, February, 2022Copyright 2022 MarkLogic Corporation. All rights reserved.

MarkLogic ServerTable of ContentsTable of ContentsNode.js Application Developer’s Guide1.0Introduction to the Node.js Client API .91.11.21.31.41.51.61.71.82.0Getting Started .9Required Software .14Security Requirements .151.3.1 Basic Security Requirements .151.3.2 Controlling Document Access .161.3.3 Evaluating Requests Against a Different Database .161.3.4 Evaluating or Invoking Server-Side Code .16Terms and Definitions .17Key Concepts and Conventions .181.5.1 MarkLogic Namespace .181.5.2 Parameter Passing Conventions .181.5.3 Document Descriptor .191.5.4 Supported Result Handling Techniques .191.5.5 Promise Result Handling Pattern .201.5.6 Stream Result Handling Pattern .211.5.7 Streaming Into the Database .221.5.8 Performing Point-in-Time Operations .231.5.9 Error Handling .24Creating a Database Client .25Authentication and Connection Security .261.7.1 Connecting to MarkLogic with SSL .271.7.2 Using SAML Authentication .271.7.3 Using Certificate-Based Authentication .281.7.3.1 Obtaining a Client Certificate .281.7.3.2 Configuring Your App Server .291.7.3.3 Examples: Database Client Configuration .291.7.4 Using Kerberos Authentication .301.7.4.1 Configuring MarkLogic to Use Kerberos .301.7.4.2 Configuring Your Client Host for Kerberos .311.7.4.3 Creating a Database Client That Uses Kerberos .31Using the Examples in This Guide .31Manipulating Documents .332.12.2Introduction to Document Operations .33Loading Documents into the Database .362.2.1 Overview .362.2.2 Input Document Descriptors .37MarkLogic 10—June, 2019Node.js Application Developer’s Guide—Page 2

MarkLogic Server2.32.42.52.62.72.82.92.103.0Table of Contents2.2.3 Calling Convention .382.2.4 Example: Loading A Single Document .392.2.5 Example: Loading Multiple Documents .402.2.6 Inserting or Updating Metadata for One Document .422.2.7 Automatically Generating Document URIs .432.2.8 Transforming Content During Ingestion .43Reading Documents from the Database .442.3.1 Retrieving the Contents of a Document By URI .452.3.2 Retrieving Metadata About a Document .462.3.3 Example: Retrieving Content and Metadata .482.3.4 Transforming Content During Retrieval .50Removing Content from the Database .512.4.1 Removing Documents By URI .512.4.2 Removing Sets of Documents .522.4.3 Removing All Documents .53Managing Collections of Objects and Documents .54Performing a Lightweight Document Check .56Conditional Updates Using Optimistic Locking .572.7.1 Understanding Optimistic Locking .572.7.2 Enable Optimistic Locking .582.7.3 Obtain a Version Id .592.7.4 Apply a Conditional Update .60Working with Binary Documents .612.8.1 Type of Binary Documents .612.8.2 Streaming Binary Content .622.8.3 Retrieving Binary Content with Range Requests .62Working with Temporal Documents .63Working with Metadata .642.10.1 Metadata Categories .642.10.2 Metadata Format .652.10.3 Working with Document Properties .672.10.4 Disabling Metadata Merging .682.10.4.1 When to Consider Disabling Metadata Merging .682.10.4.2 How to Disable Metadata Merging .69Patching Document Content or Metadata .703.13.23.3Introduction to Content and Metadata Patching .70Example: Adding a JSON Property .72Patch Reference .733.3.1 insert .753.3.2 replace .763.3.3 replaceInsert .783.3.4 remove .803.3.5 apply .813.3.6 library .823.3.7 pathLanguage .82MarkLogic 10—June, 2019Node.js Application Developer’s Guide—Page 3

MarkLogic Server3.43.53.63.73.83.94.0Table of Contents3.3.8 collections .823.3.9 permissions .833.3.10 properties .833.3.11 quality .833.3.12 metadataValues .83Defining the Context for a Patch Operation .84How Position Affects the Insertion Point .84Patch Examples .863.6.1 Preparing to Run the Examples .863.6.2 Example: Insert .873.6.3 Example: Replace .903.6.4 Example: ReplaceInsert .933.6.5 Example: Remove .963.6.6 Example: Patching Metadata .99Creating a Patch Without a Builder .102Patching XML Documents .103Constructing Replacement Data on MarkLogic Server .1043.9.1 Overview of Replacement Constructor Functions .1053.9.2 Using a Builtin Replacement Constructor .1063.9.3 Passing Parameters to a Replacement Constructor .1073.9.4 Using a Custom Replacement Constructor .1073.9.5 Writing a Custom Replacement Constructor .1083.9.6 Installing or Updating a Custom Replace Library .1093.9.7 Uninstalling a Custom Replace Library .1103.9.8 Example: Custom Replacement Constructors .1113.9.9 Additional Operations .116Querying Documents and Metadata .1174.14.24.34.4Query Interface Overview .117Introduction to Search Concepts .1184.2.1 Search Overview .1184.2.2 Query Styles .1194.2.3 Types of Query .1204.2.4 Indexing .122Understanding the queryBuilder Interface .122Searching with String Queries .1254.4.1 Introduction to String Query .1254.4.2 Example: Basic String Query .1264.4.3 Using Constraints in a String Query .1284.4.4 Example: Using Constraints in a String Query .1294.4.5 Using a Custom Constraint Parser .1314.4.6 Example: Custom Constraint Parser .1324.4.6.1 Implementing the Constraint Parser .1324.4.6.2 Installing the Constraint Parser .1334.4.6.3 Using the Custom Constraint in a String Query .1334.4.7 Additional Information .135MarkLogic 10—June, 2019Node.js Application Developer’s Guide—Page 4

MarkLogic Server4.54.64.74.84.94.104.114.124.135.0Table of ContentsSearching with Query By Example .1354.5.1 Introduction to QBE .1354.5.2 Creating a QBE with queryBuilder .1364.5.3 Querying XML Content With QBE .1384.5.4 Additional Information .139Searching with Structured Queries .1404.6.1 Basic Usage .1404.6.2 Example: Using Structured Query .1404.6.3 Builder Methods Taxonomy Reference .1424.6.3.1 Basic Content Queries .1434.6.3.2 Logical Composers .1454.6.3.3 Location Qualifiers .1454.6.3.4 Document Selectors .1474.6.4 Query Parameter Helper Functions .1474.6.5 Search Result Refiners .149Searching with Combined Query .150Searching Values Metadata Fields .152Querying Lexicons and Range Indexes .1524.9.1 Querying Values in a Lexicon or Range Index .1534.9.2 Finding Value Co-Occurrences in Lexicons .1554.9.3 Building an Index Reference .1574.9.4 Refining the Results of a Values or Co-Occurrence Query .1584.9.5 Analyzing Lexicons and Range Indexes with Aggregate Functions .1594.9.5.1 Aggregate Function Overview .1594.9.5.2 Using Builtin Aggregate Functions .1594.9.5.3 Using User-Defined Aggregate Functions .160Generating Search Facets .1614.10.1 Defining a Simple Facet .1614.10.2 Naming a Facet .1634.10.3 Including Facet Options .1634.10.4 Defining Bucket Ranges .1634.10.5 Creating and Using Custom Constraint Facets .164Refining Query Results .1654.11.1 Available Refinements .1654.11.2 Paginating Query Results .1664.11.3 Returning Metadata .1674.11.4 Excluding Document Descriptors or Values From Search Results .1674.11.5 Generating Search Snippets .1684.11.6 Transforming the Search Results .1694.11.7 Extracting a Portion of Each Matching Document .170Generating Search Term Completion Suggestions .1734.12.1 Understanding the Suggestion Interface .1734.12.2 Example: Generating Search Term Suggestions .176Loading the Example Data .179Using the Optic API for Relational Operations .183MarkLogic 10—June, 2019Node.js Application Developer’s Guide—Page 5

MarkLogic uction to the Optic Interfaces .183Interface Summary .184Preparing to Run the Examples .184Generating a Plan .185Invoking a Plan .186Configuring Row Set Format .1895.6.1 Configuration Options .1895.6.2 Layout Examples .189Streaming Row Data .1935.7.1 Object Mode Streaming .1935.7.2 Chunked Mode Streaming .1955.7.3 Sequence Mode Streaming .195Passing Parameters into a Plan .197Handling Complex Column Values .197Generating an Execution Plan .198Serializing a Plan .199Working With Semantic Data .2016.16.26.36.46.56.66.77.0Table of ContentsOverview of Common Semantics Tasks .201Loading Triples .202Querying Semantic Triples With SPARQL .204Example: SPARQL Query .205Managing Graphs .2066.5.1 Creating or Replacing a Graph .2076.5.2 Adding Triples to an Existing Graph .2076.5.3 Removing a Graph .2086.5.4 Retrieving the Contents, Metadata, or Permissions of a Graph .2096.5.5 Testing for Graph Existence .2106.5.6 Retrieving a List of Graphs .211Using SPARQL Update to Manage Graphs and Graph Data .211Applying Inferencing Rules to a SPARQL Query or Update .2136.7.1 Basic Inference Ruleset Usage .2136.7.2 Example: SPARQL Query With Inference Ruleset .2146.7.3 Example: SPARQL Update With Inference Rulesets .2146.7.4 Controlling the Default Database Ruleset .214Managing Transactions .2167.17.27.37.47.57.67.77.8Transaction Overview .216Creating a Transaction .217Associating a Transaction with an Operation .218Committing a Transaction .219Rolling Back a Transaction .219Example: Using Promises With a Multi-Statement Transaction .220Checking Transaction Status .220Managing Transactions When Using a Load Balancer .220MarkLogic 10—June, 2019Node.js Application Developer’s Guide—Page 6

MarkLogic Server8.0Extensions, Transformations, and Server-Side Code Execution .2238.18.28.38.48.58.69.0Table of ContentsWays to Extend and Customize the API .223Working with Resource Service Extensions .2248.2.1 What is a Resource Service Extension? .2248.2.2 Creating a Resource Service Extension .2258.2.3 Installing a Resource Service Extension .2258.2.4 Using a Resource Service Extension .2278.2.5 Example: Installing and Using a Resource Service Extension .2288.2.6 Retrieving the Implementation of a Resource Service Extension .2318.2.7 Discovering Resource Service Extensions .2318.2.8 Deleting Resource Service Extensions .232Working with Content Transformations .2338.3.1 What is a Content Transformation? .2338.3.2 Creating a Transformation .2348.3.3 Installing a Transformation .2348.3.4 Using a Transformation .2358.3.5 Example: Read, Write, and Query Transforms .2378.3.5.1 Install the Transforms .2378.3.5.2 Use the Write Transform .2388.3.5.3 Use the Read Transform .2408.3.5.4 Use the Query Transform .2418.3.5.5 Read Transform Source Code .2438.3.5.6 Write Transform Source Code .2448.3.5.7 Query Transform Source Code .2458.3.6 Discovering Installed Transforms .2468.3.7 Deleting a Transformation .246Error Reporting in Extensions and Transformations .2478.4.1 Example: Reporting Errors in JavaScript .2478.4.2 Example: Reporting Errors in XQuery .249Evaluating Ad-Hoc Code and Server-Side Modules .2508.5.1 Required Privileges .2508.5.2 Evaluating a Ad-Hoc Query .2518.5.3 Invoking a Module Installed on MarkLogic Server .2538.5.4 Interpreting the Results of Eval or Invoke .2558.5.5 Specifying External Variable Values .256Managing Assets in the Modules Database .2578.6.1 Overview of Asset Management .2588.6.2 Installing or Updating an Asset .2608.6.3 Referencing an Asset from Server-Side Code .2608.6.4 Removing an Asset .2618.6.5 Retrieving an Asset List .2618.6.6 Retrieving an Asset .262Administering REST API Instances .2639.1What Is a REST API Instance? .263MarkLogic 10—June, 2019Node.js Application Developer’s Guide—Page 7