Guide · Purview to OneLake Migration

How to turn Purview glossary terms into Fabric tags

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

The short answer

Microsoft limits Fabric tags: a tag name is at most 40 characters, an item holds at most 10 tags, a tenant at most 10,000, and no name can be both a tenant tag and a domain tag. Before any tag is created, a Python and DuckDB script maps each approved term to a tag name, checks those limits and writes the Bulk Create Tags request.

Why plan the tags before creating any

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) points to tags, descriptions and endorsement in Fabric, and says not to claim full glossary parity.

A Fabric tag is a name and nothing else. Microsoft's tags overview and page on creating tags (both read 2026-11-21) set the limits a glossary has to fit: a tag name is up to 40 characters, of letters, numbers, spaces (not at the beginning) and special characters, with at least one letter or number; an item or workspace holds at most 10 tags; a tenant holds at most 10,000 tags; and a tenant tag name cannot be repeated as a domain tag, or the other way round. A term's definition, steward and related terms do not travel with the tag, so keep the glossary export as the record of the definitions.

What you will have at the end

  • A tag map, tag-map.csv: each approved or published term, the tag name it becomes, whether Fabric holds that tag already, and how many items it tags.
  • The request to create the tags, create-tags.json, in the body Fabric's Bulk Create Tags call takes, and an apply plan, apply-plan.csv: the tags each item gets.
  • Eight checks, each one PASS or FAIL, with every finding in findings.csv. Send create-tags.json only when all eight pass.

Step 1. Gather the four inputs

  • terms.csv: one row per glossary term, with the columns term_guid, name and status. The terms.csv that the classic glossary guide writes has these columns.
  • assignments.csv: which Fabric item each term should tag, with the columns term_guid, workspace_id, item_id and item_name. This is the mapping only you can make: from the assets a term was assigned to in Purview to the Fabric items that hold that data now.
  • existing-tags/: every page of the tags Fabric already has, from GET https://api.fabric.microsoft.com/v1/tags (List Tags reference, read 2026-11-21), and, if any items carry tags already, item-tags.csv with the columns item_id and tag_name.
  • Optional: tag-names.csv, with the columns term_guid and tag_name, for a tag name other than the term's own name.

We did not run these commands. We have no tenant to run them against, so they are written from Microsoft's Fabric REST reference, and the runs further down use generated records. The first part saves the existing tags; the commented parts create and apply tags, and are only for after the plan passes.

# Not run by us: written from Microsoft's Fabric REST reference (read 2026-11-21).
# Needs the Azure CLI (az login). Listing tags needs Tag.Read.All; creating them needs a Fabric administrator.
OUT="fabric-tags-$(date +%Y%m%d-%H%M%S)"; mkdir -p "$OUT/existing-tags"
TOKEN=$(az account get-access-token --resource https://api.fabric.microsoft.com --query accessToken -o tsv)
API="https://api.fabric.microsoft.com/v1"
# 1. Before planning: every page of the tags Fabric already has, following continuationToken.
URL="$API/tags"; N=1
while [ -n "$URL" ]; do
  F="$OUT/existing-tags/page-$(printf %03d $N).json"
  curl -sf -H "Authorization: Bearer $TOKEN" "$URL" -o "$F" || { echo "FAILED: $F was not saved"; rm -f "$F"; break; }
  T=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('continuationToken') or '')" "$F")
  [ -n "$T" ] && URL="$API/tags?continuationToken=$(python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=''))" "$T")" || URL=""
  N=$((N + 1))
done
# 2. Only after the script reports 0 findings: create the new tags, and save the response: the response holds the new tags' ids.
#    curl -sf -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
#      "$API/admin/tags/bulkCreateTags" -d @create-tags.json
# 3. Then, for each row of apply-plan.csv, apply the tags by id (at most 25 requests a minute):
#    curl -sf -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
#      "$API/workspaces/<workspace_id>/items/<item_id>/applyTags" -d '{"tags": ["<tag id>", "<tag id>"]}'

Step 2. Plan the tags

Download plan_fabric_tags.py, install DuckDB (pip install duckdb) and run the script on the folder the commands in step 1 wrote, after you put terms.csv and assignments.csv in that folder. Add --domain-id to plan domain tags instead of tenant tags, and --fail-on-findings to exit with status 1 when any check fails.

