Creating 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 root-level category

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

Java

Create a top-level category

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

1. A name for the new category.
2. The glossary in which to create the category. Note that we don't 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. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Create a top-level category

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

client = AtlanClient()
top = AtlasGlossaryCategory.creator(
    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 don't 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.

Kotlin

Create a top-level category

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

1. A name for the new category.
2. The glossary in which to create the category. Note that we don't 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. 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)
      }
    }
  ]
}

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 child category

Parent must exist before creating the child

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

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

Java

Create a child category

GlossaryCategory child = GlossaryCategory.creator(
        "Middle", // (1)
        glossary) // (2)
    .parentCategory(top.trimToReference()) // (3)
    .build(); // (4)
AssetMutationResponse response = child.save(client); // (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. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Create a child category

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

client = AtlanClient()
child = AtlasGlossaryCategory.creator(
        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.

Kotlin

Create a child category

val child = GlossaryCategory.creator(
        "Middle", // (1)
        glossary) // (2)
    .parentCategory(top.trimToReference()) // (3)
    .build() // (4)
val response = child.save(client) // (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. 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),
        "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.

Footnotes

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. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