Skip to content

Commit 3e2751d

Browse files
authored
feat: improve SQL analyze scan diagnostics (#9565)
* feat: improve SQL analyze scan diagnostics Signed-off-by: evenyag <[email protected]> * test: redact dynamic filters in sqlness results Signed-off-by: evenyag <[email protected]> * test: stabilize analyze snapshots for merge queue Signed-off-by: evenyag <[email protected]> * test: remove obsolete scan_details assertion Signed-off-by: evenyag <[email protected]> * test: refresh explain snapshots after partition filter changes Signed-off-by: evenyag <[email protected]> --------- Signed-off-by: evenyag <[email protected]>
1 parent 4645ab9 commit 3e2751d

95 files changed

Lines changed: 1169 additions & 396 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/mito2/src/read/scan_region.rs‎

Lines changed: 124 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1964,6 +1964,41 @@ pub(crate) fn exact_sequence_range(
19641964
Ok((files, sequence_range))
19651965
}
19661966

1967+
/// Metadata totals for distinct SST files, not post-filter rows or actual read bytes.
1968+
/// Older files may have unknown row and row-group counts represented by zero.
1969+
#[derive(Default, serde::Serialize)]
1970+
struct FileSummary {
1971+
files: usize,
1972+
rows: u64,
1973+
row_groups: u64,
1974+
size: u64,
1975+
index_size: u64,
1976+
}
1977+
1978+
impl FileSummary {
1979+
fn new<'a>(files: impl IntoIterator<Item = &'a FileHandle>) -> Self {
1980+
let mut summary = Self::default();
1981+
for file in files {
1982+
summary.files += 1;
1983+
summary.rows += file.meta_ref().num_rows;
1984+
summary.row_groups += file.meta_ref().num_row_groups;
1985+
summary.size += file.size();
1986+
summary.index_size += file.index_size();
1987+
}
1988+
summary
1989+
}
1990+
}
1991+
1992+
/// Keeps the existing debug-list spacing while escaping strings as JSON, including
1993+
/// control characters for which Rust's Debug escaping is not valid JSON.
1994+
struct ExplainString<'a>(&'a str);
1995+
1996+
impl fmt::Debug for ExplainString<'_> {
1997+
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1998+
f.write_str(&serde_json::to_string(self.0).map_err(|_| fmt::Error)?)
1999+
}
2000+
}
2001+
19672002
/// Context shared by different streams from a scanner.
19682003
/// It contains the input and ranges to scan.
19692004
pub struct StreamContext {
@@ -2064,13 +2099,102 @@ impl StreamContext {
20642099
write!(f, ", \"distribution\":\"{}\"", distribution)?;
20652100
}
20662101

2102+
self.format_scan_details(f)?;
20672103
if verbose {
20682104
self.format_verbose_content(f)?;
20692105
}
20702106

20712107
Ok(())
20722108
}
20732109

