Handling Folder Structures in Elasticsearch Ingest UI

docs/how/delete-metadata.md

@@ -20,7 +20,7 @@ There are a two ways to delete metadata from DataHub:
 
 :::info
 
-Deleting metadata using DataHub's CLI is a simple, systems-level action. If you attempt to delete an entity with children, such as a container, it will not delete those children. Instead, you will need to delete each child by URN in addition to deleting the parent.
+Deleting metadata using DataHub's CLI is a simple, systems-level action. If you attempt to delete an entity with children, such as a container, it will not delete those children unless you use the `--recursive` flag. This flag ensures that all child entities are deleted along with the container. However, be cautious as this action is irreversible when using `--hard` delete.
 
 :::
 
@@ -44,7 +44,7 @@ datahub delete --platform snowflake
 datahub delete --platform looker --entity-type chart
 datahub delete --platform bigquery --env PROD
 
-# You can also do recursive deletes for container and dataPlatformInstance entities.
+# You can also do recursive deletes for container and dataPlatformInstance entities. This is particularly useful for deleting folder structures represented as containers in DataHub.
 datahub delete --urn "urn:li:container:f76..." --recursive
 ```
 
@@ -67,7 +67,7 @@ datahub delete --platform snowflake --soft
 
 #### Hard delete an entity
 
-This will physically delete all rows for all aspects of the entity. This action cannot be undone, so execute this only after you are sure you want to delete all data associated with this entity.
+This will physically delete all rows for all aspects of the entity. This action cannot be undone, so execute this only after you are sure you want to delete all data associated with this entity. When deleting folder structures, ensure that you use the `--recursive` flag to remove all child entities as well.
 
 ```shell
 datahub delete --urn "<my urn>" --hard
@@ -105,6 +105,17 @@ Make sure you surround your urn with quotes! If you do not include the quotes, y
 
 :::
 
+### Verifying Deletion of Folder Structures
+
+After performing a delete operation, verify the deletion of folder structures by checking the Elasticsearch indices and using the DataHub UI. Be aware of potential caching or indexing delays that might affect the immediate reflection of changes in the UI.
+
+### Troubleshooting Deletion Issues
+
+If you encounter issues when attempting to delete folder structures, consider the following troubleshooting tips:
+- Ensure that the correct entity type and URN are specified.
+- Use the `--recursive` flag for containers to ensure all child entities are deleted.
+- Check for caching or indexing delays in Elasticsearch that might delay the reflection of changes in the UI.
+
 _Note: All of the commands below support `--dry-run` and `--force` (skips confirmation prompts)._
 
 #### Soft delete a single entity