Power BI

The Power BI connector imports metadata from a Microsoft Power BI / Microsoft Fabric tenant over the REST APIs. One Connection can cover a whole tenant, and a datasource filter can be applied to select which workspaces and assets to import.

The Power BI connector is a primary connector.

The Power BI connector currently supports import of the following metadata, but what the connector actually captures depends on the import mode:

• The Power BI tenant as a datasource, and each workspace as a dataset group
• Semantic models, with their tables as child datasets
• Columns and measures as fields, with the model’s own datatypes, hidden flags and DAX expressions
• Relationships between the tables of a semantic model
• Reports, Dashboards and Apps, each with a link that opens it in the Power BI service
• Lineage from a source table into a semantic model, and between the Power BI items themselves

The connector does not support import of:

• Private (“My Workspace”) and Admin monitoring workspaces
• Endorsement, sensitivity labels, tags and item owners
• Usage statistics and latest refresh timestamps
• Report pages and the visuals on them
• Field-level lineage between a report visual and the model columns it uses
• Report thumbnails and workspace images

Import Modes

The connector reads a tenant in one of three ways, chosen with Import Mode on the connection. They all produce the same asset tree, but they differ in what they cost, what they need, and what metadata they can extract. This is due to inconsistencies in Microsoft’s APIs,

Fabric API reads each workspace the service principal belongs to, item by item. It needs no administrator, which makes it the mode to start with. Its cost is one long running operation per semantic model, so it does not scale: a tenant with two thousand models takes about an hour, and one with five thousand takes several.

Scanner API reads the whole tenant with the admin metadata scanning APIs — one scan per hundred workspaces, whatever their size. It requires a Fabric administrator to enable metadata scanning and does not return column descriptions nor semantic model relationships. On the other side, it is dramatically more performant and returns lineage the Fabric APIs never see.

Hybrid does both, and is the mode to use where it can be arranged. It scans the tenant, then reads the full definition of each semantic model in the workspaces the service principal belongs to — so nothing either API can report is lost. Its price is both sets of requirements at once, i.e. it requires both a Fabric Admin and per-workspace membership, and it also inherits the Fabric API’s performance limitations.

Tip

When using Hybrid mode, either set a datasource filter on dataset_group_name naming the workspaces the service principal is a member of, or only assign the service principal to a few selected workspaces that are most important. The former means that only the selected workspaces will be imported. The latter means that all workspaces are imported, but only those where the service principal is a member gets the full set of metadata Katalogue wants.

Reading a semantic model’s definition is the expensive part of a sync, and the filter is what stops it being attempted for workspaces that would be filtered out of the import anyway.

	Fabric API	Scanner API	Hybrid
Imported assets	Workspaces Semantic models, with their tables, columns and measures Reports and Paginated reports Dashboards — name and description only	Workspaces Semantic models, with their tables, columns and measures Reports and Paginated reports Dashboards Org Apps and Workspace Apps, with the reports they publish	As Scanner API
Lineage	source table → semantic model semantic model → report	source table → semantic model semantic model → report report → dashboard report → app	As Scanner API
DAX expressions and the Power Query behind each table	✅	✅	✅
Calculated tables, and which fields are calculations	✅	✅	✅
Column descriptions	✅	⚠️ measures only	✅
Primary keys on columns	✅	❌ not returned	✅
Relationships within a semantic model	✅	❌ not returned	✅
Datatype of a calculated table’s columns	✅ resolved	⚠️ often reported as String	✅
Report created and modified dates	❌	✅	✅
Cost	~6 API calls per semantic model	~10 API calls per 100 workspaces	A full tenant scan, plus ~6 API calls per model
Requires	The Member role on each workspace	Tenant settings, set once by a Fabric administrator	Both

Where the table says a mode does not return something, it means the API does not carry it — not that Katalogue chooses to skip it.

Caution

Switching an existing connection’s import mode might delete data. A sync writes what the API returned, so anything the selected import mode cannot report is deleted. For example, switching from Fabric API to Scanner API mode will change this on the next sync:

• Primary keys are cleared
• Column descriptions are cleared, except on measures
• Semantic model relationships are deleted

DAX expressions, Power Query and everything else in the table above are unaffected. Switching the other way restores them on the next sync, since the Fabric API does report them, but will instead delete all Apps and some lineage.

