## Business Graph category hierarchy

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/python/glossary/how-tos/create-hierarchy

> Create nested glossary category hierarchies programmatically using the Atlan Python SDK (pyatlan) and AtlasGlossaryCategory.

# AtlasGlossaryCategory: create glossary category hierarchies

Use `AtlasGlossaryCategory` in the Atlan Python SDK to programmatically create and organize nested category hierarchies within a glossary.

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

```java showLineNumbers title="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()`[^1] the object to create it in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="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()`[^1] the object to create it in Atlan.

### Kotlin

```kotlin showLineNumbers title="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()`[^1] the object to create it in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="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: `AtlasBusiness Graph`.
7. Within the `anchor` relationship you must provide the GUID of the glossary the category should be created within.

## Create child category

:::warning[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

```java title="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()`[^1] the object to create it in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python title="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()`[^1] the object to create it in Atlan.

### Kotlin

```kotlin title="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()`[^1] the object to create it in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="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: `AtlasBusiness Graph`.
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](https://docs.atlan.com/llms/platform/python/build-your-first-metadata-workflow/llms.txt) concept for a more detailed explanation.

---