Modeling with Quickstart or Gradle

Complex Entities

You can define your entity type to include another entity type or to link to another.

  • A local entity reference refers to an entity that is nested within the host entity as the value of a property. Use a nested entity if the values of its properties will change for every host entity. For example, an entity FullName can be nested in the entity Employee, because each employee would have a different full name.
  • An external entity reference refers to an entity that is stored separately, and the host entity contains only a link to it. Link to an entity if the values of its properties must remain the same for all host entities. For example, an entity Product can be linked in the entity Order, because the SKU and product description will be the same for all customer orders.
  • When mapping a nested entity (local entity reference), the type of the source data element must match one of the following:
    • an object, if Cardinality is set to 1..1, or
    • an array of objects, if Cardinality is set to 1..∞.
  • When mapping a linked entity (external entity reference), the type of the source data element must be a string which holds the URI of the linked entity.

Each nested entity object includes the name of the entity model as well as its properties. In the following example, the entity type Person contains the properties name and address. The property name holds a nested entity based on the entity model FullName.

   "instance": {
    "Person": {
      "name": {
        "FullName": {
          "title": "Mr.",
          "first": "John",
          "middle": "Doe",
          "last": "Smith"
      "address": "..."

Additional Artifacts

Additional artifacts associated with an entity model can be generated:

  • Database property files
  • PII protected paths and query rolesets
  • Search option files

Using QuickStart: When an entity model is saved in QuickStart, these artifacts are automatically generated and stored in the local project structure. If you click Yes to update the indexes after the entity model is saved, these artifacts are also deployed to the MarkLogic Server.

Using Gradle: You can also generate and deploy the following artifacts using the Gradle task hubDeploy or hubDeployAsDeveloper.

  • Database property files that include indexes you selected for the properties of all entity models:
    • your-project-root/src/main/entity-config/databases/staging-database.json
    • your-project-root/src/main/entity-config/databases/final-database.json
  • Protected paths and query rolesets for properties marked as Personally Identifiable Information (PII).
  • Search option files:
    • your-project-root/src/main/entity-config/staging-entity-options.xml
    • your-project-root/src/main/entity-config/final-entity-options.xml

Learn more about hubDeploy and hubDeployAsDeveloper.