use serde_json::{json, Map, Value};
use super::notification_wire::notification_fields;
use crate::wire::Notification;
use crate::wire::{plan_node_wire, PlanMetricsWire, PlanNodeWire};
use crate::CypherValue;
pub const SCHEMA: &str = "relate.plan/v1";
pub fn plan_document(
tree: &CypherValue,
statement: Option<&str>,
notifications: &[Notification],
) -> Value {
let totals = crate::wire::plan_subtree_totals(tree);
let warnings_by_operator = operator_warnings(notifications);
let operator_scoped = warnings_by_operator.values().map(Vec::len).sum::<usize>();
let mut joined = 0;
let (root, profiled) = node_json(
&plan_node_wire(tree),
&totals,
&warnings_by_operator,
&mut joined,
);
assert_eq!(
joined, operator_scoped,
"every operator-scoped notification joins exactly one plan node (ADR-0363, ADR-0381): \
{operator_scoped} stamped, {joined} joined"
);
json!({
"schema": SCHEMA,
"profiled": profiled,
"statement": statement,
"root": root,
})
}
fn operator_warnings(notifications: &[Notification]) -> crate::IndexMap<usize, Vec<&Notification>> {
let mut by_operator: crate::IndexMap<usize, Vec<&Notification>> = crate::IndexMap::new();
for notification in notifications {
if let Some(operator_id) = notification.operator_id() {
by_operator
.entry(operator_id)
.or_default()
.push(notification);
}
}
by_operator
}
fn node_json(
node: &PlanNodeWire<'_>,
totals: &crate::IndexMap<i64, i64>,
warnings_by_operator: &crate::IndexMap<usize, Vec<&Notification>>,
joined: &mut usize,
) -> (Value, bool) {
let mut profiled = node.metrics.is_some();
let children: Vec<Value> = node
.children
.iter()
.map(|child| {
let (child_json, child_profiled) =
node_json(&plan_node_wire(child), totals, warnings_by_operator, joined);
profiled |= child_profiled;
child_json
})
.collect();
let loops = node.children.first().and_then(|first| {
plan_node_wire(first)
.metrics
.map(|m| crate::wire::metric_u64(m.rows))
});
let mut out = Map::new();
out.insert("operator".to_string(), json!(node.operator_type));
out.insert("details".to_string(), json!(node.details));
out.insert(
"identifiers".to_string(),
Value::Array(node.identifiers.iter().map(|name| json!(name)).collect()),
);
out.insert("estimated_rows".to_string(), json!(node.estimated_rows));
out.insert(
"actual".to_string(),
match &node.metrics {
Some(metrics) => {
let facts = crate::wire::profiled_facts(*metrics, totals, node.id);
actual_json(&facts.metrics, facts.total_time_ns, loops)
}
None => Value::Null,
},
);
out.insert("children".to_string(), Value::Array(children));
let operator_id = node.operator_id();
let warnings = warnings_by_operator
.get(&operator_id)
.map(Vec::as_slice)
.unwrap_or_default();
*joined += warnings.len();
out.insert(
"warnings".to_string(),
Value::Array(
warnings
.iter()
.map(|notification| Value::Object(notification_fields(notification)))
.collect(),
),
);
(Value::Object(out), profiled)
}
fn actual_json(metrics: &PlanMetricsWire, subtree_ns: i64, loops: Option<u64>) -> Value {
let mut out = Map::new();
out.insert("rows".to_string(), json!(metrics.rows));
out.insert(
"time_ms".to_string(),
json!(crate::wire::time_ns_ms(metrics.time_ns)),
);
out.insert(
"total_time_ms".to_string(),
json!(crate::wire::time_ns_ms(subtree_ns)),
);
out.insert("db_hits".to_string(), json!(metrics.db_hits));
out.insert(
"seek_ms".to_string(),
json!(crate::wire::time_ns_ms(metrics.phases.seek_ns)),
);
out.insert(
"walk_ms".to_string(),
json!(crate::wire::time_ns_ms(metrics.phases.walk_ns)),
);
out.insert("loops".to_string(), json!(loops));
out.insert("memory_bytes".to_string(), json!(metrics.memory_bytes));
out.insert(
"expression_built_bytes".to_string(),
json!(metrics.expression_built_bytes),
);
out.insert("hops".to_string(), json!(metrics.reads.hops));
out.insert(
"neighbor_walks".to_string(),
json!(metrics.reads.neighbor_walks),
);
out.insert("node_reads".to_string(), json!(metrics.reads.node_reads));
out.insert("batched".to_string(), json!(metrics.batched));
out.insert("zone_skips".to_string(), json!(metrics.zone_skips));
out.insert(
"frontier".to_string(),
json!({
"edge_visits": metrics.frontier.edge_visits,
"levels": metrics.frontier.levels,
"endpoints": metrics.frontier.endpoints,
"cells": metrics.frontier.cells,
"memo_hits": metrics.frontier.memo_hits,
"memo_misses": metrics.frontier.memo_misses,
"representative_proofs": metrics.frontier.representative_proofs,
"search_proven": metrics.frontier.search_proven,
"search_disproven": metrics.frontier.search_disproven,
"declined_exhausted": metrics.frontier.declined_exhausted,
"budget_fraction": metrics.frontier.budget_fraction,
}),
);
out.insert(
"frontier_decline".to_string(),
json!(metrics.frontier_decline),
);
out.insert(
"start".to_string(),
match &metrics.start {
Some(start) => json!({
"element": start.element,
"backward": start.backward,
"reason": start.reason,
}),
None => Value::Null,
},
);
out.insert(
"kernel".to_string(),
match metrics.kernel {
Some(rung) => json!({"rung": rung.as_str(), "hops": rung.hops()}),
None => Value::Null,
},
);
Value::Object(out)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::wire::plan_test_fixtures::{plan_seek_wire_node, plan_wire_node};
#[test]
fn actual_carries_the_subtree_total() {
let scan = plan_wire_node("NodeByLabelScan", 1, Some(3_000_000), vec![]);
let root = plan_wire_node("ProduceResults", 0, Some(10_000_000), vec![scan]);
let doc = plan_document(&root, Some("MATCH (n) RETURN n"), &[]);
assert_eq!(doc["profiled"], true);
assert_eq!(
doc["root"]["actual"]["time_ms"], 10.0,
"the root's own time renders in milliseconds"
);
assert_eq!(
doc["root"]["actual"]["total_time_ms"], 13.0,
"the root's total covers itself plus the scan: 10 + 3 = 13 ms"
);
let child = &doc["root"]["children"][0];
assert_eq!(
child["actual"]["total_time_ms"], 3.0,
"a leaf's total equals its own time"
);
let explain = plan_document(
&plan_wire_node("ProduceResults", 0, None, vec![]),
Some("RETURN 1"),
&[],
);
assert!(explain["root"]["actual"].is_null());
}
#[test]
fn actual_carries_the_phase_times_and_loops() {
let scan = plan_wire_node("NodeByLabelScan", 1, Some(3_000_000), vec![]);
let root = plan_wire_node("ProduceResults", 0, Some(10_000_000), vec![scan]);
let doc = plan_document(&root, Some("MATCH (n) RETURN n"), &[]);
assert_eq!(doc["root"]["actual"]["seek_ms"], 0.0);
assert_eq!(doc["root"]["actual"]["walk_ms"], 0.0);
assert_eq!(doc["root"]["actual"]["loops"], 1, "the scan's rows");
let child = &doc["root"]["children"][0];
assert!(child["actual"]["loops"].is_null());
}
#[test]
fn projects_the_document_shape() {
let doc = plan_document(
&plan_wire_node("ProduceResults", 0, None, vec![]),
Some("RETURN 1"),
&[],
);
assert_eq!(doc["schema"], SCHEMA);
assert_eq!(doc["profiled"], false);
assert_eq!(doc["root"]["operator"], "ProduceResults");
assert_eq!(doc["root"]["identifiers"][0], "name");
assert!(
doc["root"]["warnings"].is_array(),
"warnings always present"
);
assert!(doc["root"]["actual"].is_null());
}
#[test]
fn the_seek_operators_project_into_the_document() {
let seek = plan_seek_wire_node(
"NodeIndexSeekByRange",
"RANGE INDEX n:User(age) WHERE age > 5, WHERE filter",
5,
1,
);
let root = plan_wire_node("ProduceResults", 0, None, vec![seek]);
let doc = plan_document(&root, Some("MATCH (n:User) WHERE n.age > 5 RETURN n"), &[]);
let node = &doc["root"]["children"][0];
assert_eq!(node["operator"], "NodeIndexSeekByRange");
assert_eq!(
node["details"],
"RANGE INDEX n:User(age) WHERE age > 5, WHERE filter"
);
assert_eq!(node["estimated_rows"], 5);
assert!(
node["actual"].is_null(),
"an EXPLAIN-shaped seek node carries no metrics"
);
}
#[test]
fn node_warnings_are_the_canonical_notification_projection() {
use crate::wire::{notification_keys, notification_to_wire_json, NotificationKind};
let notification =
Notification::new(NotificationKind::CartesianProduct, "no join predicate")
.with_operator_id(1);
let tree = plan_wire_node(
"ProduceResults",
0,
None,
vec![plan_wire_node("CartesianProduct", 1, None, vec![])],
);
let doc = plan_document(
&tree,
Some("MATCH (a), (b) RETURN a, b"),
std::slice::from_ref(¬ification),
);
let warning = &doc["root"]["children"][0]["warnings"][0];
let mut canonical = notification_to_wire_json(¬ification);
canonical
.as_object_mut()
.expect("the canonical notification is an object")
.remove(notification_keys::OPERATOR_ID);
assert_eq!(
*warning, canonical,
"the node warning is the canonical notification object minus the join key"
);
assert!(
warning.get(notification_keys::OPERATOR_ID).is_none(),
"the node scopes the operator, so the join key is not repeated"
);
assert_eq!(doc["root"]["warnings"], json!([]));
}
#[test]
#[should_panic(expected = "plan wire Id is non-negative")]
fn negative_operator_id_is_a_loud_wire_break() {
let tree = plan_wire_node("ProduceResults", -1, None, vec![]);
let _ = plan_document(&tree, Some("RETURN 1"), &[]);
}
#[test]
#[should_panic(expected = "every operator-scoped notification joins exactly one plan node")]
fn an_unjoined_operator_notification_is_a_loud_wire_break() {
use crate::wire::NotificationKind;
let notification =
Notification::new(NotificationKind::CartesianProduct, "no join predicate")
.with_operator_id(7);
let tree = plan_wire_node("ProduceResults", 0, None, vec![]);
let _ = plan_document(&tree, Some("RETURN 1"), &[notification]);
}
}