Categorize terms

Terms in a glossary can also be organized in one (or many) categories.

Remember the glossary is the container, not the category

Remember that the glossary is what contains the term, not the category. Therefore a term must have a glossary, but isn't required to have a category. Also, a term can (optionally) be organized in many categories, but can only exist in one glossary.

Category must exist before creating or updating the term

Remember: each category must already exist before you create or update a term that refers to the category.

During term creation

To categorize a term during its creation:

Java

Categorize during creation

GlossaryTerm term = GlossaryTerm.creator(
        "Example Term", // (1)
        glossary) // (2)
    .category(GlossaryCategory.refByGuid("dc4c0a08-a902-402b-bf24-cf935aecc343")) // (3)
    .category(GlossaryCategory.refByQualifiedName(anotherCategoryQN)) // (4)
    .build(); // (5)
AssetMutationResponse response = term.save(client); // (6)

1. A name for the new term.
2. The glossary in which to create the term.
3. You can then add any number of categories using the category() builder method. In this example the term will be categorized in a category with a GUID of dc4c0a08-a902-402b-bf24-cf935aecc343...
4. ...in this example the term will also be categorized in a category with a qualifiedName given by the anotherCategoryQN variable.
5. You need to build the object you've just defined.
6. You then only need to save()¹ the object to create it in Atlan. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Categorize during creation

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

client = AtlanClient()
term = AtlasGlossaryTerm.creator(
    name="Example Term",  # (1)
    anchor=glossary,  # (2)
    categories=[
        AtlasGlossaryCategory.ref_by_guid("dc4c0a08-a902-402b-bf24-cf935aecc343"),  # (3)
        AtlasGlossaryCategory.ref_by_qualified_name(another_category_qn)  # (4)
    ]
response = client.asset.save(term);  # (5)

1. A name for the new term.
2. The glossary in which to create the term.
3. You can then add any number of categories through the categories named argument. In this example the term will be categorized in a category with a GUID of dc4c0a08-a902-402b-bf24-cf935aecc343...
4. ...in this example the term will also be categorized in a category with a qualified_name given by the another_category_qn variable.
5. You then only need to save()¹ the object to create it in Atlan.

Kotlin

Categorize during creation

val term = GlossaryTerm.creator(
        "Example Term", // (1)
        glossary) // (2)
    .category(GlossaryCategory.refByGuid("dc4c0a08-a902-402b-bf24-cf935aecc343")) // (3)
    .category(GlossaryCategory.refByQualifiedName(anotherCategoryQN)) // (4)
    .build() // (5)
val response = term.save(client) // (6)

1. A name for the new term.
2. The glossary in which to create the term.
3. You can then add any number of categories using the category() builder method. In this example the term will be categorized in a category with a GUID of dc4c0a08-a902-402b-bf24-cf935aecc343...
4. ...in this example the term will also be categorized in a category with a qualifiedName given by the anotherCategoryQN variable.
5. You need to build the object you've just defined.
6. You then only need to save()¹ the object to create it in Atlan. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

POST /api/meta/entity/bulk

{
  "entities": [ // (1),
        "categories": [ // (8),
          {
            "typeName": "AtlasGlossaryCategory",
            "uniqueAttributes": {
              "qualifiedName": "..." // (11)
            }
          }
        ]
      }
    }
  ]
}

1. All assets must be wrapped in an entities array.
2. You must provide the exact type name for the term (case-sensitive), which for a term is AtlasGlossaryTerm.
3. You must provide the exact name of the term (case-sensitive).
4. You must provide the exact name of the term (case-sensitive) as you want it to appear in the UI.
5. You must provide an anchor relationship.
6. Within the anchor relationship you must provide the exact type name for a glossary: AtlasGlossary.
7. Within the anchor relationship you must provide the GUID of the glossary the category should be created within.
8. When you want to place the term into one or more categories, you must provide the categories relationship.
9. Within a categories relationship, you must provide the exact type name for a category: AtlasGlossaryCategory.
10. Within a categories relationship, you must provide either the GUID of the category (in this example)...
11. ...or the qualifiedName of the category, which itself must be further nested within a uniqueAttributes object.

Updating existing term

To create a child category, the steps are very similar but you add in the reference to the parent category:

Java

Update an existing term

