refactor query graph and enable profiling for a connection (#140)

The idea of this PR is to make this tool a bit more useful (and visually
appealing). I think generally it is good to have some better profiling
tools to explore queries.

**EDIT**: Initially it was only about the query graph visuals, but I
decided to expose the profiling functions enabled in the C++ API
(similar to what the Go client does with the C API).

To use the tool:
1. Build this branch (see
https://duckdb.org/docs/stable/dev/building/python)
2. Run the following in DuckDB
```sql
PRAGMA enable_profiling = 'json';
PRAGMA profiling_output = './tmp/profile.json';
SELECT ... FROM ...;
```
3. Run the script (I do it with uv):
```bash
uv run -m duckdb.query_graph --profile_input profile.json
```

If you want to use the profiling within the client:

```python
import duckdb
from duckdb.query_graph import ProfilingInfo

con = duckdb.connect()
con.enable_profiling()
con.execute("select 42").fetchall() #or some other eager operation
profiling_info = ProfilingInfo(con)

# then the options are
profiling_info.to_json()
profiling_info.to_pydict()
profiling_info.to_html()

# optionally
con.disable_profiling()
```

It is also possible to just provide the profiling info as a file:

```python
# we create profiling info from a file instead of binding it to a connection
profiling_info = ProfilingInfo(from_file = 'profile.json')

# then the stuff
profiling_info.to_html(output_file='profile.html')
```



Which should yield something like the following screenshot:
<img width="1023" height="814" alt="Screenshot 2026-01-09 at 11 09 21"
src="https://github.com/user-attachments/assets/44de8776-18b2-4320-8c90-4b9cfec40cd1"
/>
<img width="993" height="701" alt="Screenshot 2026-01-09 at 11 09 44"
src="https://github.com/user-attachments/assets/d17ffc91-0354-4ed1-824c-b44018be1a74"
/>
<img width="208" height="568" alt="Screenshot 2026-01-09 at 11 10 05"
src="https://github.com/user-attachments/assets/307f5558-9a6e-4c31-b290-a90a84283014"
/>

Author: evertlammerts

.gitignore

@@ -14,6 +14,8 @@
 .sw?
 #OS X specific files.
 .DS_store
+#VSCode specifics
+.vscode/
 
 #==============================================================================#
 # Build artifacts
@@ -45,6 +47,7 @@ cmake-build-release
 cmake-build-relwithdebinfo
 duckdb_packaging/duckdb_version.txt
 test.db
+tmp/
 
 #==============================================================================#
 # Python

_duckdb-stubs/__init__.pyi

@@ -86,9 +86,11 @@ __all__: list[str] = [
     "default_connection",
     "description",
     "df",
+    "disable_profiling",
     "distinct",
     "dtype",
     "duplicate",
+    "enable_profiling",
     "enum_type",
     "execute",
     "executemany",
@@ -109,6 +111,7 @@ __all__: list[str] = [
     "from_df",
     "from_parquet",
     "from_query",
+    "get_profiling_information",
     "get_table_names",
     "install_extension",
     "interrupt",
@@ -313,6 +316,9 @@ class DuckDBPyConnection:
         repository_url: str | None = None,
         version: str | None = None,
     ) -> None: ...
+    def get_profiling_information(self, format: str = "json") -> str: ...
+    def enable_profiling(self) -> None: ...
+    def disable_profiling(self) -> None: ...
     def interrupt(self) -> None: ...
     def list_filesystems(self) -> list[str]: ...
     def list_type(self, type: sqltypes.DuckDBPyType) -> sqltypes.DuckDBPyType: ...
@@ -1250,6 +1256,9 @@ def limit(
     *,
     connection: DuckDBPyConnection | None = None,
 ) -> DuckDBPyRelation: ...
+def get_profiling_information(*, connection: DuckDBPyConnection | None = None, format: str = "json") -> str: ...
+def enable_profiling(*, connection: DuckDBPyConnection | None = None) -> None: ...
+def disable_profiling(*, connection: DuckDBPyConnection | None = None) -> None: ...
 def list_filesystems(*, connection: DuckDBPyConnection | None = None) -> list[str]: ...
 def list_type(
     type: sqltypes.DuckDBPyType, *, connection: DuckDBPyConnection | None = None

duckdb/__init__.py

@@ -84,9 +84,11 @@
     default_connection,
     description,
     df,
+    disable_profiling,
     distinct,
     dtype,
     duplicate,
+    enable_profiling,
     enum_type,
     execute,
     executemany,
@@ -107,6 +109,7 @@
     from_df,
     from_parquet,
     from_query,
+    get_profiling_information,
     get_table_names,
     install_extension,
     interrupt,
@@ -310,9 +313,11 @@
     "default_connection",
     "description",
     "df",
+    "disable_profiling",
     "distinct",
     "dtype",
     "duplicate",
+    "enable_profiling",
     "enum_type",
     "execute",
     "executemany",
@@ -333,6 +338,7 @@
     "from_df",
     "from_parquet",
     "from_query",
+    "get_profiling_information",
     "get_table_names",
     "install_extension",
     "interrupt",

duckdb/query_graph/__init__.py

@@ -0,0 +1,3 @@
+from .__main__ import ProfilingInfo  # noqa: D104
+
+__all__ = ["ProfilingInfo"]