Note

A semantic model that has not been refreshed or republished since metadata scanning was enabled may be returned without its tables. The model is still catalogued, and a refresh in the Power BI service is what makes its schema available to a later scan. Models that use perspectives can behave the same way.

Prerequisites

Licensing

The Fabric REST API is available for Microsoft Fabric workspaces (all SKUs), Power BI Premium workspaces and Power BI Premium Per User workspaces.

Caution

Pro workspaces have limited API access. In Fabric API mode a semantic model in a Pro workspace may not return its definition, in which case the model is reported as a warning and imported without its tables. Metadata scanning has no such restriction and works for the whole tenant.

App registration

The connector authenticates as a Microsoft Entra Id service principal using the client credentials flow.

1. In the Azure portal, go to Microsoft Entra ID → App registrations → New registration. A single-tenant registration with no redirect URI is enough.
2. Note the Application (client) ID and the Directory (tenant) ID.
3. Under Certificates & secrets, create a new client secret and copy its value immediately — it is not shown again.
4. If you are using Scanner API or Hybrid mode, the service principal must have no admin-consent-required Fabric / Power BI API permissions set on its app registration. This is a Microsoft requirement.

Note

Katalogue is already configured for Microsoft Entra Id SSO, the connection can be left without credentials entirely: an empty Application (client) Id, Client Secret or Directory (tenant) Id falls back to the app registration used for SSO. That registration then needs the permissions below.

Permissions for Fabric API mode

Two things have to be granted, and both are needed:

1. Service principals must be allowed to use the Power BI APIs. In the Power BI admin portal, under Tenant settings → Developer settings, enable Service principals can call Fabric public APIs and add the app registration to the allowed security group.
2. The service principal needs access to each workspace. In the workspace, under Workspace access, add the service principal with at least the Member role.

Caution

Enabling the tenant setting is not enough on its own. The Fabric API returns the workspaces the principal can access, so a service principal that has been added to no workspace sees an empty tenant rather than an error.

Caution

Reading a semantic model’s definition requires read and write permission on the model — the Fabric API requires the SemanticModel.ReadWrite.All or Item.ReadWrite.All scope for it, which is why the Member role is the minimum and Viewer is not enough. Katalogue never writes: it calls only the read operations of both APIs.

Caution

The Fabric API’s definition endpoint is blocked for a semantic model that carries an encrypted sensitivity label. Such a model cannot be imported in Fabric API mode.

Permissions for Scanner API mode

The scanner APIs are admin APIs, so the requirements are different — and per-workspace access is not among them. Everything below is done once, by a Fabric administrator, and all four settings live in the same place: Admin portal → Tenant settings → Admin API settings.

Katalogue reaches these endpoints under the Power BI API Base URL from Configuration — they are served beneath it, at /admin — so a sovereign or government cloud needs that setting changed for a scan to reach the right tenant.

1. Put the service principal in a security group. In the Azure portal, create a Microsoft Entra group with the group type Security, and add the connector’s app registration to it as a member. An existing security group can be reused.
2. Allow service principals to call the read-only admin APIs. Enable Service principals can access read-only admin APIs, select Specific security groups, add the group from step 1, and select Apply. This enables the service principal to authenticate.
3. Enable Enhance admin APIs responses with detailed metadata. This is what makes a scan return tables, columns and measures. Without it a scan succeeds and returns items with no schema.
4. Enable Enhance admin APIs responses with DAX and mashup expressions. This adds the DAX behind each measure and the Power Query behind each table. It can only be switched on once step 3 is enabled — the two are not independent.

Note

Steps 3 and 4 are what Microsoft calls setting up metadata scanning. They are tenant-wide settings that govern what the admin APIs return to anyone, not something granted to Katalogue in particular.

Caution

Allow up to an hour before testing. Each part of this propagates on its own schedule — the app registration, its membership of the security group, and each tenant setting — and the slowest sets the pace. An hour has been observed in practice, where Microsoft’s documentation suggests fifteen minutes.

Until it takes effect, Test Connection fails with 403 - Forbidden, which looks exactly like a setting being wrong. Resist changing anything during that window: the settings above are the whole of what is required, and changing them restarts the wait.

Caution

A service principal used for the admin APIs must have no admin-consent-required Fabric / Power BI API permissions set on its app registration in the Azure portal. This is a Microsoft requirement, and an app that has them will be refused.

