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¶

1.3.3 1.0.0

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

Java Python Kotlin Raw REST API

Build enumeration for creation
EnumDef enumDef = EnumDef.creator(
        "DataQualityDimensions", // When creating the enumeration, you must provide a name (DataQualityDimensions in this example).

        List.of("Accuracy", "Completeness", "Consistency", "Timeliness", "Validity", "Uniqueness")) // 2
    .build(); // As with all other builder patterns, you must build() the object you've defined.

Build enumeration for creation
from pyatlan.model.typedef import EnumDef

enum_def = EnumDef.create(
    name="DataQualityDimensions", # When creating the enumeration, you must provide a name (DataQualityDimensions in this example).

    values=["Accuracy", "Completeness", "Consistency", "Timeliness", "Validity", "Uniqueness"] # You can then add as many valid values as you want: always as a list of strings.

)

Build enumeration for creation
val enumDef = EnumDef.creator(
        "DataQualityDimensions",  // When creating the enumeration, you must provide a name (DataQualityDimensions in this example).

        listOf("Accuracy", "Completeness", "Consistency", "Timeliness", "Validity", "Uniqueness")) // 2
    .build() // As with all other builder patterns, you must build() the object you've defined.

POST /api/meta/types/typedefs
{
  "enumDefs": [ // All enumeration definitions must be specified within the enumDefs array.

    {
      "category": "ENUM", // Each definition must be defined with a category set to ENUM.

      "name": "DataQualityDimensions", // The name you provide for the definition will be used both for the front and back-end.

      "elementDefs": [ // 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.

        {
          "value": "Accuracy",
          "ordinal": 0
        },
        {
          "value": "Completeness",
          "ordinal": 1
        },
        {
          "value": "Consistency",
          "ordinal": 2
        },
        {
          "value": "Timeliness",
          "ordinal": 3
        },
        {
          "value": "Validity",
          "ordinal": 4
        },
        {
          "value": "Uniqueness",
          "ordinal": 5
        }
      ]
    }
  ]
}

Create the enumeration from the object¶

1.3.3 4.0.0

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 Python Kotlin Raw REST API

Create the enumeration
EnumDef response = enumDef.create(client); // 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.

Create the enumeration
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.typedef.create(enum_def) # The typedef.create() operation will actually create the enumeration definition within Atlan, including all the valid values that were defined as part of it.

Create the enumeration
val response = enumDef.create(client) // 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.

Creation implicit in step above

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

Use an enumeration in a custom metadata definition¶

1.3.3 4.0.0

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

Java Python Kotlin Raw REST API

Build custom metadata definition for creation
CustomMetadataDef customMetadataDef = CustomMetadataDef.creator("DQ") // When creating the custom metadata structure, you must provide a name (DQ in this example).

    .attributeDef( // You can then add as many attributes to that structure as you want.

        AttributeDef.of(client, "Dimension", // 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.

            AtlanCustomAttributePrimitiveType.OPTIONS, // Each attribute must have a type. When using the enumeration as the type (to constrain its possible values), use AtlanCustomAttributePrimitiveType.OPTIONS as the type.

            "DataQualityDimensions", // 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.

            false)) // You must also specify whether the attribute allows multiple values to be captured on it (true) or only a single value (false).

    .options(CustomMetadataOptions.withLogoAsEmoji("🔖")) // You can specify how the custom metadata should appear (in this case, with an emoji).

    .build(); // As with all other builder patterns, you must build() the object you've defined.

customMetadataDef.create(); // Then you can create() the custom metadata definition within Atlan, including this enumeration-constrained attribute that was defined as part of it.

Build custom metadata definition for creation
from pyatlan.model.typedef import AttributeDef, CustomMetadataDef
from pyatlan.model.enums import AtlanCustomAttributePrimitiveType

cm_def = CustomMetadataDef.create(display_name="DQ") # When creating the custom metadata structure, you must provide a name (DQ in this example).

cm_def.attribute_defs = [ # You can then add as many attributes to that structure as you want.

    AttributeDef.create(
        display_name="Dimension", # Each attribute must have a name.

        attribute_type=AtlanCustomAttributePrimitiveType.OPTIONS, # Each attribute must have a type. When using the enumeration as the type (to constrain its possible values), use AtlanCustomAttributePrimitiveType.OPTIONS as the type.

        options_name="DataQualityDimensions", # 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.

    ),
]
cm_def.options = CustomMetadataDef.Options.with_logo_as_emoji( # You can specify how the custom metadata should appear (in this case, with an emoji).

    emoji="🔖"
)

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
client.typedef.create(cm_def) # Then you can create the custom metadata definition within Atlan, including this enumeration-constrained attribute that was defined as part of it.

