Skip to content

Commit 4a516d2

Browse files
adriangbclaude
andcommitted
feat(proto): round-trip EXPLAIN/EXPLAIN ANALYZE statement-level overrides
The `Analyze::analyze_level` / `Analyze::analyze_categories` and `Explain::show_statistics` fields added with the Postgres-style option list previously had to default to `None` on the proto-decode side because their wire encoding was not implemented. Encode/decode them so distributed plan serialization preserves the overrides instead of silently falling back to session config. - Add `MetricType`, `MetricCategory`, and an `ExplainAnalyzeCategoriesNode` wrapper (oneof-like via `bool all` + `repeated MetricCategory only`) in `datafusion_common.proto`, mirroring the Rust types. - Add optional fields to `AnalyzeNode` and `ExplainNode` in `datafusion.proto`. - Extend `ExplainOption` with `analyze_level` and `analyze_categories` builder setters so the proto decode arms can populate them through the same `LogicalPlanBuilder::explain_option_format` path as the SQL planner, keeping `LogicalPlan::Analyze` / `LogicalPlan::Explain` construction in one place. - Add round-trip tests covering each field set and unset, including `All`, `Only(vec![])` (plan-only) and a fully-populated `Only` list. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent f8fd0f3 commit 4a516d2

11 files changed

Lines changed: 718 additions & 16 deletions

File tree

‎datafusion/expr/src/logical_plan/builder.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1337,8 +1337,8 @@ impl LogicalPlanBuilder {
13371337
verbose: explain_option.verbose,
13381338
input: self.plan,
13391339
schema,
1340-
analyze_level: None,
1341-
analyze_categories: None,
1340+
analyze_level: explain_option.analyze_level,
1341+
analyze_categories: explain_option.analyze_categories,
13421342
})))
13431343
} else {
13441344
let stringified_plans =

‎datafusion/expr/src/logical_plan/plan.rs‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3335,6 +3335,12 @@ pub struct ExplainOption {
33353335
/// Statement-level override for `datafusion.explain.show_statistics`.
33363336
/// `None` means "fall back to session config".
33373337
pub show_statistics: Option<bool>,
3338+
/// Statement-level override for `datafusion.explain.analyze_level`.
3339+
/// `None` means "fall back to session config".
3340+
pub analyze_level: Option<MetricType>,
3341+
/// Statement-level override for `datafusion.explain.analyze_categories`.
3342+
/// `None` means "fall back to session config".
3343+
pub analyze_categories: Option<ExplainAnalyzeCategories>,
33383344
}
33393345

33403346
impl Default for ExplainOption {
@@ -3344,6 +3350,8 @@ impl Default for ExplainOption {
33443350
analyze: false,
33453351
format: ExplainFormat::Indent,
33463352
show_statistics: None,
3353+
analyze_level: None,
3354+
analyze_categories: None,
33473355
}
33483356
}
33493357
}
@@ -3373,6 +3381,23 @@ impl ExplainOption {
33733381
self.show_statistics = show_statistics;
33743382
self
33753383
}
3384+
3385+
/// Builder-style setter for a statement-level override of
3386+
/// `datafusion.explain.analyze_level`.
3387+
pub fn with_analyze_level(mut self, analyze_level: Option<MetricType>) -> Self {
3388+
self.analyze_level = analyze_level;
3389+
self
3390+
}
3391+
3392+
/// Builder-style setter for a statement-level override of
3393+
/// `datafusion.explain.analyze_categories`.
3394+
pub fn with_analyze_categories(
3395+
mut self,
3396+
analyze_categories: Option<ExplainAnalyzeCategories>,
3397+
) -> Self {
3398+
self.analyze_categories = analyze_categories;
3399+
self
3400+
}
33763401
}
33773402

33783403
/// Produces a relation with string representations of

