Manage Atlan tags¶

Similar to other objects you can create in the SDK, Atlan tags implement the builder pattern.

Atlan tags vs tags in general

Note that we intentionally use the phrase Atlan tag here to differentiate tags you can structurally maintain in Atlan vs other tags in general. For example, Snowflake tags are not managed this way, since they are owned and managed in Snowflake.

Build minimal object needed¶

1.3.3 1.0.0

For example, to create an Atlan tag to identify personally-identifiable information:

Java Python Kotlin Raw REST API

Build Atlan tag object for creation
AtlanTagDef color = AtlanTagDef.creator( // (1)
        "PII", // (2)
        AtlanTagColor.RED) // (3)
    .description("Personally-Identifiable Information") // (4)
    .build(); // (5)
AtlanTagDef icon = AtlanTagDef.creator(
        "PII",
        AtlanIcon.PASSWORD, // (6)
        AtlanTagColor.RED)
    .build();
AtlanTagDef image = AtlanTagDef.creator(
        "PII",
        "http://some.example.com/image.png", // (7)
        AtlanTagColor.RED)
    .build();

Use the creator() method to start building up the Atlan tag.
You must provide a name for the Atlan tag (PII in this example).
You must also specify the color you want to use for the Atlan tag.
(Optional) You can also give the Atlan tag a description.
As with all other builder patterns, you must build() the object you've defined.
As an alternative, you can also specify a built-in icon to use for the tag.
As an alternative, you can also specify your own image to use for the tag.

Build Atlan tag object for creation
import urllib.request
from pyatlan.model.typedef import AtlanTagDef
from pyatlan.model.enums import AtlanTagColor, AtlanIcon
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
atlan_tag_def = AtlanTagDef.create( # (1)
                name="PII", # (2)
                color=AtlanTagColor.RED) # (3)
atlan_tag_def.description = "Personally-Identifiable Information" # (4)
atlan_tag_def = AtlanTagDef.create(
                name="PII",
                icon=AtlanIcon.PASSWORD, # (5)
                color=AtlanTagColor.RED)
urllib.request.urlretrieve("http://some.example.com/image.png", "image.png") # (6)
with open("image.png", "rb") as img_file:
    image = client.upload_image(file=img_file, filename="image.png") # (7)
    atlan_tag_def = AtlanTagDef.create(
                    name="PII",
                    image=image, # (8)
                    color=AtlanTagColor.RED)

Use the create() method to set up the Atlan tag with its minimal necessary inputs.
You must provide a name for the Atlan tag (PII in this example).
You must also specify the color you want to use for the Atlan tag.
(Optional) You can also give the Atlan tag a description.
As an alternative, you can also specify a built-in icon to use for the tag.
As an alternative, you can download or use your own image file for the tag.
Before you can use the image, you must upload it to Atlan.
You can then specify the uploaded image to use for the tag.

Build Atlan tag object for creation
val color = AtlanTagDef.creator( // (1)
        "PII",  // (2)
        AtlanTagColor.RED) // (3)
    .description("Personally-Identifiable Information") // (4)
    .build() // (5)
val icon = AtlanTagDef.creator(
        "PII",
        AtlanIcon.PASSWORD,  // (6)
        AtlanTagColor.RED)
    .build()
val image = AtlanTagDef.creator(
        "PII",
        "http://some.example.com/image.png",  // (7)
        AtlanTagColor.RED)
    .build()

Use the creator() method to start building up the Atlan tag.
You must provide a name for the Atlan tag (PII in this example).
You must also specify the color you want to use for the Atlan tag.
(Optional) You can also give the Atlan tag a description.
As with all other builder patterns, you must build() the object you've defined.
As an alternative, you can also specify a built-in icon to use for the tag.
As an alternative, you can also specify your own image to use for the tag.

Image option not shown

The option to use your own image is significantly more complicated, as it involves constructing a multipart form-encoded upload of the binary image data first, and then using the resulting uploaded object's details to use the image within the tag.

POST /api/meta/types/typedefs
{
  "classificationDefs": [ // (1)
    {
      "category": "CLASSIFICATION", // (2)
      "name": "PII", // (3)
      "description": "Personally-Identifiable Information",
      "displayName": "PII", // (4)
      "options": {
        "color": "Red", // (5)
        "icon": "PhPassword", // (6)
        "iconType": "icon"
      },
      "skipDisplayNameUniquenessCheck": false
    }
  ]
}

All Atlan tag definitions must be specified within the classificationDefs array.
Each definition must be defined with a category set to CLASSIFICATION.
Whatever name you provide for the definition will be replaced by a hashed-string generated name by the back-end.
Specify the name of the Atlan tag, as it should appear in the UI, to the displayName.
Set the color to use for the Atlan tag within the options object.
(Optional) Set a built-in icon to use within the options object. When defining an icon, you must also set options.iconType to "icon".

Where can I see each icon?

We use Phosphor for the icons. They have a beautiful icon browser on their site to search and preview the icons.

Create the Atlan tag from the object¶

1.3.3 1.0.0

Now that the object is built, it will have the required information for Atlan to create it:

Java Python Kotlin Raw REST API

Create the Atlan tag
AtlanTagDef response = atlanTagDef.create(); // (1)

The create() operation will actually create the Atlan tag within Atlan.

Create the Atlan tag
response = client.typedef.create(atlan_tag_def) # (1)

The typedef.create() operation will actually create the Atlan tag within Atlan.

Create the Atlan tag
val response = color.create() // (1)

The create() operation will actually create the Atlan tag within Atlan.

Creation implicit in step above

The actual creation of the Atlan tag is implicit in the example above.

Now that the Atlan tag has been created, you can use it to tag assets.