Build custom metadata definition for creation
val customMetadataDef = CustomMetadataDef.creator("DQ") // When creating the custom metadata structure, you must provide a name (DQ in this example).

    .attributeDef( // You can then add as many attributes to that structure as you want.

        AttributeDef.of(client, "Dimension",  // 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.

            AtlanCustomAttributePrimitiveType.OPTIONS,  // Each attribute must have a type. When using the enumeration as the type (to constrain its possible values), use AtlanCustomAttributePrimitiveType.OPTIONS as the type.

            "DataQualityDimensions",  // 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.

            false)) // You must also specify whether the attribute allows multiple values to be captured on it (true) or only a single value (false).

    .options(CustomMetadataOptions.withLogoAsEmoji("🔖")) // You can specify how the custom metadata should appear (in this case, with an emoji).

    .build() // As with all other builder patterns, you must build() the object you've defined.

customMetadataDef.create() // Then you can create() the custom metadata definition within Atlan, including this enumeration-constrained attribute that was defined as part of it.

POST /api/meta/types/typedefs

{
  "businessMetadataDefs": [
    {
      "category": "BUSINESS_METADATA",
      "name": "DQ", // When creating the custom metadata structure, you must provide a name (DQ in this example).

      "attributeDefs": [ // You can then add as many attributes to that structure as you want.

        {
          "name": "", // 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 is actually the displayName that gives the name as it will appear in the UI.

          "displayName": "Dimension",
          "description": "",
          "typeName": "DataQualityDimensions", // 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.

          "isOptional": true,
          "cardinality": "SINGLE",
          "valuesMinCount": 0,
          "valuesMaxCount": 1,
          "isUnique": false,
          "isIndexable": true,
          "includeInNotification": false,
          "options": {
            "applicableEntityTypes": "[\"Asset\"]",
            "customApplicableEntityTypes": "[\"PowerBIMeasure\",\"TableauWorkbook\",\"LookerModel\",\"MetabaseCollection\",\"ModeQuery\",\"GCSBucket\",\"LookerTile\",\"Table\",\"PowerBITile\",\"PowerBIPage\",\"SalesforceOrganization\",\"PresetWorkspace\",\"TableauDatasource\",\"PresetDataset\",\"TableauCalculatedField\",\"LookerFolder\",\"TableauWorksheet\",\"MetabaseQuestion\",\"AtlasGlossary\",\"PresetChart\",\"PowerBITable\",\"LookerProject\",\"SnowflakePipe\",\"PowerBIReport\",\"SigmaDatasetColumn\",\"TableauDatasourceField\",\"TablePartition\",\"AtlasGlossaryTerm\",\"SigmaDataElementField\",\"Schema\",\"Database\",\"DbtColumnProcess\",\"S3Object\",\"LookerLook\",\"TableauSite\",\"SnowflakeStream\",\"ModeCollection\",\"LookerDashboard\",\"PowerBIWorkspace\",\"Collection\",\"AtlasGlossaryCategory\",\"TableauFlow\",\"LookerView\",\"TableauProject\",\"LookerExplore\",\"ModeReport\",\"PowerBIColumn\",\"Query\",\"ColumnProcess\",\"SalesforceDashboard\",\"SalesforceObject\",\"BIProcess\",\"DbtModelColumn\",\"S3Bucket\",\"SigmaDataElement\",\"DataStudioAsset\",\"DbtProcess\",\"DbtModel\",\"PowerBIDataset\",\"Column\",\"DbtMetric\",\"TableauDashboard\",\"SigmaDataset\",\"LookerQuery\",\"APISpec\",\"MetabaseDashboard\",\"Process\",\"PowerBIDashboard\",\"APIPath\",\"ModeChart\",\"PowerBIDataflow\",\"SalesforceField\",\"GCSObject\",\"SalesforceReport\",\"View\",\"Folder\",\"TableauMetric\",\"MaterialisedView\",\"PresetDashboard\",\"PowerBIDatasource\",\"ModeWorkspace\",\"SigmaPage\",\"LookerField\",\"SigmaWorkbook\"]",
            "allowSearch": false,
            "maxStrLength": "100000000",
            "allowFiltering": true,
            "multiValueSelect": false,
            "showInOverview": false,
            "primitiveType": "enum", // 
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


            "isEnum": true,
            "enumType": "DataQualityDimensions"
          },
          "isNew": true,
          "enumValues": [
            "Accuracy",
            "Completeness",
            "Consistency",
            "Timeliness",
            "Validity",
            "Uniqueness"
          ]
        }
      ],
      "displayName": "DQ",
      "options": {
        "logoType": "emoji",
        "emoji": "🔖"
      }
    }
  ]
}

