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

Atlas Traits

Traits were introduced in the Atlas Types section as one of the composite metatypes, along with Classes and Structs. Traits 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 Classes, Traits can extend from other super traits, and thus inherit attributes defined in those super traits. However, unlike Classes, trait 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 trait instance is defined and used is different than the way in which an entity is defined and used.

Trait 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 traits, and includes specific APIs that can be used to associate traits with entities.

[Note]Note

Atlas Traits cannot be deleted.

Create Traits

Description:

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

Request:

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

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 Traits should be defined under the traitTypes attribute.

Response:

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

Example:

Using our running example, we will define two Traits:

  • PublicData – Any metadata marked with this Trait 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 Trait indicates that any metadata associated with this Trait 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:

{
  "enumTypes":[],
  "structTypes":[],
  "traitTypes":[
    {
      "superTypes":[],
      "hierarchicalMetaTypeName":"org.apache.atlas.typesystem.types.TraitType",
      "typeName":"PublicData",
      "typeDescription":null,
      "attributeDefinitions":[]
    },
    {
      "superTypes":[],
      "hierarchicalMetaTypeName":"org.apache.atlas.typesystem.types.TraitType",
      "typeName":"Retainable",
      "typeDescription":null,
      "attributeDefinitions":[
        {
          "name":"retentionPeriod",
          "dataTypeName":"int",
          "multiplicity":"required",
          "isComposite":false,
          "isUnique":false,
          "isIndexable":true,
          "reverseAttributeName":null
        }
      ]
    }
  ],
  "classTypes":[]
}

Note that the traitTypes attribute contains the defined Traits. The rest of the metatypes – structs, enums, and classes – are empty. The retentionPeriod attribute is defined as an int in the Retainable Trait.

Example Response:

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

List Traits

Description:

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

Request:

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

Response:

The response is a list of Trait names.

Example Response:

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

Retrieve a Trait

Description:

Because Traits are a specific metatype (like Classes), the same API used to retrieve a specific metatype can be used to retrieve a Trait.

Request:

GET http://<atlas-server-host:port>/api/atlas/types/{trait_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 traitTypes attribute contains the type definition of the Trait specified in the request.

Example Request:

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

Example Response:

{
  "typeName": "Retainable",
  "definition": {
    "enumTypes": [],
    "structTypes": [],
    "traitTypes": [
      {
        "superTypes": [],
        "hierarchicalMetaTypeName": "org.apache.atlas.typesystem.types.TraitType",
        "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 Trait Instances with Entities

Description:

To catalog entities using Traits, we must associate Trait instances with entities.

Request:

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

Request Body:

The request body is a Trait 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 Trait to indicate that it is a data asset that is created by crawling public sites. We also set a Retainable Trait 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/traits

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/traits

Example Request Body:

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

Read Trait Instances Associated with Entities

Description:

When Trait instances are associated with entities according to structure that is defined in Important Atlas API Data Types, the EntityDefinition includes the traitNames and traits attributes. A request for an EntityDefinition returns a response that includes the traitNames and trait 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 traitNames and trait values are shown below.

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

Disassociate Trait Instances Associated with Entities

Description:

This is a simple DELETE operation.

Request:

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

Response:

No data is returned.

Example Request:

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