Tag (classify) assets

Atlan tags must exist before tagging assets

Remember that you must first create the Atlan tag before you will be able to tag any assets.

Cannot add tags when creating assets

Currently it is not possible to add tags when creating assets, other than via dbt.

Add to an existing asset

1.4.0 1.0.0

To add tags to an existing asset:

dbt Java Python Kotlin Raw REST API

models:
  - name: TOP_BEVERAGE_USERS # (1)
    meta:
      atlan:
        classificationNames: # (2)
          - PII # (3)
          - Marketing Analysis
        classificationNames: # (4)
          - name: PII # (5)
            propagate: true # (6)
            removePropagationsOnEntityDelete: true # (7)
            restrictPropagationThroughLineage: false # (8)
          - name: Marketing Analysis
            propagate: true
            removePropagationsOnEntityDelete: true
            restrictPropagationThroughLineage: false
        classifications: # (9)
          - typeName: yQBDoKHdTLJhqAsdR3RMq6 # (10)
            propagate: true
            removePropagationsOnEntityDelete: true
            restrictPropagationThroughLineage: false
          - typeName: WCVjmgKnW40G151dESXZ03
            propagate: true
            removePropagationsOnEntityDelete: true
            restrictPropagationThroughLineage: false

1. You must of course give the name of the object.
2. The simplest way to tag an asset, using the default values for propagation (those shown below), is to use the meta.atlan.classificationNames structure.
3. When using this simplified form, you can give the normal human-readable name of the tags rather than the hashed-string representation.
4. Alternatively, if you want to override the propagation settings, you can use this more detailed structure.
5. Each listed item must itself be a YAML object consisting of the human-readable name of the tag and the propagation setting overrides:
6. (Optional) You can decide whether to propagate this tag (true) or not (false). If you choose false, no propagation of this tag from the asset will occur — neither through lineage nor parent-child relationships.
7. (Optional) If propagation is allowed, you can then define whether propagated tags should be removed if this asset is deleted (true) or not (false).
8. (Optional) If propagation is allowed, you can also decide whether to disable propagation of the tag only for lineage (true) or still allow it through lineage (false).
9. Alternatively, you can specify tags nested within the meta.atlan.classifications structure.
10. In this structure, each tag you want to add must be given using its hashed-string representation. Its propagation settings can be overridden using the same options described above.

Replaces all tags

Unlike the examples for the SDKs and raw APIs, dbt will always replace all tags on the asset. Any tags that already exist on the asset that are not specified here will be removed.

Table.appendAtlanTags( // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS", // (2)
    List.of("PII", "Marketing Analysis")); // (3)

1. Use the appendAtlanTags() helper method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to add the tags all-in-one.
2. The qualifiedName of the asset.
3. A list of the tags (the names as you set them up in the UI) to add to the asset.

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Table

client = AtlanClient()
client.asset.add_atlan_tags( # (1)
    asset_type=Table,
    qualified_name="default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",
    atlan_tag_names=["PII", "Marketing Analysis"], # (2)
)

1. Use the asset.add_atlan_tags() method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to add the tags all-in-one.
2. A list of the tags (the names as you set them up in the UI) to add to the asset.

val table = Table.appendAtlanTags(  // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",  // (2)
    listOf("PII", "Marketing Analysis"))  // (3)

1. Use the appendAtlanTags() helper method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to add the tags all-in-one.
2. The qualifiedName of the asset.
3. A list of the tags (the names as you set them up in the UI) to add to the asset.

[
  {
    "typeName": "yQBDoKHdTLJhqAsdR3RMq6", // (1)
    "propagate": true, // (2)
    "removePropagationsOnEntityDelete": true, // (3)
    "restrictPropagationThroughLineage": false // (4)
  },
  {
    "typeName": "WCVjmgKnW40G151dESXZ03",
    "propagate": true,
    "removePropagationsOnEntityDelete": true,
    "restrictPropagationThroughLineage": false
  }
]