GlossaryTerm term = GlossaryTerm.updater(
        "gsNccqJraDZqM6WyGP3ea@FzCMyPR2LxkPFgr8eNGrq", // (1)
        "Example Term", // (2)
        "b4113341-251b-4adc-81fb-2420501c30e6") // (3)
    .category(GlossaryCategory.refByGuid("dc4c0a08-a902-402b-bf24-cf935aecc343")) // (4)
    .category(GlossaryCategory.refByQualifiedName(anotherCategoryQN)) // (5)
    .build(); // (6)
AssetMutationResponse response = child.save(client); // (7)

1. The qualifiedName of the existing term.
2. The name of the existing term.
3. The GUID of the glossary in which the term exists.
4. You can then add any number of categories using the category() builder method. In this example the term will be categorized in a category with a GUID of dc4c0a08-a902-402b-bf24-cf935aecc343...
5. ...in this example the term will also be categorized in a category with a qualifiedName given by the anotherCategoryQN variable.
6. You need to build the object you've just defined.
7. You then only need to save()¹ the object to update it in Atlan. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Update an existing term

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

term = AtlasGlossaryTerm.updater(
        qualified_name="gsNccqJraDZqM6WyGP3ea@FzCMyPR2LxkPFgr8eNGrq",  # (1)
        name="Example Term",  # (2)
        glossary_guid="b4113341-251b-4adc-81fb-2420501c30e6")  # (3)
term.categories = [
    AtlasGlossaryCategory.ref_by_guid("dc4c0a08-a902-402b-bf24-cf935aecc343"),  # (4)
    AtlasGlossaryCategory.ref_by_qualified_name(another_category_qn)  # (5)
]
response = client.asset.save(term);  # (6)

1. The qualified_name of the existing term.
2. The name of the existing term.
3. The GUID of the glossary in which the term exists.
4. You can then add any number of categories using the categories property. In this example the term will be categorized in a category with a GUID of dc4c0a08-a902-402b-bf24-cf935aecc343...
5. ...in this example the term will also be categorized in a category with a qualified_name given by the another_category_qn variable.
6. You then only need to save()¹ the object to update it in Atlan.

Kotlin

Update an existing term

val term = GlossaryTerm.updater(
        "gsNccqJraDZqM6WyGP3ea@FzCMyPR2LxkPFgr8eNGrq", // (1)
        "Example Term", // (2)
        "b4113341-251b-4adc-81fb-2420501c30e6") // (3)
    .category(GlossaryCategory.refByGuid("dc4c0a08-a902-402b-bf24-cf935aecc343")) // (4)
    .category(GlossaryCategory.refByQualifiedName(anotherCategoryQN)) // (5)
    .build() // (6)
val response = child.save(client) // (7)

1. The qualifiedName of the existing term.
2. The name of the existing term.
3. The GUID of the glossary in which the term exists.
4. You can then add any number of categories using the category() builder method. In this example the term will be categorized in a category with a GUID of dc4c0a08-a902-402b-bf24-cf935aecc343...
5. ...in this example the term will also be categorized in a category with a qualifiedName given by the anotherCategoryQN variable.
6. You need to build the object you've just defined.
7. You then only need to save()¹ the object to update it in Atlan. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

POST /api/meta/entity/bulk

{
  "entities": [ // (1),
        "categories": [ // (8),
          {
            "typeName": "AtlasGlossaryCategory",
            "uniqueAttributes": {
              "qualifiedName": "..." // (11)
            }
          }
        ]
      }
    }
  ]
}

1. All assets must be wrapped in an entities array.
2. You must provide the exact type name for the term (case-sensitive), which for a category is AtlasGlossaryCategory.
3. You must provide the exact name of the term (case-sensitive).
4. You must provide the exact qualifiedName of the term (case-sensitive), as it already exists in Atlan.
5. You must provide an anchor relationship.
6. Within the anchor relationship you must provide the exact type name for a glossary: AtlasGlossary.
7. Within the anchor relationship you must provide the GUID of the glossary the category should be created within.
8. When you want to place the term into one or more categories, you must provide the categories relationship.
9. Within a categories relationship, you must provide the exact type name for a category: AtlasGlossaryCategory.
10. Within a categories relationship, you must provide either the GUID of the category (in this example)...
11. ...or the qualifiedName of the category, which itself must be further nested within a uniqueAttributes object.

Footnotes

1. Why no distinction between create and update? This has to do with how Atlan detects changes—see the Importance of identifiers for a more detailed explanation. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