From 643bf6e209528678f4bd34eccff35dff334af80f Mon Sep 17 00:00:00 2001 From: Maggie Hays Date: Tue, 30 Aug 2022 21:23:13 -0500 Subject: [PATCH 1/4] docs(refactor): Refactor Tags Feature Guide --- docs/tags.md | 99 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 23 deletions(-) diff --git a/docs/tags.md b/docs/tags.md index 380418f58d27f2..483d698a9da8d6 100644 --- a/docs/tags.md +++ b/docs/tags.md @@ -1,52 +1,105 @@ -# Tags Guide +import FeatureAvailability from '@site/src/components/FeatureAvailability'; -## What is a Tag? +# About DataHub Tags + -Tags are metadata that can be added datasets, dataset schemas, or containers. They provide an easy way to label or categorize entities. +Tags are informal, loosely controlled labels that help in search & discovery. They can be added to datasets, dataset schemas, or containers, for an easy way to label or categorize entities – without having to associate them to a broader business glossary or vocabulary. -### Tags vs. Glossary Terms vs. Domains +Tags can help help you in: -DataHub supports Tags, Glossary Terms, & Domains as distinct types of Metadata that are suited for specific purposes: +* Querying: Tagging a dataset with a phrase that a co-worker can use to query the same dataset +* Mapping assets to a category or group of your choice -- **Tags**: Informal, loosely controlled labels that serve as a tool for search & discovery. Assets may have multiple tags. No formal, central management. -- **Glossary Terms**: A controlled vocabulary, with optional hierarchy. Terms are typically used to standardize types of leaf-level attributes (i.e. schema fields) for governance. E.g. (EMAIL_PLAINTEXT) -- **Domains**: A set of top-level categories. Usually aligned to business units / disciplines to which the assets are most relevant. Central or distributed management. Single Domain assignment per data asset. +## Tags Setup, Prerequisites, and Permissions +What you need to add tags: -## Adding a Tag +* **Edit Tags** metadata privilege to add tags at the entity level +* **Edit Dataset Column Tags** to edit tags at the column level -Users must have the Metadata Privilege called `Edit Tags` to add tags at the entity level, and the Privilege called `Edit Dataset Column Tags` to edit tags at the column level. These Privileges -can be granted by creating a new Metadata [Policy](authorization/policies.md). +You can create these privileges by creating a new [Metadata Policy](./docs/authorization/policies.md). -To add a tag at the dataset or container level, simply navigate to the page for that entity and click on the "Add Tag" button. +## Using DataHub Tags -![](./imgs/add-tag.png) +### Adding a Tag -You can then type in the name of the tag you would like to add. You can either add a tag that already exists, or add a new tag entirely. The autocomplete will pull up the tag if it already exists. +To add a tag at the dataset or container level, simply navigate to the page for that entity and click on the **Add Tag** button. -![](./imgs/add-tag-search.png) +

+ +

+ +Type in the name of the tag you want to add. You can add a new tag, or add a tag that already exists (the autocomplete will pull up the tag if it already exists). + +

+ +

Click on the "Add" button and you'll see the tag has been added! -![](./imgs/added-tag.png) +

+ +

If you would like to add a tag at the schema level, hover over the "Tags" column for a schema until the "Add Tag" button shows up, and then follow the same flow as above. -![](./imgs/added-tag.png) +

+ +

-## Removing a Tag +### Removing a Tag To remove a tag, simply click on the "X" button in the tag. Then click "Yes" when prompted to confirm tag removal. +### Searching by a Tag + +You can search for a tag in the search bar, and even filter entities by the presence of a specific tag. + +

+ +

+ +## Additional Resources + +### YouTube + +**Add Ownership, Tags, Terms, and more to DataHub via CSV!** + +

+ +

