Manage options (enumerations)

Options (or enumerations) in Atlan allow you to define a set of valid values for custom metadata attributes. Like other objects in the SDK, enumerations implement the builder pattern. This allows you to progressively build-up the list of values you want to create.

Build minimal object needed

For example, to create an enumeration to capture a data quality dimension:

Java

Build enumeration for creation

EnumDef enumDef = EnumDef.creator(
        "DataQualityDimensions", // (1)
        List.of("Accuracy", "Completeness", "Consistency", "Timeliness", "Validity", "Uniqueness")) // 2
    .build(); // (3)

1. When creating the enumeration, you must provide a name (DataQualityDimensions in this example).
2. You can then add as many valid values as you want: always as a list of strings.
3. As with all other builder patterns, you must build() the object you've defined.

Python

Build enumeration for creation

from pyatlan.model.typedef import EnumDef

enum_def = EnumDef.create(
    name="DataQualityDimensions", # (1)
    values=["Accuracy", "Completeness", "Consistency", "Timeliness", "Validity", "Uniqueness"] # (2)
)

1. When creating the enumeration, you must provide a name (DataQualityDimensions in this example).
2. You can then add as many valid values as you want: always as a list of strings.

Kotlin

Build enumeration for creation

val enumDef = EnumDef.creator(
        "DataQualityDimensions",  // (1)
        listOf("Accuracy", "Completeness", "Consistency", "Timeliness", "Validity", "Uniqueness")) // 2
    .build() // (3)

1. When creating the enumeration, you must provide a name (DataQualityDimensions in this example).
2. You can then add as many valid values as you want: always as a list of strings.
3. As with all other builder patterns, you must build() the object you've defined.

Raw REST API

POST /api/meta/types/typedefs

{
  "enumDefs": [ // (1),
        {
          "value": "Completeness",
          "ordinal": 1
        },
        {
          "value": "Consistency",
          "ordinal": 2
        },
        {
          "value": "Timeliness",
          "ordinal": 3
        },
        {
          "value": "Validity",
          "ordinal": 4
        },
        {
          "value": "Uniqueness",
          "ordinal": 5
        }
      ]
    }
  ]
}

1. All enumeration definitions must be specified within the enumDefs array.
2. Each definition must be defined with a category set to ENUM.
3. The name you provide for the definition will be used both for the front and back-end.
4. Within the definition, you need to define each valid value for the enumeration within the elementDefs array. Each valid value should have both a string value (as it will appear in the UI) and an integer ordinal. Both must be unique within the enumeration.

Create enumeration from object

Now that the object is built, this enumDef object will have the required information for Atlan to create it. You can then actually create the enumeration in Atlan by calling the create() method on the object itself:

Java

Create the enumeration

EnumDef response = enumDef.create(client); // (1)

1. The create() operation will actually create the enumeration within Atlan, including all the valid values that were defined as part of it. Because this operation will persist the structure in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Create the enumeration

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.typedef.create(enum_def) # (1)

1. The typedef.create() operation will actually create the enumeration definition within Atlan, including all the valid values that were defined as part of it.

Kotlin

Create the enumeration

val response = enumDef.create(client) // (1)

1. The create() operation will actually create the enumeration within Atlan, including all the valid values that were defined as part of it. Because this operation will persist the structure in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

Creation implicit in step above

The actual creation of the enumeration structure is implicit in the example above.

Use enumeration in custom metadata definition

To use an enumeration to restrain the values for an attribute in a custom metadata definition:

Java

Build custom metadata definition for creation

CustomMetadataDef customMetadataDef = CustomMetadataDef.creator("DQ") // (1)
    .attributeDef( // (2)
        AttributeDef.of(client, "Dimension", // (3)
            AtlanCustomAttributePrimitiveType.OPTIONS, // (4)
            "DataQualityDimensions", // (5)
            false)) // (6)
    .options(CustomMetadataOptions.withLogoAsEmoji("🔖")) // (7)
    .build(); // (8)
