Guide · Purview to OneLake Migration

How to export a classic Purview glossary with the Atlas API

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

The short answer

Call the Data Map Atlas API: list the glossaries at /datamap/api/atlas/v2/glossary, then page through each glossary's terms and categories with limit and offset. Save every page as its own JSON file. One Python and DuckDB script then runs seven checks, including missing pages, duplicate guids, links to terms not saved, approved terms with no steward and terms over 100 relationships.

Why export the classic glossary 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). For the glossary, Microsoft's transition guide (read 2026-11-21) says to export and preserve terms and ownership.

Microsoft's migration page (preview, read 2026-11-21) describes moving glossary terms from the classic data governance glossary into Unified Catalog, and sets the terms of that move: the migration is a one-time process that cannot be reversed; afterwards the classic term APIs become read-only; term templates become attributes that cannot be edited or deleted; workflows on classic terms are not migrated; terms whose names are already used in the destination governance domain are not moved automatically; and a single term can have at most 100 relationships in Unified Catalog. Microsoft marks the migration page as preview, so do not plan on the migration being available in your tenant. Whichever way the terms move, a saved export of the classic glossary is the record of what the classic glossary held.

What you will have at the end

  • The classic glossary as saved files: the Data Map's own answers, one file per page, so nothing is lost in a conversion.
  • A term list, terms.csv: one row per term, with its glossary, status, stewards and experts, related terms, assigned assets and columns, relationship count and term template.
  • Seven checks, each one PASS or FAIL, with every finding in findings.csv.

Step 1. Save the glossary through the Atlas API

The Data Map REST API (api-version 2023-09-01) lists glossaries at /datamap/api/atlas/v2/glossary and each glossary's terms and categories under /glossary/{glossaryId}/terms and /glossary/{glossaryId}/categories. Microsoft's List Terms reference (read 2026-11-21) says that by default there is no paging and recommends limit and offset, and Microsoft's timeout troubleshooting page (read 2026-11-21) recommends small pages. The commands below save every page as its own file and write the page size to page-size.txt, so the script can tell a short last page from a missing one. The glossary list also names each glossary's terms, so the script can tell whether every listed term was saved.

We did not run these commands. We have no tenant to run them against, so they are written from Microsoft's Data Map REST reference, and the runs further down use generated records in the same shape. Set ENDPOINT to your Purview account's endpoint and sign in with the Azure CLI first.

