Skip to content

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 is not 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

1.4.0 1.0.0

To categorize a term during its creation:

Categorize during creation
1
2
3
4
5
6
7
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(); // (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.
Categorize during creation
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import AtlasGlossaryTerm

client = AtlanClient()
term = AtlasGlossaryTerm.create(
    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.
Categorize during creation
1
2
3
4
5
6
7
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() // (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.
POST /api/meta/entity/bulk
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "entities": [ // (1)
    {
      "typeName": "AtlasGlossaryTerm", // (2)
      "attributes": {
        "name": "Example Term", // (3)
        "displayName": "Example Term", // (4)
        "anchor": { // (5)
          "typeName": "AtlasGlossary", // (6)
          "guid": "b4113341-251b-4adc-81fb-2420501c30e6" // (7)
        },
        "categories": [ // (8)
          {
            "typeName": "AtlasGlossaryCategory", // (9)
            "guid": "dc4c0a08-a902-402b-bf24-cf935aecc343" // (10)
          },
          {
            "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 an existing term

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:

Update an existing term
1
2
3
4
5
6
7
8
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(); // (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.
Update an existing term
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import AtlasGlossaryTerm

term = AtlasGlossaryTerm.create_for_modification(
        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.
Update an existing term
1
2
3
4
5
6
7
8
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() // (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.
POST /api/meta/entity/bulk
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "entities": [ // (1)
    {
      "typeName": "AtlasGlossaryCategory", // (2)
      "attributes": {
        "name": "Example Term", // (3)
        "qualifiedName": "gsNccqJraDZqM6WyGP3ea@FzCMyPR2LxkPFgr8eNGrq", // (4)
        "anchor": { // (5)
          "typeName": "AtlasGlossary", // (6)
          "guid": "b4113341-251b-4adc-81fb-2420501c30e6" // (7)
        },
        "categories": [ // (8)
          {
            "typeName": "AtlasGlossaryCategory", // (9)
            "guid": "dc4c0a08-a902-402b-bf24-cf935aecc343" // (10)
          },
          {
            "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.

  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. ↩↩↩↩↩↩