‎datafusion/proto-common/proto/datafusion_common.proto‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -683,4 +683,30 @@ enum ExplainFormat {
683683
EXPLAIN_FORMAT_TREE = 1;
684684
EXPLAIN_FORMAT_PGJSON = 2;
685685
EXPLAIN_FORMAT_GRAPHVIZ = 3;
686+
}
687+
688+
// Verbosity level for `EXPLAIN ANALYZE`. Mirrors
689+
// `datafusion_common::format::MetricType`.
690+
enum MetricType {
691+
METRIC_TYPE_SUMMARY = 0;
692+
METRIC_TYPE_DEV = 1;
693+
}
694+
695+
// Category of an `EXPLAIN ANALYZE` metric. Mirrors
696+
// `datafusion_common::format::MetricCategory`.
697+
enum MetricCategory {
698+
METRIC_CATEGORY_ROWS = 0;
699+
METRIC_CATEGORY_BYTES = 1;
700+
METRIC_CATEGORY_TIMING = 2;
701+
METRIC_CATEGORY_UNCATEGORIZED = 3;
702+
}
703+
704+
// Wire encoding for `datafusion_common::format::ExplainAnalyzeCategories`.
705+
//
706+
// If `all` is true, every category is shown (the `only` list is ignored).
707+
// If `all` is false, only the categories listed in `only` are shown — an
708+
// empty `only` means "plan only", i.e. suppress all metrics.
709+
message ExplainAnalyzeCategoriesNode {
710+
bool all = 1;
711+
repeated MetricCategory only = 2;
686712
}

