## Managing data domains

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/python/data-mesh/how-tos/manage-data-domains

> Create, update, and delete data domains in Atlan using the Python SDK (pyatlan) — use DataDomain.creator() to define domains with icons, colors, and hierarchies.

# DataDomain: create and manage data domains

Use `DataDomain` in the Atlan Python SDK to programmatically create and manage data domains in your data mesh.

## Create new data domain

To create a new data domain:

### Java

```java showLineNumbers title="Create a data domain"
DataDomain domain = DataDomain.creator("Marketing") // (1)
 .assetIcon(AtlanIcon.ROCKET) // (2)
 .assetThemeHex(AtlanMeshColor.MAGENTA)
 .build(); // (3)
AssetMutationResponse response = domain.save(client); // (4)
```

1. You must provide a human-readable name for your data domain.
2. You can chain onto the creator any other enrichment, for example choosing a different icon or color to represent the domain.
3. You then need to build the object.
4. You can then `save()` the object you've built to create the new data domain in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="Create a data domain"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataDomain
from pyatlan.model.enums import AtlanIcon, AtlanMeshColor

client = AtlanClient()

domain = DataDomain.creator(
 name="Marketing", # (1)
)
domain.asset_icon = AtlanIcon.ROCKET # (2)
domain.asset_theme_hex = AtlanMeshColor.MAGENTA

response = client.asset.save(domain) # (3)
```

1. You must provide a human-readable name for your data domain.
2. You can apply any other enrichment, for example choosing a different icon or color to represent the domain.
3. You can then `save()` the object to create the new data domain in Atlan.

### Kotlin

```kotlin showLineNumbers title="Create a data domain"
val domain = DataDomain.creator("Marketing") // (1)
 .assetIcon(AtlanIcon.ROCKET) // (2)
 .assetThemeHex(AtlanMeshColor.MAGENTA)
 .build() // (3)
val response = domain.save(client) // (4)
```

1. You must provide a human-readable name for your data domain.
2. You can chain onto the creator any other enrichment, for example choosing a different icon or color to represent the domain.
3. You then need to build the object.
4. You can then `save()` the object you've built to create the new data domain in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="POST /api/meta/entity/bulk"
{
 "entities": [
 {
 "typeName": "DataDomain", // (1)
 "attributes": {
 "name": "Marketing", // (2)
 "assetIcon": "PhRocket", // (3)
 "assetThemeHex": "#F34D77",
 "qualifiedName": "default/domain/marketing" // (4)
 }
 }
 ]
}
```

1. The `typeName` must be exactly `DataDomain`.
2. Human-readable name for your data domain.
3. You can specify other enrichment, for example choosing a different icon or color to represent the domain.
4. The `qualifiedName` should follow the pattern: `default/domain/<lowerCamelCaseName>`.

## Create new subdomain

To create a new subdomain:

### Java

```java showLineNumbers title="Create a subdomain"
DataDomain sub = DataDomain.creator("Social Marketing", // (1)
 DataDomain.refByQualifiedName("default/domain/marketing")) // (2)
 .build(); // (3)
AssetMutationResponse response = sub.save(client); // (4)
```

1. You must provide a human-readable name for your data domain.
2. To create subdomain, you must provide the parent domain with at least its `qualifiedName`.
3. You can chain on other enrichment, like above, but ultimately then need to build the object.
4. You can then `save()` the object you've built to create the new data subdomain in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="Create a subdomain"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataDomain

client = AtlanClient()

sub_domain = DataDomain.creator(
 name="Social Marketing", # (1)
 parent_domain_qualified_name="default/domain/marketing", # (2)
)
response = client.asset.save(sub_domain)
```

1. Human-readable name for your data domain.
2. To create subdomain, you must provide the parent domain `qualifiedName`.

### Kotlin

```kotlin showLineNumbers title="Create a subdomain"
val sub = DataDomain.creator("Social Marketing", // (1)
 DataDomain.refByQualifiedName("default/domain/marketing")) // (2)
 .build() // (3)
