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 aren't managed this way, since they're owned and managed in Snowflake.

Build minimal object needed

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

Java

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();

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

Python

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)

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

Kotlin

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()

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

Raw REST API

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),
      "skipDisplayNameUniquenessCheck": false
    }
  ]
}

1. All Atlan tag definitions must be specified within the classificationDefs array.
2. Each definition must be defined with a category set to CLASSIFICATION.
3. Whatever name you provide for the definition will be replaced by a hashed-string generated name by the back-end.
4. Specify the name of the Atlan tag, as it should appear in the UI, to the displayName.
5. Set the color to use for the Atlan tag within the options object.
6. (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 Atlan tag from object

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

Java

Create the Atlan tag

AtlanTagDef response = atlanTagDef.create(client); // (1)

1. The create() operation will actually create the Atlan tag within Atlan. Because this operation will persist the structure in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Create the Atlan tag

response = client.typedef.create(atlan_tag_def) # (1)

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

Kotlin

Create the Atlan tag

val response = color.create(client) // (1)

1. The create() operation will actually create the Atlan tag within Atlan. Because this operation will persist the structure in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

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

To update Atlan tags:

Java

Coming soon

Python

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)

1. To make sure you have the complete structure, it's easiest to start by retrieving the existing Atlan tag structure by its hashed-string name.

2. 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.

3. Now use client.typedef.update() with the updated tag definition.

Kotlin

Coming soon

Raw REST API

PUT /api/meta/types/typedefs

{
   "enumDefs": [],
   "structDefs": [],
   "classificationDefs": [ // (1),
       "subTypes": [],
       "superTypes": []
     }
   ],
   "entityDefs": [],
   "relationshipDefs": [],
   "businessMetadataDefs": []
}

1. All Atlan tag definitions must be specified within the classificationDefs array.

2. 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

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

Java

Retrieve existing tag structure

TypeDef atlanTag = client.typeDefs.get("S7qnUqZ5mBMBpzQ3Wzt6yD"); // (1)

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

Python

Retrieve existing tag structure

from pyatlan.client.atlan import AtlanClient

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

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

Kotlin

Retrieve existing tag structure

val atlanTag = client.typeDefs.get("S7qnUqZ5mBMBpzQ3Wzt6yD"); // (1)

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

Raw REST API

Atlan tag have a hashed-string representation

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

Retrieve all Atlan tags

To retrieve all Atlan tags:

Java

Retrieve all tag structures

TypeDefResponse atlanTags = client.typeDefs.list(AtlanTypeCategory.CLASSIFICATION); // (1)

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

Python

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)

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

Kotlin

Retrieve all tag structures

val atlanTags = client.typeDefs.list(AtlanTypeCategory.CLASSIFICATION) // (1)

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

Raw REST API

Delete Atlan tags

Delete Atlan tags by its human-readable name:

Java

Delete tag structure

AtlanTagDef.purge(client, "MyTagName"); // (1)

1. You only need to call the AtlanTagDef.purge() method with the human-readable name of the tag, and it will be deleted. Because this operation will remove the structure from Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Delete tag structure

from pyatlan.model.typedef import AtlanTagDef
from pyatlan.client.atlan import AtlanClient

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

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

Kotlin

Delete tag structure

AtlanTagDef.purge(client, "MyTagName") // (1)

1. You only need to call the AtlanTagDef.purge() method with the hashed-string name of the tag, and it will be deleted. Because this operation will remove the structure from Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

Atlan tag have a hashed-string representation

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