Data Governance
Also available as:
PDF
loading table of contents...

Atlas Classifications

Classifications were introduced in the Atlas Types section as one of the composite metatypes, along with Entities and Structs. Classifications share similarities with these other composite metatypes in that they define a Type and have a uniquely identifiable name in the type system. They can also have a set of attributes, although these attributes can only be of native types.

Like Entities, Classifications can extend from other super Classifications, and thus inherit attributes defined in those super Classifications. However, unlike Entities, Classification instances are not entities. They do not have a uniquely-identifiable GUID, and consequently they cannot be referenced from attributes in other types. Therefore, the way in which a Classification instance is defined and used is different than the way in which an entity is defined and used.

Classification instances also have one other special significance in Atlas. They can be associated with any entity in Atlas without prior declaration of this fact in the Type definition of the entity. Note that, in contrast, defining an entity reference in a type must declared a priori (for example, HBase table references to an HBase namespace should be declared up-front). The Atlas type system recognizes Classifications, and includes specific APIs that can be used to associate Classifications with entities.

[Note]Note

Atlas Classifications cannot be deleted.

Create Classifications

Description:

Because Classifications are Atlas Types, the same APIs used to create Types are used to create Classifications, except that Attribute definitions cannot refer to non-native metatypes.

Request:

POST http://<atlas-server-host:port>/api/atlas/v2/types/typedefs

Request Body:

The body for this request is the same structure as the TypesDef structure that is defined in Important Atlas API Data Types. The Classifications should be defined under the classificationDefs attribute.

Response:

The response is the same as the response for a Type Definition request, and contains the names of the defined Classifications.

Example:

Using our running example, we will define two Classifications:

  • PublicData – Any metadata marked with this Classification indicates that this data was collected from publicly available sources. Therefore, any policies applicable to publicly collected data can be applied to this data.

  • Retainable – This Classification indicates that any metadata associated with this Classification should be retained for a period of time. The time period is maintained in an a retentionPeriod attribute, which is the duration in days.

Example Request Body:

{
  "enumDefs":[],
  "structDefs":[],
  "classificationDefs":[
    {
      "superTypes":[],
      "category":"CLASSIFICATION",
      "name":"PublicData",
      "description":null,
      "attributeDefs":[]
    },
    {
      "superTypes":[],
      "category":"CLASSIFICATION",
      "name":"Retainable",
      "description":null,
      "attributeDefs":[
        {
          "name":"retentionPeriod",
          "typeName":"int",
          "isOptional":false,
          "isUnique":false,
          "isIndexable":true,
          "constraints":null
        }
      ]
    }
  ],
  "entityDefs":[]
}

Note that the classificationDefs attribute contains the defined Classifications. The rest of the metatypes – structs, enums, and Entities – are empty. The retentionPeriod attribute is defined as an int in the Retainable Classification.

Example Response:

{
  "requestId": "qtp221036634-18 - 59cbed8a-3637-496f-8b40-80ec829ce493",
  "types": [
    {
      "name": "Retainable"
    },
    {
      "name": "PublicData"
    }
  ]
}

List Classifications

Description:

Because Classifications are a specific metatype (like Entities), the same API used to list a specific metatype can be used to list Classifications.

Request:

GET http://<atlas-server-host:port>/api/atlas/types?type=CLASSIFICATION

Response:

The response is a list of Classification names.

Example Response:

{
  "results": [
    "Retainable",
    "PublicData"
  ],
  "count": 2,
  "requestId": "qtp221036634-16 - 423d9f90-79ae-4b29-b9bf-2d2a1d05c2bd"
}

Retrieve a Classification

Description:

Because Classifications are a specific metatype (like Entities), the same API used to retrieve a specific metatype can be used to retrieve a Classification.

Request:

GET http://<atlas-server-host:port>/api/atlas/types/{Classification_name}

Response:

The response for this request is the same structure as the TypesDef structure that is defined in Important Atlas API Data Types. The ClassificationTypes attribute contains the type definition of the Classification specified in the request.

Example Request:

GET http://<atlas-server-host:port>/api/atlas/types/Retainable

Example Response:

