bintel-05-reporting

Professional Python project: OLAP reporting on smart sales data.

Project Description

This project focuses on querying a DuckDB data warehouse using OLAP operations to generate business intelligence reports.

The project includes a pre-populated data warehouse used for the example. For your custom project, you are encouraged to use the warehouse you created in the earlier project. You can use this one if challenges remain with the earlier project.

We learn to:

• connect to a DuckDB data warehouse for reporting
• create a reporting-ready dataset from fact and dimension tables
• slice data by selecting one value from a dimension
• dice data by selecting values across multiple dimensions
• roll up detailed data into broader summaries
• drill down from summary values to quarterly and monthly detail
• visualize OLAP results with clear business charts
• explore the same OLAP concepts using Power BI or Apache Spark

Working Files

You'll work with these areas:

• artifacts/ - generated duckdb warehouse
• data/reporting/ - reporting-ready data generated by the example
• docs/ - project narrative and documentation
• src/bizintel/ - the app is an example; run only (no need to modify)
• pyproject.toml - update authorship & links
• zensical.toml - update authorship & links

Reporting (Operating System Specific)

All run the DuckDB OLAP example:

uv run python -m bizintel.olap_case

Then, follow the path by operating system:

• Windows: Load the generated reporting data into Power BI Desktop.
• macOS or Linux: Run the Apache Spark OLAP example.
• see more information below

Instructions (pro-analytics-02)

Follow the step-by-step workflow guide to complete:

1. Phase 1. Start & Run
2. Phase 2. Change Authorship
3. Phase 3. Read & Understand
4. Phase 4. Modify
5. Phase 5. Apply

Challenges

Challenges are expected. Sometimes instructions may not quite match your operating system. When issues occur, share screenshots, error messages, and details about what you tried. Working through issues is part of implementing professional projects.

Success

After completing Phase 1. Start & Run, you'll have your own GitHub project, and running the example module will print out:

========================
Executed successfully!
========================

A new file project.log will appear in the root project folder.

Command Reference

Show command reference

In a machine terminal (open in your Repos folder)

After you get a copy of this repo in your own GitHub account, open a machine terminal in your Repos folder:

# Replace username with YOUR GitHub username.
git clone https://github.com/username/bintel-05-reporting

cd bintel-05-reporting
code .

In a VS Code terminal

These are listed for convenience. For best results, follow the detailed instructions in pro-analytics-02 guide.

uv self update
uv python pin 3.14
uv lock --upgrade
uv sync --extra dev --extra docs --upgrade

uvx pre-commit install
uvx pre-commit autoupdate

git add -A
uvx pre-commit run --all-files
# repeat if changes were made
uvx pre-commit run --all-files

# OPTIONAL: run the main pipeline app
# This has been adjusted to call the functions
# from this module...we'll do this again later.
uv run python -m bizintel.app_case

# PART 1. EVERYONE: run the DuckDB OLAP reporting example
uv run python -m bizintel.olap_case

# PART 2. macOS or Linux: run the Spark OLAP example
#  1.  Add PySpark with Spark SQL support dependency
uv add "pyspark[sql]"
#  2. Restore the environment
uv sync --extra dev --extra docs --upgrade
#  3. Run the spark example
uv run python -m bizintel.olap_spark_case

# PART 2. Windows: use Power BI Desktop
#  1. Open Power BI Desktop.
#  2. Select Home > Get data > Text/CSV.
#  3. Browse to your chosen file: e.g., for the example: data/reporting/sales_reporting_case.csv
#  4. Select Open.
#  5. Review the data preview, and then select Load.

# run common chores
uv run ruff format .
uv run ruff check . --fix
uv run python -m pyright
uv run python -m pytest
uv run python -m zensical build

# save progress
git add -A
git commit -m "update"
git push -u origin main

Notes

• Use the UP ARROW and DOWN ARROW in the terminal to scroll through past commands.
• Use CTRL+f to find (and replace) text within a file.
• You do not need to add to or modify tests/. They are provided for example only.
• Many files are silent helpers. Explore as you like, but nothing is required.
• You do NOT need to understand everything; understanding builds naturally over time.

Troubleshooting >>>

If you see something like this in your terminal: >>> or ... You accidentally started Python interactive mode. It happens. Press Ctrl+c (both keys together) or Ctrl+Z then Enter on Windows.

Example Output (Remove this Section after You Verify or Replace with output from your custom project)

| BI | ========================
| BI | SUMMARY
| BI | ========================
| BI | Slice: In East, the leading category is Office ($456,342.94)
| BI | Dice: The strongest selected combination is East / Electronics ($218,291.81)
| BI | Roll-up: Total sales across all years are $3,673,389.85
| BI | Drill-down: The strongest month in 2025 is 2025-05 ($369,056.60)
| BI | ========================
| BI | ANALYST NOTES:
| BI | Use slice to focus on one dimension value.
| BI | Use dice to investigate a selected multidimensional subset.
| BI | Use roll-up to move from detail to broader summaries.
| BI | Use drill-down to investigate the detail behind a summary.
| BI | ========================
| BI | CALL a function to show charts........
| BI | Closed DuckDB connection
| BI | Workflow complete
| BI | CLOSE chart windows to continue.
| BI | Terminate this process with CTRL+c as needed.
| BI | ========================
| BI | Executed successfully!
| BI | ========================

Findings and Visuals

Take screenshots of your charts and provide them here with a discussion. In Markdown, display a figure using: an exclamation mark immediately followed by square brackets containing a useful caption immediately followed by parentheses containing the relative path to your figure.

In your custom project:

• your figures and narrative should reflect your work
• this README.md should include your commands, process, and visuals
• docs/index.md should include your narrative

Replace these placeholders with screenshots from your own project run:

NOTE: These are old visuals. Run the example to generate the correct ones. Save your images to docs/images/ and update the links below.

Project Documentation

Additional project instructions, terms, and notes:

docs/index.md

Citation

CITATION.cff

License

MIT