1. Each tag you want to add must be given using its hashed-string representation.
2. (Optional) You can decide whether to propagate this tag (true) or not (false). If you choose false, no propagation of this tag from the asset will occur — neither through lineage nor parent-child relationships.
3. (Optional) If propagation is allowed, you can then define whether propagated tags should be removed if this asset is deleted (true) or not (false).
4. (Optional) If propagation is allowed, you can also decide whether to disable propagation of the tag only for lineage (true) or still allow it through lineage (false).

Update on an existing asset

1.6.4 1.7.1

To update tags on an existing asset:

dbt Java Python Kotlin Raw REST API

Not possible through dbt

In dbt, the tags will be replaced in their entirety. It is not possible to just update a single tag through dbt.

Table.updateAtlanTags( // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS", // (2)
    List.of("PII", "Marketing Analysis"), // (3)
    true, // (4)
    true, // (5)
    false // (6)
);

1. Use the updateAtlanTags() helper method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to update tags for an asset, all-in-one.
2. The qualifiedName of the asset.
3. A list of the tags (the names as you set them up in the UI) to update for the asset.
4. (Optional) You can decide whether to propagate these tags (true) or not (false). If you choose false, no propagation for these tags from the asset will occur — neither through lineage nor parent-child relationships.
5. (Optional) If propagation is allowed, you can then define whether propagated tags should be removed if this asset is deleted (true) or not (false).
6. (Optional) If propagation is allowed, you can also decide whether to disable propagation of the tags only for lineage (true) or still allow it through lineage (false).

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Table

client = AtlanClient()
client.asset.update_atlan_tags( # (1)
    asset_type=Table,
    qualified_name="default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",
    atlan_tag_names=["PII", "Marketing Analysis"], # (2)
    True, # (3)
    True, # (4)
    False, # (5)
)

1. Use the asset.update_atlan_tags() method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to update tags for an asset, all-in-one.
2. A list of the tags (the names as you set them up in the UI) to update for the asset.
3. (Optional) You can decide whether to propagate these tags (True) or not (False). If you choose False, no propagation for these tags from the asset will occur — neither through lineage nor parent-child relationships.
4. (Optional) If propagation is allowed, you can then define whether propagated tags should be removed if this asset is deleted (True) or not (False).
5. (Optional) If propagation is allowed, you can also decide whether to disable propagation of the tags only for lineage (True) or still allow it through lineage (False).

val table = Table.updateAtlanTags(  // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",  // (2)
    listOf("PII", "Marketing Analysis"), // (3)
    true, // (4)
    true, // (5)
    false // (6)
)

1. Use the updateAtlanTags() helper method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to update tags for an asset, all-in-one.
2. The qualifiedName of the asset.
3. A list of the tags (the names as you set them up in the UI) to update for the asset.
4. (Optional) You can decide whether to propagate these tags (true) or not (false). If you choose false, no propagation for these tags from the asset will occur — neither through lineage nor parent-child relationships.
5. (Optional) If propagation is allowed, you can then define whether propagated tags should be removed if this asset is deleted (true) or not (false).
6. (Optional) If propagation is allowed, you can also decide whether to disable propagation of the tags only for lineage (true) or still allow it through lineage (false).

[
  {
    "typeName": "yQBDoKHdTLJhqAsdR3RMq6", // (1)
    "propagate": true, // (2)
    "removePropagationsOnEntityDelete": true, // (3)
    "restrictPropagationThroughLineage": false // (4)
  },
  {
    "typeName": "WCVjmgKnW40G151dESXZ03",
    "propagate": true,
    "removePropagationsOnEntityDelete": true,
    "restrictPropagationThroughLineage": false
  }
]

