Entity Formats

Result Property

The "result" property of many API methods represents Entity object(s) or objects that embed Entity objects. Some system attributes of an Entity object, such as Context, Source and Destination, may also contain Entity objects. For details on MM system attributes, refer to Metadata Query Language (MQL).

Legacy Entity Format

A legacy Entity format consists of the following properties. Not all properties are required.

• id

• name

• objectType

• attributes

• labels

• parentId

• term

• dataClassifications

Following is a sample Entity object in the legacy Entity format:

{
"attributes":
    [
        {
        "attributeType":
            {
            "displayName": "Last Modified Date",
            "name": "Last Modified Date",
            "type": "SYSTEM_ATTRIBUTE"
            },
        "value": "2018-09-24 13:47:37"
        },
        {
        "attributeType":
            {
            "displayName": "Name",
            "name": "Name",
            "type": "SYSTEM_ATTRIBUTE"
            },
        "value": "CategoryGroup"
        },
        {
        "attributeType":
            {
            "displayName": "Native Type",
            "name": "Native Type",
            "type": "ATTRIBUTE"
            },
        "value": "TABLE"
        }
    ],
"id": "73555_35",
"name": "CategoryGroup",
"objectType":
    {
    "displayName": "RDBMS Relational Database (Database).Table",
    "name": "RDBMS Relational Database (Database).Table"
    },
"parentId": "73555_28"
}

MQL Entity Format

The new Entity format, also known as the MQL Entity Format, is based on the SELECT list of an MQL query. The new Entity format contains a single "attributes" property which consists of the attribute type names that appear in the "select" property. For MQL SELECT list details, refer to Metadata Query Language (MQL).

Following is a sample Entity object in the MQL Entity Format which corresponds to the SELECT list: Name, "Object Type", "Object Id":

{
"attributes":
    [
        {
        "attributeType":
            {
            "displayName": "Name",
            "name": "Name",
            "type": "SYSTEM_ATTRIBUTE"
            },
        "value": "PurchaseOrder"
        },
        {
        "attributeType":
            {
            "displayName": "Object Type",
            "name": "Object Type",
            "type": "SYSTEM_ATTRIBUTE"
            },
        "value": "Table"
        },
        {
        "attributeType":
            {
            "displayName": "Object Id",
            "name": "Object Id",
            "type": "SYSTEM_ATTRIBUTE"
            },
        "value": "69585_200"
        }
    ]
}

Every legacy Entity property can be mapped to an MM system attribute. Here is the mapping between the legacy Entity properties and MM system attributes.

Legacy Entity Property	MM System Attribute
id	"Object Id"
name	Name
objectType	"Object Type"
labels	Labels
parentId	Context
term	"Term Classification"
semanticTypes	"Data Classifications"

API Methods Returning Entity Object(s)

Some API methods return Entity objects in the Legacy Entity format only. Some API methods may return both formats depending on the value of the input. In general, the MQL Entity format is used whenever there is a "select" property/parameter specified.

API method	Legacy format	MQL format
GET /entities/{objectId}	If "select" parameter is not specified	If "select" parameter is specified
GET /relationships/{objectId}	If "select" parameter is not specified	If "select" parameter is specified
POST /entities/executeMQLQuery	If "legacyEntityFormat" is set to true	If "legacyEntityFormat" is set to false
GET /repository/getContext	Always
GET /configuration/listModels	Always
GET /entities/reports/{termId}	Always
GET /configurations/listConnectedModels	Always

The entity objects that the system attributes such as Context, Source and Destination, may have are always returned in the legacy entity format even though the object itself may be represented in the MQL entity format.

Following is a sample Entity object in the MQL Entity Format which corresponds to the SELECT list: Name, Context:

{
"attributes":
    [
        {
        "attributeType":
            {
            "displayName": "Name",
            "name": "Name",
            "type": "ATTRIBUTE"
            },
        "value": "Employee Sales by Country"
        },
        {
        "attributeType":
            {
            "displayName": "Context",
            "name": "Context",
            "type": "SYSTEM_ATTRIBUTE"
            },
        "value":
            [
                {
                "id": "20_1",
                "name": "Northwind",
                "objectType":
                    {
                    "displayName": "RDBMS Relational Database (Server).Database Server",
                    "name": "RDBMS Relational Database (Server).Database Server"
                    }
                },
                {
                "id": "22_1",
                "name": "dbo",
                "objectType":
                    {
                    "displayName": "RDBMS Relational Database (Database).Database Schema",
                    "name": "RDBMS Relational Database (Database).Database Schema"
                    }
                }
            ]
        }
    ]
}

The entity objects embedded within the system attributes contain only the following properties: id, name and objectType.