How to export Purview glossary terms with their relationships
The short answer
Save the glossary with two Unified Catalog API calls: every page of terms, then each term's links. Run one Python and DuckDB script on the saved files. The script's nine checks show whether every page of terms and links was saved and whether each term can be moved, before Microsoft ends support for Purview Data Governance on November 12, 2027.
Why check the export first
Microsoft announced on November 12, 2026 that Purview Data Governance is retiring: “Support for Purview Data Governance will end Nov. 12, 2027” (Microsoft Security blog, read 2026-11-21). Purview itself stays for classifying, labeling and protecting sensitive data and for data loss prevention. As of 2026-11-21, Microsoft's transition guide (read 2026-11-21) maps the glossary to tags, descriptions and endorsement in the OneLake catalog, and its advice for the glossary is to export and preserve terms and ownership.
A glossary export is the record of what you had. If the export is missing a page, a term's links or a term's owner, nobody can prove later that the move kept everything, because the source is switched off. So check the export before anything moves, while you can still fix the glossary in Purview and export it again.
What you will have at the end
- A saved export of every glossary term and every term's links to other terms, data assets, data columns, data products and critical data elements, as the Unified Catalog API returns them.
- Nine checks, each one PASS or FAIL, that every page of terms and links was saved and that each term can be moved as it is.
- Two CSV files a steward can open in Excel:
findings.csv(one row per problem) andterms.csv(one row per term, with its parent, owners and link counts).
Step 1. Save the export
The Unified Catalog API (read 2026-11-21) is in public preview; the commands below use its version 2026-03-20-preview. The identity that runs them needs the Data Catalog Reader role in every governance domain you export, which Microsoft's authentication page (read 2026-11-21) lists for reading terms, and a token for the resource https://purview.azure.net, requested as that page shows. The requests are Microsoft's Terms - List and Terms - List Related Entities (both read 2026-11-21).
We did not run these commands. We have no Purview tenant to run them against, so they are written from Microsoft's reference pages, and the runs further down use generated records in the same shape. They need curl and jq.
# Not run by us: written from Microsoft's reference pages (read 2026-11-21).
# 1. A token for Purview (an app registration that holds Data Catalog Reader), renewed when Purview answers 401
token() {
curl -s -X POST "https://login.microsoftonline.com/$TENANT_ID/oauth2/token" \
-d grant_type=client_credentials -d client_id="$CLIENT_ID" \
--data-urlencode client_secret="$CLIENT_SECRET" -d resource=https://purview.azure.net \
| jq -r .access_token
}
fetch() { # fetch URL FILE: save the answer; on 401 get a new token and try once more
code=$(curl -s -o "$2" -w '%{http_code}' -H "Authorization: Bearer $TOKEN" "$1")
if [ "$code" = 401 ]; then
TOKEN=$(token)
code=$(curl -s -o "$2" -w '%{http_code}' -H "Authorization: Bearer $TOKEN" "$1")
fi
[ "$code" = 200 ] || echo "HTTP $code: $2 holds an error, fetch $1 again" >&2
}
TOKEN=$(token)
EP="https://api.purview-service.microsoft.com" # the endpoint Microsoft's reference shows
API="api-version=2026-03-20-preview"
OUT="export-$(date +%Y%m%d-%H%M%S)" # a new, empty folder for every export
mkdir -p "$OUT/terms" "$OUT/relationships" "$OUT/domains"
# 2. Every term, one file per page, following nextLink until there is none
url="$EP/datagovernance/catalog/terms?$API"; n=1
while [ -n "$url" ]; do
f=$(printf "$OUT/terms/page-%03d.json" "$n")
fetch "$url" "$f"
url=$(jq -r '.nextLink // empty' "$f"); n=$((n + 1))
done
# 3. Each term's links, one file per entity type and page (later pages: <id>.<TYPE>.2.json ...)
for id in $(jq -r '.value[].id' "$OUT"/terms/page-*.json | sort -u); do
for type in TERM DATAASSET DATACOLUMN DATAPRODUCT CRITICALDATAELEMENT; do
url="$EP/datagovernance/catalog/terms/$id/relationships?$API&entityType=$type"; p=1
while [ -n "$url" ]; do
f="$OUT/relationships/$id.$type.json"
[ "$p" -gt 1 ] && f="$OUT/relationships/$id.$type.$p.json"
fetch "$url" "$f"
url=$(jq -r '.nextLink // empty' "$f"); p=$((p + 1))
done
done
done
# 4. Optional: domain names, so the report shows names instead of ids
fetch "$EP/datagovernance/catalog/businessdomains?$API" "$OUT/domains/page-001.json"
echo "Saved to $OUT"
Each run of the commands writes a new folder named export- with the date and time, so a second export never mixes with files left from the first. Keep every folder: the newest folder is the record of what Purview held when you exported. The folder holds terms/page-001.json onward, one file per page of terms, and one file per term and entity type in relationships/. When the links of one entity type run to more than one page, the commands save the later pages beside the first as <termId>.<TYPE>.2.json, .3.json and so on.
When Purview answers 401 because the token expired, the commands get a new token and try the request once more. If a request fails for another reason (for example when you pass Purview's rate limit), the commands print the file's name, the file holds an error instead of a value list, and the check in step 2 stops on that file; fetch that file again. A failed domain names file does not stop the check; the report then shows domain ids instead of names.
| Field in the export | What the check uses it for |
|---|---|
id, name, domain, status | Required on every term in Microsoft's API specification (commit be93aca, read 2026-11-21); the check stops if one is missing |
parentId | The term hierarchy: orphan parents and cycles |
contacts.owner | Who signs for the term |
description, acronyms, resources, managedAttributes | Counted as content a tag cannot carry |
nextLink on a page of terms | Whether the last page was saved |
entityId, relationshipType (Related, Synonym or Parent) | Links between terms, and from terms to data assets |
Step 2. Run the check
Download check_glossary_export.py, install DuckDB (pip install duckdb) and run the script on the folder. The script reads the files with Python, loads them into DuckDB in memory and runs nine checks, most of them in SQL. Nothing is sent anywhere.
python3 check_glossary_export.py export-20261121-093000
| Check | Why it matters for the move |
|---|---|
Every page of terms was saved, and the last has no nextLink | A gap in the page numbers, or a nextLink on the last file, means terms are missing from the export. |
| No term id appears twice | Pages that overlap count a term twice and inflate every total you sign off. |
| Every term has every page of its links saved, for every entity type | A missing file or page of links looks the same as a term with fewer links, so links would be lost without anyone noticing. |
Every parentId is a term in the export | A child whose parent is missing cannot be placed in the new hierarchy. |
| No term is its own ancestor | A loop in the hierarchy has no top term, so the hierarchy cannot be rebuilt. |
| Every term-to-term link points to a term in the export | A related term or synonym that is not in the export is a link that cannot be recreated. |
| No two terms in one domain share a name, ignoring case and spaces | In Fabric, a tag name is the whole tag, so two terms with the same name in one domain cannot become two tags. The check also flags names that differ only in case or spacing, because a reader sees them as one term. Fabric allows the same tag name in different Fabric domains (Tags in Microsoft Fabric, read 2026-11-21), so the check compares names only within one Purview governance domain. |
| Every published term has an owner | Someone has to confirm the term arrived intact. A term with no owner has nobody to confirm that the term arrived intact. |
| No data asset is linked to more than 10 terms | A Fabric item holds at most 10 tags (Tags in Microsoft Fabric, read 2026-11-21), so a data asset linked to more terms cannot carry all of them as tags. |
The tag limit is a setting at the top of the script, MAX_TAGS_PER_ITEM = 10, with its source beside it. Change it if Microsoft changes the limit, or if your terms land in a catalog with a different limit.
Run 1. A generated export, clean
The script writes a generated export when you ask for one: three invented domains with 20 terms each, in the shape the API returns, with a fixed seed so every run gives the same records.
python3 check_glossary_export.py --make-demo demo
Wrote a generated export to demo: 3 pages, 60 term records, 205 relationships, 3 domains (seed 273)
python3 check_glossary_export.py demo
Python 3.14.8 duckdb 1.5.6 Export: demo Read 3 pages of terms (60 terms, 60 distinct ids), 300 relationship files (205 relationships), 3 domain names Term ids fingerprint (SHA-256 of the sorted ids): 29c82e181dfe13ce Terms by domain and status Finance draft 1 published 17 expired 2 total 20 Sales draft 1 published 17 expired 2 total 20 Supply Chain draft 1 published 17 expired 2 total 20 Relationships by entity type CRITICALDATAELEMENT Related 12 DATAASSET Related 75 DATACOLUMN Related 64 DATAPRODUCT Related 15 TERM Parent 21 TERM Related 12 TERM Synonym 6 Content a Fabric tag cannot carry (a tag is a name only) terms with description 60 terms with acronyms 15 terms with resources (links) 12 terms with managed attributes 0 terms with a parent term 21 terms with synonyms 6 Checks PASS Every page of terms was saved, and the last has no nextLink PASS No term id appears twice in the export PASS Every term has every page of its links saved, for every entity type PASS Every parentId is a term in the export PASS No term is its own ancestor PASS Every term-to-term relationship points to a term in the export PASS No two terms in one domain share a name, ignoring case and spaces PASS Every published term has an owner PASS No data asset is linked to more than 10 terms Wrote findings.csv (0 rows) and terms.csv (60 rows) to . RESULT: no check blocks the move.
How to read it
The first block is the inventory: terms by domain and status, and links by entity type. The second block counts what a tag cannot hold. A Fabric tag is a name, so a term's description, acronyms, links to documents, parent and synonyms need another home, or a decision that they are not kept. The fingerprint is a short hash of the sorted term ids: export again later, and a different fingerprint means the set of terms changed.
Run 2. The same export with nine planted errors
python3 check_glossary_export.py --make-demo demo-planted --plant-errors
Wrote a generated export to demo-planted: 3 pages, 62 term records, 217 relationships, 3 domains (seed 273) Planted one error for each check: DANGLING_TERM_LINK, DUPLICATE_ID, DUPLICATE_NAME_IN_DOMAIN, EXPORT_INCOMPLETE, MISSING_RELATIONSHIPS, NO_OWNER, ORPHAN_PARENT, OVER_TAG_LIMIT, PARENT_CYCLE
python3 check_glossary_export.py demo-planted --tag planted
Python 3.14.8 duckdb 1.5.6 Export: demo-planted Read 3 pages of terms (62 terms, 61 distinct ids), 305 relationship files (217 relationships), 3 domain names Term ids fingerprint (SHA-256 of the sorted ids): a7fe27181408b829 Terms by domain and status Finance draft 2 published 17 expired 2 total 21 Sales draft 1 published 17 expired 2 total 20 Supply Chain draft 1 published 17 expired 2 total 20 Relationships by entity type CRITICALDATAELEMENT Related 12 DATAASSET Related 86 DATACOLUMN Related 64 DATAPRODUCT Related 15 TERM Parent 21 TERM Related 13 TERM Synonym 6 Content a Fabric tag cannot carry (a tag is a name only) terms with description 61 terms with acronyms 16 terms with resources (links) 13 terms with managed attributes 0 terms with a parent term 24 terms with synonyms 6 Checks FAIL Every page of terms was saved, and the last has no nextLink (1) FAIL No term id appears twice in the export (1) FAIL Every term has every page of its links saved, for every entity type (1) FAIL Every parentId is a term in the export (1) FAIL No term is its own ancestor (2) FAIL Every term-to-term relationship points to a term in the export (1) FAIL No two terms in one domain share a name, ignoring case and spaces (2) FAIL Every published term has an owner (1) FAIL No data asset is linked to more than 10 terms (1) Findings EXPORT_INCOMPLETE page-003.json still has a nextLink: later pages were not saved DUPLICATE_ID Opportunity [Sales] id on 2 rows (pages 1, 2) MISSING_RELATIONSHIPS Lead Time [Supply Chain] page 1 of DATAASSET links has a nextLink; page 2 was not saved ORPHAN_PARENT Write-off [Finance] parentId e74ec2a1-5c9c-4f3f-968e-ecfe3c63730b is not in the export PARENT_CYCLE Booking [Sales] its parent chain leads back to it PARENT_CYCLE Order [Sales] its parent chain leads back to it DANGLING_TERM_LINK Win Rate [Sales] Related link to term 0cebb385-21bb-47d5-9b4d-ba341efbab02, which is not in the export DUPLICATE_NAME_IN_DOMAIN net revenue [Finance] same name as "Net Revenue" DUPLICATE_NAME_IN_DOMAIN Net Revenue [Finance] same name as "net revenue" NO_OWNER Gross Margin [Finance] published with no owner OVER_TAG_LIMIT data asset f1fee30e-a1a3-484a-80c0-78fc01a5ae2b is linked to 11 terms; a Fabric item holds at most 10 tags Wrote findings-planted.csv (11 rows) and terms-planted.csv (61 rows) to . RESULT: 11 findings block the move. Fix them in Purview, export again and re-run.
| Check | The error planted in run 2 |
|---|---|
| Every page of terms saved | The last saved page still points to a page that was never saved. |
| No duplicate ids | Page 2 repeats the last term of page 1, the way overlapping pages do. |
| Every page of links saved | Lead Time's data asset links point to a second page that was never saved. |
| Parents in the export | Write-off's parentId is an id no term has. |
| No cycles | Booking and Order are each other's parent. |
| Term links in the export | Win Rate has a Related link to an id no term has. |
| No duplicate names in a domain | A draft term named “net revenue” beside Net Revenue in Finance. |
| Published terms have an owner | Gross Margin's owner list is empty. |
| Tag limit | One data asset is linked to 11 terms. |
The cycle and the duplicate name each produce two findings, one per term involved, so nine planted errors give 11 findings.
What to do with each finding
- Export problems (a missing page of terms, a duplicate id, a missing file or page of links): fetch the missing files again. Do not fix the files by hand, because the export is the record of what Purview held.
- Glossary problems (orphan parents, cycles, links to missing terms, duplicate names, no owner): fix them in Purview, where the stewards work today, then export again and re-run until every check passes.
- The tag limit: decide which terms each crowded data asset keeps as tags, and where the rest go. The check does not choose the terms for you.
Run the check on your own export
To run it on your own glossary, save your export with the commands in step 1 into one folder, then run python3 check_glossary_export.py followed by that folder's path. You do not edit the script. The script reads what the API returned and changes nothing in Purview. Add --fail-on-findings to make it exit with code 1 when a check fails, for example in a pipeline step, and --out <folder> to write the CSVs somewhere other than the script's folder.
We tested a run on a reader's own export: a second generated export laid out the way a reader would save one, with other term names, no domain names file, upper-case ids in the term records, empty fields, a page of links whose next page was never saved, and at least one planted error for each check. All nine checks failed as planted, and nothing else was flagged.
Download check_glossary_export.py · Get the full guide (PDF)
Results from the runs above: terms.csv from run 1 and findings-planted.csv from run 2.
Get the full guide as a PDF
We'll email you a link to it. Please use your work email.
Thanks, . We're sending the link to now. If it isn't there in a few minutes, check your spam or junk folder, or email info@datameaning.com.
Limits
- The runs on this page use generated records, not a real Purview tenant, and the export commands in step 1 were not run. The field names come from Microsoft's API specification and reference pages, read on 2026-11-21.
- The Unified Catalog API is in preview. Microsoft can change its fields or paging; check the reference before you export.
- The check covers glossary terms in Unified Catalog. Classic Data Map glossaries, data quality rules, lineage and scan settings need their own export.
- Passing every check means every page of terms and links the API returned was saved, and each term can be moved as it is. Passing does not decide where each term should land.
- The check cannot see a governance domain where the identity that exported holds no role. Grant Data Catalog Reader in every governance domain before you export.
- Dates and limits here are as of 2026-11-21. This guide is about Purview Data Governance, whose support ends on November 12, 2027; after that date the guide describes history.
Tested on
Tested on
- Platform
- DuckDB 1.5.6, run from Python 3.14.8
- Edition
- Open-source DuckDB library (
pip install duckdb) - Date
- 2026-11-21
- Records
- Generated: an invented glossary of 60 terms in three domains, fixed seed 273, in the shape of Unified Catalog API version 2026-03-20-preview (specification at commit be93aca, read 2026-11-21). Not a run against a Purview tenant.
- Code
- check_glossary_export.py
- Results
- terms.csv, findings-planted.csv
When this is not enough
This check tells you the export is complete and each term can be moved. The next questions are harder: for each term, whether it lands in the OneLake catalog, in another catalog or in an archive; how its description and links survive; who signs that each domain arrived; and when Purview can be switched off. Those are decisions about your whole governance catalog, not only the glossary.
Moving your whole Purview governance catalog, not only the glossary?
Purview to OneLake Migration is in early access. The offering starts with the four-day Catalog Transition Assessment: one fixed fee of $12,000, and no commitment to anything else. You get an inventory of every object in your Purview governance catalog and a decision for each object. AI does the first pass, and your stewards sign every domain.