To check: Azure portal → Microsoft Entra ID → Enterprise applications → the application → Permissions. There must be no admin-consent-required permissions of type Application registered for the app. A registration created for this connector needs no API permissions at all, so the simplest arrangement is to leave them empty.

Configuration

The API endpoints, the OAuth scopes and the Power BI service address the connector uses are configurable in the Settings → Connectors → Power BI section. They are settings rather than hardcoded values so a sovereign or government cloud — which uses different hosts — can be reached without a new release, and they do not need changing for the public cloud.

Setting	Default
Fabric API Base URL	https://api.fabric.microsoft.com/v1
Fabric API Scope	https://api.fabric.microsoft.com/.default
Power BI API Base URL	https://api.powerbi.com/v1.0/myorg
Power BI API Scope	https://analysis.windows.net/powerbi/api/.default
Power BI Service Base URL	https://app.powerbi.com

The Power BI Service Base URL is the odd one out: it is not an API Katalogue reads, but where a user opens the asset. Every link Katalogue stores for an imported Power BI asset is built from it, and it is the hostname the datasource is registered under, so on a sovereign cloud it has to be changed along with the API endpoints or the links open nothing. Assets that are already imported keep the links they were imported with until the next sync.

Two APIs are used, and therefore two access tokens: the Fabric API serves workspaces, semantic models and model definitions, while the Power BI API serves the metadata scanning endpoints and — in Fabric API mode only — a workspace’s reports, since the Fabric item listing returns neither a report’s web URL nor the semantic model it is built on. A token is valid for one audience only, so the connector acquires one per scope from the same service principal.

Note what that means for Power BI API Base URL: the admin endpoints the metadata scan is built on — /admin/workspaces/modified, /admin/workspaces/getInfo, /admin/workspaces/scanStatus, /admin/workspaces/scanResult and /admin/apps — are served under that same base URL, so it is the setting that moves Scanner API and Hybrid mode to another cloud as well, not only the reading of reports.

Concept Mapping

A Power BI tenant is one datasource, and each workspace in it is a dataset group. Every item in a workspace — a semantic model, a report, a dashboard, an app — is a dataset directly under it. The workspace and each item keep a link back to themselves in the Power BI service, so either can be opened from Katalogue. A report and the semantic model it is built on almost always share a name, because that is what publishing a PBIX produces; what tells the two apart in Katalogue is the kind of asset each one is.

Contoso Power BI                 datasource
└── Sales BI                     dataset group  (workspace)
    ├── Sales                    dataset        (semantic model)
    │   ├── Customer             dataset        (table)
    │   │   ├── CustomerKey      field          (column)
    │   │   └── Total Sales      field          (measure)
    │   └── Date                 dataset        (calculated table)
    ├── Sales                    dataset        (report)
    ├── Exec Dashboard           dataset        (dashboard)
    └── Sales                    dataset        (app)

Katalogue concept	Power BI concept
datasource_name	the Power BI Tenant Name from the connection, or the connection’s name when that is left empty
datasource_hostname	the Power BI service URL
dataset_group_name	workspace name, for workspaces of type Workspace only
dataset_name (type semantic_model)	a semantic model
dataset_name (type table)	a table of a semantic model
dataset_name (type report, paginated_report)	a report, typed by its reportType
dataset_name (type dashboard)	a dashboard
dataset_source_id	the item’s id in Power BI
dataset_source_url	the item in the Power BI service, opened from the asset in Katalogue
dataset_technical_definition	the M/Power Query code that produces a table (or DAX for calculated tables)
dataset_is_hidden	a table’s isHidden
field	a column or a measure of a table
datatype_name	the column’s dataType, exactly as the model declares it (int64, string, dateTime, …). A measure declares none, so it is automatic
field_technical_definition	the DAX expression of a measure or a calculated column
field_is_hidden	a column’s or measure’s isHidden
is_primary_key	a column’s isKey, in Fabric API mode
relationship	a relationship between two tables of the same semantic model

Names

Power BI identifies an item by id and does not require its name to be unique, while Katalogue identifies a dataset by its name within its parent and kind. Where two items of the same kind in one workspace share a name, the second and later ones are renamed as Name (2), Name (3) and so on. A semantic model and a report sharing a name are unaffected — the two are told apart by what they are.

