Metadata in Practice

Lineage showed you how data flows between systems
This module is about the layer on top of that: the human-readable context that makes data trustworthy
By the end of this session, you will be able to read, write, and evaluate metadata in DataHub

What You See on an Entity Page

Header: name, platform icon, owner, Deprecated indicator if the asset has been marked deprecated
Description area: the business-level summary of this asset
Tags: colored label chips (free-form classification)
Glossary Terms: linked terms from the company's business vocabulary
Columns tab: column names, types, and column-level metadata
Lineage tab: upstream and downstream connections (Lineage)
Quality tab: assertion results (Data Quality)

Brief: Screenshot of a dataset entity page on a demo instance, full header-to-tabs view, with callout arrows pointing to the header (name, platform icon, owner, Deprecated indicator), the description area, the Tags panel, the Glossary Terms panel, and the Columns / Lineage / Quality tab bar.

Reading a Description as a Consumer

A useful description answers three questions: what does this data represent, when and how is it updated, and what should you NOT use it for
Example of a good description: "This table contains one row per customer per day, tracking their daily product activity. Updated daily at 6am UTC via the dbt activity pipeline. Do not use this table for financial reporting -- use fact_revenue_daily instead. This table counts events, not transactions."

Brief: Screenshot of a dataset entity page's description field on a demo instance, showing a description that states the grain, update cadence, and a "do not use for X" caveat, with the three parts annotated to match the three-question rubric on the slide.

When you land on an unfamiliar dataset, start here. A good description tells you the grain (one row per customer per day), the update cadence (daily at 6am UTC), the pipeline responsible (dbt activity pipeline), and critically, what the table is NOT for. That last piece is what separates a helpful description from a legal one. Many descriptions say what something is but don't say what it isn't -- and that ambiguity is what causes analysts to use the wrong table for financial reporting. When you see a description that answers all three questions, you can proceed confidently. When you see a description that says "Customer data" and nothing else, treat the dataset as unverified until you can track down the owner. Best practice: write for someone who has never seen this data before. The best description tells: what the data represents, when it is updated, its primary use cases, and any important caveats. Bad: "This table contains data." Good: "Contains all e-commerce transactions from 2020 to present. Updated daily at 6 AM via Airflow ETL. Excludes refunds (see customer_refunds table). Currency is always USD. Use transaction_date for reporting, not created_at."

Tags: Quick-Scan Classification Labels

Tags are free-form colored labels attached to an entity or column
Common tags in enterprise deployments:
PII -- contains personally identifiable information
Confidential / Restricted -- access controls apply
High-Value -- frequently used and widely trusted
Deprecated -- being phased out
Raw -- upstream, unprocessed data; treat with caution

Brief: Screenshot of a dataset entity page's Tags panel on a demo instance, showing several colored tag chips applied (e.g. PII, Confidential, Deprecated, Raw), cropped tightly to the header/tags region.

Think of tags like sticky notes on a filing cabinet drawer. They're fast to apply, fast to read, and fast to search. When you're scanning search results and trying to narrow down which dataset to use, tags let you filter at a glance. The most important tags from a governance perspective are PII and Confidential/Restricted, because those connect to legal and compliance obligations. If you see either of those tags on a dataset you want to use, pause and confirm with your data steward that you have the right level of access. Tags can be applied at the column level, not just the table level -- we'll come back to that in a moment. Clarification for the room: you may see "Deprecated" used as an informal tag in some deployments. This is different from the formal Deprecated indicator in the entity page header, which is set through an explicit "Mark as deprecated" action and carries governance weight. One is a label anyone can apply; the other is a deliberate governance decision. The formal indicator is covered on the next slide.

Tags vs. Glossary Terms vs. Structured Properties: When to Use Each

