Entities

Overview

Entities are the high-level business objects in your enterprise. For example, employee, product, purchase order, or department.

In MarkLogic Data Hub, you can use MarkLogic's Entity Services to create models of your business entities and to generate code scaffolding, database configurations, index settings, and validations based on those models. Entity Services handles the model definition and entity instance documents through API calls. If you use your own abstract entities, you must provide this framework.

Note: MarkLogic strongly recommends that you use Entity Services unless you have specific needs that it cannot address.

An entity model is comprised of entity types.

  • An entity type is a data type to which each record of your data will be standardized, so that data from all sources can be viewed and used uniformly. An entity type is comprised of entity properties.
  • An entity property is a data field in a record of your data.
  • An entity instance is a copy of the entity type structure, which is added to your data record during mapping and then populated with values from the raw data.

All the data about an entity is consolidated in a single record, which contains the standardized entity instance, the original raw data, the provenance and lineage, and other metadata. The provenance and lineage information includes the changes that occurred from the raw data to the most recent entity instance.

Note: An entity model is not required to ingest your raw data. However, it is required to configure your mapping.

See:

Entity Model Validation

Only valid entity models are loaded into the MarkLogic Server instance. A valid entity model meets the following requirements:

  • info/baseUri in the model must have a value that is a valid URI.
  • The model must pass the Entity Services validation function es:model-validate.

If the entity model is valid and loaded, Data Hub creates the following in the STAGING and FINAL databases:

  • schema files:
    • /entities/YourEntityName.entity.json. The validated entity model returned by es:model-validate.
    • /entities/YourEntityName.entity.schema.json. The entity model as a JSON schema for use in XDMP validation (xdmp.jsonValidate).
    • /entities/YourEntityName.entity.xsd. The entity model as a XSD schema for use in XDMP validation (xdmp.validate).
  • a TDE template (/tde/YourEntityName-YourEntityVersion.tdex) with the following permissions:
    • read permissions for the data-hub-operator
    • update permissions for the data-hub-developer
    • default permissions allowed to the user who loaded the entity model to MarkLogic Server
    Important: In MarkLogic 10 and later versions, a user assigned to the admin role only must be explicitly given read access to view the TDE template.

    If a TDE template with the same URI already exists but is not in the ml-data-hub-tde collection, a new TDE template will not be created.