Calculated Tables

A table whose rows come from a DAX expression rather than from a source is catalogued as a calculated table, with that DAX as its technical definition. Its columns carry no expression of their own — the one that produces them belongs to the table.

Measures and Calculated Columns

Fields that are themselves calculations are catalogued as what they are with their DAX code as their technical definition, rather than by what they hold: a measure gets the datatype measure, and a calculated column calculated column. Neither of Microsoft’s APIs reports a datatype for these that can be relied on.

Workspace Apps

A Workspace App is a bundled, read-only snapshot of selected assets in a Power BI workspace, and a workspace can have exactly one. These are catalogued as its own asset type in Katalogue, with the same name as the workspace and the reports and dashboards it publishes are recorded as lineage into it.

Publishing a workspace as an app in Power BI creates a copy of its reports and dashboards. Power BI names them with an [App] prefix at the moment they were published while the original goes on being edited. These are not visible in the workspace in Power BI Service, but the APIs return them alongside the originals. Katalogue never shows them either, with one exception - A copy whose original has since been deleted from the workspace. Katalogue records these with the name given by Power BI ([App] Original name) and with the Is hidden attribute set to true.

Auto Date/Time Tables

Power BI’s own auto date/time tables are not imported. With that option on, Power BI silently creates a LocalDateTable_<guid> behind every date column and one DateTableTemplate_<guid> per model, to drive the date hierarchy. They appear nowhere in the Power BI model view or field list. They are part of the exported data from the APIs, but Katalogue never syncs these to reflect what end users actually see in Power BI.

Lineage

The connector records three kinds of dataset lineage. Which of them you get depends on the import mode — see the comparison above.

From	To	How it is found
A table in a source database	A table of a semantic model	Parsed from the model’s M/Power Query code
A semantic model	A report	The report names the model it is built on
A semantic model or report	A dashboard	The dashboard’s tiles name what they are pinned from

Source lineage is best-effort. The connector reads the model’s M/Power Query for the database, schema and table each model table is loaded from, and emits an edge naming them. That edge appears in Katalogue only if the upstream database is already synced to Katalogue, and its Katalogue datasource name matches the database name in the Power BI connection string. When it does not match, nothing is created and nothing breaks — the M/Power Query code is still visible on the table as its technical definition.

The sources recognised by the connector are Microsoft SQL Server, PostgreSQL, Snowflake and Azure Databricks. The connector also parses Amazon Redshift, MySQL, Vertica and Teradata eventhough Katalogue does not have native connectors for those yet. Common to all sources above is that they are the ones whose Power Query names both the database and the table. Oracle is not among them: Oracle.Database takes a connect string — a net service name, or an EZConnect host:port/service — so it identifies a service, while the Katalogue Oracle connector catalogues a datasource by its database or PDB name. A model loading from anything else, or through Power Query the reader cannot follow, simply produces no source lineage.

A paginated (RDL) report has no semantic model, so it gets no lineage to one. This is a limitation of what metadata Microsoft exposes for paginated reports rather than a limitation of the connector.

Filtering

The whole tenant is read first, then datasource filters are applied within Katalogue before import. See Datasource Filters.

Caution

Without a filter, every workspace the connection can see is imported. Test the connection before the first sync: it reports how many workspaces are visible.

Filter on dataset_group_name to select workspaces, on dataset_name to select individual items or tables, and on dataset_type_name to select a kind of asset (semantic_model, table, calculated_table, report, paginated_report, dashboard, org_app, workspace_app).

Filtering keeps the ancestors of whatever matches, so selecting a semantic model brings its containing workspace with it without having to name it.

The example below imports the Sales BI workspace, and from it only the semantic models and their contents:

{
  "datasource_filter": [
    {
      "concatenator": "and",
      "filters": [
        {
          "field": "dataset_group_name",
          "operator": "equal",
          "value": "Sales BI"
        },
        {
          "field": "dataset_type_name",
          "operator": "in",
          "value": ["semantic_model", "table"]
        }
      ]
    }
  ]
}

Model Definition Format

In Fabric API mode a semantic model’s structure is read with the Fabric Get Semantic Model Definition operation, which can return the model in either of two formats: TMSL, a single JSON document (model.bim), or TMDL, a folder of tab-indented text files. The connector asks for TMSL explicitly, because TMSL states a column’s datatype, its hidden flag and a measure’s DAX as ordinary JSON fields, where TMDL would have to be parsed as text.

