Manage cube assets

You can represent most multidimensional cube objects through a common set of multidimensional dataset assets. You can use this structure to create assets for any cube-oriented system you like:

erDiagram
    Connection ||--o{ Cube : contains
    Cube ||--o{ CubeDimension : cubeDimensions
    CubeDimension ||--o{ CubeHierarchy : cubeHierarchies
    CubeHierarchy ||--o{ CubeField : cubeFields
    CubeField ||--o{ CubeField : cubeNestedFields

In general, these should be:

• Created in top-down order (connection, then cube, then dimension, and so on)
• Deleted in bottom-up order (fields, then hierarchies, then dimensions, then cubes, then connection)¹

Where do the icons come from?

Atlan will display icons for these assets based on the type of connector you define in the Connection. You can use API-first types like essbase, for example.

However, note that in all cases the same structure (and types) as illustrated above are used — there are no differences in types between these multidimensional dataset assets across different systems.

Asset structure

Connection

2.0.0 1.0.0

A connection requires a name and qualifiedName. As noted above, a specific setting is also required to determine the icons to use for assets in the connection. In addition, at least one of adminRoles, adminGroups, or adminUsers must be provided.

Java Python Raw REST API

String adminRoleGuid = RoleCache.getIdForName("$admin"); // (1)
Connection connection = Connection.creator( // (2)
        "cube-connection", // (3)
        AtlanConnectorType.ESSBASE, // (4)
        List.of(adminRoleGuid), // (5)
        List.of("group2"), // (6)
        List.of("jsmith")) // (7)
    .build();
AssetMutationResponse response = connection.save(); // (8)
String connectionQualifiedName = response.getCreatedAssets().get(0).getQualifiedName(); // (9)

1. Retrieve the GUID for the admin role, to use later for defining the roles that can administer the connection.
2. Build up the minimum request to create a connection.
3. Provide a human-readable name for your connection, such as production or development.

4. Set the type of connection.

   Determines the icon

   This determines the icon that Atlan will use for all the assets in the connection.

5. List the workspace roles that should be able to administer the connection (or null if none). All users with that workspace role (current and future) will be administrators of the connection. Note that the values here need to be the GUID(s) of the workspace role(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.

6. List the group names that can administer this connection (or null if none). All users within that group (current and future) will be administrators of the connection. Note that the values here are the name(s) of the group(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
7. List the user names that can administer this connection (or null if none). Note that the values here are the username(s) of the user(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
8. Actually call Atlan to create the connection.
9. Retrieve the qualifiedName for use in subsequent creation calls. (You'd probably want to do some null checking first.)

from pyatlan.cache.role_cache import RoleCache
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Connection, Cube, CubeDimension, CubeHierarchy, CubeField
from pyatlan.model.enums import AtlanConnectorType

client = AtlanClient()
admin_role_guid = RoleCache.get_id_for_name("$admin") # (1)
connection = Connection.creator( # (2)
    name="cube-connection", # (3)
    connector_type=AtlanConnectorType.ESSBASE, # (4)
    admin_roles=[admin_role_guid], # (5)
    admin_groups=["group2"], # (6)
    admin_users=["jsmith"], # (7)
)
response = client.asset.save(connection) # (8)
connection_qualified_name = response.assets_created(asset_type=Connection)[0].qualified_name # (9)

1. Retrieve the GUID for the admin role, to use later for defining the roles that can administer the connection.
2. Build up the minimum request to create a connection.
3. Provide a human-readable name for your connection, such as production or development.

4. Set the type of connection.

   Determines the icon

   This determines the icon that Atlan will use for all the assets in the connection.

5. List the workspace roles that should be able to administer the connection (if any, defaults to None). All users with that workspace role (current and future) will be administrators of the connection. Note that the values here need to be the GUID(s) of the workspace role(s). At least one of admin_roles, admin_groups, or admin_users must be provided.

6. List the group names that can administer this connection (if any, defaults to None). All users within that group (current and future) will be administrators of the connection. Note that the values here are the name(s) of the group(s). At least one of admin_roles, admin_groups, or admin_users must be provided.
7. List the user names that can administer this connection (if any, defaults to None). Note that the values here are the username(s) of the user(s). At least one of admin_roles, admin_groups, or admin_users must be provided.
8. Actually call Atlan to create the connection.
9. Retrieve the qualified_name for use in subsequent creation calls. (You'd probably want to do some checks first.)

{
  "entities": [
    {
      "typeName": "Connection", // (1)
      "attributes": {
        "name": "cube-connection", // (2)
        "connectorName": "essbase", // (3)
        "qualifiedName": "default/essbase/123456789", // (4)
        "category": "database", // (5)
        "adminRoles": [ // (6)
          "e7ae0295-c60a-469a-bd2c-fb903943aa02"
        ],
        "adminGroups": [ // (7)
          "group2"
        ],
        "adminUsers": [ // (8)
          "jsmith"
        ]
      }
    }
  ]
}

1. The typeName must be exactly Connection.
2. Human-readable name for your connection, such as production or development.

3. The connectorName should be a known value, such as essbase.

   Determines the icon

   This determines the icon that Atlan will use for all the assets in the connection. If you use a value that is not a known value, you will have a default gear icon instead.

4. The qualifiedName should follow the pattern: default/<connectorName>/<epoch>, where <epoch> is the time in milliseconds at which the connection is being created, and <connectorName> exactly matches the value used for connectorName (above).

5. The category should also be a known value, that defines the kind of cube store. This should be database.
6. List any workspace roles that can administer this connection. All users with that workspace role (current and future) will be administrators of the connection. Note that the values here need to be the GUID(s) of the workspace role(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
7. List any groups that can administer this connection. All users within that group (current and future) will be administrators of the connection. Note that the values here are the name(s) of the group(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
8. List any users that can administer this connection. Note that the values here are the username(s) of the user(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.

Access policies

Atlan creates the policies that grant access to a connection, including the ability to retrieve the connection and to create assets within it, asynchronously. It can take several seconds (even up to approximately 30 seconds) before these are in place after creating the connection.

You may therefore need to wait before you'll be able to create the assets below within the connection.

To confirm access, retrieve the connection after it has been created. The SDKs' retry loops will automatically retry until the connection can be successfully retrieved. At that point, your API token has permission to create the other assets.

Note: if you are reusing an existing connection rather than creating one via your API token, you must give your API token a persona that has access to that connection. Otherwise all attempts to create, read, update, or delete assets within that connection will fail due to a lack of permissions.

Cube

1.10.13

A cube requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the cube.

Java Python Raw REST API

Cube cube = Cube.creator( // (1)
        "cube_name", // (2)
        connectionQualifiedName) // (3)
    .cubeDimensionCount(10) // (4)
    .build();
AssetMutationResponse response = cube.save(); // (4)
cube = response.getResult(cube); // (5)

1. Build up the minimum request to create a cube.
2. Provide a human-readable name for your cube.
3. Provide the qualifiedName of the connection for this cube.
4. (Optional) To ensure the UI displays the correct count of CubeDimensions's, set the cubeDimensionCount directly on the cube instance.
5. Actually call Atlan to create the cube.
6. Retrieve the created cube for use in subsequent creation calls. (You'd probably want to do some null checking first.)

Coming soon

cube = Cube.creator( # (1)
    name="cube_name", # (2)
    connection_qualified_name=connection_qualified_name # (3)
)
cube.cube_dimension_count = 10 # (4)
response = client.asset.save(cube) # (5)
cube_qualified_name = response.assets_created(asset_type=Cube)[0].qualified_name # (6)

1. Build up the minimum request to create a cube.
2. Provide a human-readable name for your cube.
3. Provide the qualified_name of the connection for this cube.
4. (Optional) To ensure the UI displays the correct count of CubeDimensions's, set the cube_dimension_count directly on the Cube instance.
5. Actually call Atlan to create the cube.
6. Retrieve the qualified_name for use in subsequent creation calls. (You'd probably want to do some checks first.)

{
  "entities": [
    {
      "typeName": "Cube", // (1)
      "attributes": {
        "name": "cube_name", // (2)
        "qualifiedName": "default/essbase/123456789/cube_name", // (3)
        "connectionQualifiedName": "default/essbase/123456789", // (4)
        "connectorName": "essbase", // (5)
        "cubeDimensionCount": 10 // (6)
      }
    }
  ]
}

1. The typeName must be exactly Cube.
2. Human-readable name for your cube.
3. The qualifiedName should follow the pattern: default/<connectorName>/<epoch>/<name>, where default/<connectorName>/<epoch> is the qualifiedName of the connection for this cube and <name> is the name of this cube.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this cube.
5. The connectorName must be exactly as used when defining the connection.
6. (Optional) To ensure the UI displays the correct count of CubeDimensions's, set the cubeDimensionCount directly on the cube instance.

CubeDimension

1.10.13

A dimension requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the dimension, and the names and qualifiedNames of the dimension's ancestors.

Java Python Raw REST API

CubeDimension dimension = CubeDimension.creator( // (1)
        "dimension_name", // (2)
        cube) // (3)
    .cubeHierarchyCount(10) // (4)
    .build();
AssetMutationResponse response = dimension.save(); // (5)
dimension = response.getResult(dimension); // (6)

1. Build up the minimum request to create a dimension.
2. Provide a human-readable name for your dimension.
3. Provide the cube for this dimension. If you did not already have the object, you could also use Cube.refByGuid() with the GUID of the cube, or Cube.refByQualifiedName() with the qualifiedName of the cube.
4. (Optional) To ensure the UI displays the correct count of CubeHierarchy's, set the cubeHierarchyCount directly on the CubeHierarchy instance.
5. Actually call Atlan to create the dimension.
6. Retrieve the created dimension for use in subsequent creation calls. (You'd probably want to do some null checking first.)

Coming soon

dimension = CubeDimension.creator( # (1)
    name="dimension_name", # (2)
    cube_qualified_name=cube_qualified_name # (3)
)
dimension.cube_hierarchy_count = 10 # (4)
response = client.asset.save(dimension) # (5)
dimension_qualified_name = response.assets_created(asset_type=CubeDimension)[0].qualified_name # (6)

1. Build up the minimum request to create a dimension.
2. Provide a human-readable name for your dimension.
3. Provide the qualified_name of the cube for this dimension.
4. (Optional) To ensure the UI displays the correct count of CubeHierarchy's, set the cube_hierarchy_count directly on the CubeDimension instance.
5. Actually call Atlan to create the dimension.
6. Retrieve the qualified_name for use in subsequent creation calls. (You'd probably want to do some checks first.)

{
  "entities": [
    {
      "typeName": "CubeDimension", // (1)
      "attributes": {
        "name": "dimension_name", // (2)
        "qualifiedName": "default/essbase/123456789/cube_name/dimension_name", // (3)
        "connectionQualifiedName": "default/essbase/123456789", // (4)
        "connectorName": "essbase", // (5)
        "cube": { // (6)
          "typeName": "Cube", // (7)
          "uniqueAttributes": { // (8)
            "qualifiedName": "default/essbase/123456789/cube_name"
          }
        },
        "cubeName": "cube_name", // (9)
        "cubeQualifiedName": "default/essbase/123456789/cube_name", // (10)
        "cubeHierarchyCount": 10 // (11)
      }
    }
  ]
}

1. The typeName must be exactly CubeDimension.
2. Human-readable name for your dimension.
3. The qualifiedName should follow the pattern: default/<connectorName>/<epoch>/<cube_name>/<name>, where default/<connectorName>/<epoch>/<cube_name> is the qualifiedName of the cube for this dimension, and <name> is the name of the dimension.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this dimension.
5. The connectorName must be exactly as used when defining the connection.
6. The cube in which this dimension exists is embedded in the cube attribute.
7. The typeName for this embedded reference must be Cube.
8. To complete the reference, you must include a uniqueAttributes object with the qualifiedName of the cube. Note: the cube must already exist in Atlan before creating the dimension.
9. The cubeName should be the human-readable name of the cube.
10. The cubeQualifiedName should be the qualifiedName of the cube.
11. (Optional) To ensure the UI displays the correct count of CubeHierarchy's, set the cubeHierarchyCount directly on the CubeHierarchy instance.

CubeHierarchy

2.1.2 1.10.13

A hierarchy requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the hierarchy, and the names and qualifiedNames of the hierarchy's ancestors.

Java Python Raw REST API

CubeHierarchy hierarchy = CubeHierarchy.creator( // (1)
        "hierarchy_name", // (2)
        dimension) // (3)
    .cubeFieldCount(10) // (4)
    .build();
AssetMutationResponse response = hierarchy.save(); // (5)
hierarchy = response.getResult(hierarchy).get(0).getQualifiedName(); // (6)

1. Build up the minimum request to create a hierarchy.
2. Provide a human-readable name for your hierarchy.
3. Provide the dimension for this hierarchy. If you did not already have the object, you could also use CubeDimension.refByGuid() with the GUID of the dimension, or CubeDimension.refByQualifiedName() with the qualifiedName of the dimension.
4. (Optional) To ensure the UI displays the correct count of CubeField's, set the cubeFieldCount directly on the CubeHierarchy instance.
5. Actually call Atlan to create the hierarchy.
6. Retrieve the created hierarchy for use in subsequent creation calls. (You'd probably want to do some null checking first.)

Coming soon

hierarchy = CubeHierarchy.creator( # (1)
    name="hierarchy_name", # (2)
    cube_dimension_qualified_name=dimension_qualified_name # (3)
)
hierarchy.cube_field_count = 10 # (4)
response = client.asset.save(hierarchy) # (5)
hierarchy_qualified_name = response.assets_created(asset_type=CubeHierarchy)[0].qualified_name # (6)

1. Build up the minimum request to create a hierarchy.
2. Provide a human-readable name for your hierarchy.
3. Provide the qualified_name of the dimension for this hierarchy.
4. (Optional) To ensure the UI displays the correct count of CubeField's, set the cube_field_count directly on the CubeHierarchy instance.
5. Actually call Atlan to create the hierarchy.
6. Retrieve the qualified_name for use in subsequent creation calls. (You'd probably want to do some checks first.)

{
  "entities": [
    {
      "typeName": "CubeHierarchy", // (1)
      "attributes": {
        "name": "hierarchy_name", // (2)
        "qualifiedName": "default/essbase/123456789/cube_name/dimension_name/hierarchy_name", // (3)
        "connectionQualifiedName": "default/essbase/123456789", // (4)
        "connectorName": "essbase", // (5)
        "cubeDimension": { // (6)
          "typeName": "CubeDimension", // (7)
          "uniqueAttributes": { // (8)
            "qualifiedName": "default/essbase/123456789/cube_name/dimension_name"
          }
        },
        "cubeDimensionName": "dimension_name", // (9)
        "cubeDimensionQualifiedName": "default/essbase/123456789/cube_name/dimension_name", // (10)
        "cubeName": "cube_name", // (11)
        "cubeQualifiedName": "default/essbase/123456789/cube_name", // (12)
        "cubeFieldCount": 10 // (13)
      }
    }
  ]
}

1. The typeName must be exactly CubeHierarchy.
2. Human-readable name for your hierarchy.
3. The qualifiedName should follow the pattern: default/<connectorName>/<epoch>/<cube_name>/<dimension_name>/<name>, where default/<connectorName>/<epoch>/<cube_name>/<dimension_name> is the qualifiedName of the dimension for this hierarchy, and <name> is the name of the hierarchy.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this hierarchy.
5. The connectorName must be exactly as used when defining the connection.
6. The dimension in which this hierarchy exists is embedded in the cubeDimension attribute.
7. The typeName for this embedded reference must be CubeDimension.
8. To complete the reference, you must include a uniqueAttributes object with the qualifiedName of the dimension. Note: the dimension must already exist in Atlan before creating the hierarchy.
9. The cubeDimensionName should be the human-readable name of the dimension.
10. The cubeDimensionQualifiedName should be the qualifiedName of the dimension.
11. The cubeName should be the human-readable name of the cube.
12. The cubeQualifiedName should be the qualifiedName of the cube.
13. (Optional) To ensure the UI displays the correct count of CubeField's, set the cubeFieldCount directly on the CubeHierarchy instance.

CubeField

2.1.2 1.10.13

A field requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the field, and the names and qualifiedNames of the fields's ancestors.

Java Python Raw REST API

CubeField field = CubeField.creator( // (1)
        "field1", // (2)
        hierarchy) // (3)
    .build();
AssetMutationResponse response = field.save(); // (4)

1. Build up the minimum request to create a field.
2. Provide a human-readable name for your field.
3. Provide the parent for this field. If you did not already have the object, you could also use CubeHierarchy.refByGuid() with the GUID of a hierarchy (or CubeField.refByGuid() if this is a nested field), or CubeHierarchy.refByQualifiedName() with the qualifiedName of a hierarchy (or CubeField.refByQualifiedName() if this is a nested field).
4. Actually call Atlan to create the field.

Coming soon

field = CubeField.creator( # (1)
    name="field1", # (2)
    parent_type=Table, # (3)
    parent_qualified_name=hierarchy_qualified_name # (4)
)
response = client.asset.save(field) # (5)

1. Build up the minimum request to create a field.
2. Provide a human-readable name for your field.
3. Specify the type of the parent asset for the field (hierarchy or field).
4. Provide the qualified_name of the parent asset for this field. In this example you're defining a field in a hierarchy, so you can use the hierarchy_qualified_name created above. If the parent asset type were CubeField you would want to use the qualified_name of some previously-created field.
5. Actually call Atlan to create the field.

{
  "entities": [
    {
      "typeName": "CubeField", // (1)
      "attributes": {
        "name": "field1", // (2)
        "qualifiedName": "default/essbase/123456789/cube_name/dimension_name/hierarchy_name/field1", // (3)
        "connectionQualifiedName": "default/essbase/123456789", // (4)
        "connectorName": "essbase", // (5)
        "cubeHierarchy": { // (6)
          "typeName": "CubeHierarchy", // (7)
          "uniqueAttributes": { // (8)
            "qualifiedName": "default/essbase/123456789/cube_name/dimension_name/hierarchy_name"
          }
        },
        "cubeHierarchyName": "hierarchy_name", // (9)
        "cubeHierarchyQualifiedName": "default/essbase/123456789/cube_name/dimension_name/hierarchy_name", // (10)
        "cubeDimensionName": "dimension_name", // (11)
        "cubeDimensionQualifiedName": "default/essbase/123456789/cube_name/dimension_name", // (12)
        "cubeName": "cube_name", // (13)
        "cubeQualifiedName": "default/essbase/123456789/cube_name" // (14)
      }
    }
  ]
}

1. The typeName must be exactly CubeField.
2. Human-readable name for your field.
3. The qualifiedName should follow the pattern: default/<connectorName>/<epoch>/<cube_name>/<dimension_name>/<hierarchy_name>/<name>, where default/<connectorName>/<epoch>/<cube_name>/<dimension_name>/<hierarchy_name> is the qualifiedName of the parent hierarchy for this field, and <name> is the name of the field.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this field.
5. The connectorName must be exactly as used when defining the connection.
6. The hierarchy in which the field exists is embedded in the cubeHierarchy attribute.
7. The typeName for this embedded reference must be CubeHierarchy.
8. To complete the reference, you must include a uniqueAttributes object with the qualifiedName of the hierarchy. Note: the hierarchy must already exist in Atlan before creating the field.
9. The cubeHierarchyName should be the human-readable name of the hierarchy.
10. The cubeHierarchyQualifiedName should be the qualifiedName of the hierarchy.
11. The cubeDimensionName should be the human-readable name of the dimension.
12. The cubeDimensionQualifiedName should be the qualifiedName of the dimension.
13. The cubeName should be the human-readable name of the cube.
14. The cubeQualifiedName should be the qualifiedName of the cube.

Available relationships

Every level of the cube structure is an Asset, and can therefore be related to the following other assets.

erDiagram
  Asset }o--o{ AtlasGlossaryTerm : meanings
  Asset ||--o{ Link : links
  Asset ||--o| Readme : readme
  Asset }o--o{ Process : inputToProcesses
  Asset }o--o{ Process : outputFromProcesses

AtlasGlossaryTerm

A glossary term provides meaning to an asset. The link terms to assets snippet provides more detail on setting this relationship.

Link

A link provides additional context to an asset, by providing a URL to additional information.

Readme

A README provides rich documentation for an asset. The add asset READMEs snippet provides more detail on setting this relationship.

Process

A process provides lineage information for an asset. An asset can be both an input and an output for one or more processes. The lineage snippets provide more detail on creating and working with lineage.

---

1. Although if you want to delete everything in a connection, your better avenue is the packaged connection delete utility in the UI. ↩

---