{
  "typeName": "Retainable",
  "definition": {
    "enumTypes": [],
    "structTypes": [],
    "ClassificationTypes": [
      {
        "superTypes": [],
        "hierarchicalMetaTypeName": "org.apache.atlas.typesystem.types.ClassificationType",
        "typeName": "Retainable",
        "typeDescription": null,
        "attributeDefinitions": [
          {
            "name": "retentionPeriod",
            "dataTypeName": "int",
            "multiplicity": "required",
            "isComposite": false,
            "isUnique": false,
            "isIndexable": true,
            "reverseAttributeName": null
          }
        ]
      }
    ],
    "classTypes": []
  },
  "requestId": "qtp221036634-204 - b9f43388-49d8-452b-8901-d05581d2b442"
}

Associate Classification Instances with Entities

Description:

To catalog entities using Classifications, we must associate Classification instances with entities.

Request:

POST http://<atlas-server-host:port>/api/atlas/entities/{entity_guid}/Classifications

Request Body:

The request body is a Classification InstanceDefinition structure that is defined in Important Atlas API Data Types.

Response:

No data is returned in the response. A 201 status code indicates success.

Example:

In this example, we annotate our webtable (GUID f4019a65-8948-46f1-afcf-545baa2df99f) with PublicData Classification to indicate that it is a data asset that is created by crawling public sites. We also set a Retainable Classification on the column family contents (GUID 9e6308c6-1006-48f8-95a8-a605968e64d2) with a retention period of 100 days.

The following requests would be sent:

Example Request:

POST http://<atlas-server-host:port>/api/atlas/entities/f4019a65-8948-46f1-afcf-545baa2df99f/Classifications

Example Request Body:

{
  "jsonClass":"org.apache.atlas.typesystem.json.InstanceSerialization$_Struct",
  "typeName":"PublicData",
  "values":{
    
  }
}

Example Request:

POST http://<atlas-server-host:port>/api/atlas/entities/9e6308c6-1006-48f8-95a8-a605968e64d2/Classifications

Example Request Body:

{
  "jsonClass":"org.apache.atlas.typesystem.json.InstanceSerialization$_Struct",
  "typeName":"Retainable",
  "values":{
    "retentionPeriod":"100"
  }
}

Read Classification Instances Associated with Entities

Description:

When Classification instances are associated with entities according to structure that is defined in Important Atlas API Data Types, the EntityDefinition includes the ClassificationNames and Classifications attributes. A request for an EntityDefinition returns a response that includes the ClassificationNames and Classification values.

Request:

GET http://<atlas-server-host:port>/api/atlas/entities/{entity_guid}

Example Request:

This is a request for an HBase table EntityDefinition.

GET http://<atlas-server-host:port>/api/atlas/entities/f4019a65-8948-46f1-afcf-545baa2df99f

Example Response:

For the sake of brevity, only the ClassificationNames and Classification values are shown below.

{
    ...
    "typeName": "hbase_table",
    "values": {
      ...
      "columnFamilies": [
        {
          "typeName": "hbase_column_family",
          "values": {
            "qualifiedName": "default.webtable.contents@cluster2",
          },
          "ClassificationNames": [
            "Retainable"
          ],
          "Classifications": {
            "Retainable": {
              "jsonClass": "org.apache.atlas.typesystem.json.InstanceSerialization$_Struct",
              "typeName": "Retainable",
              "values": {
                "retentionPeriod": 100
              }
            }
          }
        }
      ],
      "qualifiedName": "default.webtable@cluster2",
      ...
       "ClassificationNames": [
      "PublicData"
    ],
    "Classifications": {
      "PublicData": {
        "jsonClass": "org.apache.atlas.typesystem.json.InstanceSerialization$_Struct",
        "typeName": "PublicData",
        "values": {}
      }
    }
  }
}

Disassociate Classification Instances Associated with Entities

Description:

This is a simple DELETE operation.

Request:

DELETE http://<atlas-server-host:port>/api/atlas/entities/{entity_guid}/Classifications/{Classification_name}

Response:

No data is returned.

Example Request:

DELETE http://<atlas-server-host:port>/api/atlas/entities/f4019a65-8948-46f1-afcf-545baa2df99f/Classifications/PublicData