Note

The format is a query parameter, not a field in the request body. When it is not specified the service applies its own default, which has been TMDL since Microsoft made TMDL the default item definition format in 2024 — so a request that appears to ask for TMSL in the body silently receives TMDL instead. If the service ever returns a format other than the one requested, the connector fails with a message naming the format it received rather than guessing at the payload.

Performance

Fabric API mode reads every visible workspace, one definition per semantic model, and is bounded by Fabric’s quota of 200 API calls per minute per identity. At roughly six calls per model that is about 33 models a minute, so a tenant of 2,000 models takes around an hour however the connector is tuned.

Scanner API mode is bounded instead by the scanning APIs’ own limits: 500 requests an hour and 16 simultaneous scans, with 100 workspaces per scan. A tenant of 500 workspaces is about 50 calls in total, so the limits are not a practical constraint.

Both import modes run four queries/scans in parallell. The log records at debug level how long time each workspace took to scan.

Troubleshooting

This section lists a few common errors you might encounter with the connector.

“Failed to acquire an access token for the Power BI tenant” The client id, client secret or tenant id is wrong, or the secret has expired. If the fields were left empty, the Microsoft Entra Id SSO app registration is being used and it is that registration which needs checking.

No workspaces are visible In Fabric API mode the service principal has not been granted access to any workspace, or Service principals can call Fabric public APIs is not enabled — both are needed. In Scanner API mode Service principals can access read-only admin APIs is not enabled, the application is not in the security group named there, or metadata scanning has not been set up. The sync fails rather than reporting an empty success, because importing nothing would delete everything a previous sync had imported. The message names which of the two situations applies.

“403 - Forbidden” from an /admin/ endpoint (Scanner API mode) The admin APIs refuse the service principal. The service principal does not need to be a Fabric administrator — a Fabric administrator has to switch the setting on once, which is a different thing. In order of likelihood:

1. Service principals can access read-only admin APIs is not enabled in Admin portal → Tenant settings → Admin API settings.
2. It is enabled, but set to Specific security groups and the application is not a member of any group listed there.
3. The app registration has admin-consent-required Fabric/Power BI permissions set on it in the Azure portal, which Microsoft refuses for this flow. It should have none.
4. The settings were changed recently. Propagation can take up to an hour — the app registration, its group membership and each tenant setting take effect independently. If everything above checks out, wait rather than change anything; an hour of no action is more likely to fix this than any edit.

The connection tests green but the sync fails with an authorization error Check that you tested in the mode the connection is actually set to. The two modes call different APIs and need different rights: a service principal with the Member role on every workspace passes the Fabric API test and is still refused by the metadata scanning APIs, which are admin APIs and need the tenant settings under Permissions for Scanner API mode. Test Connection follows the selected mode, so re-testing after switching mode reports the real problem.

The scan succeeds but no model has any tables The two detailed-metadata tenant settings have not been enabled. A scan without them returns items but no schema.

“Failed to read the definition of semantic model …” (Fabric API mode) A warning rather than a failure: the model is still catalogued, with its name, description and link, but without its tables and fields. The sync only fails outright when no model in the tenant could be read, which points at the permission rather than at any one model.

The message names the request that failed and the error code the API returned, which is what tells the cases apart:

• 403, or every model failing — the service principal has the Viewer role rather than Member. Listing a model works with Viewer, reading its definition does not.
• 404 RequestedItemNotFound or EntityNotFound on one model — that model has no definition the Fabric item API can serve. Usage metrics models, push and streaming datasets, the semantic models generated automatically for a lakehouse or warehouse, and older models never migrated to Fabric item storage all behave this way. Nothing is wrong with the connection.
• A model with an encrypted sensitivity label is blocked by the API and behaves the same way.

“Power BI reported no schema for semantic model …” (Scanner API mode) The same situation, reported by the scan itself as a schemaRetrievalError. The model is imported without its tables.

A model shows no source lineage Either the upstream database is not catalogued in Katalogue under the name Power BI uses for it, or the model’s Power Query is not one of the shapes the reader recognises. The Power Query is still on the table as its technical definition, so the dependency remains visible.