Update options (enumerations)¶

2.1.0 4.0.0

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

Java Python Kotlin Raw REST API

Update existing enum structure
EnumDef enumDef = EnumDef.updater(
        client, "DataQualityDimensions", // 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.

        List.of("Unknown", "Others"),  // You can then add as many valid values as you want: always as a list of strings.

        false // 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).

    ).build(); // As with all other builder patterns, you must build() the object you've defined.

EnumDef response = enumDef.update(client); // 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.

Update existing enum structure
from pyatlan.model.typedef import EnumDef
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

enum_def = EnumDef.update(
    name="DataQualityDimensions", # When updating the existing enumeration, you must provide
a name (DataQualityDimensions in this example).

    values=["Unknown", "Others"] # You can then add as many valid values as you want: always as a list of strings.

    replace_existing=False # 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).

)

response = client.typedef.update(enum_def) # The client.typedef.update() operation will actually update the enumeration within Atlan,
including all the valid values that were defined as part of it.

Update existing enum structure
val enumDef = EnumDef.updater(
        client, "DataQualityDimensions", // 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.

        listOf("Unknown", "Others"),  // You can then add as many valid values as you want: always as a list of strings.

        false // 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).

    ).build() // As with all other builder patterns, you must build() the object you've defined.

val response = enumDef.update(client) // 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.

PUT /api/meta/types/typedefs
{
  "enumDefs": [ // All enumeration definitions must be specified within the enumDefs array.

    {
      "category": "ENUM", // Each definition must be defined with a category set to ENUM.

      "name": "DataQualityDimensions", // The name of the enumeration definition you want to update.

      "elementDefs": [ // 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.

        {
          "value": "Accuracy",
          "ordinal": 0
        },
        {
          "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
        }
      ]
    }
  ]
}

Retrieve options (enumerations)¶

2.1.0 1.0.0

To retrieve options (enumeration) by name:

Java Python Kotlin Raw REST API

Retrieve existing enum structure
TypeDef enumDef = client.typeDefs.get("DataQualityDimensions"); // To retrieve the enumeration, you need to call the .typeDefs.get() method on a client, with the human-readable name of the enumeration.

Retrieve existing enum structure
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
enum_def = client.typedef.get_by_name("DataQualityDimensions") # To retrieve the enumeration, you need to call the
client.typedef.get_by_name() method with its human-readable name.

Retrieve existing enum structure
val enumDef = client.typeDefs.get("DataQualityDimensions") // To retrieve the enumeration, you need to call the .typeDefs.get() method on a client, with the human-readable name of the enumeration.

GET /api/meta/types/typedef/name/DataQualityDimensions
1

Options (enumerations) do not have a hashed-string representation

Note that unlike a custom metadata structure, options (enumerations) do not 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)¶

1.3.3 4.0.0

To retrieve all options (enumeration):

Java Python Kotlin Raw REST API

Retrieve all enum structures
TypeDefResponse enumDefs = client.typeDefs.list(AtlanTypeCategory.ENUM); // To retrieve all enumerations, call the .typeDefs.list() method on a client, with the category AtlanTypeCategory.ENUM.

Retrieve all enum structures
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.typedef.get(type_category=AtlanTypeCategory.ENUM) # To retrieve all enumerations, call the client.typedef.get()
method with the definition category AtlanTypeCategory.ENUM.

enum_defs = response.enum_defs # Specifically retrieve the list of enumerations from TypeDefResponse.

Retrieve all enum structures
val enumDefs = client.typeDefs.list(AtlanTypeCategory.ENUM) // To retrieve all enumerations, call the .typeDefs.list() method on a client, with the category AtlanTypeCategory.ENUM.

GET /api/meta/types/typedefs/?type=ENUM
1

Delete options (enumerations)¶

1.3.3 4.0.0

To delete options (enumeration):

Java Python Kotlin Raw REST API

Delete enum structure
EnumDef.purge(client, "DataQualityDimensions"); // 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.

Delete enum structure
from pyatlan.model.typedef import EnumDef
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
client.typedef.purge("DataQualityDimensions", EnumDef) # You only need to call the clietn.typedef.purge() method
with the human-readable name of the enumeration, and it will be deleted.

Delete enum structure
EnumDef.purge("DataQualityDimensions") // 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.

DELETE /api/meta/types/typedef/name/DataQualityDimensions
1

Options (enumerations) do not have a hashed-string representation

Note that unlike a custom metadata structure, options (enumerations) do not 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.