This article covers what is specific to Microsoft Purview. How connections, mappings, Push, Pull, Status and the run report work is described in Data Governance Integrations — read that first.
What you need from Purview
| Requirement | Where to set it |
|---|---|
| An enterprise-tier Purview account | Azure portal, by your Purview or Azure admin. The free tier can read but blocks every write |
| An Entra (Azure AD) app registration with a client secret | Microsoft Entra admin center, by an Entra admin |
| Collection Admin and Data Curator for that application on the collections SqlDBM should read and write | Purview, by a collection admin |
| Your Purview endpoint and your Directory (tenant) ID | Azure portal / Entra admin center |
Use an app registration created for SqlDBM, not a person's account. SqlDBM signs in with the application's client id and secret and never stores a user's password.
Preparing Purview
These steps are done in Entra and Purview by an admin.
1. Register an application. In the Entra admin center, create an app registration for SqlDBM and add a client secret to it. Record three values from the app's Overview blade:
- Application (client) ID
- Directory (tenant) ID
- Client secret — the Value shown once when the secret is created, not the Secret ID
2. Check the account tier. The free tier rejects Data Map writes regardless of the roles you grant, so pushes fail until the account is on the enterprise tier. Per-user Purview seat licences do not matter; this is an account-level prerequisite.
3. Grant the application two roles on the collections it should work with. Purview authorises Data Map access through collection role assignments, not through Microsoft 365 role groups.
- Collection Admin lists the collection tree. Without it, the collections list SqlDBM reads comes back empty and no collection can be selected. Collection Admin also allows changing role assignments on those collections, so scope it to the narrowest collections that hold the assets you map, and remove it when the integration is retired.
- Data Curator reads and writes business metadata values.
Both roles inherit to child collections. Grant them in the Purview portal under the collection's Role assignments. Add the application's service principal to a security group first if your portal only offers groups; if the portal does not expose the assignment for a service principal, an admin can add the same role through the Purview metadata policy API.
4. Create your business metadata. Purview's custom attributes live in Data Map → Business metadata. Beyond the general rule that SqlDBM never creates attributes, for Purview it also never changes a set, an attribute or an enum, and never adds an option to a dropdown. Create everything you need first, and make each attribute applicable to the asset types you scan (for example snowflake_table and snowflake_table_column).
5. Network. The account firewall must allow public network access, or explicitly allow SqlDBM's outbound addresses. With public access disabled, the connection check reports Purview as unreachable rather than as a credentials problem.
6. Guest users. If the admin setting this up is a guest user in the tenant, the Purview portal may hide the collection role-assignment controls even when the permission exists. Do the grants as a member user or through the metadata policy API, and verify with SqlDBM's connection test rather than the portal view.
Connecting
The Microsoft Purview connection form asks for:
- Application (client) ID
- Client secret
- Directory (tenant) ID — a GUID. SqlDBM requests tokens from this tenant
-
Endpoint — one of two options:
-
Classic account: the account's own host,
https://<your-account>.purview.azure.com -
Tenant-level: the fixed host
https://api.purview-service.microsoft.com, used by accounts opened from the new Purview portal without an account-specific host
-
Classic account: the account's own host,
If your admin can name an account host, choose Classic account and enter it. If the account was created in the new Purview portal and has no host of its own, choose Tenant-level. Both expose the same Data Map API, and SqlDBM treats them the same once connected.
Select Test connection before saving. The test signs in, reads the business metadata definitions and checks that writes are permitted. Possible outcomes are listed under Troubleshooting.
Mapping container: Collection
A Purview mapping targets one Collection.
The Collection picker lists every collection the application administers, including the root, shown with its full path (for example Root / Finance / Warehouse).
[Screenshot: Settings tab with the Collection picker showing full paths]
A mapping covers the assets that sit directly in the selected collection. Assets in its child collections are not included; map each child collection you need separately.
Objects
Purview holds tables, views and columns from the SQL-style sources it scans: Snowflake, Azure SQL Database, SQL Managed Instance, Synapse, Databricks, BigQuery, Redshift, Amazon RDS, PostgreSQL, MySQL, Oracle, Teradata, Db2 and others. SqlDBM offers the tables and views in the collection, and the columns each one carries.
Purview does not give SqlDBM a database or schema level to match on, so tables are matched by name within the collection. Keep one schema's worth of objects per collection, or resolve same-named tables by hand with Rematch — otherwise a table name that repeats across schemas cannot be matched unambiguously.
[Screenshot: Objects tab with tables matched within a collection]
Purview assigns a new id to an asset when it is deleted and re-created by a scan, or when it moves to another collection. Either way the Objects tab then shows the object as no longer in Purview.
Attributes
The Microsoft Purview column offers business metadata attributes applicable to tables or columns, listed as Set name.Attribute name (for example SqlDBM.Sensitivity). Business metadata definitions are account-wide, not scoped to a collection, so the same attribute list appears for every mapping.
[Screenshot: Attribute mapping tab with Set.Attribute names]
Type pairs:
| SqlDBM field | Purview attribute |
|---|---|
| Text |
string; also date, int, long, double and the other number types. The value is sent as text and Purview converts it |
| URL |
string (Purview has no URL type) |
| Checkbox | boolean |
| Dropdown | An enum-typed attribute |
| Multiselect | array<enum> |
Not offered: array<string> and any other array or complex type. They are left out of the list and counted in the run log.
Two Purview-specific behaviours:
- Purview does not enforce applicability; SqlDBM does. Purview accepts a value written to an attribute that is not applicable to the asset's type and then discards it without an error. SqlDBM checks applicability before writing instead, which is why Attribute can't be set on tables (or columns) appears in the report. The Purview-side fix is to edit the attribute's applicable entity types in Data Map → Business metadata.
- Options are never added. A dropdown value the enum does not offer is skipped, and the only fix is to add it to the enum in Purview.
Push to Microsoft Purview
Other business metadata sets on the asset are left alone as well as unmapped attributes. Empty Text and URL fields clear the attribute in Purview; an unchecked checkbox and an empty dropdown are sent as no value.
Background batching starts above 100 objects, in batches of 100. A typical 200-object push completes in about a minute.
Purview rejects simultaneous writes to columns of the same table as version conflicts. SqlDBM retries those automatically; they do not appear in the report.
Pull from Microsoft Purview
A pull reads the whole collection in one pass: tables and views first, then the columns each one carries.
A dropdown value on an asset whose option was removed from the enum is skipped; the object stays in the comparison and, if SqlDBM holds a value for that field, the comparison proposes clearing it.
[Screenshot: pull comparison screen with a proposed clear highlighted]
Limits and behaviour
| Topic | Behaviour |
|---|---|
| Request rate | SqlDBM paces its calls to your account at about 600 per minute per operation and backs off on Purview's throttling responses |
| Capacity units | On classic accounts, every Data Map call, reads included, is billed against your account's capacity units. A large pull or push shows up on that meter |
| Push size | Up to 100 objects per request; larger pushes run in the background in batches of 100 |
| Collection size | Up to 50,000 assets (roughly 5,000 tables with their columns). A larger collection is refused with a message naming the limit; split the collection or map a smaller one |
| Pull duration | A pull has three minutes to read the collection. Over that, nothing is applied and the message asks you to reduce scope or retry |
| Number and date values | Sent as text; Purview converts them. A value it cannot convert is skipped with value not convertible. Dates are epoch milliseconds |
| Special characters | Angle brackets and ampersands in text are escaped on the wire and arrive intact in Purview |
Troubleshooting
Messages Purview produces on its own. Shared messages — a busy container, an oversized push, a missing attribute — are explained in Data Governance Integrations.
| You see | It means | What to do |
|---|---|---|
| The Purview credentials were rejected. | Wrong client id, client secret or tenant id, or the secret expired | Re-enter the values; check the secret's expiry in Entra |
| Writes are blocked — the Purview account is on the free tier (enterprise upgrade required), or the credential has no data-curator grant on any collection. | The account is on the free tier, or Data Curator is missing everywhere | Upgrade the account tier; grant Data Curator on the collections you map |
| Purview could not be reached — a network, DNS or TLS failure, or public network access is disabled on the account. | Wrong endpoint, egress blocked, or the account firewall denies public access | Check the Endpoint choice and the account firewall |
| The Purview collections list is unavailable — grant the credential Collection Admin. / the Collection picker is empty | Collection Admin is missing | Grant Collection Admin on the collections you want to map |
| The Purview connection settings are not valid. | The endpoint is neither a purview.azure.com host nor the tenant-level host, or the tenant id is not a GUID |
Correct the form; Save stays disabled until both parse |
| Collection holds more than 50000 assets; scope the collection or await bulk pull. | The collection exceeds the read limit | Split the collection, or map a smaller one |
| Values pushed, but not visible on the asset in Purview | Purview accepted and discarded a value for a non-applicable attribute, or the portal is showing a cached asset | Check the attribute's applicable types; refresh the asset page |