‎datafusion/proto-common/src/generated/pbjson.rs‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4116,6 +4116,118 @@ impl<'de> serde::Deserialize<'de> for EmptyMessage {
41164116
deserializer.deserialize_struct("datafusion_common.EmptyMessage", FIELDS, GeneratedVisitor)
41174117
}
41184118
}
4119+
impl serde::Serialize for ExplainAnalyzeCategoriesNode {
4120+
#[allow(deprecated)]
4121+
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
4122+
where
4123+
S: serde::Serializer,
4124+
{
4125+
use serde::ser::SerializeStruct;
4126+
let mut len = 0;
4127+
if self.all {
4128+
len += 1;
4129+
}
4130+
if !self.only.is_empty() {
4131+
len += 1;
4132+
}
4133+
let mut struct_ser = serializer.serialize_struct("datafusion_common.ExplainAnalyzeCategoriesNode", len)?;
4134+
if self.all {
4135+
struct_ser.serialize_field("all", &self.all)?;
4136+
}
4137+
if !self.only.is_empty() {
4138+
let v = self.only.iter().cloned().map(|v| {
4139+
MetricCategory::try_from(v)
4140+
.map_err(|_| serde::ser::Error::custom(format!("Invalid variant {}", v)))
4141+
}).collect::<std::result::Result<Vec<_>, _>>()?;
4142+
struct_ser.serialize_field("only", &v)?;
4143+
}
4144+
struct_ser.end()
4145+
}
4146+
}
4147+
impl<'de> serde::Deserialize<'de> for ExplainAnalyzeCategoriesNode {
4148+
#[allow(deprecated)]
4149+
fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
4150+
where
4151+
D: serde::Deserializer<'de>,
4152+
{
4153+
const FIELDS: &[&str] = &[
4154+
"all",
4155+
"only",
4156+
];
4157+
4158+
#[allow(clippy::enum_variant_names)]
4159+
enum GeneratedField {
4160+
All,
4161+
Only,
4162+
}
4163+
impl<'de> serde::Deserialize<'de> for GeneratedField {
4164+
fn deserialize<D>(deserializer: D) -> std::result::Result<GeneratedField, D::Error>
4165+
where
4166+
D: serde::Deserializer<'de>,
4167+
{
4168+
struct GeneratedVisitor;
4169+
4170+
impl serde::de::Visitor<'_> for GeneratedVisitor {
4171+
type Value = GeneratedField;
4172+
4173+
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4174+
write!(formatter, "expected one of: {:?}", &FIELDS)
4175+
}
4176+
4177+
#[allow(unused_variables)]
4178+
fn visit_str<E>(self, value: &str) -> std::result::Result<GeneratedField, E>
4179+
where
4180+
E: serde::de::Error,
4181+
{
4182+
match value {
4183+
"all" => Ok(GeneratedField::All),
4184+
"only" => Ok(GeneratedField::Only),
4185+
_ => Err(serde::de::Error::unknown_field(value, FIELDS)),
4186+
}
4187+
}
4188+
}
4189+
deserializer.deserialize_identifier(GeneratedVisitor)
4190+
}
4191+
}
4192+
struct GeneratedVisitor;
4193+
impl<'de> serde::de::Visitor<'de> for GeneratedVisitor {
4194+
type Value = ExplainAnalyzeCategoriesNode;
4195+
4196+
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4197+
formatter.write_str("struct datafusion_common.ExplainAnalyzeCategoriesNode")
4198+
}
4199+
4200+
fn visit_map<V>(self, mut map_: V) -> std::result::Result<ExplainAnalyzeCategoriesNode, V::Error>
4201+
where
4202+
V: serde::de::MapAccess<'de>,
4203+
{
4204+
let mut all__ = None;
4205+
let mut only__ = None;
4206+
while let Some(k) = map_.next_key()? {
4207+
match k {
4208+
GeneratedField::All => {
4209+
if all__.is_some() {
4210+
return Err(serde::de::Error::duplicate_field("all"));
4211+
}
4212+
all__ = Some(map_.next_value()?);
4213+
}
4214+
GeneratedField::Only => {
4215+
if only__.is_some() {
4216+
return Err(serde::de::Error::duplicate_field("only"));
4217+
}
4218+
only__ = Some(map_.next_value::<Vec<MetricCategory>>()?.into_iter().map(|x| x as i32).collect());
4219+
}
4220+
}
4221+
}
4222+
Ok(ExplainAnalyzeCategoriesNode {
4223+
all: all__.unwrap_or_default(),
4224+
only: only__.unwrap_or_default(),
4225+
})
4226+
}
4227+
}
4228+
deserializer.deserialize_struct("datafusion_common.ExplainAnalyzeCategoriesNode", FIELDS, GeneratedVisitor)
4229+
}
4230+
}
41194231
impl serde::Serialize for ExplainFormat {
41204232
#[allow(deprecated)]
41214233
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
@@ -5474,6 +5586,154 @@ impl<'de> serde::Deserialize<'de> for Map {
54745586
deserializer.deserialize_struct("datafusion_common.Map", FIELDS, GeneratedVisitor)
54755587
}
54765588
}
5589+
impl serde::Serialize for MetricCategory {
5590+
#[allow(deprecated)]
5591+
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
5592+
where
5593+
S: serde::Serializer,
5594+
{
5595+
let variant = match self {
5596+
Self::Rows => "METRIC_CATEGORY_ROWS",
5597+
Self::Bytes => "METRIC_CATEGORY_BYTES",
5598+
Self::Timing => "METRIC_CATEGORY_TIMING",
5599+
Self::Uncategorized => "METRIC_CATEGORY_UNCATEGORIZED",
5600+
};
5601+
serializer.serialize_str(variant)
5602+
}
5603+
}
5604+
impl<'de> serde::Deserialize<'de> for MetricCategory {
5605+
#[allow(deprecated)]
5606+
fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
5607+
where
5608+
D: serde::Deserializer<'de>,
5609+
{
5610+
const FIELDS: &[&str] = &[
5611+
"METRIC_CATEGORY_ROWS",
5612+
"METRIC_CATEGORY_BYTES",
5613+
"METRIC_CATEGORY_TIMING",
5614+
"METRIC_CATEGORY_UNCATEGORIZED",
5615+
];
5616+
5617+
struct GeneratedVisitor;
5618+
5619+
impl serde::de::Visitor<'_> for GeneratedVisitor {
5620+
type Value = MetricCategory;
5621+
5622+
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
5623+
write!(formatter, "expected one of: {:?}", &FIELDS)
5624+
}
5625+
5626+
fn visit_i64<E>(self, v: i64) -> std::result::Result<Self::Value, E>
5627+
where
5628+
E: serde::de::Error,
5629+
{
5630+
i32::try_from(v)
5631+
.ok()
5632+
.and_then(|x| x.try_into().ok())
5633+
.ok_or_else(|| {
5634+
serde::de::Error::invalid_value(serde::de::Unexpected::Signed(v), &self)
5635+
})
5636+
}
5637+
5638+
fn visit_u64<E>(self, v: u64) -> std::result::Result<Self::Value, E>
5639+
where
5640+
E: serde::de::Error,
5641+
{
5642+
i32::try_from(v)
5643+
.ok()
5644+
.and_then(|x| x.try_into().ok())
5645+
.ok_or_else(|| {
5646+
serde::de::Error::invalid_value(serde::de::Unexpected::Unsigned(v), &self)
5647+
})
5648+
}
5649+
5650+
fn visit_str<E>(self, value: &str) -> std::result::Result<Self::Value, E>
5651+
where
5652+
E: serde::de::Error,
5653+
{
5654+
match value {
5655+
"METRIC_CATEGORY_ROWS" => Ok(MetricCategory::Rows),
5656+
"METRIC_CATEGORY_BYTES" => Ok(MetricCategory::Bytes),
5657+
"METRIC_CATEGORY_TIMING" => Ok(MetricCategory::Timing),
5658+
"METRIC_CATEGORY_UNCATEGORIZED" => Ok(MetricCategory::Uncategorized),
5659+
_ => Err(serde::de::Error::unknown_variant(value, FIELDS)),
5660+
}
5661+
}
5662+
}
5663+
deserializer.deserialize_any(GeneratedVisitor)
5664+
}
5665+
}
5666+
impl serde::Serialize for MetricType {
5667+
#[allow(deprecated)]
5668+
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
5669+
where
5670+
S: serde::Serializer,
5671+
{
5672+
let variant = match self {
5673+
Self::Summary => "METRIC_TYPE_SUMMARY",
5674+
Self::Dev => "METRIC_TYPE_DEV",
5675+
};
5676+
serializer.serialize_str(variant)
5677+
}
5678+
}
5679+
impl<'de> serde::Deserialize<'de> for MetricType {
5680+
#[allow(deprecated)]
5681+
fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
5682+
where
5683+
D: serde::Deserializer<'de>,
5684+
{
5685+
const FIELDS: &[&str] = &[
5686+
"METRIC_TYPE_SUMMARY",
5687+
"METRIC_TYPE_DEV",
5688+
];
5689+
5690+
struct GeneratedVisitor;
5691+
5692+
impl serde::de::Visitor<'_> for GeneratedVisitor {
5693+
type Value = MetricType;
5694+
5695+
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
5696+
write!(formatter, "expected one of: {:?}", &FIELDS)
5697+
}
5698+
5699+
fn visit_i64<E>(self, v: i64) -> std::result::Result<Self::Value, E>
5700+
where
5701+
E: serde::de::Error,
5702+
{
5703+
i32::try_from(v)
5704+
.ok()
5705+
.and_then(|x| x.try_into().ok())
5706+
.ok_or_else(|| {
5707+
serde::de::Error::invalid_value(serde::de::Unexpected::Signed(v), &self)
5708+
})
5709+
}
5710+
5711+
fn visit_u64<E>(self, v: u64) -> std::result::Result<Self::Value, E>
5712+
where
5713+
E: serde::de::Error,
5714+
{
5715+
i32::try_from(v)
5716+
.ok()
5717+
.and_then(|x| x.try_into().ok())
5718+
.ok_or_else(|| {
5719+
serde::de::Error::invalid_value(serde::de::Unexpected::Unsigned(v), &self)
5720+
})
5721+
}
5722+
5723+
fn visit_str<E>(self, value: &str) -> std::result::Result<Self::Value, E>
5724+
where
5725+
E: serde::de::Error,
5726+
{
5727+
match value {
5728+
"METRIC_TYPE_SUMMARY" => Ok(MetricType::Summary),
5729+
"METRIC_TYPE_DEV" => Ok(MetricType::Dev),
5730+
_ => Err(serde::de::Error::unknown_variant(value, FIELDS)),
5731+
}
5732+
}
5733+
}
5734+
deserializer.deserialize_any(GeneratedVisitor)
5735+
}
5736+
}
54775737
impl serde::Serialize for NdJsonFormat {
54785738
#[allow(deprecated)]
54795739
fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>

0 commit comments

Comments
 (0)