From 59a26a654316ae1346dd2aca004b7fa753ecaeba Mon Sep 17 00:00:00 2001
From: Ellie O'Neil <110510035+eboneil@users.noreply.github.com>
Date: Tue, 19 Mar 2024 09:17:10 -0700
Subject: [PATCH] Update domains docs to include nested domains (#9890)

Co-authored-by: Hyejin Yoon <0327jane@gmail.com>
---
 docs/api/tutorials/domains.md                 | 35 +++++++++++++++++++
 docs/domains.md                               | 10 ++++++
 .../examples/library/create_nested_domain.py  | 27 ++++++++++++++
 3 files changed, 72 insertions(+)
 create mode 100644 metadata-ingestion/examples/library/create_nested_domain.py

diff --git a/docs/api/tutorials/domains.md b/docs/api/tutorials/domains.md
index 617864d233..800d3dbff5 100644
--- a/docs/api/tutorials/domains.md
+++ b/docs/api/tutorials/domains.md
@@ -79,6 +79,41 @@ You can now see `Marketing` domain has been created under `Govern > Domains`.
   <img width="70%"  src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/apis/tutorials/domain-created.png"/>
 </p>
 
+### Creating a Nested Domain
+
+You can also create a nested domain, or a domain within another domain.
+
+<Tabs>
+<TabItem value="graphql" label="GraphQL" default>
+
+```json
+mutation createDomain {
+  createDomain(input: { name: "Verticals", description: "An optional description", parentDomain: "urn:li:domain:marketing" })
+}
+```
+
+</TabItem>
+<TabItem value="curl" label="Curl">
+
+```shell
+curl --location --request POST 'http://localhost:8080/api/graphql' \
+--header 'Authorization: Bearer <my-access-token>' \
+--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":{}}'
+```
+
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+{{ inline /metadata-ingestion/examples/library/create_nested_domain.py show_path_as_comment }}
+```
+
+</TabItem>
+</Tabs>
+
+This query will create a new domain, "Verticals", under the "Marketing" domain.
+
 
 ## Read Domains
 
diff --git a/docs/domains.md b/docs/domains.md
index 1b2ebc9d47..94ba5f9f96 100644
--- a/docs/domains.md
+++ b/docs/domains.md
@@ -202,6 +202,16 @@ mutation createDomain {
 
 This query will return an `urn` which you can use to fetch the Domain details. 
 
+## Create a Nested Domain
+
+```graphql
+mutation createDomain {
+  createDomain(input: { name: "Verticals", description: "An optional description", parentDomain: "urn:li:domain:marketing" })
+}
+```
+
+This query will create a new domain, "Verticals", under the "Marketing" domain.
+
 **Fetching a Domain by Urn**
 
 ```graphql
diff --git a/metadata-ingestion/examples/library/create_nested_domain.py b/metadata-ingestion/examples/library/create_nested_domain.py
new file mode 100644
index 0000000000..da6b107004
--- /dev/null
+++ b/metadata-ingestion/examples/library/create_nested_domain.py
@@ -0,0 +1,27 @@
+import logging
+
+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 ChangeTypeClass, DomainPropertiesClass
+
+log = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+domain_urn = make_domain_urn("marketing")
+domain_properties_aspect = DomainPropertiesClass(
+    name="Verticals",
+    description="Entities related to the verticals sub-domain",
+    parentDomain="urn:li:domain:marketing",
+)
+
+event: MetadataChangeProposalWrapper = MetadataChangeProposalWrapper(
+    entityType="domain",
+    changeType=ChangeTypeClass.UPSERT,
+    entityUrn=domain_urn,
+    aspect=domain_properties_aspect,
+)
+
+rest_emitter = DatahubRestEmitter(gms_server="http://localhost:8080")
+rest_emitter.emit(event)
+log.info(f"Created domain {domain_urn}")