# Not run by us: written from Microsoft's Data Map REST reference, api-version 2023-09-01 (read 2026-11-21).
# Needs the Azure CLI (az login) and an account that can read the classic glossary.
ENDPOINT="https://<your-account>.purview.azure.com"   # your Purview account's endpoint
LIMIT=100                                              # page size: small pages, as Microsoft recommends
OUT="classic-glossary-$(date +%Y%m%d-%H%M%S)"; mkdir -p "$OUT"; echo "$LIMIT" > "$OUT/page-size.txt"
TOKEN=$(az account get-access-token --resource https://purview.azure.net --query accessToken -o tsv)
API="$ENDPOINT/datamap/api/atlas/v2/glossary"
curl -sf -H "Authorization: Bearer $TOKEN" \
  "$API?api-version=2023-09-01&limit=1000&offset=0" -o "$OUT/glossaries.json"
for G in $(python3 -c "import json,sys; [print(g['guid']) for g in json.load(open(sys.argv[1]))]" "$OUT/glossaries.json"); do
  mkdir -p "$OUT/$G"
  for KIND in terms categories; do
    OFFSET=0
    while :; do
      F="$OUT/$G/$KIND-$OFFSET.json"
      [ "$KIND" = terms ] && V="api-version=2023-09-01&" || V=""   # the categories call takes no api-version in Microsoft's specification
      curl -sf -H "Authorization: Bearer $TOKEN" "$API/$G/$KIND?${V}limit=$LIMIT&offset=$OFFSET" -o "$F" \
        || { echo "FAILED: $F was not saved"; rm -f "$F"; break; }
      N=$(python3 -c "import json,sys; print(len(json.load(open(sys.argv[1]))))" "$F")
      [ "$N" -lt "$LIMIT" ] && break
      OFFSET=$((OFFSET + LIMIT))
    done
  done
done
echo "Saved to $OUT"

Step 2. Check the export

Download check_classic_glossary.py, install DuckDB (pip install duckdb) and run the script on the folder the commands wrote:

python3 check_classic_glossary.py classic-glossary-20261121-093000
CheckWhat a failure means
Every page of terms and categories was savedA full page has no next page after it, a later page was saved without an earlier one, or a term the glossary lists is in no saved page, so the export is missing terms.
No term guid appears twiceThe same term was saved on two pages, often because terms changed while the export was paging, so the counts are too high.
Every category a term names is in the exportA term points to a category that was not saved, so the term's place in the glossary is lost.
Every related term is in the exportA synonym, see-also or other related-term link points to a term that was not saved.
No two terms in one glossary share a name, ignoring case and spacesMicrosoft's migration page says a term whose name is already used in the destination governance domain is not moved automatically.
Every approved term has a steward or an expertNobody is named to answer for the term's definition once it moves.
No term has more than 100 relationshipsMicrosoft's migration page allows a single term at most 100 relationships in Unified Catalog and says to clean them up before migrating.

Run 1. A generated glossary, clean

The script writes a generated export when you ask for one: one glossary of 35 invented terms in three categories, saved in pages of 25, with a fixed seed.

python3 check_classic_glossary.py --make-demo demo
Wrote a generated classic glossary export to demo: 1 glossary, 35 term records, 3 categories, page size 25 (seed 262)
python3 check_classic_glossary.py demo
Python 3.14.8 duckdb 1.5.6
Export: demo
Read 1 glossary, 35 term records (35 distinct guids), 3 categories, 13 related-term links

Terms by glossary and status
  Enterprise Glossary    Approved      29
  Enterprise Glossary    Draft          6
Terms built from a term template: 5; terms with template attribute values: 5

Checks
  PASS  Every page of terms and categories was saved
  PASS  No term guid appears twice
  PASS  Every category a term names is in the export
  PASS  Every related term is in the export
  PASS  No two terms in one glossary share a name, ignoring case and spaces
  PASS  Every approved term has a steward or an expert
  PASS  No term has more than 100 relationships

Wrote findings.csv (0 rows) and terms.csv (35 rows) to .
RESULT: 0 findings. No check blocks the move.

How to read it

All seven checks pass, so the export is whole and nothing in it blocks a move. The counts by status show what a reviewer signs off: 29 approved terms and 6 drafts. Five terms were built from a term template. Microsoft's migration page says term templates become attributes that cannot be edited or deleted, so review the template before any term moves.

Run 2. The same glossary with seven planted problems

python3 check_classic_glossary.py --make-demo demo-planted --plant-errors
Wrote a generated classic glossary export to demo-planted: 2 glossaries, 37 term records, 3 categories, page size 25 (seed 262)
Planted one error for each check: DANGLING_RELATED, DUPLICATE_GUID, DUPLICATE_NAME, NO_STEWARD, OVER_RELATIONSHIP_LIMIT, PAGES_MISSING, UNKNOWN_CATEGORY
python3 check_classic_glossary.py demo-planted --tag planted
Python 3.14.8 duckdb 1.5.6
Export: demo-planted
Read 2 glossaries, 62 term records (61 distinct guids), 3 categories, 15 related-term links

Terms by glossary and status
  Enterprise Glossary    Approved      29
  Enterprise Glossary    Draft          7
  Regional Glossary      Draft         25
Terms built from a term template: 5; terms with template attribute values: 5

Checks
  FAIL  Every page of terms and categories was saved  (2)
  FAIL  No term guid appears twice  (1)
  FAIL  Every category a term names is in the export  (1)
  FAIL  Every related term is in the export  (1)
  FAIL  No two terms in one glossary share a name, ignoring case and spaces  (2)
  FAIL  Every approved term has a steward or an expert  (1)
  FAIL  No term has more than 100 relationships  (1)
  PAGES_MISSING            Regional Glossary: terms-25.json was not saved after a full page
  PAGES_MISSING            Regional Glossary: 1 term the glossary lists is in no saved page
  DUPLICATE_GUID           Enterprise Glossary: Safety Stock: guid 3c02db95-a417-45a3-88c0-db51c4ef063b on 2 records
  UNKNOWN_CATEGORY         Enterprise Glossary: Accrual: category 14c66546-f94f-4501-b536-27badc48a0ce is not in the export
  DANGLING_RELATED         Enterprise Glossary: Win Rate: seeAlso link to term 99f17050-9773-46f3-b2f8-054780497def, which is not in the export
  DUPLICATE_NAME           Enterprise Glossary: invoice : same name as "Invoice"
  DUPLICATE_NAME           Enterprise Glossary: Invoice: same name as "invoice "
  NO_STEWARD               Enterprise Glossary: Shipment: approved with no steward or expert
  OVER_RELATIONSHIP_LIMIT  Enterprise Glossary: Customer: 101 relationships (related terms, assets and columns); Unified Catalog allows 100

Wrote findings-planted.csv (9 rows) and terms-planted.csv (61 rows) to .
RESULT: 9 findings. Fix them in Purview, export again and re-run.
CheckThe problem planted in run 2
PagesA second glossary of 26 terms whose first page of 25 is full and whose next page was never saved.
Duplicate guidsThe last term of page one saved again at the top of page two.
CategoriesThe Accrual term names a Treasury category that is not in the export.
Related termsThe Win Rate term has a see-also link to a Close Rate term that is not in the export.
NamesA draft term named “invoice ” next to the approved Invoice term.
StewardsThe approved Shipment term with no steward and no expert.
RelationshipsThe Customer term assigned to 101 assets.

The seven planted problems give nine findings: a shared name is reported on both terms that share the name, and the missing page is reported twice, once as a page that was never saved and once as a listed term that is in no saved page.

Run the check on your own glossary

Run the commands in step 1 with ENDPOINT set to your Purview account's endpoint. The commands write a folder named classic-glossary- followed by the date and time, for example classic-glossary-20261121-093000, holding glossaries.json, page-size.txt and one folder of term and category pages for each glossary. Then run python3 check_classic_glossary.py followed by that folder's name. The script writes findings.csv and terms.csv to the script's own folder; add --out followed by a folder name to write the two files somewhere else. You do not edit the script.

We also tested a run on a second generated export, saved the way you would save your own: other glossary names, a page size of 3, upper-case guids in links, an approved term with an expert and no steward, a term template, and one planted problem for each check. All seven checks failed as planted, and nothing else was flagged.

Download check_classic_glossary.py · Get the full guide (PDF)

Result from run 1: terms.csv.

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 Purview tenant, and the commands in step 1 were not run. The field names come from Microsoft's Data Map REST reference, read on 2026-11-21.
  • Microsoft's migration page does not say what counts toward the 100 relationships. The script counts related-term links plus assigned assets and columns; change MAX_RELATIONSHIPS or the count if Microsoft defines it differently.
  • The name check compares terms within one glossary. Terms from two glossaries that share a name are not flagged; if both glossaries go to the same governance domain, compare them too.
  • The commands save glossaries in one call of up to 1,000. An account with more glossaries needs the same paging as the terms.
  • Paging by offset can skip or repeat a term that changes during the export. Export at a quiet time, and export again if the duplicate guid check fails.
  • The export holds terms, categories, contacts, related terms, assigned assets and template values. Workflows on classic terms are not in the export, and Microsoft's migration page says workflows are not migrated; record the workflows separately.
  • Dates are as of 2026-11-21. This guide is about Purview Data Governance, whose support ends on November 12, 2027.

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 classic glossary of 35 terms in three categories, fixed seed 262, in the shape of the Data Map API's answers (api-version 2023-09-01). Not a run against a tenant.
Code
check_classic_glossary.py
Results
terms.csv

When this is not enough

The check shows whether the export is whole and which terms need work before they move. Each term then needs a decision about where it lives after the switch-off, and someone to sign off the definitions in their new home.

Moving your whole Purview governance catalog, not only the classic 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