Tag -- use for quick informal labels, status flags, pipeline stage markers; free-form text you type and create on the spot; no definition, no owner, no linkage (e.g. "Raw", "PII", "Finance")
Glossary Term -- use for shared business concepts that need a definition and consistent usage; a defined term with description, owner, and cross-links; search returns all assets using the term (e.g. "Monthly Recurring Revenue", "Churn Rate")
Structured Property -- use for governed fields that need a fixed type, an allowed-value list, or an audit trail; a typed value configured by an admin; invalid values are rejected (e.g. PII Classification: High/Low/None)
Quick rule: if you need a definition, use Glossary Terms. If you need enforcement, use Structured Properties. Everything else: Tags.

Metadata Goes All the Way Down to Columns

Descriptions, tags, and glossary terms can all be applied at the column level, not just the table level
A table can contain both PII and non-PII columns -- the PII tag belongs on the specific column, not the whole table
Column-level tags tell governance tooling (masking, access control) exactly which fields to protect
Column-level glossary terms create precise concept linkage (e.g. "this 'user_id' column maps to the concept Customer ID")
To view: click the Columns tab on any entity page
Best practice: apply tags and glossary terms at the column level too

Brief: Screenshot of the Columns tab on a dataset entity page in a demo instance, showing a column list where one column (e.g. email) has a PII tag chip and a description, while sibling columns do not -- illustrates column-level tagging precision.

This is one of the most practically important things you'll learn today. Tagging a table as PII is helpful but imprecise -- it tells governance tooling that somewhere in this table there is sensitive data, but not which columns. When you tag at the column level -- say, putting PII on the email and phone_number columns specifically -- you enable downstream systems to mask or restrict access at the field level. This is how you support column-level encryption or dynamic data masking. For analysts, column-level descriptions are equally valuable: a column named "d7_ret" means nothing without a description that says "7-day retention rate, calculated as active users on day 7 divided by new users on day 0." Go to the Columns tab on your current dataset and check whether the columns have descriptions.

Don't Use Tags Where You Mean Glossary Terms (and Vice Versa)

Mistake: creating a tag called "Monthly Recurring Revenue" instead of a Glossary Term
A tag named "Monthly Recurring Revenue" is just a label -- it has no definition, no ownership, no linkage to the official concept
Two analysts can create "MRR" and "Monthly Recurring Revenue" as separate tags with no connection
Glossary Terms prevent this: one canonical term, one official definition, all assets linked to the same concept
Mistake: trying to encode business definitions in tags
Rule of thumb: if it needs a definition, make it a Glossary Term. If it's a routing or classification label, make it a Tag.

Deprecated: What It Means and What to Do

Deprecated: a data steward has explicitly marked this asset as being phased out
Set through the entity's "Mark as deprecated" action -- it never happens automatically
The deprecation note (and an optional linked replacement asset) explain why and what to use instead
No indicator shown: the asset has no formal deprecation status -- true for most assets
Key rule: if an asset is Deprecated, always check its deprecation note and replacement link before you stop using it

Brief: Screenshot of a dataset entity page header on a demo instance after an asset has been marked deprecated, with the Deprecated indicator's note popover open showing the deprecation note and a linked replacement asset.

How to Add Metadata (Hands-On Reference)

Adding a Tag: (1) navigate to the entity page, or open a column in the Columns tab; (2) click the + button next to Tags; (3) search for an existing tag or type a new name to create one; (4) press Enter to apply
Linking a Glossary Term: (1) navigate to the entity page, or open a column in the Columns tab; (2) click the + button next to Glossary Terms; (3) search for the term by name, or browse the glossary tree to find it; (4) select it to apply

Brief: Screenshot of a demo instance entity page showing the + button next to Tags clicked and the tag search/create dropdown open, illustrating the add-a-tag flow.

Contribute to the Catalog Even If You're Not the Owner

You do not need to be the dataset owner to add or improve metadata
If you land on a dataset with no description and you know what it contains: add the description
The catalog improves incrementally when everyone contributes
Your contribution is tracked (DataHub records who added each piece of metadata)
If your organization has Proposals enabled (DataHub Cloud), submit a proposed description for steward review
(DataHub Cloud) Reader-role users without edit permissions can use the Propose button to suggest a description, tag, or term; the proposal goes to the data owner for review and approval

Brief: Screenshot of a Reader-role user's view of a dataset's description field on a DataHub Cloud demo instance, showing the Propose button/option alongside the standard edit/save controls (Cloud-only feature -- capture from a Cloud instance, not OSS).

This is culturally one of the most important things I can share with you. Data catalogs fail when contribution is treated as the sole responsibility of the data engineering team. The people who actually know what a dataset means -- the analysts, the product managers, the BI developers who query it every day -- are often not the owners in DataHub. But they can contribute. If you run a query on a dataset, figure out what it contains, and it has no description, spend 60 seconds adding one. That description will save the next person 30 minutes of investigation. Your edit is logged with your name, so you get credit. If your organization requires steward approval before descriptions go live, the Propose workflow (DataHub Cloud) still reduces the owner's burden to just reviewing rather than writing from scratch.

What are Structured Properties?

Typed, validated custom metadata fields defined by your organization
Unlike free-form tags, they have a schema: name, type (string, number, date, URN), allowed values, and which entity types they apply to
Managed under Govern > Structured Properties by admins
Editable by authorized data stewards on any entity page

Brief: Screenshot of the Govern > Structured Properties admin page on a demo instance, showing a list of defined structured properties with their configured type and allowed values.

Structured Properties in Practice

"Data Tier": Bronze / Silver / Gold
"PII Classification": None / Low / High
"Retention Policy": 30d / 90d / 1yr / Indefinite
"SLA Hours": number (e.g., 25 for a daily table)
All of these are queryable -- search returns all Gold-tier datasets in one click

Brief: Screenshot of a dataset entity page on a demo instance showing the Structured Properties panel populated with example values (e.g. Data Tier: Gold, PII Classification: High).

Use Structured Properties for Governance Fields That Need Validation

If the field has an allowed value list or type constraint: use Structured Properties, not tags
Tags are for quick informal labeling ("Raw," "Certified," "Deprecated")
Structured Properties are for enforced governance standards ("PII Classification: High")
Rule: if a future auditor needs to query and filter by it, make it a Structured Property

Documents -- Long-Form Knowledge on Any Entity

Attach rich-text documents directly to datasets, domains, or data products
Different from the Description field: documents support full formatting and extended length
Use for: runbooks, ingestion architecture notes, data dictionaries, known data quality quirks
Beta feature -- available in supported deployments

Brief: Screenshot of a dataset entity page's Documentation tab on a demo instance, showing a rich-text document (e.g. a runbook) linked in the Related Documents section, with formatted headings and paragraphs visible.

Documents Are Supplemental, Not a Substitute for a Good Description

The Description field is part of the dataset's own search record -- it shows up in the dataset's search result card
Documents are indexed too, but as their own separate entity -- a document's content does not get folded into the dataset's search card
Rule: always write a solid description first, then add a document for the longer narrative
If a user searching for this asset should see it in the dataset's own result: put it in the description

Write Metadata for a Cold Dataset

Setup: open the training_cold_dataset entity in DataHub (your facilitator will share the link)
Task 1 (5 min): write a description for this dataset. Apply the three-question rule.
Task 2 (3 min): apply at least one tag. Choose from the tags your facilitator lists on the board.
Task 3 (2 min): link one glossary term if one applies.
Rubric: compare your description against the provided rubric (see participant guide). Good descriptions score on grain, cadence, known limitations. Bad descriptions score on vagueness, missing cadence, no caveats.

Brief: Screenshot of the training_cold_dataset entity page on the training demo instance, showing a blank or minimal description field and no tags applied -- the starting state participants will enrich during the lab.

Check for Understanding

You find a dataset marked Deprecated. What is the first thing you should do?
An analyst wants to mark a table as containing "Net Revenue." Should they use a Tag or a Glossary Term? Why?
A column in the Columns tab has the PII tag but the table itself does not. Is the table considered to contain PII?