## Categorize terms

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

> Organize glossary terms into categories programmatically using the Atlan Python SDK (pyatlan) and AtlasGlossaryTerm.

# AtlasGlossaryTerm: categorize and assign glossary terms

Use `AtlasGlossaryTerm` in the Atlan Python SDK to programmatically categorize terms and assign them to glossary categories.

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

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

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

### Kotlin

```kotlin showLineNumbers title="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()`[^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),
 "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: `AtlasBusiness Graph`.
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

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

### Kotlin

```kotlin showLineNumbers title="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()`[^1] the object to update 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),
 "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: `AtlasBusiness Graph`.
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.

[^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) for a more detailed explanation.

---