customMetadataDef.create(); // (9)

1. When creating the custom metadata structure, you must provide a name (DQ in this example).
2. You can then add as many attributes to that structure as you want.
3. Each attribute must have a name. Because this operation may need to retrieve information from Atlan, you must provide it an AtlanClient through which to connect to the tenant.
4. Each attribute must have a type. When using the enumeration as the type (to constrain its possible values), use AtlanCustomAttributePrimitiveType.OPTIONS as the type.
5. You must then also specify the enumeration that defines the valid values for this attribute. Carrying on the same example, we give the name of the enumeration here: DataQualityDimensions.
6. You must also specify whether the attribute allows multiple values to be captured on it (true) or only a single value (false).
7. You can specify how the custom metadata should appear (in this case, with an emoji).
8. As with all other builder patterns, you must build() the object you've defined.
9. Then you can create() the custom metadata definition within Atlan, including this enumeration-constrained attribute that was defined as part of it.

Python

Build custom metadata definition for creation

from pyatlan.model.typedef import AttributeDef, CustomMetadataDef
from pyatlan.model.enums import AtlanCustomAttributePrimitiveType
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

cm_def = CustomMetadataDef.create(display_name="DQ") # (1)
cm_def.attribute_defs = [ # (2)
    AttributeDef.create(
        client=client, # (3)
        display_name="Dimension", # (4)
        attribute_type=AtlanCustomAttributePrimitiveType.OPTIONS, # (5)
        options_name="DataQualityDimensions", # (6)
    ),
]
cm_def.options = CustomMetadataDef.Options.with_logo_as_emoji( # (7)
    emoji="🔖"
)
client.typedef.create(cm_def) # (8)

1. When creating the custom metadata structure, you must provide a name (DQ in this example).
2. You can then add as many attributes to that structure as you want.
3. You must provide a client instance.
4. Each attribute must have a name.
5. Each attribute must have a type. When using the enumeration as the type (to constrain its possible values), use AtlanCustomAttributePrimitiveType.OPTIONS as the type.
6. You must then also specify the enumeration that defines the valid values for this attribute. Carrying on the same example, we give the name of the enumeration here: DataQualityDimensions.
7. You can specify how the custom metadata should appear (in this case, with an emoji).
8. Then you can create the custom metadata definition within Atlan, including this enumeration-constrained attribute that was defined as part of it.

Kotlin

Build custom metadata definition for creation

val customMetadataDef = CustomMetadataDef.creator("DQ") // (1)
    .attributeDef( // (2)
        AttributeDef.of(client, "Dimension",  // (3)
            AtlanCustomAttributePrimitiveType.OPTIONS,  // (4)
            "DataQualityDimensions",  // (5)
            false)) // (6)
    .options(CustomMetadataOptions.withLogoAsEmoji("🔖")) // (7)
    .build() // (8)
customMetadataDef.create() // (9)

1. When creating the custom metadata structure, you must provide a name (DQ in this example).
2. You can then add as many attributes to that structure as you want.
3. Each attribute must have a name. Because this operation may need to retrieve information from Atlan, you must provide it an AtlanClient through which to connect to the tenant.
4. Each attribute must have a type. When using the enumeration as the type (to constrain its possible values), use AtlanCustomAttributePrimitiveType.OPTIONS as the type.
5. You must then also specify the enumeration that defines the valid values for this attribute. Carrying on the same example, we give the name of the enumeration here: DataQualityDimensions.
6. You must also specify whether the attribute allows multiple values to be captured on it (true) or only a single value (false).
7. You can specify how the custom metadata should appear (in this case, with an emoji).
8. As with all other builder patterns, you must build() the object you've defined.
9. Then you can create() the custom metadata definition within Atlan, including this enumeration-constrained attribute that was defined as part of it.

Raw REST API

POST /api/meta/types/typedefs