+ +### GraphQL + +* [Tag](./docs/graphql/queries.md#tag) +* [AddTagsInput](./docs/graphql/inputObjects.md#addtagsinput) +* [BatchAddTagsInput](./docs/graphql/inputObjects.md#batchaddtagsinput) +* [BatchRemoveTagsInput](./docs/graphql/inputObjects.md#batchremovetagsinput) + +### DataHub Blog + +* [Tags and Terms: Two Powerful DataHub Features, Used in Two Different Scenarios +Managing PII in DataHub: A Practitioner’s Guide](https://blog.datahubproject.io/tags-and-terms-two-powerful-datahub-features-used-in-two-different-scenarios-b5b4791e892e) + +## FAQ and Troubleshooting + +**What is the difference between DataHub Tags and Glossary Terms?** + +DataHub Tags are informal, loosely controlled labels while Terms are part of a controlled vocabulary, with optional hierarchy. Tags have no element of formal, central management. + +Usage and applications: -## Searching by Tag +* An asset may have multiple tags. +* Tags serve as a tool for search & discovery while Terms are typically used to standardize types of leaf-level attributes (i.e. schema fields) for governance. E.g. (EMAIL_PLAINTEXT) -You can search for a tag in the search bar, and if you wish, even filter entities by the presence of a specific tag. +**How are DataHub Tags different from Domains?** -![](./imgs/search-tag.png) +Domains are a set of top-level categories usually aligned to business units/disciplines to which the assets are most relevant. They rely on central or distributed management. A single domain is assigned per data asset. +*Need more help? Join the conversation in [Slack](http://slack.datahubproject.io)!* -## Feedback / Questions / Concerns +### Related Features -We want to hear from you! For any inquiries, including Feedback, Questions, or Concerns, reach out on Slack! \ No newline at end of file +* [Glossary Terms](./docs/how/business-glossary-guide.md) +* [Domains](./docs/domains.md) \ No newline at end of file From a4087f9cb1229a952dd4fc779f70b6d9dbc3c1ce Mon Sep 17 00:00:00 2001 From: Maggie Hays Date: Wed, 31 Aug 2022 15:06:11 -0500 Subject: [PATCH 2/4] update graphql links --- docs/tags.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tags.md b/docs/tags.md index 483d698a9da8d6..e1a36c03fa5449 100644 --- a/docs/tags.md +++ b/docs/tags.md @@ -72,10 +72,10 @@ You can search for a tag in the search bar, and even filter entities by the pres ### GraphQL -* [Tag](./docs/graphql/queries.md#tag) -* [AddTagsInput](./docs/graphql/inputObjects.md#addtagsinput) -* [BatchAddTagsInput](./docs/graphql/inputObjects.md#batchaddtagsinput) -* [BatchRemoveTagsInput](./docs/graphql/inputObjects.md#batchremovetagsinput) +* [Tag](../graphql/queries.md#tag) +* [AddTagsInput](../graphql/inputObjects.md#addtagsinput) +* [BatchAddTagsInput](../graphql/inputObjects.md#batchaddtagsinput) +* [BatchRemoveTagsInput](../graphql/inputObjects.md#batchremovetagsinput) ### DataHub Blog From 11c45f4ec572226e60a4965b2982f6b2a7067825 Mon Sep 17 00:00:00 2001 From: Maggie Hays Date: Wed, 31 Aug 2022 15:16:18 -0500 Subject: [PATCH 3/4] remove unneeded WIP tag guide doc --- docs-website/sidebars.js | 1 - docs/wip/tags-guide.md | 7 ------- 2 files changed, 8 deletions(-) delete mode 100644 docs/wip/tags-guide.md diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index 8f463ff876e769..be534947e3e509 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -445,7 +445,6 @@ module.exports = { // className: "saasOnly", // }, // "docs/wip/ui-ingestion-guide", -- not needed - // "docs/wip/tags-guide", -- not needed // "docs/wip/personal-access-tokens-guide", -- not needed { diff --git a/docs/wip/tags-guide.md b/docs/wip/tags-guide.md deleted file mode 100644 index 83b78767910edd..00000000000000 --- a/docs/wip/tags-guide.md +++ /dev/null @@ -1,7 +0,0 @@ -import FeatureAvailability from '@site/src/components/FeatureAvailability'; - -# Tags Guide - - - -This page is under construction - more details coming soon! From 041f12d3564a25307c52af7ecbb19111b76cb9e8 Mon Sep 17 00:00:00 2001 From: Maggie Hays Date: Thu, 1 Sep 2022 16:28:54 -0500 Subject: [PATCH 4/4] update tags guide to match template --- docs/tags.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tags.md b/docs/tags.md index e1a36c03fa5449..9b06331b125c4b 100644 --- a/docs/tags.md +++ b/docs/tags.md @@ -62,7 +62,7 @@ You can search for a tag in the search bar, and even filter entities by the pres ## Additional Resources -### YouTube +### Videos **Add Ownership, Tags, Terms, and more to DataHub via CSV!**