Development
Metrics
The query tree has two types of nodes: the `QUERY_ROOT` and `OPERATOR` nodes.
The `QUERY_ROOT` refers exclusively to the top-level node, and the metrics it contains are measured over the entire query.
The `OPERATOR` nodes refer to the individual operators in the query plan.
Some metrics are only available for `QUERY_ROOT` nodes, while others are only for `OPERATOR` nodes.
The table below describes each metric and which nodes they are available for.  
Other than `QUERY_NAME` and `OPERATOR_TYPE`, it is possible to turn all metrics on or off.  
| Metric                  | Return type |   Unit   | Query | Operator | Description                                                                                                                   |
|-------------------------|-------------|----------|:-----:|:--------:|-------------------------------------------------------------------------------------------------------------------------------|
| `BLOCKED_THREAD_TIME`   | `double`    | seconds  |   ✅  |          | The total time threads are blocked.                                                                                          |
| `EXTRA_INFO`            | `string`    |          |   ✅  |    ✅    | Unique operator metrics.                                                                                                     |
| `LATENCY`               | `double`    | seconds  |   ✅  |          | The total elapsed query execution time.                                                                                      |
| `OPERATOR_CARDINALITY`  | `uint64`    | absolute |       |    ✅    | The cardinality of each operator, i.e., the number of rows it returns to its parent. Operator equivalent of `ROWS_RETURNED`. |
| `OPERATOR_ROWS_SCANNED` | `uint64`    | absolute |       |    ✅    | The total rows scanned by each operator.                                                                                     |
| `OPERATOR_TIMING`       | `double`    | seconds  |       |    ✅    | The time taken by each operator. Operator equivalent of `LATENCY`.                                                           |
| `OPERATOR_TYPE`         | `string`    |          |       |    ✅    | The name of each operator.                                                                                                   |
| `QUERY_NAME`            | `string`    |          |   ✅  |          | The query string.                                                                                                            |
| `RESULT_SET_SIZE`       | `uint64`    |  bytes   |   ✅  |    ✅    | The size of the result.                                                                                                      |
| `ROWS_RETURNED`         | `uint64`    | absolute |   ✅  |          | The number of rows returned by the query.                                                                                    |  
#### Cumulative Metrics {#docs:dev:profiling::cumulative-metrics}  
DuckDB also supports several cumulative metrics that are available in all nodes.
In the `QUERY_ROOT` node, these metrics represent the sum of the corresponding metrics across all operators in the query.
The `OPERATOR` nodes represent the sum of the operator's specific metric and those of all its children recursively.  
These cumulative metrics can be enabled independently, even if the underlying specific metrics are disabled.
The table below shows the cumulative metrics.
It also depicts the metric based on which DuckDB calculates the cumulative metric.  
| Metric                    | Unit     | Metric calculated cumulatively |
|---------------------------|----------|--------------------------------|
| `CPU_TIME`                | seconds  | `OPERATOR_TIMING`              |
| `CUMULATIVE_CARDINALITY`  | absolute | `OPERATOR_CARDINALITY`         |
| `CUMULATIVE_ROWS_SCANNED` | absolute | `OPERATOR_ROWS_SCANNED`        |  
`CPU_TIME` measures the cumulative operator timings.
It does not include time spent in other stages, like parsing, query planning, etc.
Thus, for some queries, the `LATENCY` in the `QUERY_ROOT` can be greater than the `CPU_TIME`.