MarkLogic Server Entity Services Developer’s Guide 1 MarkLogic 10 May, 2019 Last Revised: 10.0-5, July, 2020 Copyright © 2020 MarkLogic Corporation. All rights reserved. MarkLogic Server Table of Contents Table of Contents Entity Services Developer’s Guide 1.0 Introduction to Entity Services ......................................................................6 1.1 Terms and Definitions ............................................................................................7 1.2 Why Use Entity Modeling? ....................................................................................8 1.3 Entity Services Overview .....................................................................................10 1.3.1 Modeling Vocabulary ...............................................................................11 1.3.2 Persistence Convention .............................................................................12 1.3.3 Application Scaffolding ............................................................................13 1.4 Next Steps .............................................................................................................14 1.5 Exploring the Entity Services Open-Source Examples ........................................14 1.5.1 Downloading the Project as a ZIP File .....................................................15 1.6 Security Considerations ........................................................................................15 2.0 Getting Started With Entity Services ...........................................................17 2.1 Before You Begin .................................................................................................17 2.2 Optional: Create a Content Database ....................................................................17 2.3 Getting Started Using XQuery ..............................................................................18 2.3.1 Stage the Source Data ...............................................................................19 2.3.2 Create a Model Descriptor ........................................................................20 2.3.3 Create a Model ..........................................................................................23 2.3.4 Create and Deploy an Instance Converter ................................................25 2.3.4.1 Generate the Default Converter Module ...................................25 2.3.4.2 Customize the Converter Module .............................................26 2.3.4.3 Deploy the Converter Module ...................................................28 2.3.5 Create Entity Instances .............................................................................28 2.3.6 Query the Data ..........................................................................................33 2.3.7 Query the Model .......................................................................................34 2.4 Getting Started Using JavaScript ..........................................................................35 2.4.1 Stage the Source Data ...............................................................................36 2.4.2 Create a Model Descriptor ........................................................................37 2.4.3 Create a Model ..........................................................................................39 2.4.4 Create and Deploy an Instance Converter ................................................41 2.4.4.1 Generate the Default Converter Module ...................................41 2.4.4.2 Customize the Converter Module .............................................43 2.4.4.3 Deploy the Converter Module ...................................................44 2.4.5 Create Entity Instances .............................................................................45 2.4.6 Query the Data ..........................................................................................49 2.4.7 Query the Model .......................................................................................52 2.5 Next Steps .............................................................................................................53 MarkLogic 10—May, 2019 Entity Services Developer’s Guide—Page 2 MarkLogic Server Table of Contents 3.0 Creating and Managing Models ...................................................................54 3.1 Introduction ...........................................................................................................54 3.2 Writing a Model Descriptor ..................................................................................56 3.2.1 Model Descriptor Basics ...........................................................................57 3.2.2 Entity Type Definition Overview .............................................................58 3.2.3 Defining an Entity Property with a SimpleType ......................................61 3.2.4 Defining an Entity Property with a Complex Type ..................................62 3.2.5 Defining an Entity Property with Array Type ..........................................63 3.2.6 Defining an IRI Entity Property ................................................................64 3.2.7 Identifying the Primary Key Entity Property ............................................64 3.2.8 Identifying Personally Identifiable Information (PII) ...............................66 3.2.9 Distinguishing Required and Optional Entity Properties .........................67 3.2.10 Defining a Namespace URI for an Entity Type ........................................68 3.2.11 Identifying Entity Properties for Indexing ................................................72 3.2.11.1 Specifying Indexable Properties ................................................72 3.2.11.2 Interaction with Generated Artifacts .........................................73 3.2.11.3 Example: Identifying Indexable Entity Properties ....................74 3.2.11.4 Supported Datatypes .................................................................75 3.2.12 Controlling the Model IRI and Module Namespaces ...............................76 3.3 Defining Entity Relationships ...............................................................................77 3.3.1 Defining a Local Entity Reference ...........................................................78 3.3.2 Defining an External Entity Reference .....................................................79 3.4 Creating a Model from a Model Descriptor ..........................................................80 3.5 Working With an XML Model Descriptor ...........................................................81 3.6 Validating a Model Descriptor .............................................................................82 3.7 Extending a Model with Additional Facts ............................................................84 3.8 Managing Model Changes ....................................................................................85 3.8.1 Generating Instances From the New Model .............................................85 3.8.2 Replacing the Old Model with a New Version .........................................87 3.8.3 Making Multiple Model Versions Available ............................................87 3.8.3.1 Instance Data .............................................................................88 3.8.3.2 Entity Type Schema ..................................................................89 3.8.3.3 TDE Template ...........................................................................90 3.8.3.4 Query Options ...........................................................................90 3.8.3.5 Database Configuration .............................................................90 3.9 Model Descriptor Syntax Reference .....................................................................91 3.9.1 model_info ................................................................................................91 3.9.1.1 Syntax Summary .......................................................................91 3.9.1.2 Component Description .............................................................92 3.9.1.3 Examples ...................................................................................93 3.9.2 entity_type_definition ...............................................................................93 3.9.2.1 Syntax Summary .......................................................................94 3.9.2.2 Component Description .............................................................95 3.9.2.3 Examples ...................................................................................97 3.9.2.4 See Also .....................................................................................98 3.9.3 property_definition ...................................................................................98 MarkLogic 10—May, 2019 Entity Services Developer’s Guide—Page 3 MarkLogic Server Table of Contents 3.9.3.1 Syntax Summary .......................................................................99 3.9.3.2 Component Description ...........................................................100 3.9.3.3 Examples .................................................................................101 3.9.3.4 See Also ...................................................................................102 3.9.4 property_type ..........................................................................................102 4.0 Generating Code and Other