MarkLogic Server Node.js Application Developer’s Guide 1 MarkLogic 9 May, 2017 Last Revised: 9.0-4, January 2018 Copyright © 2018 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 .........................................................26 1.7.2 Using Certificate-Based Authentication ...................................................27 1.7.2.1 Obtaining a Client Certificate ...................................................27 1.7.2.2 Configuring Your App Server ...................................................28 1.7.2.3 Examples: Database Client Configuration ................................28 1.7.3 Using Kerberos Authentication ................................................................29 1.7.3.1 Configuring MarkLogic to Use Kerberos .................................29 1.7.3.2 Configuring Your Client Host for Kerberos .............................29 1.7.3.3 Creating a Database Client That Uses Kerberos .......................30 1.8 Using the Examples in This Guide .......................................................................30 2.0 Manipulating Documents .............................................................................32 2.1 Introduction to Document Operations ..................................................................32 2.2 Loading Documents into the Database .................................................................35 2.2.1 Overview ...................................................................................................35 2.2.2 Input Document Descriptors .....................................................................36 2.2.3 Calling Convention ...................................................................................37 MarkLogic 9—May, 2017 Node.js Application Developer’s Guide—Page 2 MarkLogic Server Table of Contents 2.2.4 Example: Loading A Single Document ....................................................38 2.2.5 Example: Loading Multiple Documents ...................................................39 2.2.6 Inserting or Updating Metadata for One Document .................................41 2.2.7 Automatically Generating Document URIs ..............................................42 2.2.8 Transforming Content During Ingestion ...................................................42 2.3 Reading Documents from the Database ................................................................43 2.3.1 Retrieving the Contents of a Document By URI ......................................44 2.3.2 Retrieving Metadata About a Document ..................................................45 2.3.3 Example: Retrieving Content and Metadata .............................................47 2.3.4 Transforming Content During Retrieval ...................................................49 2.4 Removing Content from the Database ..................................................................50 2.4.1 Removing Documents By URI .................................................................50 2.4.2 Removing Sets of Documents ...................................................................51 2.4.3 Removing All Documents ........................................................................52 2.5 Managing Collections of Objects and Documents ...............................................53 2.6 Performing a Lightweight Document Check ........................................................55 2.7 Conditional Updates Using Optimistic Locking ...................................................56 2.7.1 Understanding Optimistic Locking ...........................................................56 2.7.2 Enable Optimistic Locking .......................................................................57 2.7.3 Obtain a Version Id ...................................................................................58 2.7.4 Apply a Conditional Update .....................................................................59 2.8 Working with Binary Documents .........................................................................60 2.8.1 Type of Binary Documents .......................................................................60 2.8.2 Streaming Binary Content ........................................................................61 2.8.3 Retrieving Binary Content with Range Requests .....................................61 2.9 Working with Temporal Documents ....................................................................62 2.10 Working with Metadata ........................................................................................63 2.10.1 Metadata Categories .................................................................................63 2.10.2 Metadata Format .......................................................................................64 2.10.3 Working with Document Properties .........................................................66 2.10.4 Disabling Metadata Merging ....................................................................67 2.10.4.1 When to Consider Disabling Metadata Merging .......................67 2.10.4.2 How to Disable Metadata Merging ...........................................67 3.0 Patching Document Content or Metadata ....................................................69 3.1 Introduction to Content and Metadata Patching ...................................................69 3.2 Example: Adding a JSON Property ......................................................................71 3.3 Patch Reference ....................................................................................................72 3.3.1 insert ..........................................................................................................74 3.3.2 replace .......................................................................................................75 3.3.3 replaceInsert ..............................................................................................77 3.3.4 remove ......................................................................................................79 3.3.5 apply ..........................................................................................................80 3.3.6 library ........................................................................................................81 3.3.7 pathLanguage ............................................................................................81 3.3.8 collections .................................................................................................81 MarkLogic 9—May, 2017 Node.js Application Developer’s Guide—Page 3 MarkLogic Server Table of Contents 3.3.9 permissions ...............................................................................................82 3.3.10 properties ..................................................................................................82 3.3.11 quality .......................................................................................................82 3.3.12 metadataValues .........................................................................................82 3.4 Defining the Context for a Patch Operation .........................................................83