Skip to content

Conversation

@guillesd
Copy link
Collaborator

@guillesd guillesd commented Oct 22, 2025

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
PRAGMA enable_profiling = 'json';
PRAGMA profiling_output = './tmp/profile.json';
SELECT ... FROM ...;
  1. Run the script (I do it with uv):
uv run -m duckdb.query_graph --profile_input profile.json

If you want to use the profiling within the client:

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:

# 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:
Screenshot 2026-01-09 at 11 09 21
Screenshot 2026-01-09 at 11 09 44
Screenshot 2026-01-09 at 11 10 05

@guillesd guillesd marked this pull request as draft October 22, 2025 15:19
@guillesd guillesd changed the title [DRAFT] refactor query graph to make it more useful [DRAFT] refactor query graph and enable profiling for a connection Oct 24, 2025
@evertlammerts evertlammerts changed the base branch from main to v1.5-variegata January 9, 2026 10:15
@guillesd guillesd changed the title [DRAFT] refactor query graph and enable profiling for a connection refactor query graph and enable profiling for a connection Jan 9, 2026
@guillesd guillesd marked this pull request as ready for review January 9, 2026 10:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant