execute_sql
Execute a PerfettoSQL query on a loaded trace to return columnar JSON results. Use for custom aggregations and joins not covered by dedicated tools.
Instructions
Run a PerfettoSQL query against the loaded trace and return rows as columnar JSON. Read-only against trace data; SQLite operates in-memory per session. Aggregates are strongly preferred over raw row data; results are capped at 5000 rows.
Use when: composing analyses not covered by the dedicated tools — custom aggregations, joins across stdlib modules, or queries against base tables (slice, thread, process, sched).
Don't use for: questions the dedicated chrome_* tools answer — they return the same data with the JOIN shape already correct. Don't hand-roll slice scans with LIKE '%x%' patterns when a stdlib module covers the data; INCLUDE PERFETTO MODULE chrome.tasks is faster and the joins are pre-baked.
Parameters: sql is a single PerfettoSQL statement (the INCLUDE PERFETTO MODULE foo; and SELECT ... can be in the same call). Requires load_trace to have run first.
Empty rows means the query matched nothing — distinct from a SQL error, which is returned as an error string with a hint pointing at the most likely cause (missing module, missing column, missing table).
Reference docs (fetch when you need exact column names or function signatures): https://perfetto.dev/docs/analysis/stdlib-docs (24 stdlib packages — chrome / android / sched / slices / linux / wattson / v8 / ...; use per-package anchors like #package-chrome), https://perfetto.dev/docs/analysis/perfetto-sql-syntax (syntax).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to execute (PerfettoSQL syntax). |