2110+
fn format_scan_details(&self, f: &mut fmt::Formatter) -> fmt::Result {
2111+
let output_schema = self.input.mapper.output_schema();
2112+
if !output_schema.is_empty() {
2113+
write!(f, ", \"projection\": ")?;
2114+
f.debug_list()
2115+
.entries(
2116+
output_schema
2117+
.column_schemas()
2118+
.iter()
2119+
.map(|col| ExplainString(&col.name)),
2120+
)
2121+
.finish()?;
2122+
}
2123+
if let Some(predicate) = self.input.predicate.predicate() {
2124+
if !predicate.exprs().is_empty() {
2125+
let exprs: Vec<_> = predicate.exprs().iter().map(|e| e.to_string()).collect();
2126+
write!(f, ", \"filters\": ")?;
2127+
f.debug_list()
2128+
.entries(exprs.iter().map(|e| ExplainString(e)))
2129+
.finish()?;
2130+
}
2131+
if !predicate.dyn_filters().is_empty() {
2132+
let filters: Vec<_> = predicate
2133+
.dyn_filters()
2134+
.iter()
2135+
.map(|filter| filter.to_string())
2136+
.collect();
2137+
write!(f, ", \"dyn_filters\": ")?;
2138+
f.debug_list()
2139+
.entries(filters.iter().map(|filter| ExplainString(filter)))
2140+
.finish()?;
2141+
}
2142+
}
2143+
if let Some(time_range) = &self.input.time_range {
2144+
write!(
2145+
f,
2146+
", \"time_range\": {:?}",
2147+
ExplainString(&time_range.to_string())
2148+
)?;
2149+
}
2150+
let summary = FileSummary::new(&self.input.files);
2151+
write!(
2152+
f,
2153+
", \"file_summary\": {}",
2154+
serde_json::to_string(&summary).map_err(|_| fmt::Error)?
2155+
)?;
2156+
2157+
// Source indices are unique within a range even when a file is split into
2158+
// row groups. Memtables and extension sources must not count as files.
2159+
let file_offset = self.input.num_memtables();
2160+
let file_end = file_offset + self.input.num_files();
2161+
let mut max_range = None;
2162+
let mut max_files = 0;
2163+
for range in &self.ranges {
2164+
let files = range
2165+
.indices
2166+
.iter()
2167+
.filter(|source| (file_offset..file_end).contains(&source.index))
2168+
.count();
2169+
if files > max_files {
2170+
max_files = files;
2171+
max_range = Some(range);
2172+
}
2173+
}
2174+
if let Some(range) = max_range {
2175+
let summary = FileSummary::new(range.indices.iter().filter_map(|source| {
2176+
source
2177+
.index
2178+
.checked_sub(file_offset)
2179+
.and_then(|index| self.input.files.get(index))
2180+
}));
2181+
let (start, end) = range.time_range;
2182+
// RangeMeta bounds are inclusive, just like the verbose file list.
2183+
let summary = serde_json::json!({
2184+
"time_range_start": format!("{}::{}", start.value(), start.unit()),
2185+
"time_range_end": format!("{}::{}", end.value(), end.unit()),
2186+
"files": summary.files,
2187+
"rows": summary.rows,
2188+
"row_groups": summary.row_groups,
2189+
"size": summary.size,
2190+
"index_size": summary.index_size,
2191+
"estimated_rows": range.num_rows,
2192+
});
2193+
write!(f, ", \"max_part_range\": {summary}")?;
2194+
}
2195+
Ok(())
2196+
}
2197+
20742198
fn format_verbose_content(&self, f: &mut fmt::Formatter) -> fmt::Result {
20752199
struct FileWrapper<'a> {
20762200
file: &'a FileHandle,
@@ -2118,30 +2242,6 @@ impl StreamContext {
21182242

21192243
impl fmt::Debug for InputWrapper<'_> {
21202244
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2121-
let output_schema = self.input.mapper.output_schema();
2122-
if !output_schema.is_empty() {
2123-
let names: Vec<_> = output_schema
2124-
.column_schemas()
2125-
.iter()
2126-
.map(|col| &col.name)
2127-
.collect();
2128-
write!(f, ", \"projection\": {:?}", names)?;
2129-
}
2130-
if let Some(predicate) = &self.input.predicate.predicate() {
2131-
if !predicate.exprs().is_empty() {
2132-
let exprs: Vec<_> =
2133-
predicate.exprs().iter().map(|e| e.to_string()).collect();
2134-
write!(f, ", \"filters\": {:?}", exprs)?;
2135-
}
2136-
if !predicate.dyn_filters().is_empty() {
2137-
let dyn_filters: Vec<_> = predicate
2138-
.dyn_filters()
2139-
.iter()
2140-
.map(|f| format!("{}", f))
2141-
.collect();
2142-
write!(f, ", \"dyn_filters\": {:?}", dyn_filters)?;
2143-
}
2144-
}
21452245
if !self.input.files.is_empty() {
21462246
write!(f, ", \"files\": ")?;
21472247
f.debug_list()

‎tests-integration/tests/http.rs‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ macro_rules! http_tests {
163163
test_http_auth,
164164
test_sql_api,
165165
test_http_analyze_stream_tql,
166+
test_http_analyze_stream_scan_diagnostics,
166167
test_http_sql_slow_query,
167168
test_prometheus_promql_api,
168169
test_promql_over_non_millisecond_physical_tables,
@@ -1338,6 +1339,133 @@ async fn test_sql_format_api() {
13381339
guard.remove_all().await;
13391340
}
13401341

1342+
pub async fn test_http_analyze_stream_scan_diagnostics(store_type: StorageType) {
1343+
// Check both levels of JSON: the analyze node schema and the verbose scan
1344+
// object inside its string-valued `param`.
1345+
fn scan_details(node: &Value, scans: &mut Vec<Value>) {
1346+
assert!(node["name"].is_string());
1347+
assert!(node["param"].is_string());
1348+
assert!(node["output_rows"].is_u64());
1349+
assert!(node["elapsed_compute"].is_u64());
1350+
assert!(node["metrics"].is_object());
1351+
if matches!(
1352+
node["name"].as_str(),
1353+
Some("SeqScan" | "UnorderedScan" | "SeriesScan")
1354+
) {
1355+
let (_, fields) = node["param"].as_str().unwrap().split_once("), ").unwrap();
1356+
let fields = if fields.starts_with('{') {
1357+
fields.to_string()
1358+
} else {
1359+
format!("{{{fields}}}")
1360+
};
1361+
let details: Value = serde_json::from_str(&fields).unwrap();
1362+
assert_eq!(details["projection"], json!(["reading", "ts"]));
1363+
assert!(
1364+
details["filters"]
1365+
.as_array()
1366+
.is_some_and(|filters| !filters.is_empty())
1367+
);
1368+
assert_eq!(details["time_range"], "TimestampRange{[0ms,6000ms)}");
1369+
assert_eq!(details["file_summary"]["files"], 2);
1370+
assert_eq!(details["file_summary"]["rows"], 4);
1371+
assert_eq!(details["file_summary"]["row_groups"], 2);
1372+
assert_eq!(details["max_part_range"]["files"], 2);
1373+
assert!(details["max_part_range"].get("identifier").is_none());
1374+
scans.push(details);
1375+
}
1376+
for child in node["children"].as_array().unwrap() {
1377+
scan_details(child, scans);
1378+
}
1379+
}
1380+
fn assert_verbose(scans: &[Value]) {
1381+
assert!(!scans.is_empty());
1382+
for scan in scans {
1383+
let files = scan["files"].as_array().unwrap();
1384+
assert_eq!(files.len(), 2);
1385+
for key in ["rows", "size", "index_size"] {
1386+
assert_eq!(
1387+
scan["file_summary"][key],
1388+
files
1389+
.iter()
1390+
.map(|file| file[key].as_u64().unwrap())
1391+
.sum::<u64>()
1392+
);
1393+
}
1394+
}
1395+
}
1396+
1397+
let (app, mut guard) = setup_test_http_app_with_frontend(store_type, "scan_diagnostics").await;
1398+
let client = TestClient::new(app).await;
1399+
for sql in [
1400+
"CREATE TABLE scan_diagnostics (host STRING PRIMARY KEY, reading DOUBLE, ts TIMESTAMP TIME INDEX)",
1401+
"INSERT INTO scan_diagnostics VALUES ('a', 1, 0), ('b', 2, 3000)",
1402+
"ADMIN FLUSH_TABLE('scan_diagnostics')",
1403+
"INSERT INTO scan_diagnostics VALUES ('c', 3, 2000), ('d', 4, 5000)",
1404+
"ADMIN FLUSH_TABLE('scan_diagnostics')",
1405+
"INSERT INTO scan_diagnostics VALUES ('outside', 5, 10000)",
1406+
"ADMIN FLUSH_TABLE('scan_diagnostics')",
1407+
"INSERT INTO scan_diagnostics VALUES ('mem', 6, 1000)",
1408+
] {
1409+
let response = execute_sql(&client, sql).await;
1410+
let status = response.status();
1411+
let body = response.text().await;
1412+
assert_eq!(status, StatusCode::OK, "{sql}: {body}");
1413+
let body: Value = serde_json::from_str(&body).unwrap();
1414+
assert!(body.get("error").is_none(), "{body}");
1415+
}
1416+
let query = "SELECT reading, ts FROM scan_diagnostics WHERE ts >= 0 AND ts < 6000";
1417+
let sql = format!("EXPLAIN ANALYZE FORMAT JSON {query}");
1418+
let response = execute_sql(&client, &sql).await;
1419+
let status = response.status();
1420+
let body = response.text().await;
1421+
assert_eq!(status, StatusCode::OK, "{body}");
1422+
let body: Value = serde_json::from_str(&body).unwrap();
1423+
let mut explain_scans = vec![];
1424+
for row in body["output"][0]["records"]["rows"].as_array().unwrap() {
1425+
if row[0].is_null() {
1426+
assert_eq!(row[2], "Total rows: 5");
1427+
continue;
1428+
}
1429+
let plan: Value = serde_json::from_str(row[2].as_str().unwrap()).unwrap();
1430+
scan_details(&plan, &mut explain_scans);
1431+
}
1432+
assert!(!explain_scans.is_empty());
1433+
assert!(explain_scans.iter().all(|scan| scan.get("files").is_none()));
1434+
1435+
let sql = format!("EXPLAIN ANALYZE VERBOSE FORMAT JSON {query}");
1436+
let response = client
1437+
.post("/v1/sql/analyze/stream?snapshot_interval_ms=100")
1438+
.header("Accept", "text/event-stream")
1439+
.form(&BTreeMap::from([("sql", sql)]))
1440+
.send()
1441+
.await;
1442+
assert_eq!(response.status(), StatusCode::OK);
1443+
let body = response.text().await;
1444+
let mut first_scan_seen = false;
1445+
let mut final_seen = false;
1446+
for event in body.split("\n\n") {
1447+
let Some(data) = event.lines().find_map(|line| line.strip_prefix("data: ")) else {
1448+
continue;
1449+
};
1450+
let payload: Value = serde_json::from_str(data).unwrap();
1451+
let mut scans = vec![];
1452+
for stage in payload["metrics"].as_array().unwrap() {
1453+
assert!(stage["stage"].is_u64());
1454+
assert!(stage["node"].is_u64());
1455+
scan_details(&stage["plan"], &mut scans);
1456+
}
1457+
// Every available scan is checked, including its first appearance. A fast
1458+
// query may finish before the first periodic snapshot.
1459+
first_scan_seen |= !scans.is_empty();
1460+
if payload["state"] == "final" {
1461+
assert_verbose(&scans);
1462+
final_seen = true;
1463+
}
1464+
}
1465+
assert!(first_scan_seen && final_seen, "{body}");
1466+
guard.remove_all().await;
1467+
}
1468+
13411469
pub async fn test_http_analyze_stream_tql(store_type: StorageType) {
13421470
common_telemetry::init_default_ut_logging();
13431471
let (app, mut guard) =

‎tests/cases/distributed/explain/analyze.result‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ SELECT count(*) FROM system_metrics;
3333
-- SQLNESS REPLACE (\s\s+) _
3434
-- SQLNESS REPLACE (peers.*) REDACTED
3535
-- SQLNESS REPLACE region=\d+\(\d+,\s+\d+\) region=REDACTED
36+
-- SQLNESS REPLACE \\?"(dyn_filters|time_range|file_summary|max_part_range)\\?":.* "$1":REDACTED
3637
explain analyze SELECT count(*) FROM system_metrics;
3738

3839
+-+-+-+
@@ -45,7 +46,7 @@ explain analyze SELECT count(*) FROM system_metrics;
4546
|_|_|_AggregateExec: mode=Final, gby=[], aggr=[count(system_REDACTED
4647
|_|_|_CoalescePartitionsExec REDACTED
4748
|_|_|_AggregateExec: mode=Partial, gby=[], aggr=[count(system_REDACTED
48-
|_|_|_SeqScan: region=REDACTED, "partition_count":{"count":1, "mem_ranges":1, "files":0, "file_ranges":0} REDACTED
49+
|_|_|_SeqScan: region=REDACTED, "partition_count":{"count":1, "mem_ranges":1, "files":0, "file_ranges":0}, "projection": ["ts"], "time_range":REDACTED
4950
|_|_|_|
5051
|_|_| Total rows: 1_|
5152
+-+-+-+

‎tests/cases/distributed/explain/analyze.sql‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ SELECT count(*) FROM system_metrics;
2323
-- SQLNESS REPLACE (\s\s+) _
2424
-- SQLNESS REPLACE (peers.*) REDACTED
2525
-- SQLNESS REPLACE region=\d+\(\d+,\s+\d+\) region=REDACTED
26+
-- SQLNESS REPLACE \\?"(dyn_filters|time_range|file_summary|max_part_range)\\?":.* "$1":REDACTED
2627
explain analyze SELECT count(*) FROM system_metrics;
2728

2829
drop table system_metrics;

‎tests/cases/distributed/explain/order_by.result‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ SELECT i, t AS alias_ts FROM test_pk ORDER BY alias_ts DESC LIMIT 5;
116116
-- SQLNESS REPLACE (metrics.*) REDACTED
117117
-- SQLNESS REPLACE region=\d+\(\d+,\s+\d+\) region=REDACTED
118118
-- SQLNESS REPLACE num_ranges=\d+ num_ranges=REDACTED
119+
-- SQLNESS REPLACE \\?"(dyn_filters|time_range|file_summary|max_part_range)\\?":.* "$1":REDACTED
119120
EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY t DESC LIMIT 5;
120121

121122
+-+-+-+
@@ -127,7 +128,7 @@ EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY t DESC LIMIT 5;
127128
| 1_| 0_|_ProjectionExec: expr=[i@0 as i, t@1 as alias_ts] REDACTED
128129
|_|_|_SortPreservingMergeExec: [t@1 DESC], fetch=5 REDACTED
129130
|_|_|_SortExec: TopK(fetch=5), expr=[t@1 DESC], preserve_partitioning=[true], filter=[t@1 IS NULL OR t@1 > 2] REDACTED
130-
|_|_|_SeqScan: region=REDACTED, "partition_count":{"count":1, "mem_ranges":1, "files":0, "file_ranges":0} REDACTED
131+
|_|_|_SeqScan: region=REDACTED, "partition_count":{"count":1, "mem_ranges":1, "files":0, "file_ranges":0}, "projection": ["i", "t"], "dyn_filters":REDACTED
131132
|_|_|_|
132133
|_|_| Total rows: 5_|
133134
+-+-+-+
@@ -138,6 +139,7 @@ EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY t DESC LIMIT 5;
138139
-- SQLNESS REPLACE (metrics.*) REDACTED
139140
-- SQLNESS REPLACE region=\d+\(\d+,\s+\d+\) region=REDACTED
140141
-- SQLNESS REPLACE num_ranges=\d+ num_ranges=REDACTED
142+
-- SQLNESS REPLACE \\?"(dyn_filters|time_range|file_summary|max_part_range)\\?":.* "$1":REDACTED
141143
EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY alias_ts DESC LIMIT 5;
142144

143145
+-+-+-+
@@ -149,7 +151,7 @@ EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY alias_ts DESC LIMI
149151
| 1_| 0_|_ProjectionExec: expr=[i@0 as i, t@1 as alias_ts] REDACTED
150152
|_|_|_SortPreservingMergeExec: [t@1 DESC], fetch=5 REDACTED
151153
|_|_|_SortExec: TopK(fetch=5), expr=[t@1 DESC], preserve_partitioning=[true], filter=[t@1 IS NULL OR t@1 > 2] REDACTED
152-
|_|_|_SeqScan: region=REDACTED, "partition_count":{"count":1, "mem_ranges":1, "files":0, "file_ranges":0} REDACTED
154+
|_|_|_SeqScan: region=REDACTED, "partition_count":{"count":1, "mem_ranges":1, "files":0, "file_ranges":0}, "projection": ["i", "t"], "dyn_filters":REDACTED
153155
|_|_|_|
154156
|_|_| Total rows: 5_|
155157
+-+-+-+

‎tests/cases/distributed/explain/order_by.sql‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ SELECT i, t AS alias_ts FROM test_pk ORDER BY alias_ts DESC LIMIT 5;
4444
-- SQLNESS REPLACE (metrics.*) REDACTED
4545
-- SQLNESS REPLACE region=\d+\(\d+,\s+\d+\) region=REDACTED
4646
-- SQLNESS REPLACE num_ranges=\d+ num_ranges=REDACTED
47+
-- SQLNESS REPLACE \\?"(dyn_filters|time_range|file_summary|max_part_range)\\?":.* "$1":REDACTED
4748
EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY t DESC LIMIT 5;
4849

4950
-- SQLNESS REPLACE (-+) -
@@ -52,6 +53,7 @@ EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY t DESC LIMIT 5;
5253
-- SQLNESS REPLACE (metrics.*) REDACTED
5354
-- SQLNESS REPLACE region=\d+\(\d+,\s+\d+\) region=REDACTED
5455
-- SQLNESS REPLACE num_ranges=\d+ num_ranges=REDACTED
56+
-- SQLNESS REPLACE \\?"(dyn_filters|time_range|file_summary|max_part_range)\\?":.* "$1":REDACTED
5557
EXPLAIN ANALYZE SELECT i, t AS alias_ts FROM test_pk ORDER BY alias_ts DESC LIMIT 5;
5658

5759
DROP TABLE test_pk;

0 commit comments

Comments
 (0)