Guide · Purview to OneLake Migration

How to export Purview glossary terms with their relationships

Updated 2026-11-21Python and DuckDBRuns shown on generated records, PDF by email

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) and terms.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 exportWhat the check uses it for
id, name, domain, statusRequired on every term in Microsoft's API specification (commit be93aca, read 2026-11-21); the check stops if one is missing
parentIdThe term hierarchy: orphan parents and cycles
contacts.ownerWho signs for the term
description, acronyms, resources, managedAttributesCounted as content a tag cannot carry
nextLink on a page of termsWhether 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
CheckWhy it matters for the move
Every page of terms was saved, and the last has no nextLinkA gap in the page numbers, or a nextLink on the last file, means terms are missing from the export.
No term id appears twicePages 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 typeA 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 exportA child whose parent is missing cannot be placed in the new hierarchy.
No term is its own ancestorA 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 exportA 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 spacesIn 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 ownerSomeone 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 termsA 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.
CheckThe error planted in run 2
Every page of terms savedThe last saved page still points to a page that was never saved.
No duplicate idsPage 2 repeats the last term of page 1, the way overlapping pages do.
Every page of links savedLead Time's data asset links point to a second page that was never saved.
Parents in the exportWrite-off's parentId is an id no term has.
No cyclesBooking and Order are each other's parent.
Term links in the exportWin Rate has a Related link to an id no term has.
No duplicate names in a domainA draft term named “net  revenue” beside Net Revenue in Finance.
Published terms have an ownerGross Margin's owner list is empty.
Tag limitOne 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.

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.

See Purview to OneLake Migration