{
  "businessMetadataDefs": [
    {
      "category": "BUSINESS_METADATA",
      "name": "DQ", // (1)
      "attributeDefs": [ // (2),
          "isNew": true,
          "enumValues": [
            "Accuracy",
            "Completeness",
            "Consistency",
            "Timeliness",
            "Validity",
            "Uniqueness"
          ]
        }
      ],
      "displayName": "DQ",
      "options": {
        "logoType": "emoji",
        "emoji": "🔖"
      }
    }
  ]
}

1. When creating the custom metadata structure, you must provide a name (DQ in this example).

2. You can then add as many attributes to that structure as you want.

3. Each attribute must have a name. Note, however, that the name should be sent as an empty string when creating an attribute (the name will be generated by the back-end), and it's actually the displayName that gives the name as it will appear in the UI.

4. You must specify the enumeration that defines the valid values for this attribute. Carrying on the same example, we give the name of the enumeration here: DataQualityDimensions.

5. Each attribute must also have a primitive type. When using the enumeration as the type (to constrain its possible values), use:

   • enum as the primitive type
   • isEnum set to true
   • and set enumType to the name of the enumeration

Update options (enumerations)

For example, to update our data quality dimension enumeration by adding a new set of valid values.

Java

Update existing enum structure

EnumDef enumDef = EnumDef.updater(
        client, "DataQualityDimensions", // (1)
        List.of("Unknown", "Others"),  // (2)
        false // (3)
    ).build(); // (4)

EnumDef response = enumDef.update(client); // (5)

1. When updating the existing enumeration, you must provide a name (DataQualityDimensions in this example). Because this operation may need to retrieve information from Atlan, you must provide it an AtlanClient through which to connect to the tenant.
2. You can then add as many valid values as you want: always as a list of strings.
3. You must specify whether you want to replace all existing values in the enumeration with the new ones (true), or if the new ones will be appended to the existing set (false).
4. As with all other builder patterns, you must build() the object you've defined.
5. The update() operation will actually update the enumeration within Atlan, including all the valid values that were defined as part of it. Because this operation will persist the structure in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Update existing enum structure

from pyatlan.model.typedef import EnumDef
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

enum_def = EnumDef.update(
    client=client,
    name="DataQualityDimensions", # (1)
    values=["Unknown", "Others"] # (2)
    replace_existing=False # (3)
)

response = client.typedef.update(enum_def) # (4)

1. When updating the existing enumeration, you must provide a name (DataQualityDimensions in this example).
2. You can then add as many valid values as you want: always as a list of strings.
3. You must specify whether you want to replace all existing values in the enumeration with the new ones (True), or if the new ones will be appended to the existing set (False).
4. The client.typedef.update() operation will actually update the enumeration within Atlan, including all the valid values that were defined as part of it.

Kotlin

Update existing enum structure

val enumDef = EnumDef.updater(
        client, "DataQualityDimensions", // (1)
        listOf("Unknown", "Others"),  // (2)
        false // (3)
    ).build() // (4)

val response = enumDef.update(client) // (5)

1. When updating the existing enumeration, you must provide a name (DataQualityDimensions in this example). Because this operation may need to retrieve information from Atlan, you must provide it an AtlanClient through which to connect to the tenant.
2. You can then add as many valid values as you want: always as a list of strings.
3. You must specify whether you want to replace all existing values in the enumeration with the new ones (true), or if the new ones will be appended to the existing set (false).
4. As with all other builder patterns, you must build() the object you've defined.
5. The update() operation will actually update the enumeration within Atlan, including all the valid values that were defined as part of it. Because this operation will persist the structure in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

PUT /api/meta/types/typedefs