1. Each tag you want to update must be given using its hashed-string representation.
2. (Optional) You can decide whether to propagate these tags (true) or not (false). If you choose false, no propagation for these tags from the asset will occur — neither through lineage nor parent-child relationships.
3. (Optional) If propagation is allowed, you can then define whether propagated tags should be removed if this asset is deleted (true) or not (false).
4. (Optional) If propagation is allowed, you can also decide whether to disable propagation of the tags only for lineage (true) or still allow it through lineage (false).

Remove from existing assets

Remove a single tag

1.4.0 1.0.0

To remove a single tag from an existing asset:

dbt Java Python Kotlin Raw REST API

models:
  - name: TOP_BEVERAGE_USERS # (1)
    meta:
      atlan:
        classificationNames: # (2)
          - PII # (3)
        classifications: # (4)
          - typeName: yQBDoKHdTLJhqAsdR3RMq6 # (5)
            propagate: true
            removePropagationsOnEntityDelete: true
            restrictPropagationThroughLineage: false

1. You must of course give the name of the object.
2. You can use the meta.atlan.classificationNames structure, as above.

3. When using this simplified form, you can give the normal human-readable name of the tags you want to remain, rather than the hashed-string representation.

   The tag being removed is no longer present

   You are removing the tag by not specifying it anymore here in dbt.

4. The tags must be nested within the meta.atlan.classifications structure.

5. Each tag you want to remain must be given using its hashed-string representation.

   The tag being removed is no longer present

   You are removing the tag by not specifying it anymore here in dbt.

Table.removeAtlanTag( // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS", // (2)
    "Marketing Analysis"); // (3)

1. Use the removeAtlanTag() helper method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to remove a tag from an asset, all-in-one.
2. The qualifiedName of the asset.
3. The tag (the name you set up in the UI) to remove from the asset.

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Table

client = AtlanClient()
client.asset.remove_atlan_tag(  # (1)
    asset_type=Table,
    qualified_name="default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",
    atlan_tag_name="Marketing Analysis",  # (2)
)

1. Use the asset.remove_atlan_tag() method, which for most objects requires a minimal set of information. This method will construct the necessary request and call the necessary API(s) to remove a tag from an asset, all-in-one.
2. The tag (the name you set up in the UI) to remove from the asset.

Table.removeAtlanTag(  // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",  // (2)
    "Marketing Analysis")  // (3)

1. Use the removeAtlanTag() helper method, which for most objects requires a minimal set of information. This helper method will construct the necessary request and call the necessary API(s) to remove a tag from an asset, all-in-one.
2. The qualifiedName of the asset.
3. The tag (the name you set up in the UI) to remove from the asset.

// (1)

1. Note that all of the details for the deletion are embedded in the URL or query parameters to the request. Once again the hashed-string representation of the tag is required. You would either need to first retrieve the list of tags via API to determine this value, or look through the development console of your browser while opening the tag in the Atlan UI.

Remove all tags

Could create a new asset

Remember that Atlan matches the provided qualifiedName to determine whether to update or create the asset.

1.4.0 1.0.0

To remove all tags from an existing asset, you need to specify no tags in your object:

dbt Java Python Kotlin Raw REST API

models:
  - name: TOP_BEVERAGE_USERS # (1)
    meta:
      atlan:
        classifications: [] # (2)

1. You must of course give the name of the object.
2. The tags must be nested within the meta.atlan.classifications structure. To remove all of them, send an explicit empty list.

Table table = Table.updater( // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",
    "TOP_BEVERAGE_USERS").build();
AssetMutationResponse response = table.save(true); // (2)
assert response.getUpdatedAssets().size() == 1; // (3)

