Extending Atlan's model

You can extend the metadata model in Atlan through its typedefs.

Closed beta

This feature is currently provided as a closed beta. Specific policies must be configured in your tenant to have the necessary access to create these extensions; without these operations these will not work.

Further caveats

When extending the Atlan data model, you should be aware of these additional restrictions:

• You can only manage definitions that are not in Atlan's internally-managed namespace, defined by the serviceType of each model.
• So if you want to extend an existing model, you should create a new type in your own serviceType and specify the model you want to extend as the supertype of that model.
• You should follow a naming convention that prefixes all attributes you define, to avoid potential future conflicts with Atlan-managed attributes.

Create new struct models

You can use structs to embed complex structures within other models. If you only intend to use primitive attributes, you do not need to define any structs.

To create a new struct model:

Java

final String ATTR_PREFIX = "myns";
List<AttributeDef> attrs = List.of( // (1)
        AttributeDef.creator(ATTR_PREFIX + "FieldOne", AtlanAttributeType.STRING).build(), // (2)
        AttributeDef.creator(ATTR_PREFIX + "FieldTwo", AtlanAttributeType.LONG).build());
StructDef sd = StructDef.creator("SomeStruct", attrs) // (3)
    .serviceType("custom") // (4)
    .build();
TypeDefResponse response = Atlan.getDefaultClient().typeDefs._create(sd); // (5)

1. Begin by defining the list of attribute definitions for the struct model.
2. Each attribute definition must have at least a name and a type.
3. Define the struct model itself by providing at least a name and the list of attribute definitions.
4. (Optional) You can also specify your own namespace for the model using serviceType. This will default to custom_extension if not specified.
5. Call the _create() method to actually create the new struct model in Atlan.

Create new entity models

Entities define the metadata objects that Atlan can store, update, search, and so on. They can be made up of both primitive and struct-based (complex) attributes. To create a new entity model:

Java

List<AttributeDef> attrs = List.of( // (1)
        AttributeDef.creator(ATTR_PREFIX + "ParentAttrOne", AtlanAttributeType.STRING).build(),
        AttributeDef.creator( // (2)
                        ATTR_PREFIX + "ParentStructs",
                        AtlanAttributeType.STRUCT,
                        "SomeStruct",
                        AtlanCustomAttributeCardinality.SET) // (3)
                .build());
EntityDef ed = EntityDef.creator("SomeParent", attrs)
    .serviceType("custom") // (4)
    .build(); // (5)
TypeDefResponse response = Atlan.getDefaultClient().typeDefs._create(ed); // (6)
attrs = List.of(
        AttributeDef.creator(ATTR_PREFIX + "ChildAttrOne", AtlanAttributeType.LONG).build(),
        AttributeDef.creator(ATTR_PREFIX + "ChildAttrTwo", AtlanAttributeType.DATE).build());
ed = EntityDef.creator("SomeChild", attrs)
    .serviceType("custom")
    .build();
TypeDefResponse response = Atlan.getDefaultClient().typeDefs._create(ed);

1. Begin by defining the list of attribute definitions for the entity model.
2. Each attribute definition must have at least a name and a type. If the type is not primitive (in this example a struct), you must also specify the kind of object (struct).
3. You can also override the cardinality, in this example we allow multiple embedded complex values against this single attribute.
4. (Optional) You can also specify your own namespace for the model using serviceType. This will default to custom_extension if not specified.
5. Define the entity model itself by providing at least a name and the list of attribute definitions.
6. Call the _create() method to actually create the new entity model in Atlan.

Create new relationship models

Relationships define connections between entities. They must always have two entity model endpoints. To create a new relationship model:

Java

List<AttributeDef> attrs = List.of( // (1)
        AttributeDef.creator(ATTR_PREFIX + "RelationshipAttrOne", AtlanAttributeType.STRING).build(), // (2)
        AttributeDef.creator(ATTR_PREFIX + "RelationshipAttrTwo", AtlanAttributeType.LONG).build());
