Skip to content

Quick start

Basic Functionality#

This basic example tests that your PowerBI report can be parsed and reassembled by pbi_core. 

1
2
3
4
from pbi_core import LocalReport

report = LocalReport.load_pbix("example.pbix")  # (1)!
report.save_pbix("example_out.pbix")  # (1)!

Common Issue

One of the current limitations in the pbi_core library is the incomplete pydantic typing of the Layout file. This generally appears as a message like: 

pydantic_core._pydantic_core.ValidationError: 2 validation errors for Layout
sections.0.visualContainers.1.config.singleVisual.TableChart.objects.columnHeaders.0.properties.underline
Extra inputs are not permitted [type=extra_forbidden, input_value={'expr': {'Literal': {'Value': 'true'}}}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/extra_forbidden
sections.0.visualContainers.1.config.singleVisual.TableChart.objects.values.0.properties.underline
Extra inputs are not permitted [type=extra_forbidden, input_value={'expr': {'Literal': {'Value': 'true'}}}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/extra_forbidden

If you encounter an error message like this, please do the following:

  1. Create an issue on the Github page with the error message. If you're able, attaching a pbix file will make the fix quicker and can be added to the test suite to ensure the issue doesn't re-appear in future versions
  2. Add --allow-extra to your python call. This will tell Pydantic to include extra arguments as standard JSON lists/dicts/strings/ints

Altering Data model#

This example shows how you can add automatic descriptions to PowerBI columns (possibly from some governance tool??)

1
2
3
4
5
6
7
8
from pbi_core import LocalReport

report = LocalReport.load_pbix("example.pbix")
for column in report.ssas.columns:
    column.description = "pbi_core has touched this"
    column.alter()  # saves the changes to the SSAS DB

report.save_pbix("example_out.pbix")

Finding records in SSAS tables#

This example shows how to find SSAS records and extract data from report columns

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from pbi_core import LocalReport

report = LocalReport.load_pbix("example.pbix")
values = report.ssas.columns.find({"explicit_name": "a"}).data()
print(values)
values2 = report.ssas.tables.find({"name": "Table"}).data()
print(values2)

measure = report.ssas.measures.find({"name": "Measure"})
column = measure.table().columns()[1]  
# Note: the first column is a hidden row-count column that can't be used in measures
values3 = measure.data(column, head=10)
print(values3)

pbi_core Lineage Chart#

This example displays a lineage chart in HTML:

1
2
3
4
5
from pbi_core import LocalReport

report = LocalReport.load_pbix("example.pbix", kill_ssas_on_exit=True)
col = report.ssas.columns.find({"explicit_name": "MeasureColumn"})
col.get_lineage("parents").to_mermaid().show()

Improved Multilanguage Support#

This example displays the ability to easily convert PBIX reports to alternate languages:

1
2
3
4
5
6
7
8
from pbi_core import LocalReport
from pbi_core.misc.internationalization import get_static_elements, set_static_elements

report = LocalReport.load_pbix("example.pbix", kill_ssas_on_exit=True)
x = get_static_elements(report.static_files.layout)
x.to_excel("multilang.xlsx")

set_static_elements("multilang1.xlsx", "example.pbix")

Automatic Data Model Cleaning#

One of the core tensions in PowerBI is the size of the data model. In development, you want to have many measures, columns, and tables to simplify new visual creation. After developing the report, the additional elements create two issues:

  1. It's difficult to understand which elements are being used and how they relate to each other
  2. The additional columns and tables can slow down visual rendering times, negatively impacting UX

pbi_core has an automatic element culler that allows you to remove unnecessary elements after the report has been designed:

1
2
3
4
5
from pbi_core import LocalReport

report = LocalReport.load_pbix("example_pbis/api.pbix")
report.cleanse_ssas_model()
report.save_pbix("cull_out.pbix")

Performance Analysis#

This example shows how to analyze the performance of a Power BI report's visual:

Warning

In the current implementation, the performance trace occassionally hangs. If this happens, you can kill the process and restart it. This is a known issue that will be fixed in a future release.

1
2
3
4
5
6
7
8
from pbi_core import LocalReport

report = LocalReport.load_pbix("example_pbis/example_section_visibility.pbix")
# x = report.static_files.layout.sections[0].visualContainers[0].get_performance(report.ssas)
x = report.static_files.layout.sections[0].get_performance(report.ssas)
print(x)
print("=================")
print(x[0].pprint())

Which generates the following output.

2025-07-05 14:07:31 [info     ] Loading PBIX                   path=example_pbis/example_section_visibility.pbix
2025-07-05 14:07:33 [warning  ] Removing old version of PBIX data model for new version db_name=example_section_visibility
2025-07-05 14:07:33 [info     ] Tabular Model load complete   
2025-07-05 14:07:35 [info     ] Beginning trace               
2025-07-05 14:07:38 [info     ] Running DAX commands          
2025-07-05 14:07:41 [info     ] Terminating trace             
[Performance(rows=5, total_duration=0.0, total_cpu_time=0.0, peak_consumption=1.0 MiB]
=================
Performance(
    Command:

        DEFINE VAR __DS0Core =
                SUMMARIZECOLUMNS('example'[b], "Suma", CALCULATE(SUM('example'[a])))

        EVALUATE
                __DS0Core

    Start Time: 2025-07-05T19:07:38.450000+00:00
    End Time: 2025-07-05T19:07:38.453000+00:00
    Total Duration: 4 ms
    Total CPU Time: 0 ms
    Query CPU Time: 0 ms
    Vertipaq CPU Time: 0 ms
    Execution Delay: 0 ms
    Approximate Peak Consumption: 1.0 MiB
    Rows Returned: 5
)

Styling Layout Elements#

This example shows how to apply style changes to elements in a PowerBI report globally. This ensures consistent styling and protects hands from carpal tunnel.

Alternate Selection Methods

We also included two alternate methods of finding elements on lines 8 and 9. You can pass dictionaries of attribute/value pairs or a function returning a boolean and only elements matching those will return. One downside of these methods in this case is that Slicer is a more specific type than BaseVisual. The return of the find_all method returns list[<input type>], so the more specific type of Slicer will provide better autocompletion if your IDE supports it. For instance, the Slicer class knows there's an objects attribute and it's children, but the BaseVisual doesn't.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from pbi_core import LocalReport
from pbi_core.static_files.layout.visuals.properties.base import SolidColorExpression
from pbi_core.static_files.layout.visuals.slicer import Slicer

report = LocalReport.load_pbix("example_pbis/api.pbix", load_ssas=False, load_static_files=True)
slicers = report.static_files.layout.find_all(Slicer)
# from pbi_core.static_files.layout.visuals.base import BaseVisual
# slicers = report.static_files.layout.find_all(BaseVisual, {"visualType": "slicer"})
# slicers = report.static_files.layout.find_all(BaseVisual, lambda v: v.visualType == "slicer")
for s in slicers:
    new_color = SolidColorExpression.from_hex("#FF0000")
    s.objects.header[0].properties.fontColor = new_color
    s.objects.items[0].properties.fontColor = new_color
report.save_pbix("example_out.pbix")