Creating a hierarchy

Categories in a glossary can be organized within another category, to create a hierarchy of categories.

To do this, you need to create the upper levels of the hierarchy before the lower levels. Each level you create should refer to its parent, and therefore its parent must first exist.

Create a root-level category

1.4.0 1.0.0

To create a root- or top-level category (no parent):

Java Python Kotlin Raw REST API

GlossaryCategory top = GlossaryCategory.creator(
        "Top", // (1)
        glossary) // (2)
    .build(); // (3)
AssetMutationResponse response = top.save(); // (4)

1. A name for the new category.
2. The glossary in which to create the category. Note that we do not specify any parent category anywhere, since this will be a top-level category.
3. You need to build the object you've just defined.
4. You then only need to save()¹ the object to create it in Atlan.

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

client = AtlanClient()
top = AtlasGlossaryCategory.create(
    name="Top",  # (1)
    anchor=glossary  # (2)
)
response = client.asset.save(top)  # (3)

1. A name for the new category.
2. The glossary in which to create the category. Note that we do not specify any parent category anywhere, since this will be a top-level category.
3. You then only need to save()¹ the object to create it in Atlan.

val top = GlossaryCategory.creator(
        "Top", // (1)
        glossary) // (2)
    .build() // (3)
val response = top.save() // (4)

1. A name for the new category.
2. The glossary in which to create the category. Note that we do not specify any parent category anywhere, since this will be a top-level category.
3. You need to build the object you've just defined.
4. You then only need to save()¹ the object to create it in Atlan.

{
  "entities": [ // (1)
    {
      "typeName": "AtlasGlossaryCategory", // (2)
      "attributes": {
        "name": "Top", // (3)
        "displayName": "Top", // (4)
        "anchor": { // (5)
          "typeName": "AtlasGlossary", // (6)
          "guid": "b4113341-251b-4adc-81fb-2420501c30e6" // (7)
        }
      }
    }
  ]
}

1. All assets must be wrapped in an entities array.
2. You must provide the exact type name for the category (case-sensitive), which for a category is AtlasGlossaryCategory.
3. You must provide the exact name of the category (case-sensitive).
4. You must provide the exact name of the category (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.

Create a child category

Parent must exist before creating the child

Remember: the parent category must exist before you create the child category.

1.4.0 1.0.0

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

Java Python Kotlin Raw REST API

GlossaryCategory child = GlossaryCategory.creator(
        "Middle", // (1)
        glossary) // (2)
    .parentCategory(top.trimToReference()) // (3)
    .build(); // (4)
AssetMutationResponse response = child.save(); // (5)

1. A name for the new category.
2. The glossary in which to create the category.

3. Now you add in the reference to the parent category. There are multiple ways you can reference the category:

   • If you have the parent category already, you can use trimToReference() to obtain the minimal reference to it.
   • If you only know the GUID, you can use GlossaryCategory.refByGuid() to create a minimal reference to it.
   • If you only know the qualifiedName, you can use GlossaryCategory.refByQualifiedName() to create a minimal reference to it.

4. You need to build the object you've just defined.

5. You then only need to save()¹ the object to create it in Atlan.

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

client = AtlanClient()
child = AtlasGlossaryCategory.create(
        name="Middle",  # (1)
        anchor=glossary,  # (2)
        parent_category=top)  # (3)
response = client.asset.save(child);  # (4)

1. A name for the new category.
2. The glossary in which to create the category.

3. Now you add in the reference to the parent category. There are multiple ways you can reference the category:

   • If you have the parent category already, you can send it through as-is.
   • If you only know the GUID, you can use AtlasGlossaryCategory.ref_by_guid() to create a minimal reference to it.
   • If you only know the qualifiedName, you can use GlossaryCategory.ref_by_qualified_name() to create a minimal reference to it.

4. You then only need to save()¹ the object to create it in Atlan.

val child = GlossaryCategory.creator(
        "Middle", // (1)
        glossary) // (2)
    .parentCategory(top.trimToReference()) // (3)
    .build() // (4)
val response = child.save() // (5)

1. A name for the new category.
2. The glossary in which to create the category.

3. Now you add in the reference to the parent category. There are multiple ways you can reference the category:

   • If you have the parent category already, you can use trimToReference() to obtain the minimal reference to it.
   • If you only know the GUID, you can use GlossaryCategory.refByGuid() to create a minimal reference to it.
   • If you only know the qualifiedName, you can use GlossaryCategory.refByQualifiedName() to create a minimal reference to it.

4. You need to build the object you've just defined.

5. You then only need to save()¹ the object to create it in Atlan.

{
  "entities": [ // (1)
    {
      "typeName": "AtlasGlossaryCategory", // (2)
      "attributes": {
        "name": "Middle", // (3)
        "displayName": "Middle", // (4)
        "anchor": { // (5)
          "typeName": "AtlasGlossary", // (6)
          "guid": "b4113341-251b-4adc-81fb-2420501c30e6" // (7)
        },
        "parentCategory": { // (8)
          "typeName": "AtlasGlossaryCategory", // (9)
          "guid": "dc4c0a08-a902-402b-bf24-cf935aecc343" // (10)
        }
      }
    }
  ]
}

1. All assets must be wrapped in an entities array.
2. You must provide the exact type name for the category (case-sensitive), which for a category is AtlasGlossaryCategory.
3. You must provide the exact name of the category (case-sensitive).
4. You must provide the exact name of the category (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. You must provide a parentCategory relationship to define the parent category.
9. Within the parentCategory relationship you must provide the exact type name for a category: AtlasGlossaryCategory.
10. Within the parentCategory relationship you must provide the GUID of the category this category should be organized within.

---

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

---