# Domains ## Why Would You Use Domains? Domains are curated, top-level folders or categories where related assets can be explicitly grouped. Management of Domains can be centralized, or distributed out to Domain owners Currently, an asset can belong to only one Domain at a time. For more information about domains, refer to [About DataHub Domains](/docs/domains.md). ### Goal Of This Guide This guide will show you how to - Create a domain. - Read domains attached to a dataset. - Add a dataset to a domain - Remove the domain from a dataset. ## Prerequisites For this tutorial, you need to deploy DataHub Quickstart and ingest sample data. For detailed steps, please refer to [DataHub Quickstart Guide](/docs/quickstart.md). ## Create Domain #### GraphQL ```json mutation createDomain { createDomain(input: { name: "Marketing", description: "Entities related to the marketing department" }) } ``` If you see the following response, the operation was successful: ```json { "data": { "createDomain": "" }, "extensions": {} } ``` #### Curl ```shell curl --location --request POST 'http://localhost:8080/api/graphql' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "mutation createDomain { createDomain(input: { name: \"Marketing\", description: \"Entities related to the marketing department.\" }) }", "variables":{}}' ``` Expected Response: ```json { "data": { "createDomain": "" }, "extensions": {} } ``` #### Python ```python # Inlined from /metadata-ingestion/examples/library/domain_create.py import os from datahub.emitter.mce_builder import make_domain_urn from datahub.emitter.mcp import MetadataChangeProposalWrapper from datahub.emitter.rest_emitter import DatahubRestEmitter from datahub.metadata.schema_classes import DomainPropertiesClass # Get DataHub connection details from environment gms_server = os.getenv("DATAHUB_GMS_URL", "http://localhost:8080") token = os.getenv("DATAHUB_GMS_TOKEN") domain_urn = make_domain_urn("marketing") domain_properties_aspect = DomainPropertiesClass( name="Marketing", description="Entities related to the marketing department" ) event: MetadataChangeProposalWrapper = MetadataChangeProposalWrapper( entityUrn=domain_urn, aspect=domain_properties_aspect, ) rest_emitter = DatahubRestEmitter(gms_server=gms_server, token=token) rest_emitter.emit(event) print(f"Created domain {domain_urn}") ``` ### Expected Outcomes of Creating Domain You can now see `Marketing` domain has been created under `Govern > Domains`.