RelationshipEndDef one = RelationshipEndDef.creator( // (3)
                ATTR_PREFIX + "Children", // (4)
                "SomeParent", // (5)
                true, // (6)
                AtlanCustomAttributeCardinality.SET) // (7)
        .build();
RelationshipEndDef two = RelationshipEndDef.creator( // (8)
                ATTR_PREFIX + "Parent", // (9)
                "SomeChild", // (10)
                false, // (11)
                AtlanCustomAttributeCardinality.SINGLE) // (12)
        .build();
RelationshipDef rd = RelationshipDef.creator(RELATIONSHIP_DEF_NAME, one, two, attrs) // (13)
        .relationshipCategory(RelationshipCategory.AGGREGATION) // (14)
        .serviceType("custom") // (15)
        .build();
TypeDefResponse response = Atlan.getDefaultClient().typeDefs._create(rd); // (16)

1. (Optional) Begin by defining the list of attribute definitions for the relationship model. These are optional for a relationship, but are used to capture any attributes on each instance of the relationship.
2. Each attribute definition must have at least a name and a type. If the type is not primitive (in this example a struct), you must also specify the kind of object (struct).
3. Define each entity endpoint of the relationship.
4. You must give the endpoint a name — this will be the name of the attribute that appears in the entity itself to represent this relationship.
5. You must specify the type of entity this relationship exists on (where the attribute name above will appear).
6. Specify whether the relationship on this entity "contains" the other entities. For parent-child relationships this should be true on the parent entity type, and false otherwise.
7. Specify the cardinality of the relationship: in this example we allow multiple children to be related to the parent type.
8. Since every relationship is between exactly two entities, create an endpoint for the other side of the relationship as well.
9. As before, you must give the endpoint a name — this will be the name of the attribute that appears in the entity itself to represent this relationship.
10. You must specify the type of entity this relationship exists on (where the attribute name above will appear).
11. Since this example is the child referring to its parent, the child is not a container.
12. Since this example is the child referring to a single parent, this end of the relationship's cardinality is singular.
13. Define the relationship model itself by providing at least a name, the two endpoints, and (optionally) the list of attribute definitions.

14. By default, a relationship will be created as an ASSOCIATION. You can override this with any of:

    • ASSOCIATION: defines a peer-to-peer relationship between the entity endpoints.
    • AGGREGATION: defines a relationship where one endpoint is logically the "parent" of another endpoint. This differs from the COMPOSITION by not cascading deletes to related entities.
    • COMPOSITION: defines a relationship where one endpoint is strictly the "parent" of another endpoint. This differs from AGGREGATION because any removal of the entity at the parent end of the relationship will cascade to removing any of the related children entities as well.

15. (Optional) You can also specify your own namespace for the model using serviceType. This will default to custom_extension if not specified.

16. Call the _create() method to actually create the new entity model in Atlan.

Update existing models

Treat existing attributes as immutable

You can also update existing entity models. However, in general you should only append (create new) attributes and not remove or attempt to change any existing attributes, or you may lose data from those existing attributes.

To update an existing model, first retrieve it and then apply updates to it:

Java

EntityDef parent = (EntityDef) Atlan.getDefaultClient().typeDefs.get("SomeParent"); // (1)
parent = parent.toBuilder() // (2)
        .attributeDef(AttributeDef.creator(ATTR_PREFIX + "ThirdAttribute", AtlanAttributeType.BOOLEAN) // (3)
                .build())
        .typeVersion("1.1") // (4)
        .build();
TypeDefResponse response = Atlan.getDefaultClient().typeDefs._update(parent); // (5)

1. Begin by retrieving the existing model's definition.

2. You can convert the immutable object returned into a mutatable builder using the .toBuilder() method.

   Remember to assign the value back

   Remember to assign the built immutable value back to some variable, and use that variable in the next step. Otherwise the changes you make here will not be applied back.

3. You can then append as many additional attributes as you like.

4. You should also update the typeVersion of the model to the next minor version.
5. Call the _update() method to actually update the existing model in Atlan.

---