MarkLogic Server Node.js Application Developer’s Guide 1 MarkLogic 10 June, 2019 Last Revised: 10.0-1, June 2019 Copyright © 2019 MarkLogic Corporation. All rights reserved. MarkLogic Server Table of Contents Table of Contents Node.js Application Developer’s Guide 1.0 Introduction to the Node.js Client API ..........................................................9 1.1 Getting Started ........................................................................................................9 1.2 Required Software ................................................................................................14 1.3 Security Requirements ..........................................................................................15 1.3.1 Basic Security Requirements ....................................................................15 1.3.2 Controlling Document Access ..................................................................16 1.3.3 Evaluating Requests Against a Different Database ..................................16 1.3.4 Evaluating or Invoking Server-Side Code ................................................16 1.4 Terms and Definitions ..........................................................................................17 1.5 Key Concepts and Conventions ............................................................................18 1.5.1 MarkLogic Namespace .............................................................................18 1.5.2 Parameter Passing Conventions ................................................................18 1.5.3 Document Descriptor ................................................................................19 1.5.4 Supported Result Handling Techniques ...................................................19 1.5.5 Promise Result Handling Pattern ..............................................................20 1.5.6 Stream Result Handling Pattern ................................................................21 1.5.7 Streaming Into the Database .....................................................................22 1.5.8 Performing Point-in-Time Operations ......................................................23 1.5.9 Error Handling ..........................................................................................24 1.6 Creating a Database Client ...................................................................................25 1.7 Authentication and Connection Security ..............................................................26 1.7.1 Connecting to MarkLogic with SSL .........................................................27 1.7.2 Using SAML Authentication ....................................................................27 1.7.3 Using Certificate-Based Authentication ...................................................28 1.7.3.1 Obtaining a Client Certificate ...................................................28 1.7.3.2 Configuring Your App Server ...................................................29 1.7.3.3 Examples: Database Client Configuration ................................29 1.7.4 Using Kerberos Authentication ................................................................30 1.7.4.1 Configuring MarkLogic to Use Kerberos .................................30 1.7.4.2 Configuring Your Client Host for Kerberos .............................31 1.7.4.3 Creating a Database Client That Uses Kerberos .......................31 1.8 Using the Examples in This Guide .......................................................................31 2.0 Manipulating Documents .............................................................................33 2.1 Introduction to Document Operations ..................................................................33 2.2 Loading Documents into the Database .................................................................36 2.2.1 Overview ...................................................................................................36 2.2.2 Input Document Descriptors .....................................................................37 MarkLogic 10—June, 2019 Node.js Application Developer’s Guide—Page 2 MarkLogic Server Table of Contents 2.2.3 Calling Convention ...................................................................................38 2.2.4 Example: Loading A Single Document ....................................................39 2.2.5 Example: Loading Multiple Documents ...................................................40 2.2.6 Inserting or Updating Metadata for One Document .................................42 2.2.7 Automatically Generating Document URIs ..............................................43 2.2.8 Transforming Content During Ingestion ...................................................43 2.3 Reading Documents from the Database ................................................................44 2.3.1 Retrieving the Contents of a Document By URI ......................................45 2.3.2 Retrieving Metadata About a Document ..................................................46 2.3.3 Example: Retrieving Content and Metadata .............................................48 2.3.4 Transforming Content During Retrieval ...................................................50 2.4 Removing Content from the Database ..................................................................51 2.4.1 Removing Documents By URI .................................................................51 2.4.2 Removing Sets of Documents ...................................................................52 2.4.3 Removing All Documents ........................................................................53 2.5 Managing Collections of Objects and Documents ...............................................54 2.6 Performing a Lightweight Document Check ........................................................56 2.7 Conditional Updates Using Optimistic Locking ...................................................57 2.7.1 Understanding Optimistic Locking ...........................................................57 2.7.2 Enable Optimistic Locking .......................................................................58 2.7.3 Obtain a Version Id ...................................................................................59 2.7.4 Apply a Conditional Update .....................................................................60 2.8 Working with Binary Documents .........................................................................61 2.8.1 Type of Binary Documents .......................................................................61 2.8.2 Streaming Binary Content ........................................................................62 2.8.3 Retrieving Binary Content with Range Requests .....................................62 2.9 Working with Temporal Documents ....................................................................63 2.10 Working with Metadata ........................................................................................64 2.10.1 Metadata Categories .................................................................................64 2.10.2 Metadata Format .......................................................................................65 2.10.3 Working with Document Properties .........................................................67 2.10.4 Disabling Metadata Merging ....................................................................68 2.10.4.1 When to Consider Disabling Metadata Merging .......................68 2.10.4.2 How to Disable Metadata Merging ...........................................69 3.0 Patching Document Content or Metadata ....................................................70 3.1 Introduction to Content and Metadata Patching ...................................................70 3.2 Example: Adding a JSON Property ......................................................................72 3.3 Patch Reference ....................................................................................................73 3.3.1 insert ..........................................................................................................75 3.3.2 replace .......................................................................................................76 3.3.3 replaceInsert ..............................................................................................78 3.3.4 remove ......................................................................................................80 3.3.5 apply ..........................................................................................................81 3.3.6 library ........................................................................................................82 3.3.7 pathLanguage ............................................................................................82 MarkLogic 10—June, 2019 Node.js Application Developer’s Guide—Page 3 MarkLogic Server Table of Contents 3.3.8 collections .................................................................................................82 3.3.9 permissions ...............................................................................................83 3.3.10 properties ..................................................................................................83 3.3.11 quality .......................................................................................................83 3.3.12 metadataValues .........................................................................................83