python3 plan_fabric_tags.py fabric-tags-20261121-093000
CheckWhat a failure means
Every assignment names a term in terms.csvThe mapping points to a term that was not exported, or to a mistyped id.
Every term that tags an item is approved or publishedA draft or expired term would become a tag that every reader in Fabric sees. Approved is the classic glossary's status; published is Unified Catalog's.
Every tag name is at most 40 charactersFabric refuses the name; add a shorter name to tag-names.csv. The script suggests one.
Every tag name starts with no space and holds a letter or numberThe name breaks Microsoft's naming rule.
No two terms become the same tag name, ignoring caseTwo terms would share one tag and readers could not tell them apart. Microsoft's pages do not say whether tag names are case sensitive, so the check treats names that differ only by case as the same.
No new tag repeats a tag name Fabric holds in the other scopeFabric does not allow a tenant tag and a domain tag with the same name.
No item ends up with more than 10 tagsThe item already carries tags, or too many terms point at one item; choose the terms that matter most for that item.
The tenant ends up with at most 10,000 tagsThe plan does not fit the tenant's limit; retire unused tags or tag fewer terms.

Run 1. A generated glossary and ten Fabric items, clean

The script writes generated inputs when you ask for them: 27 terms (two of them drafts), 53 assignments to 10 Fabric items, 4 tags Fabric already holds and 3 tags already on items, with a fixed seed.

python3 plan_fabric_tags.py --make-demo demo
Wrote generated inputs to demo: 27 terms, 53 assignments to 10 Fabric items, 4 existing tags in 1 page (seed 265)
python3 plan_fabric_tags.py demo
Python 3.14.8 duckdb 1.5.6
Input: demo
Read 27 terms, 53 assignments to 10 Fabric items, 4 existing Fabric tags, 3 tags already on items; new tags at tenant scope

Plan: 25 approved or published terms become 25 tag names; 2 already in Fabric, 23 to create; 10 items to tag
Tags per item after the move: fewest 2, most 9 (limit 10)
Tags in the tenant after the move: 27 (limit 10,000)

Checks
  PASS  Every assignment names a term in terms.csv
  PASS  Every term that tags an item is approved or published
  PASS  Every tag name is at most 40 characters
  PASS  Every tag name starts with no space and holds a letter or number
  PASS  No two terms become the same tag name, ignoring case
  PASS  No new tag repeats a tag name Fabric holds in the other scope
  PASS  No item ends up with more than 10 tags
  PASS  The tenant ends up with at most 10,000 tags

Wrote tag-map.csv, create-tags.json (23 tags), apply-plan.csv (10 items) and findings.csv (0 rows) to .
RESULT: 0 findings. The plan fits Microsoft's tag limits.

How to read it

The 25 approved terms that tag an item become 25 tag names. Two of those names, Customer and Invoice, are tags Fabric already holds, so the plan reuses them and creates 23. The two busiest items, the Revenue report and the Sales semantic model, end up with 9 tags each, so each of those items has room for one more tag before the limit of 10. The two draft terms tag nothing.

Run 2. The same inputs with eight planted problems

python3 plan_fabric_tags.py --make-demo demo-planted --plant-errors
Wrote generated inputs to demo-planted: 30 terms, 67 assignments to 10 Fabric items, 9,980 existing tags in 10 pages (seed 265)
Planted one problem for each check: NAME_CLASH, NAME_NOT_ALLOWED, NAME_TOO_LONG, NOT_APPROVED, OVER_ITEM_LIMIT, OVER_TENANT_LIMIT, SCOPE_CLASH, UNKNOWN_TERM
python3 plan_fabric_tags.py demo-planted --tag planted
Python 3.14.8 duckdb 1.5.6
Input: demo-planted
Read 30 terms, 67 assignments to 10 Fabric items, 9,980 existing Fabric tags, 3 tags already on items; new tags at tenant scope

Plan: 28 approved or published terms become 27 tag names; 2 already in Fabric, 25 to create; 10 items to tag
Tags per item after the move: fewest 2, most 15 (limit 10)
Tags in the tenant after the move: 10,005 (limit 10,000)

