Retrieving glossary objects by name

Glossary objects (terms, categories and even glossaries themselves) in Atlan have complicated qualifiedNames. This makes retrieving them using the get() operation less than ideal.

To address this, the SDKs provide helper methods to retrieve glossary objects based on their human-readable names.

Retrieve a glossary by name

1.4.0 1.0.0

To retrieve a glossary by its human-readable name:

Java Python Kotlin Raw REST API

Glossary glossary = Glossary.findByName( // (1)
    "Concepts") // (2)

1. The findByName() helper method retrieves the glossary based on its human-readable name.
2. You must provide the human-readable name of the glossary. The method will only include a bare minimum set of attributes about the glossary — you can request additional attributes by providing a list of them as an (optional) second parameter to this method.

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
glossary = client.asset.find_glossary_by_name( # (1)
    name="Concepts", # (2)
    attributes=None) # (3)

1. The asset.find_glossary_by_name() method retrieves the glossary based on its human-readable name.
2. You must provide the human-readable name of the glossary.
3. The method will only include a bare minimum set of attributes about the glossary — you can request additional attributes by providing a list of them as the second parameter to this method.

val glossary = Glossary.findByName( // (1)
    "Concepts") // (2)

1. The findByName() helper method retrieves the glossary based on its human-readable name.
2. You must provide the human-readable name of the glossary. The method will only include a bare minimum set of attributes about the glossary — you can request additional attributes by providing a list of them as an (optional) second parameter to this method.

{
  "dsl": { // (1)
    "from": 0,
    "size": 2,
    "query": {
      "bool": {
        "filter": [
          {
            "term": {
              "__state": {
                "value": "ACTIVE"
              }
            }
          },
          {
            "term": { // (2)
              "__typeName.keyword": {
                "value": "AtlasGlossary"
              }
            }
          },
          {
            "term": { // (3)
              "name.keyword": {
                "value": "Concepts"
              }
            }
          }
        ]
      }
    },
    "track_total_hits": true
  },
  "suppressLogs": true,
  "showSearchScore": false,
  "excludeMeanings": false,
  "excludeClassifications": false
}

1. You actually need to run a search to retrieve glossary objects by name.
2. You should filter the search by a specific type, in this example AtlasGlossary is the name of the type in Atlan for glossaries.
3. You then must also filter by the name of the glossary you want to find. This example does an exact match against the provided Concepts value (case-sensitive).

Retrieve a category by name

1.4.0 1.0.0

To retrieve a category by its human-readable name:

Java Python Kotlin Raw REST API

GlossaryCategory category = GlossaryCategory.findByName( // (1)
    "Finance", // (2)
    "Concepts"); // (3)

1. The findByName() helper method retrieves the category based on its human-readable name.
2. You must provide the human-readable name of the category.
3. You must also provide the human-readable name of the glossary for that category. (A category with the same name can exist in different glossaries, but not in the same glossary.) The method will only include a bare minimum set of attributes about the category — you can request additional attributes by providing a list of them as an (optional) third parameter to this method.

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
category = client.asset.find_category_by_name( # (1)
    name="Finance", # (2)
    glossary_name="Concepts", #(3)
    attributes=None) # (4)

1. The asset.find_category_by_name() method retrieves the category based on its human-readable name.
2. You must provide the human-readable name of the category.
3. You must also provide the human-readable name of the glossary for that category. (A category with the same name can exist in different glossaries, but not in the same glossary.)
4. The method will only include a bare minimum set of attributes about the category — you can request additional attributes by providing a list of them as the third parameter to this method.

val category = GlossaryCategory.findByName( // (1)
    "Finance", // (2)
    "Concepts") // (3)

1. The findByName() helper method retrieves the category based on its human-readable name.
2. You must provide the human-readable name of the category.
3. You must also provide the human-readable name of the glossary for that category. (A category with the same name can exist in different glossaries, but not in the same glossary.) The method will only include a bare minimum set of attributes about the category — you can request additional attributes by providing a list of them as an (optional) third parameter to this method.

Requires multiple API operations

To find a category by its name, using the name of the glossary it exists within (rather than the qualifiedName of the glossary), you must first find the glossary by name. (See above example.) Then use the returned qualifiedName of the glossary to run the search below for the category within that glossary.