{
  "enumDefs": [ // (1),
        {
          "value": "Completeness",
          "ordinal": 1
        },
        {
          "value": "Consistency",
          "ordinal": 2
        },
        {
          "value": "Timeliness",
          "ordinal": 3
        },
        {
          "value": "Validity",
          "ordinal": 4
        },
        {
          "value": "Uniqueness",
          "ordinal": 5
        },
        {
          "value": "Unknown",
          "ordinal": 6
        },
        {
          "value": "Others",
          "ordinal": 7
        }
      ]
    }
  ]
}

1. All enumeration definitions must be specified within the enumDefs array.
2. Each definition must be defined with a category set to ENUM.
3. The name of the enumeration definition you want to update.
4. You must send all valid values in the elementDefs array, as the existing list of elements for the enumerations will be entirely replaced by what you provide here.

Retrieve options (enumerations)

To retrieve options (enumeration) by name:

Java

Retrieve existing enum structure

TypeDef enumDef = client.typeDefs.get("DataQualityDimensions"); // (1)

1. To retrieve the enumeration, you need to call the .typeDefs.get() method on a client, with the human-readable name of the enumeration.

Python

Retrieve existing enum structure

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
enum_def = client.typedef.get_by_name("DataQualityDimensions") # (1)

1. To retrieve the enumeration, you need to call the client.typedef.get_by_name() method with its human-readable name.

Kotlin

Retrieve existing enum structure

val enumDef = client.typeDefs.get("DataQualityDimensions") // (1)

1. To retrieve the enumeration, you need to call the .typeDefs.get() method on a client, with the human-readable name of the enumeration.

Raw REST API

Options (enumerations) don't have a hashed-string representation

Note that unlike a custom metadata structure, options (enumerations) don't have a hashed-string name. Therefore, use their human-readable name when retrieving its structure.

URL-encoding

However, since this name is embedded in the URL for retrieval, it does need to be url-encoded. For example, if the name contains spaces these need to be replaced with %20.

:::

Retrieve all options (enumerations)

To retrieve all options (enumeration):

Java

Retrieve all enum structures

TypeDefResponse enumDefs = client.typeDefs.list(AtlanTypeCategory.ENUM); // (1)

1. To retrieve all enumerations, call the .typeDefs.list() method on a client, with the category AtlanTypeCategory.ENUM.

Python

Retrieve all enum structures

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.typedef.get(type_category=AtlanTypeCategory.ENUM) # (1)
enum_defs = response.enum_defs # (2)

1. To retrieve all enumerations, call the client.typedef.get() method with the definition category AtlanTypeCategory.ENUM.
2. Specifically retrieve the list of enumerations from TypeDefResponse.

Kotlin

Retrieve all enum structures

val enumDefs = client.typeDefs.list(AtlanTypeCategory.ENUM) // (1)

1. To retrieve all enumerations, call the .typeDefs.list() method on a client, with the category AtlanTypeCategory.ENUM.

Raw REST API

Delete options (enumerations)

To delete options (enumeration):

Java

Delete enum structure

EnumDef.purge(client, "DataQualityDimensions"); // (1)

1. You only need to call the EnumDef.purge() method with the human-readable name of the enumeration, and it will be deleted. Because this operation will remove the structure from Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Python

Delete enum structure

from pyatlan.model.typedef import EnumDef
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
client.typedef.purge("DataQualityDimensions", EnumDef) # (1)

1. You only need to call the clietn.typedef.purge() method with the human-readable name of the enumeration, and it will be deleted.

Kotlin

Delete enum structure

EnumDef.purge("DataQualityDimensions") // (1)

1. You only need to call the EnumDef.purge() method with the human-readable name of the enumeration, and it will be deleted. Because this operation will remove the structure from Atlan, you must provide it an AtlanClient through which to connect to the tenant.

Raw REST API

Options (enumerations) don't have a hashed-string representation

Note that unlike a custom metadata structure, options (enumerations) don't have a hashed-string name. Therefore, use their human-readable name when deleting.

URL-encoding

However, since this name is embedded in the URL for deletion, it does need to be url-encoded. For example, if the name contains spaces these need to be replaced with %20.

:::