### Creating a Nested Domain You can also create a nested domain, or a domain within another domain. #### GraphQL ```json mutation createDomain { createDomain(input: { name: "Verticals", description: "An optional description", parentDomain: "urn:li:domain:marketing" }) } ``` #### Curl ```shell curl --location --request POST 'http://localhost:8080/api/graphql' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "mutation createDomain { createDomain(input: { name: \"Verticals\", description: \"Entities related to the verticals sub-domain.\", parentDomain: \"urn:li:domain:marketing\" }) }", "variables":{}}' ``` #### Python ```python # Inlined from /metadata-ingestion/examples/library/domain_create_nested.py import os from datahub.emitter.mce_builder import make_domain_urn from datahub.emitter.mcp import MetadataChangeProposalWrapper from datahub.emitter.rest_emitter import DatahubRestEmitter from datahub.metadata.schema_classes import DomainPropertiesClass domain_urn = make_domain_urn("verticals") domain_properties_aspect = DomainPropertiesClass( name="Verticals", description="Entities related to the verticals sub-domain", parentDomain="urn:li:domain:marketing", ) event: MetadataChangeProposalWrapper = MetadataChangeProposalWrapper( entityUrn=domain_urn, aspect=domain_properties_aspect, ) # Get DataHub connection details from environment gms_server = os.getenv("DATAHUB_GMS_URL", "http://localhost:8080") token = os.getenv("DATAHUB_GMS_TOKEN") rest_emitter = DatahubRestEmitter(gms_server=gms_server, token=token) rest_emitter.emit(event) print(f"Created domain {domain_urn}") ``` This query will create a new domain, "Verticals", under the "Marketing" domain. ## Read Domains #### GraphQL ```json query { dataset(urn: "urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)") { domain { associatedUrn domain { urn properties { name } } } } } ``` If you see the following response, the operation was successful: ```python { "data": { "dataset": { "domain": { "associatedUrn": "urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)", "domain": { "urn": "urn:li:domain:71b3bf7b-2e3f-4686-bfe1-93172c8c4e10", "properties": { "name": "Marketing" } } } } }, "extensions": {} } ``` #### Curl ```shell curl --location --request POST 'http://localhost:8080/api/graphql' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "{ dataset(urn: \"urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)\") { domain { associatedUrn domain { urn properties { name } } } } }", "variables":{}}' ``` Expected Response: ```json { "data": { "dataset": { "domain": { "associatedUrn": "urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)", "domain": { "urn": "urn:li:domain:71b3bf7b-2e3f-4686-bfe1-93172c8c4e10", "properties": { "name": "Marketing" } } } } }, "extensions": {} } ``` #### Python ```python # Inlined from /metadata-ingestion/examples/library/dataset_query_domain.py from datahub.sdk import DataHubClient, DatasetUrn client = DataHubClient.from_env() dataset = client.entities.get( DatasetUrn(platform="hive", name="fct_users_created", env="PROD") ) # Print the dataset domain print(dataset.domain) ``` ## Add Domains #### GraphQL ```json mutation setDomain { setDomain(domainUrn: "urn:li:domain:marketing", entityUrn: "urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)") } ``` If you see the following response, the operation was successful: ```python { "data": { "setDomain": true }, "extensions": {} } ``` #### Curl ```shell curl --location --request POST 'http://localhost:8080/api/graphql' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "mutation setDomain { setDomain(entityUrn: "urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)", domainUrn: "urn:li:domain:marketing")) }", "variables":{}}' ``` Expected Response: ```json { "data": { "setDomain": true }, "extensions": {} } ``` #### Python ```python # Inlined from /metadata-ingestion/examples/library/dataset_add_domain.py from datahub.metadata.urns import DatasetUrn, DomainUrn from datahub.sdk import DataHubClient client = DataHubClient.from_env() dataset = client.entities.get(DatasetUrn(platform="snowflake", name="example_dataset")) # If you don't know the domain urn, you can look it up: # domain_urn = client.resolve.domain(name="marketing") # NOTE: This will overwrite the existing domain dataset.set_domain(DomainUrn(id="marketing")) client.entities.update(dataset) ``` ### Expected Outcomes of Adding Domain You can now see `Marketing` domain has been added to the dataset.

## Remove Domains #### GraphQL ```json mutation unsetDomain { unsetDomain( entityUrn:"urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)" ) } ``` Expected Response: ```python { "data": { "removeDomain": true }, "extensions": {} } ``` #### Curl ```shell curl --location --request POST 'http://localhost:8080/api/graphql' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "mutation unsetDomain { unsetDomain(entityUrn: \"urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)\") }", "variables":{}}' ``` #### Python ```python # Inlined from /metadata-ingestion/examples/library/dataset_remove_domain_execute_graphql.py # read-modify-write requires access to the DataHubGraph (RestEmitter is not enough) from datahub.ingestion.graph.client import DatahubClientConfig, DataHubGraph gms_endpoint = "http://localhost:8080" graph = DataHubGraph(DatahubClientConfig(server=gms_endpoint)) # Query multiple aspects from entity query = """ mutation unsetDomain { unsetDomain( entityUrn:"urn:li:dataset:(urn:li:dataPlatform:hive,fct_users_created,PROD)" ) } """ result = graph.execute_graphql(query=query) print(result) ``` ### Expected Outcomes of Removing Domain You can now see a domain `Marketing` has been removed from the `fct_users_created` dataset.