Update Atlan tags¶

2.1.0

To update Atlan tags:

Java Python Kotlin Raw REST API

Coming soon

Update existing tag structure
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

atlan_tag = client.typedef.get_by_name("S7qnUqZ5mBMBpzQ3Wzt6yD") # (1)
atlan_tag.options["color"] = "Green" # (2)
atlan_tag.options["emoji"] = "💪"
atlan_tag.display_name = "MyTagName"

response = client.typedef.update(atlan_tag) # (3)

To ensure you have the complete structure, it is easiest to start by retrieving the existing Atlan tag structure by its hashed-string name.
In this example, we're updating the following properties of an Atlan tag:
- color of the tag.
- emoji of the tag.
- display name of the tag.
Now use client.typedef.update() with the updated tag definition.

Coming soon

PUT /api/meta/types/typedefs
{
   "enumDefs": [],
   "structDefs": [],
   "classificationDefs": [ // (1)
     {
       "category": "CLASSIFICATION",
       "createTime": 1716829706708,
       "createdBy": "service-account-apikey-2e721c86-2814-4c98-8e1a-fc3fdf6b0489",
       "guid": "884091b2-4fbc-4c8e-85d1-173ad90547cf",
       "name": "S7qnUqZ5mBMBpzQ3Wzt6yD",
       "typeVersion": "1.0",
       "updateTime": 1716835149934,
       "updatedBy": "service-account-apikey-2e721c86-2814-4c98-8e1a-fc3fdf6b0489",
       "version": 16,
       "attributeDefs": [],
       "entityTypes": [],
       "displayName": "MyTagName", // (2)
       "options": {
         "color": "Green",
         "emoji": "💪",
         "imageID": "",
         "iconName": "PhRocketLaunch",
         "iconType": "emoji"
       },
       "subTypes": [],
       "superTypes": []
     }
   ],
   "entityDefs": [],
   "relationshipDefs": [],
   "businessMetadataDefs": []
}

All Atlan tag definitions must be specified within the classificationDefs array.
In this example, we're updating the following properties of an Atlan tag:
- display name of the tag.
- color of the tag.
- emoji of the tag.

Retrieve Atlan tags¶

2.1.0 1.0.0

To retrieve Atlan tag by its hashed-string name eg: S7qnUqZ5mBMBpzQ3Wzt6yD:

Java Python Kotlin Raw REST API

Retrieve existing tag structure
AtlanClient client = Atlan.getDefaultClient();
TypeDef atlanTag = client.typeDefs.get("S7qnUqZ5mBMBpzQ3Wzt6yD"); // (1)

To retrieve the tag, you need to call the client.typeDefs.get() method with its hashed-string name.

Retrieve existing tag structure
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
atlan_tag = client.typedef.get_by_name("S7qnUqZ5mBMBpzQ3Wzt6yD") # (1)

To retrieve the tag, you need to call the client.typedef.get_by_name() method with its hashed-string name.

Retrieve existing tag structure
val client = Atlan.getDefaultClient();
val atlanTag = client.typeDefs.get("S7qnUqZ5mBMBpzQ3Wzt6yD"); // (1)

To retrieve the tag, you need to call the client.typeDefs.get() method with its hashed-string name.

GET /api/meta/types/typedef/name/S7qnUqZ5mBMBpzQ3Wzt6yD

Atlan tag have a hashed-string representation

Use their hashed-string name when retrieving its structure eg: S7qnUqZ5mBMBpzQ3Wzt6yD.

Retrieve all Atlan tags¶

1.3.3 1.0.0

To retrieve all Atlan tags:

Java Python Kotlin Raw REST API

Retrieve all tag structures
AtlanClient client = Atlan.getDefaultClient();
TypeDefResponse atlanTags = client.typeDefs.list(AtlanTypeCategory.CLASSIFICATION); // (1)

To retrieve all tags, call the client.typeDefs.list() method with the definition category AtlanTypeCategory.CLASSIFICATION.

Retrieve all tag structures
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.typedef.get(type_category=AtlanTypeCategory.CLASSIFICATION) # (1)
atlan_tags = response.atlan_tag_defs # (2)

To retrieve all tags, call the client.typedef.get() method with the definition category AtlanTypeCategory.CLASSIFICATION.
Specifically retrieve the list of tags from TypeDefResponse.

Retrieve all tag structures
val client = Atlan.getDefaultClient();
val atlanTags = client.typeDefs.list(AtlanTypeCategory.CLASSIFICATION); // (1)

To retrieve all tags, call the client.typeDefs.list() method with the definition category AtlanTypeCategory.CLASSIFICATION.

GET /api/meta/types/typedefs/?type=CLASSIFICATION

Delete Atlan tags¶

1.3.3 1.0.0

Delete Atlan tags by its human-readable name:

Java Python Kotlin Raw REST API

Delete tag structure
AtlanTagDef.purge("MyTagName"); // (1)

You only need to call the AtlanTagDef.purge() method with the human-readable name of the tag, and it will be deleted.

Delete tag structure
from pyatlan.model.typedef import AtlanTagDef
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
client.typedef.purge("MyTagName", AtlanTagDef) # (1)

You only need to call the clietn.typedef.purge() method with the human-readable name of the tag, and it will be deleted.

Delete tag structure
AtlanTagDef.purge("MyTagName") // (1)

You only need to call the AtlanTagDef.purge() method with the hashed-string name of the tag, and it will be deleted.

DELETE /api/meta/types/typedef/name/S7qnUqZ5mBMBpzQ3Wzt6yD

Atlan tag have a hashed-string representation

Use their hashed-string name when deleting its structure eg: S7qnUqZ5mBMBpzQ3Wzt6yD.