val response = sub.save(client) // (4)
```

1. You must provide a human-readable name for your data domain.
2. To create subdomain, you must provide the parent domain with at least its `qualifiedName`.
3. You can chain on other enrichment, like above, but ultimately then need to build the object.
4. You can then `save()` the object you've built to create the new data subdomain in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="POST /api/meta/entity/bulk"
{
 "entities": [
 {
 "typeName": "DataDomain", // (1)
 "attributes": {
 "name": "Social Marketing", // (2)
 "qualifiedName": "default/domain/gAbQGZNrFjG2F9lGB3hYp/super/domain/socialMarketing", // (3)
 "parentDomainQualifiedName": "default/domain/gAbQGZNrFjG2F9lGB3hYp/super", // (4)
 "superDomainQualifiedName": "default/domain/gAbQGZNrFjG2F9lGB3hYp/super" // (5)
 },
 "relationshipAttributes": {
 "parentDomain": { // (6)
 "typeName": "DataDomain",
 "uniqueAttributes": {
 "qualifiedName": "default/domain/gAbQGZNrFjG2F9lGB3hYp"
 }
 }
 }
 }
 ]
}
```

1. The `typeName` must be exactly `DataDomain`.
2. Human-readable name for your data sub-domain.
3. The `qualifiedName` should follow the pattern: `<parentQualifiedName>/domain/<lowerCamelCaseName>`.
4. You must provide the `qualifiedName` of the parent domain.
5. Provide a `superDomainQualifiedName` for the data domain under which you want to create this sub-domain.
If creating a sub-domain under another sub-domains (ie. nested sub-domains), this should be the qualified name of the root-level domain.
6. You must also specify a relationship to the parent domain, in this example through its `qualifiedName`.

## Retrieve data domain

To retrieve a data domain by its human-readable name:

### Java

```java showLineNumbers title="Retrieve a data domain by its human-readable name"
DataDomain domain = DataDomain.findByName( // (1)
 client, "marketing", List.of("certificateStatus")
).get(0);
```

1. Use `DataDomain.findByName()` method to retrieve a data domain by its human-readable name:

 - client through which to access a tenant.
 - name of the data domain.
 - (optional) a list of attributes to retrieve for the data domain, for example `certificateStatus`.

### Python

```python showLineNumbers title="Retrieve a data domain by its human-readable name"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataDomain

client = AtlanClient()

domain = client.asset.find_domain_by_name( # (1)
 name="marketing",
 attributes=["certificateStatus"]
)

assert domain
assert domain.certificate_status
```

1. Use `client.asset.find_domain_by_name()` method to retrieve a data domain by its human-readable name:

 - name of the data domain.
 - (optional) a list of attributes to retrieve
 for the data domain, for example `certificateStatus`.

### Kotlin

```kotlin showLineNumbers title="Retrieve a data domain by its human-readable name"
val domain = DataDomain.findByName( // (1)
 client, "marketing", listOf("certificateStatus")
).get(0)
```

1. Use `DataDomain.findByName()` method to retrieve a data domain by its human-readable name:

 - client through which to access a tenant.
 - name of the data domain.
 - (optional) a list of attributes to retrieve for the data domain, for example `certificateStatus`.

### Raw REST API

```json showLineNumbers title="POST /api/meta/search/indexsearch"
{
 "dsl": {
 "from": 0,
 "size": 100,
 "aggregations": {},
 "track_total_hits": true,
 "query": {
 "bool": {
 "filter": [
 {
 "term": {
 "name.keyword": {
 "value": "marketing" // (1)
 }
 }
 },
 {
 "term": {
 "__typeName.keyword": {
 "value": "DataDomain"
 }
 }
 }
 ]
 }
 },
 "sort": [
 {
 "__guid": {
 "order": "asc"
 }
 }
 ]
 },
 "attributes": [
 "certificateStatus" // (2)
 ]
}
```

1. Human-readable name of the data domain.
2. (optional) a list of attributes to retrieve
for the data domain, for example `certificateStatus`.

## Update data domain

To update a data domain or subdomain:

### Java

```java showLineNumbers title="Update a data domain"
DataDomain domain = DataDomain.updater("default/domain/marketing", // (1)
 "Marketing")
 .userDescription("Now with a description!") // (2)
 .build(); // (3)
AssetMutationResponse response = domain.save(client); // (4)
```

1. Use the `updater()` method to update a data domain, providing the `qualifiedName` and name of the data domain.
2. You can chain onto the updater any other enrichment, for example changing the domain's description.
3. You then need to build the object.
4. You can then `save()` the object you've built to update the data domain in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="Update a data domain"
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataDomain

client = AtlanClient()

data_domain = DataDomain.updater( # (1)
 qualified_name="default/domain/marketing", # (2)
 name="Marketing", # (3)
)
data_domain.user_description = "Now with a description!" # (4)

response = client.asset.save(data_domain) # (5)
```

1. Use the `updater()` method to update a data domain.
2. You must provide the `qualifiedName` of the data domain.
3. You must provide the `name` of the data domain.
4. You can then add on any other updates, such as changing the user description of the data domain.
5. To update the data domain in Atlan, call the `save()` method with the object you've built.

### Kotlin

```kotlin showLineNumbers title="Update a data domain"
val domain = DataDomain.updater("default/domain/marketing", // (1)
 "Marketing")
 .userDescription("Now with a description!") // (2)
 .build() // (3)
val response = domain.save(client) // (4)
```

1. Use the `updater()` method to update a data domain, providing the `qualifiedName` and name of the data domain.
2. You can chain onto the updater any other enrichment, for example changing the domain's description.
3. You then need to build the object.
4. You can then `save()` the object you've built to update the data domain in Atlan. Because this operation will persist the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="POST /api/meta/entity/bulk"
{
 "entities": [
 {
 "typeName": "DataDomain", // (1)
 "attributes": {
 "name": "Marketing", // (2)
 "qualifiedName": "default/domain/marketing", // (3)
 "userDescription": "Now with a description!" // (4)
 },
 }
 ]
}
```

1. The `typeName` must be exactly `DataDomain`.
2. Human-readable name for your data domain.
3. You must provide the the `qualifiedName` of the domain to update.
4. You can add on any other updates, such as changing the user description of the data domain.

## Delete data domain

### Soft-delete (archive)

To soft-delete, or archive, a data domain:

### Java

```java showLineNumbers title="Delete a data domain"
AssetDeletionResponse response = DataDomain.delete(client, "218c8144-dc39-43a5-b0c0-9eeb4d11e74a"); // (1)
```

1. To archive a data domain in Atlan, call the `DataDomain.delete()` method with the GUID of the data domain. Because this operation will archive the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="Delete a data domain"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

client.asset.delete_by_guid("218c8144-dc39-43a5-b0c0-9eeb4d11e74a") # (1)
```

1. To archive a data domain in Atlan, call the `asset.delete_by_guid()` method with the GUID of the data domain.

### Kotlin

```kotlin showLineNumbers title="Delete a data domain"
val response = DataDomain.delete(client, "218c8144-dc39-43a5-b0c0-9eeb4d11e74a") // (1)
```

1. To archive a data domain in Atlan, call the `DataDomain.delete()` method with the GUID of the data domain. Because this operation will archive the asset in Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="DELETE /api/meta/entity/bulk?guid=218c8144-dc39-43a5-b0c0-9eeb4d11e74a&deleteType=SOFT"
// (1)
```

1. All the details for deleting the data domain are specified in the URL directly. Note that you must provide the GUID of the data domain to delete it.

### Hard-delete (purge)

To permanently delete (purge) a data domain:

### Java

```java showLineNumbers title="Purge a data domain"
AssetDeletionResponse response = DataDomain.purge(client, "218c8144-dc39-43a5-b0c0-9eeb4d11e74a"); // (1)
```

1. To permanently delete a data domain in Atlan, call the `DataDomain.purge()` method with the GUID of the data domain. Because this operation will remove the asset from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="Purge a data domain"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

client.asset.purge_by_guid("218c8144-dc39-43a5-b0c0-9eeb4d11e74a") # (1)
```

1. To permanently delete a data domain in Atlan, call the `asset.purge_by_guid()` method with the GUID of the data domain.

### Kotlin

```kotlin showLineNumbers title="Purge a data domain"
val response = DataDomain.purge("218c8144-dc39-43a5-b0c0-9eeb4d11e74a") // (1)
```

1. To permanently delete a data domain in Atlan, call the `DataDomain.purge()` method with the GUID of the data domain. Because this operation will remove the asset from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Raw REST API

```json showLineNumbers title="DELETE /api/meta/entity/bulk?guid=218c8144-dc39-43a5-b0c0-9eeb4d11e74a&deleteType=PURGE"
// (1)
```

1. All the details for deleting the data domain are specified in the URL directly. Note that you must provide the GUID of the data domain to delete it.

---