{
  "dsl": { // (1)
    "from": 0,
    "size": 2,
    "query": {
      "bool": {
        "filter": [
          {
            "term": {
              "__state": {
                "value": "ACTIVE"
              }
            }
          },
          {
            "term": { // (2)
              "__typeName.keyword": {
                "value": "AtlasGlossaryCategory"
              }
            }
          },
          {
            "term": { // (3)
              "name.keyword": {
                "value": "Finance"
              }
            }
          },
          {
            "term": { // (4)
              "__glossary": {
                "value": "LD5Tb30qbuYCZKsmFRpmS"
              }
            }
          }
        ]
      }
    },
    "track_total_hits": true
  },
  "suppressLogs": true,
  "showSearchScore": false,
  "excludeMeanings": false,
  "excludeClassifications": false
}

1. You actually need to run a search to retrieve category objects by name.
2. You should filter the search by a specific type, in this example AtlasGlossaryCategory is the name of the type in Atlan for categories.
3. You then must also filter by the name of the category you want to find. This example does an exact match against the provided Finance value (case-sensitive).

4. Finally, you should also filter the search for the specific glossary in which to find the category. (Since the same category name could exist in many glossaries.)

   Requires qualifiedName of the glossary

   Note that this requires the `qualifiedName of the glossary, which therefore must first be known or found by an earlier search on glossaries.

Retrieve a term by name

1.4.0 1.0.0

To retrieve a term by its human-readable name:

Java Python Kotlin Raw REST API

GlossaryTerm term = GlossaryTerm.findByName( // (1)
    "Revenue", // (2)
    "Concepts"); // (3)

1. The findByName() helper method retrieves the term based on its human-readable name.
2. You must provide the human-readable name of the term.
3. You must also provide the human-readable name of the glossary for that term. (A term with the same name can exist in different glossaries, but not in the same glossary.) The method will only include a bare minimum set of attributes about the term — you can request additional attributes by providing a list of them as an (optional) third parameter to this method.

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
term = client.asset.find_term_by_name( # (1)
    name="Revenue", # (2)
    glossary_name="Concepts", #(3)
    attributes=None) # (4)

1. The asset.find_term_by_name() method retrieves the term based on its human-readable name.
2. You must provide the human-readable name of the term.
3. You must also provide the human-readable name of the glossary for that term. (A term with the same name can exist in different glossaries, but not in the same glossary.)
4. The method will only include a bare minimum set of attributes about the term — you can request additional attributes by providing a list of them as the third parameter to this method.

val term = GlossaryTerm.findByName( // (1)
    "Revenue", // (2)
    "Concepts") // (3)

1. The findByName() helper method retrieves the term based on its human-readable name.
2. You must provide the human-readable name of the term.
3. You must also provide the human-readable name of the glossary for that term. (A term with the same name can exist in different glossaries, but not in the same glossary.) The method will only include a bare minimum set of attributes about the term — you can request additional attributes by providing a list of them as an (optional) third parameter to this method.

Requires multiple API operations

To find a term by its name, using the name of the glossary it exists within (rather than the qualifiedName of the glossary), you must first find the glossary by name. (See above example.) Then use the returned qualifiedName of the glossary to run the search below for the term within that glossary.

{
  "dsl": { // (1)
    "from": 0,
    "size": 2,
    "query": {
      "bool": {
        "filter": [
          {
            "term": {
              "__state": {
                "value": "ACTIVE"
              }
            }
          },
          {
            "term": { // (2)
              "__typeName.keyword": {
                "value": "AtlasGlossaryTerm"
              }
            }
          },
          {
            "term": { // (3)
              "name.keyword": {
                "value": "Revenue"
              }
            }
          },
          {
            "term": { // (4)
              "__glossary": {
                "value": "LD5Tb30qbuYCZKsmFRpmS"
              }
            }
          }
        ]
      }
    },
    "track_total_hits": true
  },
  "suppressLogs": true,
  "showSearchScore": false,
  "excludeMeanings": false,
  "excludeClassifications": false
}

1. You actually need to run a search to retrieve term objects by name.
2. You should filter the search by a specific type, in this example AtlasGlossaryTerm is the name of the type in Atlan for terms.
3. You then must also filter by the name of the term you want to find. This example does an exact match against the provided Revenue value (case-sensitive).

4. Finally, you should also filter the search for the specific glossary in which to find the term. (Since the same term name could exist in many glossaries.)

   Requires qualifiedName of the glossary

   Note that this requires the `qualifiedName of the glossary, which therefore must first be known or found by an earlier search on glossaries.

---