PBIXRay

Overview

PBIXRay is a Python library designed to parse and analyze PBIX files, which are used with Microsoft Power BI. This library provides a straightforward way to extract valuable information from PBIX files, including tables, metadata, Power Query code, and more.

This library is the Python implementation of the logic embedded in the DuckDB extension duckdb-pbix-extension.

Note: PBIXRay also supports Excel (XLSX) files with embedded PowerPivot models. You can use the same API to extract and analyze data models from XLSX files that contain PowerPivot data.

Installation

Install with pip:

pip install pbixray

Getting Started

To start using PBIXRay, import the module and initialize it with the path to your PBIX file:

from pbixray import PBIXRay

model = PBIXRay('path/to/your/file.pbix')

Large models (on-disk loading)

By default the entire decompressed data model is held in memory. For models whose uncompressed size approaches or exceeds available RAM, pass on_disk=True: the decompressed data is streamed to a temporary file and memory-mapped, so only the pages a requested table actually touches are faulted in. Use temp_dir to control where the spill file is created (defaults to the system temp directory).

# Spill to disk + mmap instead of holding everything in RAM.
with PBIXRay('path/to/large.pbix', on_disk=True, temp_dir='/fast/scratch') as model:
    df = model.get_table('Sales')
# leaving the `with` block releases the mapping and removes the temp file

PBIXRay is also a context manager; model.close() (or exiting the with block) deterministically releases the memory map and the metadata connection. When on_disk=False (the default) behavior is unchanged. Metadata (DAX, TMSCHEMA_*, etc.) is loaded lazily on first access, so simply opening a file is cheap.

Features and Usage

Tables

To list all tables in the model:

tables = model.tables
print(tables)

Metadata

To get metadata about the Power BI configuration used during model creation:

metadata = model.metadata
print(metadata)

Power Query

To display all M/Power Query code used for data transformation, in a dataframe with TableName and Expression columns:

power_query = model.power_query
print(power_query)

M Parameters

To display all M Parameters values in a dataframe with ParameterName, Description, Expression and ModifiedTime columns:

m_parameters = model.m_parameters
print(m_parameters)

Model Size

To find out the model size in bytes:

size = model.size
print(f"Model size: {size} bytes")

DAX Calculated Tables

To view DAX calculated tables in a dataframe with TableName and Expression columns:

dax_tables = model.dax_tables
print(dax_tables)

DAX Measures

To access DAX measures in a dataframe with TableName, Name, Expression, DisplayFolder, and Description columns:

dax_measures = model.dax_measures
print(dax_measures)

Calculated Columns

To access calculated column DAX expressions in a dataframe with TableName,ColumnName and Expression columns:

dax_columns = model.dax_columns
print(dax_columns)

Schema

To get details about the data model schema and column types in a dataframe with TableName, ColumnName, and PandasDataType columns:

schema = model.schema
print(schema)

Relationships

To get the details about the data model relationships in a dataframe with FromTableName, FromColumnName, ToTableName, ToColumnName, IsActive, Cardinality, CrossFilteringBehavior, FromKeyCount, ToKeyCount and RelyOnReferentialIntegrity columns:

relationships = model.relationships
print(relationships)

Row-Level Security (RLS)

To get the details about Row-Level Security roles and permissions in a dataframe with TableName, RoleName, RoleDescription, FilterExpression, State and MetadataPermission columns:

rls = model.rls
print(rls)

Get Table Contents

To retrieve the contents of a specified table:

table_name = 'YourTableName'
table_contents = model.get_table(table_name)
print(table_contents)

To decode only a subset of columns from a wide table (decoding the others is skipped), pass columns:

table_contents = model.get_table(table_name, columns=['ProductKey', 'Sales'])

Dictionary decode runs on a native Huffman kernel (xmhuffman) and fans out across cores automatically for large dictionaries.

Statistics

To get statistics about the model, including column cardinality and byte sizes of dictionary, hash index, and data components, in a dataframe with columns TableName, ColumnName, Cardinality, Dictionary, HashIndex, and DataSize:

statistics = model.statistics
print(statistics)

Connections

Reports expose their Connections manifest — the list of data connections declared by the report — as a list of dictionaries:

print(model.connections)

Self-contained (import) models usually return an empty list.

Live-connection (thin) reports

Some .pbix files are thin reports with no embedded model: they live-connect to an external Analysis Services server (analysisServicesDatabaseLive) or a Power BI Service dataset (pbiServiceLive). Because the model lives on a remote server, there is nothing to extract on disk, and constructing PBIXRay raises LiveConnectionError. The exception carries the parsed connection details so you can still identify what the report points at:

from pbixray import PBIXRay, LiveConnectionError, NoEmbeddedModelError

try:
    model = PBIXRay("thin-report.pbix")
except LiveConnectionError as e:
    print(e.connection_type)   # e.g. 'pbiServiceLive'
    print(e.database_name)     # remote dataset id, when available
    print(e.connections)       # full manifest (list of dicts)

The exception hierarchy is LiveConnectionError → NoEmbeddedModelError → PBIXRayError. NoEmbeddedModelError is raised when a file has no model and no connection manifest. Both also subclass RuntimeError for backward compatibility.

Tabular Model Schema (TMSCHEMA) Endpoints

Full equivalents of the Analysis Services $System.TMSCHEMA_* DMVs, read directly from the embedded SQLite metadata database.

# Example — list all columns with their tables
print(model.tmschema_columns[["TableName", "Name", "DataType", "IsHidden"]])

# Example — inspect incremental refresh policies
print(model.tmschema_refresh_policies)

# Example — list all security roles and their members
print(model.tmschema_role_memberships)

Roadmap

Planned optimizations for very large models (Arrow output, direct zip-member mmap, RecordBatch streaming) are tracked in ROADMAP.md.