Checks
  FAIL  Every assignment names a term in terms.csv  (1)
  FAIL  Every term that tags an item is approved or published  (1)
  FAIL  Every tag name is at most 40 characters  (1)
  FAIL  Every tag name starts with no space and holds a letter or number  (1)
  FAIL  No two terms become the same tag name, ignoring case  (1)
  FAIL  No new tag repeats a tag name Fabric holds in the other scope  (1)
  FAIL  No item ends up with more than 10 tags  (1)
  FAIL  The tenant ends up with at most 10,000 tags  (1)
  UNKNOWN_TERM      item Supply chain warehouse: term e2b14965-439b-417d-a2ba-d1e52911920a is not in terms.csv
  NOT_APPROVED      term Churn Risk: status Draft, yet assigned to 1 item
  NAME_NOT_ALLOWED  term  Net margin: tag name " Net margin" starts with a space or holds no letter or number
  NAME_TOO_LONG     term Recognized revenue under contracts with customers (ASC 606): 59 characters; add a row to tag-names.csv, for example "Recognized revenue under contracts with"
  NAME_CLASH        tag Customer: terms "Customer", "customer" become the same tag name
  SCOPE_CLASH       term Supplier: Fabric already holds a domain tag named "Supplier"
  OVER_ITEM_LIMIT   item Pipeline report: 15 tags, counting the ones already on the item
  OVER_TENANT_LIMIT tenant: 9,980 existing + 25 new = 10,005 tags

Wrote tag-map-planted.csv, create-tags-planted.json (25 tags), apply-plan-planted.csv (10 items) and findings-planted.csv (8 rows) to .
RESULT: 8 findings. Fix them, and re-run, before you send create-tags.json.
CheckThe problem planted in run 2
Unknown termsAn assignment to the Supply chain warehouse for a term that is not in terms.csv.
ApprovalThe draft term Churn Risk assigned to the Sales semantic model.
LengthA 59-character term about revenue under contracts with customers.
Naming ruleA term named “ Net margin”, with a leading space.
Same nameA term named “customer” next to the term Customer.
ScopeA domain tag named Supplier that Fabric already holds, while the plan creates tenant tags.
Item limitNine more terms pointed at the Pipeline report, which ends up with 15 tags.
Tenant limit9,980 tags Fabric already holds, so 25 new tags pass 10,000.

Plan the tags for your own glossary

Put the inputs in one folder. The commands in step 1 write a folder named fabric-tags- followed by the date and time, for example fabric-tags-20261121-093000, holding an existing-tags folder with one file for each page of the tags Fabric already has. A line that starts with FAILED names a page that was not saved; run the commands again. Add terms.csv and assignments.csv to the same folder, item-tags.csv if any items carry tags already, and tag-names.csv for any tag name other than the term's own name. Then run python3 plan_fabric_tags.py followed by the folder's name; add --domain-id followed by the domain's id to plan domain tags instead of tenant tags. The script writes tag-map.csv, create-tags.json, apply-plan.csv and findings.csv to the script's own folder; add --out followed by a folder name to write the four files somewhere else. Send create-tags.json only when all eight checks pass. You do not edit the script.

We also tested a run on a second set of generated inputs, saved the way you would save your own: the terms.csv the classic glossary guide writes, with its extra columns and a status in lower case, upper-case ids, a tag-names.csv that shortens one long name, existing tags in two pages, six tags already on one item, and one planted problem for each check. All eight checks failed as planted, and nothing else was flagged.

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

Results from run 1: tag-map.csv, create-tags.json and apply-plan.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 tenant, and the commands in step 1 were not run. The limits come from Microsoft's Fabric pages, read on 2026-11-21.
  • The script plans; the script creates and applies nothing. Microsoft's reference limits List Tags, Bulk Create Tags and Apply Tags to 25 requests a minute for each caller.
  • Microsoft's pages do not say whether tag names are case sensitive, what Apply Tags answers when an item would pass 10 tags, or how many tags one Bulk Create Tags call takes. The script treats names that differ by case as the same and stops the plan at 10 tags an item.
  • A tag carries no definition, steward or relation to other terms. Keep the glossary export as the record of definitions, stewards and relations.
  • The mapping from Purview assets to Fabric items in assignments.csv is yours to make; the script checks the mapping, not where the data now lives.
  • 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: 27 invented glossary terms, 53 assignments to 10 invented Fabric items and 4 existing tags, fixed seed 265, with tags in the shape of Fabric's List Tags answer. Not a run against a tenant.
Code
plan_fabric_tags.py
Results
tag-map.csv

When this is not enough

Tags make terms findable in Fabric; they do not hold the meaning. The definitions, owners and relations need a home of their own, and each item's tags need someone to keep them current after the move.

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