1. Use the updater() method to initialize the object with all necessary attributes for updating it(../advanced-examples/update.md#build-minimal-object-needed). (Removing the tags is still an update to the asset, we are not deleting the asset itself.)
2. Call the save() method to actually update the asset, using true as the first argument to overwrite tags. Since we have not provided any tags in our object, this will replace the existing tags on the asset with no tags. (In other words, it will remove all tags from the asset.)
3. The response will include that single asset that was updated (again, removing tags is an update to the asset — we are not deleting the asset itself).

from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Table

client = AtlanClient()
table = Table.create_for_modification( # (1)
    qualified_name="default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",
    name="TOP_BEVERAGE_USERS",
)
response = client.asset.save(table, replace_atlan_tags=True) #  (2)
assert 1 == len(response.assets_updated(asset_type=Table)) # (3)

1. Use the create_for_modification() method to create an asset suitable for modifiaction i.e. with all the requisite attributes.
2. Call the save() method to actually update the asset, using True for the replace_atlan_tags argument will cause the tags to be overwritten. Since we have not provided any tags in our object, this will replace the existing tags on the asset with no tags. (In other words, it will remove all tags from the asset.)
3. The response should only include that single asset that was updated (again, removing tags is an update to the asset — we are not deleting the asset itself).

val table = Table.updater(  // (1)
    "default/snowflake/1657037873/SAMPLE_DB/FOOD_BEV/TOP_BEVERAGE_USERS",
    "TOP_BEVERAGE_USERS").build()
val response = table.save(true)  // (2)
assert(response.updatedAssets.size == 1)  // (3)

1. Use the updater() method to initialize the object with all necessary attributes for updating it(../advanced-examples/update.md#build-minimal-object-needed). (Removing the tags is still an update to the asset, we are not deleting the asset itself.)
2. Call the save() method to actually update the asset, using true as the first argument to overwrite tags. Since we have not provided any tags in our object, this will replace the existing tags on the asset with no tags. (In other words, it will remove all tags from the asset.)
3. The response will include that single asset that was updated (again, removing tags is an update to the asset — we are not deleting the asset itself).

{ // (1)
  "entities": [ // (2)
    {
      "typeName": "Table", // (3)
      "attributes": {
        "qualifiedName": "default/snowflake/1665450065/DBT_FOOD_BEVERAGE/PUBLIC/INSTACART_ORDER_PRODUCTS_USERS_TIME_MASTER", // (4)
        "name": "INSTACART_ORDER_PRODUCTS_USERS_TIME_MASTER" // (5)
      }
    }
  ]
}

1. Note that the query parameter replaceClassifications is equal to true in the request. This is what causes the override behavior — so when you do not specify any tags in the request body those overwrite any existing tags on the asset. (The result being that there are then no tags on the asset.)
2. All assets must be wrapped in an entities array.
3. You must provide the exact type name for the asset (case-sensitive).
4. You must provide the exact qualifiedName of the asset (case-sensitive).
5. You must provide the exact name of the asset (case-sensitive).

Find hashed-string names

When using either the raw APIs or dbt, you must provide the custom metadata names using Atlan's hashed-string representation.

Not necessary for SDKs

Note that this is not needed when using the SDKs, which translate these for you!

To look up the hashed-string representations:

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

The response will include displayName and name for each tag. The displayName is what you see in Atlan's UI, and the name is the hashed-string representation:

{
  "enumDefs": [],
  "structDefs": [],
  "classificationDefs": [
    {
      "category": "CLASSIFICATION",
      "guid": "c43e2f52-975f-40b6-88fa-93697fb54f52",
      "name": "WCVjmgKnW40G151dESXZ03",
      "displayName": "Marketing Analysis",
      "description": "Assets relevant to the marketing domain",
      "options": {
        "color": "Green"
      }
    },
    {
      "category": "CLASSIFICATION",
      "guid": "ec641061-d8fa-4090-9145-a5f23c9c3e99",
      "name": "yQBDoKHdTLJhqAsdR3RMq6",
      "displayName": "PII",
      "description": "Personally-identifiable information can be used to uniquely identify an individual person.",
      "options": {
        "color": "Red"
      }
    }
  ],
  "entityDefs": [],
  "relationshipDefs": [],
  "businessMetadataDefs": []
}

---