diff --git a/Cargo.lock b/Cargo.lock index a5df32ae2ee..13c70d54a64 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -6101,7 +6101,7 @@ dependencies = [ [[package]] name = "greptime-proto" version = "0.1.0" -source = "git+https://github.com/GreptimeTeam/greptime-proto.git?rev=9533078d6fd4bdaddbca0750cb9bf7ad64b2e568#9533078d6fd4bdaddbca0750cb9bf7ad64b2e568" +source = "git+https://github.com/GreptimeTeam/greptime-proto.git?rev=f51cb5312bf7feaf1199361ce16edc63a0ad40b2#f51cb5312bf7feaf1199361ce16edc63a0ad40b2" dependencies = [ "prost 0.14.1", "prost-types 0.14.1", @@ -14641,6 +14641,7 @@ dependencies = [ "promql", "prost 0.14.1", "snafu 0.8.6", + "tokio", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index e591a76feda..cd47c13f779 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -161,7 +161,7 @@ fs2 = "0.4" fst = "0.4.7" futures = "0.3" futures-util = "0.3" -greptime-proto = { git = "https://github.com/GreptimeTeam/greptime-proto.git", rev = "9533078d6fd4bdaddbca0750cb9bf7ad64b2e568" } +greptime-proto = { git = "https://github.com/GreptimeTeam/greptime-proto.git", rev = "f51cb5312bf7feaf1199361ce16edc63a0ad40b2" } hdfs-native = "0.14.6" hex = "0.4" hostname = "0.4.0" diff --git a/src/common/query/src/series_frame.rs b/src/common/query/src/series_frame.rs index 5fb942ca156..d48c4e855e8 100644 --- a/src/common/query/src/series_frame.rs +++ b/src/common/query/src/series_frame.rs @@ -26,9 +26,9 @@ //! identity or provenance, and neither side is authenticated as field provenance. This adapter //! preserves //! scan candidates only; it is not a residual filter, authorization check, remote transport, or -//! compaction boundary. Only -//! [`SeriesOrdering::Contiguous`] and [`SeriesOrdering::KeyThenTime`] are accepted for raw frames and -//! only `Contiguous` for evaluated ones; `Interleaved` is rejected before any poll. +//! compaction boundary. Raw frames accept all three [`SeriesOrdering`] declarations, while evaluated +//! frames accept only `Contiguous`. Raw `Interleaved` supports independently closed producer +//! fragment chains in sequence, including recurring keys; it does not multiplex open chains. //! //! An evaluated frame is the same physical family: [`pack_evaluated_series`] and //! [`unpack_evaluated_series`] carry computed values under complete labels and grid positions, so a @@ -86,8 +86,7 @@ pub type SendableStateFrameStream = /// Builds the canonical raw frame schema with the producer's label binding and ordering. /// -/// Ordering records a producer guarantee; it is not inferred from frame contents. `Interleaved` -/// has no wire representation and is rejected before the schema is assembled. The label binding +/// Ordering records a producer guarantee; it is not inferred from frame contents. The label binding /// determines both the label mode and, for a primary-key binding, the self-describing label decode /// description written into the schema, so a frame can never declare a label layout it does not /// describe. @@ -130,11 +129,7 @@ pub fn frame_schema_with( let ordering = match ordering { SeriesOrdering::Contiguous => "contiguous", SeriesOrdering::KeyThenTime => "read_key_then_time", - SeriesOrdering::Interleaved => { - return Err(invalid( - "interleaved series ordering has no wire representation", - )); - } + SeriesOrdering::Interleaved => "interleaved", }; let schema = series_frame_schema(schema, mode, decode).map_err(codec_error)?; let mut metadata = schema.metadata().clone(); @@ -202,19 +197,22 @@ pub fn series_frame_ordering(schema: &ArrowSchema) -> datafusion_common::Result< match schema.metadata().get(ORDERING_KEY).map(String::as_str) { Some("contiguous") => Ok(SeriesOrdering::Contiguous), Some("read_key_then_time") => Ok(SeriesOrdering::KeyThenTime), + Some("interleaved") => Ok(SeriesOrdering::Interleaved), None | Some(_) => Err(invalid("missing or unknown series ordering")), } } /// Packs a storage raw-series stream into DataFusion record batches incrementally. /// -/// Only [`SeriesOrdering::Contiguous`] and [`SeriesOrdering::KeyThenTime`] streams are accepted; an -/// `Interleaved` declaration is rejected before the first poll, including for an empty stream. Rows -/// accumulate across chunks into batches bounded by the builder's row and estimated payload limits; -/// one legal oversized row may be emitted alone, and these limits are a work bound, not a -/// resident-memory cap. A ready batch is yielded without polling the source again. Producers must -/// keep each series' chunks contiguous. Validation checks adjacent chunk conditions but does not -/// certify nonadjacent recurrence for `Contiguous` ordering. +/// Rows accumulate across chunks into batches bounded by the builder's row and estimated payload +/// limits; one legal oversized row may be emitted alone, and these limits are a work bound, not a +/// resident-memory cap. A ready batch is yielded without polling the source again. +/// +/// Even under [`SeriesOrdering::Interleaved`], each producer fragment chain must close before +/// another starts; arbitrary multiplexing of open chains is rejected. Closed fragment chains may +/// recur with the same key and overlapping timestamps. Finality closes a producer fragment, not +/// necessarily the logical series. For `Contiguous`, validation checks adjacent chunk conditions +/// but does not certify nonadjacent recurrence. /// /// The stream's own declaration is the only decode input: a frame unpacked without a scan-bound /// [`RawLabelSource`] round trips unchanged instead of being re-declared from a binding it does not @@ -224,7 +222,6 @@ pub fn pack_raw_series( source: SendableRawSeriesStream, ) -> datafusion_common::Result { let ordering = source.ordering(); - ensure_supported_ordering(ordering)?; let schema = source.schema().clone(); let decode = source.label_decode_spec().cloned(); let labels = declared_label_mode(&decode); @@ -417,11 +414,10 @@ pub fn unpack_aggregate_state( /// /// The frame is the sole source of decode information: the payload fields, the label mode, the /// label decode description, and the producer ordering are all read from the stream's own schema, -/// so unpacking a frame a producer wrote needs no local copy of its binding. Only -/// [`SeriesOrdering::Contiguous`] and [`SeriesOrdering::KeyThenTime`] streams are accepted; an -/// `Interleaved` declaration is rejected before the stream is returned, including for an empty -/// stream. Producers must keep each series' chunks contiguous. Validation checks adjacent chunk -/// conditions but does not certify nonadjacent recurrence for `Contiguous` ordering. +/// so unpacking a frame a producer wrote needs no local copy of its binding. Like packing, unpacking +/// accepts `Interleaved` only when every producer fragment chain closes before the next starts; it +/// rejects multiplexed open chains. Closed fragment chains may recur with the same key and overlapping +/// timestamps. Validation does not certify nonadjacent recurrence for `Contiguous` ordering. /// /// Every frame is validated here, unconditionally. The declared layout must be this revision's, the /// label decode description must parse, name a known version, and agree with the declared label @@ -453,7 +449,6 @@ pub fn unpack_raw_series( ensure_declared_schema(&schema, expected)?; } let ordering = series_frame_ordering(frame_schema.as_ref())?; - ensure_supported_ordering(ordering)?; let decoder = SeriesFrameDecoder::try_new(&schema, labels, declared.as_ref()).map_err(codec_error)?; // Validate even empty streams' declared schema and layout before returning the stream. @@ -588,21 +583,11 @@ fn declared_label_mode(declared: &Option) -> FrameLabelMode { } } -/// Rejects orderings this adapter cannot validate; a bad declaration is an error, not a fallback. -fn ensure_supported_ordering(ordering: SeriesOrdering) -> datafusion_common::Result<()> { - match ordering { - SeriesOrdering::Contiguous | SeriesOrdering::KeyThenTime => Ok(()), - SeriesOrdering::Interleaved => { - Err(invalid("interleaved raw series ordering is not supported")) - } - } -} - /// Rejects an evaluated frame that claims more order than its producer promised. /// /// Computed values have no storage key to be ordered by, so `read_key_then_time` is not a claim this -/// layer can honour; `Interleaved` is not consumable at all. Treating either as `contiguous` would -/// silently weaken a guarantee a consumer may rely on. +/// layer can honour; `Interleaved` is not supported for evaluated frames. Treating either as +/// `contiguous` would silently weaken a guarantee a consumer may rely on. fn ensure_contiguous_ordering(ordering: SeriesOrdering) -> datafusion_common::Result<()> { match ordering { SeriesOrdering::Contiguous => Ok(()), @@ -630,10 +615,11 @@ fn invalid(reason: impl Into) -> DataFusionError { ))) } -/// Cross-chunk validation state for raw chains. The producer must keep each series' chunks -/// contiguous; this validator checks adjacent chunks only and never sees `Interleaved` streams. It -/// retains only the previous complete owned key (not an Arrow buffer), timestamp, metric, and -/// finality. +/// Cross-chunk validation state for raw producer fragment chains. Every chain's chunks must be +/// contiguous, including for `Interleaved`; this validator checks adjacent chunks only and retains +/// the previous owned key (not an Arrow buffer), timestamp, metric, and finality. An `Interleaved` +/// chain releases that state on closure, so later fragment chains may recur with the same key, +/// labels, and timestamps independently. struct SequenceValidator { ordering: SeriesOrdering, previous_key: Option>, @@ -697,10 +683,17 @@ impl SequenceValidator { } } } - self.previous_key = Some(key.to_vec()); - self.previous_timestamp = Some(timestamp); - self.previous_metric = chunk.metric.clone(); - self.previous_is_last = chunk.is_last; + if self.ordering == SeriesOrdering::Interleaved && chunk.is_last { + self.previous_key = None; + self.previous_timestamp = None; + self.previous_metric = None; + self.previous_is_last = false; + } else { + self.previous_key = Some(key.to_vec()); + self.previous_timestamp = Some(timestamp); + self.previous_metric = chunk.metric.clone(); + self.previous_is_last = chunk.is_last; + } Ok(()) } } diff --git a/src/common/query/src/series_frame/tests.rs b/src/common/query/src/series_frame/tests.rs index 5f2ccc725ee..aeb0fbdeb8f 100644 --- a/src/common/query/src/series_frame/tests.rs +++ b/src/common/query/src/series_frame/tests.rs @@ -430,6 +430,108 @@ async fn contiguous_adapter_does_not_certify_nonadjacent_recurrence() { } assert!(decoded.next().await.is_none()); } + +/// Raw Interleaved supports concatenated independently closed producer fragments, not a +/// merge: identical identities may recur with overlapping timestamps and different labels. +#[tokio::test] +async fn interleaved_closed_fragment_roundtrips() { + type Row = (&'static [u8], i64, bool, Option<&'static str>); + let cases: &[(&str, &[Row])] = &[ + ("empty", &[]), + ( + "adjacent_same_key_equal_time", + &[(b"a", 5, true, None), (b"a", 5, true, None)], + ), + ( + "adjacent_multichunk_reversed_time_and_labels", + &[ + (b"a", 10, false, Some("x")), + (b"a", 12, true, Some("x")), + (b"a", 2, false, Some("y")), + (b"a", 3, true, Some("y")), + ], + ), + ( + "nonadjacent_same_key_overlapping_time", + &[ + (b"a", 5, true, None), + (b"b", 8, true, None), + (b"a", 4, true, None), + ], + ), + ]; + for (name, rows) in cases { + // Pending forces a batch boundary inside the multichunk fragment, exercising state + // continuity both across batches and when several closed fragments share a batch. + let chunks = rows + .iter() + .map(|(key, time, last, host)| { + chunk_with( + key, + &[*time], + vec![Some(*time as f64)], + Some(host.map_or_else(metric, labeled_metric)), + *last, + ) + }) + .collect(); + let (input, _, _) = raw_pending(chunks, SeriesOrdering::Interleaved, 1); + let mut packed = pack_raw_series(input).unwrap(); + let declared = packed.schema(); + assert_eq!( + declared.metadata()["greptime.series.ordering"], + "interleaved", + "{name}" + ); + let mut batches = Vec::new(); + while let Some(batch) = packed.next().await { + let batch = batch.unwrap_or_else(|error| panic!("{name}: {error}")); + assert_eq!(batch.schema(), declared, "{name}"); + batches.push(batch); + } + let (input, _, _) = df_source(batches, declared); + let mut output = unpack_raw_series(input, Some(schema())).unwrap(); + assert_eq!(output.ordering(), SeriesOrdering::Interleaved, "{name}"); + for (key, time, last, host) in *rows { + let chunk = output.next().await.unwrap().unwrap(); + assert_chunk(&chunk, key, &[*time], &[Some(*time as f64)], *last); + assert_metric(&chunk, *host); + } + assert!(output.next().await.is_none(), "{name}"); + } +} + +/// The key-encoded form uses the same ordering and fragment-local finality as explicit labels. +#[tokio::test] +async fn interleaved_key_fragment_roundtrip() { + let binding = key_binding("cpu"); + let chunks = vec![ + chunk_with(b"key", &[4], vec![Some(4.0)], None, false), + chunk_with(b"key", &[5], vec![Some(5.0)], None, true), + chunk_with(b"key", &[1], vec![Some(1.0)], None, true), + ]; + let (input, _, _) = raw_custom(chunks, SeriesOrdering::Interleaved, binding.clone()); + let mut packed = pack_raw_series(input).unwrap(); + let declared = packed.schema(); + assert_eq!( + datatypes::series::frame::series_frame_label_decode(&declared).unwrap(), + label_decode_spec(&binding) + ); + let mut batches = Vec::new(); + while let Some(batch) = packed.next().await { + batches.push(batch.unwrap()); + } + let (input, _, _) = df_source(batches, declared); + let mut output = unpack_raw_series(input, Some(schema())).unwrap(); + assert_eq!(output.ordering(), SeriesOrdering::Interleaved); + for (time, last) in [(4, false), (5, true), (1, true)] { + let chunk = output.next().await.unwrap().unwrap(); + assert_chunk(&chunk, b"key", &[time], &[Some(time as f64)], last); + assert!(chunk.metric.is_none()); + } + assert!(output.next().await.is_none()); +} + fn assert_metric(chunk: &RawSeriesChunk, host: Option<&str>) { let actual = chunk .metric @@ -595,6 +697,12 @@ async fn invalid_sequence_reports_valid_prefix_then_one_terminal_error() { order: SeriesOrdering::Contiguous, prefix: vec![(b"a", 1, true, None)], }, + Case { + name: "key_then_time_final_then_same_key", + items: vec![chunk(b"a", &[1], true), chunk(b"a", &[2], true)], + order: SeriesOrdering::KeyThenTime, + prefix: vec![(b"a", 1, true, None)], + }, Case { name: "unfinished_then_new_key", items: vec![chunk(b"a", &[1], false), chunk(b"b", &[2], true)], @@ -629,6 +737,53 @@ async fn invalid_sequence_reports_valid_prefix_then_one_terminal_error() { order: SeriesOrdering::Contiguous, prefix: vec![(b"a", 3, false, None)], }, + Case { + name: "interleaved_multiplexed_open_chains", + items: vec![ + chunk(b"a", &[1], false), + chunk(b"b", &[2], true), + chunk(b"a", &[3], true), + ], + order: SeriesOrdering::Interleaved, + prefix: vec![(b"a", 1, false, None)], + }, + Case { + name: "interleaved_changed_key_before_open_fragment_closes", + items: vec![ + chunk(b"a", &[1], false), + chunk(b"b", &[2], false), + chunk(b"a", &[3], true), + ], + order: SeriesOrdering::Interleaved, + prefix: vec![(b"a", 1, false, None)], + }, + Case { + name: "interleaved_timestamp_equal_within_open_chain", + items: vec![chunk(b"a", &[2], false), chunk(b"a", &[2], true)], + order: SeriesOrdering::Interleaved, + prefix: vec![(b"a", 2, false, None)], + }, + Case { + name: "interleaved_timestamp_decreases_within_open_chain", + items: vec![chunk(b"a", &[3], false), chunk(b"a", &[2], true)], + order: SeriesOrdering::Interleaved, + prefix: vec![(b"a", 3, false, None)], + }, + Case { + name: "interleaved_metric_changes_within_open_chain", + items: vec![ + chunk_with( + b"a", + &[1], + vec![Some(1.0)], + Some(labeled_metric("x")), + false, + ), + chunk_with(b"a", &[2], vec![Some(2.0)], Some(labeled_metric("y")), true), + ], + order: SeriesOrdering::Interleaved, + prefix: vec![(b"a", 1, false, Some("x"))], + }, Case { name: "metric_changes_within_key", items: vec![ @@ -739,6 +894,59 @@ async fn invalid_sequence_reports_valid_prefix_then_one_terminal_error() { assert!(decoded.next().await.is_none()); } +/// Once a closed fragment is followed by an open one, EOF must still report the latter on both +/// paths; closing the previous fragment must not erase the new fragment's state. +#[tokio::test] +async fn interleaved_unfinished_fragment_at_eof_is_rejected() { + let rows = vec![chunk(b"a", &[10], true), chunk(b"a", &[1], false)]; + let (input, _, _) = raw_pending(rows.clone(), SeriesOrdering::Interleaved, 1); + let mut packed = pack_raw_series(input).unwrap(); + let prefix = packed.next().await.unwrap().unwrap(); + assert_eq!(prefix.num_rows(), 1); + let error = packed.next().await.unwrap().unwrap_err(); + assert_eq!( + crate::error::datafusion_status_code::(&error, None), + StatusCode::InvalidArguments + ); + assert!(error.to_string().contains("ended before key was final")); + assert!(packed.next().await.is_none()); + + let frame_schema = super::raw_series_frame_schema_with_ordering( + &schema(), + &RawLabelSource::Explicit, + SeriesOrdering::Interleaved, + ) + .unwrap(); + let mut frames = Vec::new(); + for row in &rows { + for frame in datatypes::series::frame::pack_raw_series_chunk( + &schema(), + FrameLabelMode::Explicit, + None, + row, + ) + .unwrap() + { + frames.push( + RecordBatch::try_new(frame_schema.clone(), frame.columns().to_vec()).unwrap(), + ); + } + } + let (source, _, _) = df_source(frames, frame_schema); + let mut decoded = unpack_raw_series(source, Some(schema())).unwrap(); + for (time, last) in [(10, true), (1, false)] { + let chunk = decoded.next().await.unwrap().unwrap(); + assert_chunk(&chunk, b"a", &[time], &[Some(time as f64)], last); + } + let error = decoded.next().await.unwrap().unwrap_err(); + assert_eq!( + common_error::ext::ErrorExt::status_code(&error), + StatusCode::InvalidArguments + ); + assert!(error.to_string().contains("ended before key was final")); + assert!(decoded.next().await.is_none()); +} + /// EOF before a non-final key is an error: buffered rows are not reported as a partial success. #[tokio::test] async fn pack_rejects_nonfinal_eof_without_buffered_partial_success() { @@ -2364,60 +2572,34 @@ async fn public_chunk_with_empty_times_is_rejected_without_panic() { } } -/// `Interleaved` is rejected by the constructor before any source poll, for a pack source and for -/// an empty unpack stream; the wire-schema helper rejects it before assembling a schema, since the -/// wire carries only the two representable spellings. No adjacent-only fallback is installed. +/// An Interleaved declaration is available for raw streams without polling either source, including +/// streams that ultimately contain no batches. #[tokio::test] -async fn interleaved_ordering_is_rejected_before_any_poll() { - assert!( - super::raw_series_frame_schema_with_ordering( - &schema(), - &RawLabelSource::Explicit, - SeriesOrdering::Interleaved, - ) - .is_err(), - "interleaved cannot be declared on the wire schema" +async fn interleaved_constructors_accept_without_polling() { + let frame = super::raw_series_frame_schema_with_ordering( + &schema(), + &RawLabelSource::Explicit, + SeriesOrdering::Interleaved, + ) + .unwrap(); + assert_eq!(frame.metadata()["greptime.series.ordering"], "interleaved"); + assert_eq!( + series_frame_ordering(&frame).unwrap(), + SeriesOrdering::Interleaved ); let (source, polls, drops) = raw_never_polled(SeriesOrdering::Interleaved); - let error = match pack_raw_series(source) { - Ok(_) => panic!("interleaved pack stream must be rejected"), - Err(error) => error, - }; - assert_eq!( - crate::error::datafusion_status_code::(&error, None), - StatusCode::InvalidArguments - ); - assert_eq!( - polls.load(Ordering::SeqCst), - 0, - "a rejected source is never polled" - ); + let packed = pack_raw_series(source).unwrap(); + assert_eq!(packed.schema(), frame); + assert_eq!(polls.load(Ordering::SeqCst), 0); + drop(packed); assert_eq!(drops.load(Ordering::SeqCst), 1); - // An unpack has no ordering argument, so the only way an `Interleaved` stream could reach it is - // a frame that declares one; that spelling has no wire representation and is rejected. - let frame = datatypes::series::frame::raw_series_frame_schema( - &schema(), - datatypes::series::frame::FrameLabelMode::Explicit, - ) - .unwrap(); - let mut metadata = frame.metadata().clone(); - metadata.insert( - "greptime.series.ordering".to_string(), - "interleaved".to_string(), - ); - let frame = Arc::new(Schema::new_with_metadata(frame.fields().clone(), metadata)); let (source, polls, drops) = df_never_polled(frame); - let error = match unpack_raw_series(source, Some(schema())) { - Ok(_) => panic!("an interleaved declaration must be rejected"), - Err(error) => error, - }; - assert_eq!( - crate::error::datafusion_status_code::(&error, None), - StatusCode::InvalidArguments - ); + let unpacked = unpack_raw_series(source, Some(schema())).unwrap(); + assert_eq!(unpacked.ordering(), SeriesOrdering::Interleaved); assert_eq!(polls.load(Ordering::SeqCst), 0); + drop(unpacked); assert_eq!(drops.load(Ordering::SeqCst), 1); } @@ -2449,8 +2631,10 @@ async fn unpack_rejects_unrelated_metadata_drift_and_empty_schema_changes() { reserved.insert("greptime.series.layout".into(), "v1".into()); let mut renamed = base.metadata().clone(); renamed.insert("app.renamed".into(), "y".into()); + let mut different_ordering = base.metadata().clone(); + different_ordering.insert("greptime.series.ordering".into(), "interleaved".into()); - let cases: [(&str, Arc, bool); 3] = [ + let cases: [(&str, Arc, bool); 4] = [ ( "unrelated metadata added", Arc::new((*base).clone().with_metadata(unrelated)), @@ -2466,6 +2650,11 @@ async fn unpack_rejects_unrelated_metadata_drift_and_empty_schema_changes() { Arc::new((*base).clone().with_metadata(renamed)), true, ), + ( + "ordering changed on an empty batch", + Arc::new((*base).clone().with_metadata(different_ordering)), + true, + ), ]; for (label, changed, empty) in cases { let bad = if empty { @@ -2568,7 +2757,11 @@ fn raw_series_ordering_metadata_fixture() { #[tokio::test] async fn pack_declares_ordering_on_every_batch_and_ipc_roundtrips_it() { - for ordering in [SeriesOrdering::Contiguous, SeriesOrdering::KeyThenTime] { + for ordering in [ + SeriesOrdering::Contiguous, + SeriesOrdering::KeyThenTime, + SeriesOrdering::Interleaved, + ] { for chunks in [ vec![ chunk_with(b"a", &[1], vec![Some(1.0)], Some(metric()), false), @@ -2589,12 +2782,7 @@ async fn pack_declares_ordering_on_every_batch_and_ipc_roundtrips_it() { match ordering { SeriesOrdering::Contiguous => "contiguous", SeriesOrdering::KeyThenTime => "read_key_then_time", - // The wire carries exactly these two spellings, so the loop above - // admits only the two representable modes; `Interleaved` is rejected - // before any poll (see `interleaved_ordering_is_rejected_before_any_poll`). - SeriesOrdering::Interleaved => { - unreachable!("interleaved raw series ordering has no wire spelling") - } + SeriesOrdering::Interleaved => "interleaved", } .to_string(), ); @@ -2628,6 +2816,7 @@ async fn pack_declares_ordering_on_every_batch_and_ipc_roundtrips_it() { assert!(ipc_batches.iter().all(|batch| batch.schema() == declared)); let (source, _, _) = df_source(ipc_batches, declared); let mut decoded = unpack_raw_series(source, Some(schema())).unwrap(); + assert_eq!(decoded.ordering(), ordering); if is_empty { assert!(decoded.next().await.is_none()); } else { @@ -3224,7 +3413,7 @@ async fn unpack_pack_unpack_preserves_the_description_and_the_ordering() { /// Each typed schema entry point refuses the content it cannot describe. /// /// The raw entry point is handed an evaluated series schema and the shared builder is handed an -/// evaluated schema with a key-then-time ordering. Both would otherwise produce a frame whose +/// evaluated schema with a non-contiguous ordering. Both would otherwise produce a frame whose /// declaration contradicts its own columns, and the reader would be the first to notice — after the /// producer had already published it. #[test] @@ -3248,6 +3437,16 @@ fn typed_schema_entry_points_refuse_the_content_they_cannot_describe() { .is_err(), "an evaluated frame has no storage key to be ordered by" ); + assert!( + super::frame_schema_with( + &evaluated_schema(), + FrameLabelMode::Explicit, + None, + SeriesOrdering::Interleaved, + ) + .is_err(), + "an evaluated frame cannot declare interleaved ordering" + ); assert!( super::frame_schema_with( &evaluated_schema(), diff --git a/src/common/substrait/Cargo.toml b/src/common/substrait/Cargo.toml index a56b56b8301..21b3d8a7396 100644 --- a/src/common/substrait/Cargo.toml +++ b/src/common/substrait/Cargo.toml @@ -20,3 +20,6 @@ datafusion-substrait.workspace = true promql.workspace = true prost.workspace = true snafu.workspace = true + +[dev-dependencies] +tokio.workspace = true diff --git a/src/common/substrait/src/extension_serializer.rs b/src/common/substrait/src/extension_serializer.rs index e14cf627515..e87b632f5de 100644 --- a/src/common/substrait/src/extension_serializer.rs +++ b/src/common/substrait/src/extension_serializer.rs @@ -20,7 +20,7 @@ use datafusion_common::DataFusionError; use datafusion_expr::UserDefinedLogicalNode; use promql::extension_plan::{ Absent, EmptyMetric, FusedSeries, HistogramFold, InstantManipulate, RangeManipulate, - ScalarCalculate, SeriesDivide, SeriesNormalize, UnionDistinctOn, + RawSeriesSource, ScalarCalculate, SeriesDivide, SeriesNormalize, UnionDistinctOn, }; #[derive(Debug)] @@ -94,6 +94,13 @@ impl SerializerRegistry for ExtensionSerializer { .expect("Failed to downcast to UnionDistinctOn"); Ok(union_distinct_on.serialize()) } + name if name == RawSeriesSource::name() => { + let raw_series_source = node + .as_any() + .downcast_ref::() + .expect("Failed to downcast to RawSeriesSource"); + Ok(raw_series_source.serialize()) + } name if name == EmptyMetric::name() => Err(DataFusionError::Substrait( "EmptyMetric should not be serialized".to_string(), )), @@ -145,6 +152,9 @@ impl SerializerRegistry for ExtensionSerializer { let union_distinct_on = UnionDistinctOn::deserialize(bytes)?; Ok(Arc::new(union_distinct_on)) } + name if name == RawSeriesSource::name() => { + Ok(Arc::new(RawSeriesSource::deserialize(bytes)?)) + } name if name == EmptyMetric::name() => Err(DataFusionError::Substrait( "EmptyMetric should not be deserialized".to_string(), )), @@ -155,3 +165,91 @@ impl SerializerRegistry for ExtensionSerializer { } } } + +#[cfg(test)] +mod tests { + use datafusion::arrow::datatypes::{DataType, Field, Schema, TimeUnit}; + use datafusion::datasource::{MemTable, provider_as_source}; + use datafusion::execution::SessionStateBuilder; + use datafusion::logical_expr::{Extension, LogicalPlan, LogicalPlanBuilder, col, lit}; + use datafusion::prelude::SessionContext; + + use super::*; + use crate::{DFLogicalSubstraitConvertor, SubstraitPlan}; + + #[tokio::test] + async fn raw_series_source_substrait_roundtrip_restores_scan() { + let table_name = "raw_source_input"; + let input_schema = Arc::new(Schema::new(vec![ + Field::new("z", DataType::Utf8, false), + Field::new("value_b", DataType::Float64, false), + Field::new("value_a", DataType::Float64, false), + Field::new("a", DataType::Utf8, false), + Field::new("unused", DataType::Utf8, true), + Field::new( + "ts", + DataType::Timestamp(TimeUnit::Millisecond, None), + false, + ), + ])); + let provider = Arc::new(MemTable::try_new(input_schema, vec![vec![]]).unwrap()); + let filter = col("raw_source_input.z").eq(lit("web-1")); + let input = LogicalPlanBuilder::scan_with_filters( + table_name, + provider_as_source(provider.clone()), + Some(vec![0, 3, 2, 1, 5]), + vec![filter], + ) + .unwrap() + .build() + .unwrap(); + let LogicalPlan::TableScan(expected_scan) = &input else { + panic!("expected table scan"); + }; + let expected_projection = expected_scan.projection.clone(); + let expected_schema = Arc::clone(&expected_scan.projected_schema); + let expected_filters = expected_scan.filters.clone(); + let source = RawSeriesSource::try_new( + Arc::from("http_requests_total"), + vec!["z".into(), "a".into()], + vec!["value_b".into(), "value_a".into()], + input, + ) + .unwrap(); + let expected_source_schema = Arc::clone(source.schema()); + let plan = LogicalPlan::Extension(Extension { + node: Arc::new(source), + }); + let converter = DFLogicalSubstraitConvertor; + let bytes = converter.encode(&plan, ExtensionSerializer).unwrap(); + let state = SessionStateBuilder::new() + .with_default_features() + .with_serializer_registry(Arc::new(ExtensionSerializer)) + .build(); + let context = SessionContext::new_with_state(state); + context.register_table(table_name, provider).unwrap(); + let decoded = converter.decode(bytes, context.state()).await.unwrap(); + + let LogicalPlan::Extension(extension) = decoded else { + panic!("expected restored RawSeriesSource extension"); + }; + let restored = extension + .node + .as_any() + .downcast_ref::() + .expect("expected RawSeriesSource"); + assert_eq!(restored.metric_name(), "http_requests_total"); + assert_eq!(restored.tags(), ["z", "a"]); + assert_eq!(restored.fields(), ["value_b", "value_a"]); + assert_eq!(restored.schema(), &expected_source_schema); + let inputs = extension.node.inputs(); + assert_eq!(inputs.len(), 1); + let LogicalPlan::TableScan(scan) = inputs[0] else { + panic!("expected restored table scan child, got: {inputs:?}"); + }; + assert_eq!(scan.table_name.to_string(), table_name); + assert_eq!(scan.projection, expected_projection); + assert_eq!(scan.projected_schema, expected_schema); + assert_eq!(scan.filters, expected_filters); + } +} diff --git a/src/datatypes/src/series.rs b/src/datatypes/src/series.rs index 08f4b36bc3b..11595b4de22 100644 --- a/src/datatypes/src/series.rs +++ b/src/datatypes/src/series.rs @@ -30,13 +30,18 @@ use crate::error::{InvalidSeriesSnafu, Result}; /// /// Every series has strictly increasing sample positions, including across chunks; positions /// are raw timestamps or, for evaluated series, current-stage evaluation times or grid positions. -/// They need not all be explicit times on the grid. No mode permits -/// duplicate positions. `Interleaved` permits A1, B1, A2; only the latter two modes keep each -/// series contiguous. `KeyThenTime` also orders by this stream's series identity, then time: +/// They need not all be explicit times on the grid. Within one series or producer fragment, +/// no mode permits duplicate positions. `Interleaved` permits A1, B1, A2; only the latter two modes +/// keep each series contiguous. `KeyThenTime` also orders by this stream's series identity, then time: /// raw streams use the complete bound-compatible identity (not just a TSID or hash), while /// evaluated streams use current name/label identity, not storage primary keys or object address/hash. -/// This ordering -/// is not a query-global ordering, partition-ownership rule, or finality guarantee. +/// This ordering is not a query-global ordering, partition-ownership rule, or finality guarantee. +/// +/// A raw frame adapter accepts only a subset of `Interleaved`: it transports independently closed +/// producer fragment chains in sequence, allowing the same key and overlapping timestamps in +/// different fragment chains. Finality closes a fragment, not necessarily the logical series. The +/// adapter rejects switching keys before a chain closes; it does not support arbitrary multiplexing +/// of open chains, even though the general ordering permits it. #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize, Hash)] pub enum SeriesOrdering { /// Series chunks may interleave; positions within each series remain strictly increasing. diff --git a/src/datatypes/src/series/frame.rs b/src/datatypes/src/series/frame.rs index bc92636bc57..c253c262cdb 100644 --- a/src/datatypes/src/series/frame.rs +++ b/src/datatypes/src/series/frame.rs @@ -33,8 +33,9 @@ //! Packing accumulates bounded multi-row batches: [`SeriesFrameCursor`] walks one validated chunk //! and [`SeriesFrameBuilder`] emits rows directly as Arrow arrays once a row or estimated byte bound //! is reached. Decoding reuses one prepared -//! schema per stream through [`SeriesFrameDecoder`]. Column layout, metadata, and wire strings stay -//! on the frozen `v2` contract; a key-encoded frame additionally declares a versioned +//! schema per stream through [`SeriesFrameDecoder`]. The column layout and existing metadata stay +//! on the `v2` contract. Raw frames may also declare `greptime.series.ordering=interleaved`; older +//! readers that do not recognize this ordering reject it. A key-encoded frame declares a versioned //! [`LabelDecodeSpec`] so its labels can be decoded from the received schema alone, and an evaluated //! frame declares its [`GridSpec`] once instead of repeating timestamps. //! @@ -650,10 +651,11 @@ pub struct SeriesFrameDeclaration { fn validate_ordering(schema: &Schema, content: FrameContent) -> Result<()> { match schema.metadata().get(ORDERING).map(String::as_str) { Some("contiguous") => Ok(()), - Some("read_key_then_time") if content == FrameContent::Raw => Ok(()), + Some("read_key_then_time" | "interleaved") if content == FrameContent::Raw => Ok(()), Some("read_key_then_time") => Err(err( "an evaluated frame cannot claim key-then-time ordering", )), + Some("interleaved") => Err(err("an evaluated frame cannot claim interleaved ordering")), None => Err(err(format!("frame declares no {ORDERING} value"))), Some(_) => Err(err("unknown series ordering")), } diff --git a/src/datatypes/src/series/frame/tests.rs b/src/datatypes/src/series/frame/tests.rs index b16839c5bad..04a212c527a 100644 --- a/src/datatypes/src/series/frame/tests.rs +++ b/src/datatypes/src/series/frame/tests.rs @@ -1800,7 +1800,8 @@ fn direct_decoder_validates_ordering_for_raw_and_evaluated_batches() { for (ordering, accepted) in [ (None, false), (Some("future_value"), false), - (Some("interleaved"), false), + (Some("interleaved"), content == "raw"), + (Some("interv"), false), (Some("contiguous"), true), (Some("read_key_then_time"), content == "raw"), ] { diff --git a/src/promql/src/extension_plan/fused_series.rs b/src/promql/src/extension_plan/fused_series.rs index f2fe15e91dc..3b61d201b12 100644 --- a/src/promql/src/extension_plan/fused_series.rs +++ b/src/promql/src/extension_plan/fused_series.rs @@ -365,6 +365,10 @@ struct FusedSeriesPayload { format: FusedOutputFormat, promql: Arc, output_schema: datafusion::arrow::datatypes::Schema, + /// Whether this node is the partition-local producer of a canonical merge; part of the node's + /// identity, not of where it may be placed. + #[serde(default)] + canonical_producer: bool, } impl FusedSeries { @@ -372,32 +376,12 @@ impl FusedSeries { /// The PromQL text is included for diagnostics only and never drives execution; children /// remain ordinary Substrait inputs. /// - /// A node that reads aggregate state is refused: that is the `Final` half of a split - /// aggregate, which folds every partition's state and so has to run where all of it arrives, - /// not inside one region. The `Partial` half below it exports state rather than reading it, so - /// it travels as an ordinary series-frame producer. + /// This is only the node's own encoding. Whether a planner is allowed to place this node on + /// another machine is a separate decision, made by the planner and the transport, not here. /// /// The envelope is [`FUSED_SERIES_ENVELOPE_VERSION`], the payload's length in bytes, then the /// postcard payload itself. pub fn serialize(&self) -> DataFusionResult> { - if self.canonical_producer { - return Err(DataFusionError::NotImplemented( - "FusedSeries serialization does not support a canonical producer".into(), - )); - } - if self.reads_aggregate_state() { - return Err(DataFusionError::NotImplemented( - "FusedSeries serialization does not support reading aggregate state".into(), - )); - } - // A node that exports state is only ever planned inside the region it reads: the frame's - // `AggregateState` content has no wire form, and the frontend half is what folds it. Refusing - // here is what keeps the state router on one machine instead of trusting the encoder. - if matches!(&self.tree().root().output, NativeType::AggregateState(_)) { - return Err(DataFusionError::NotImplemented( - "FusedSeries serialization does not support exporting aggregate state".into(), - )); - } let payload = FusedSeriesPayload { tree: self.tree.clone(), grid: self.binding.grid.spec(), @@ -407,6 +391,7 @@ impl FusedSeries { format: self.format, promql: Arc::clone(&self.promql), output_schema: self.output_schema.as_arrow().clone(), + canonical_producer: self.canonical_producer, }; let encoded = postcard::to_stdvec(&payload).map_err(|e| { DataFusionError::Plan(format!("cannot serialize FusedSeries payload: {e}")) @@ -463,6 +448,7 @@ impl FusedSeries { format, promql, output_schema, + canonical_producer: _, } = payload; let grid = Arc::new( EvalGrid::try_deferred(grid) @@ -487,8 +473,17 @@ impl FusedSeries { )); } let output_schema = Arc::new(datafusion::common::DFSchema::try_from(output_schema)?); - let node = + let canonical_producer = payload.canonical_producer; + let mut node = Self::try_new_with_format(promql, tree, binding, children, output_schema, format)?; + if canonical_producer { + if !matches!(node.tree.root().expr, NativeExpr::Merge { .. }) { + return Err(DataFusionError::Plan( + "a canonical merge producer requires a merge at the tree's root".into(), + )); + } + node.canonical_producer = true; + } if format == FusedOutputFormat::PlainRows { let schema = Arc::new(node.output_schema.as_arrow().clone()); validate_plain_output_schema( @@ -644,18 +639,11 @@ impl FusedSeries { binding: FusedSeriesBinding, children: Vec, ) -> DataFusionResult { - let NativeExpr::Merge { input } = &tree.root().expr else { + let NativeExpr::Merge { input: _ } = &tree.root().expr else { return Err(DataFusionError::Plan( "a canonical merge producer requires a merge at the tree's root".into(), )); }; - if !matches!(input_locality(input), InputLocality::PartitionLocal) - && !canonical_evaluated_local_prefix(input) - { - return Err(DataFusionError::Plan( - "a canonical merge producer requires a partition-local prefix".into(), - )); - } validate_binding(&tree, &binding, &children)?; let frame = Self::series_frame_schema(&tree)?; let output_schema = Arc::new(datafusion::common::DFSchema::try_from( @@ -706,17 +694,6 @@ impl FusedSeries { .any(|input| matches!(input.output, NativeType::AggregateState(_))) } - /// Whether this node's output carries the metric name its sources report. - /// - /// A nameless selector declares `__name__` without binding one name: the sources fill it in. - /// A `Final` half inherits that arrangement from the producer it reads, which is why the proof - /// has to cross the state boundary rather than stop at a scan. - fn publishes_source_metric_name(&self) -> bool { - self.binding.tags.iter().any(|tag| tag == METRIC_NAME) - && (self.binding.metric_name.is_some() - || self.children().iter().all(source_names_its_metric)) - } - /// The compiled tree this node runs. pub fn tree(&self) -> &NativeTree { &self.tree @@ -866,6 +843,26 @@ impl FusedSeries { return Ok((routed, RawLabelSource::Explicit, ordering)); } if declaration.content() != FrameContent::Evaluated { + let count = input.properties().partitioning.partition_count(); + if count == 0 { + return Err(DataFusionError::Plan(format!( + "FusedSeries input {index} has no partitions" + ))); + } + // Region streams may each close the same storage key. Reconcile those + // fragments even when the merged stream has only one output partition. + let (input, label_source, ordering) = if ordering == SeriesOrdering::Interleaved + { + let width = if normalize { 1 } else { count }; + let input = Arc::new(SeriesRepartitionExec::try_new_with_routing( + input, + width, + SeriesRouting::RawPrimaryKey, + )?) as Arc; + (input, RawLabelSource::Explicit, SeriesOrdering::Contiguous) + } else { + (input, label_source, ordering) + }; let count = input.properties().partitioning.partition_count(); if normalize && count != 1 { let input = Arc::new(SeriesRepartitionExec::try_new(input, 1)?) @@ -1407,36 +1404,6 @@ fn preserves_matching_key(node: &NativeNode, matching: &MatchingLabels) -> bool } } -/// Whether this input reports the metric each of its rows came from, by naming it itself. -/// -/// A discovered selector binds one source per metric, so the name comes from the sources rather -/// than from a single name on the node. -fn source_names_its_metric(plan: &LogicalPlan) -> bool { - match plan { - LogicalPlan::Extension(extension) => { - if let Some(source) = extension - .node - .as_any() - .downcast_ref::() - { - return !source.metric_name().is_empty(); - } - // A split's final half reads its producer's state, and the producer is the node that - // named the metric: it either bound one name or was itself built over sources that do. - extension - .node - .as_any() - .downcast_ref::() - .is_some_and(FusedSeries::publishes_source_metric_name) - } - LogicalPlan::Union(union) => union - .inputs - .iter() - .all(|input| source_names_its_metric(input)), - _ => false, - } -} - /// Whether matching operands can be segmented as independent single-source computations and /// at least one fails to preserve the requested key. /// @@ -1677,15 +1644,6 @@ fn validate_binding( binding: &FusedSeriesBinding, children: &[LogicalPlan], ) -> DataFusionResult<()> { - // A `__name__` tag is filled either by one bound metric name or by the sources themselves. - if binding.tags.iter().any(|tag| tag == METRIC_NAME) - && binding.metric_name.is_none() - && !children.iter().all(source_names_its_metric) - { - return Err(DataFusionError::Plan(format!( - "FusedSeries declares {METRIC_NAME:?} but binds no metric name" - ))); - } let schemas = collect_source_schemas(tree)?; // A tree built without its constructor carries no proof of its contracts, and one without an // input has no scan to refuse it later. diff --git a/src/promql/src/extension_plan/fused_series/tests.rs b/src/promql/src/extension_plan/fused_series/tests.rs index 8162f440aa6..576e32ae8e8 100644 --- a/src/promql/src/extension_plan/fused_series/tests.rs +++ b/src/promql/src/extension_plan/fused_series/tests.rs @@ -1345,6 +1345,93 @@ impl Drop for StagedStream { } } +fn canonical_producer_node() -> FusedSeries { + let grid = grid(); + let schema = Arc::new(SeriesSchema { + fields: raw_schema().fields.clone(), + eval_grid: Some(Arc::clone(&grid)), + }); + let evaluated = NativeType::Samples(Arc::clone(&schema)); + let raw = NativeType::Samples(raw_schema()); + let input = NativeNode { + expr: NativeExpr::Input(BoundInput { + output: raw.clone(), + source_index: 0, + ordering: SeriesOrdering::Contiguous, + }), + output: raw, + }; + let window = NativeNode { + expr: NativeExpr::Window { + input: Box::new(input), + op: BoundWindow { + function: RangeFunction::LastOverTime, + window: RangeWindow { + range_ms: 1, + offset_ms: 0, + anchor_ms: None, + modifier: None, + }, + input_grid: None, + output_grid: Arc::clone(&grid), + }, + }, + output: evaluated.clone(), + }; + let map = NativeNode { + expr: NativeExpr::Map { + input: Box::new(window), + op: BoundMap { + ops: Arc::from([MapOp::Label(Arc::new( + LabelRewrite::replace("host", "web-1", "host", "web-.*").unwrap(), + ))]), + }, + }, + output: evaluated.clone(), + }; + let tree = NativeTree::try_new(NativeNode { + expr: NativeExpr::Merge { + input: Box::new(map), + }, + output: evaluated, + }) + .unwrap(); + FusedSeries::try_new_canonical_producer( + Arc::from(PROMQL), + tree.clone(), + binding(&tree), + vec![input_plan(frame_schema())], + ) + .unwrap() +} + +#[test] +fn fused_series_encoding_preserves_state_and_canonical_producer() { + // A state-exporting producer encodes like any other node: serialization is the node's own + // capability, not a decision about where it may run. + let tree = partial_tree(rate_tree(), AggregateKind::Sum, &[HOST, JOB]); + let producer = FusedSeries::try_new_state_export( + Arc::from(PROMQL), + tree.clone(), + binding(&tree), + vec![input_plan(frame_schema())], + ) + .unwrap(); + let decoded = FusedSeries::deserialize(&producer.serialize().unwrap()).unwrap(); + assert_eq!(decoded.tree(), producer.tree()); + assert_eq!(decoded.binding(), producer.binding()); + assert_eq!(decoded.schema(), producer.schema()); + assert!(decoded.reads_aggregate_state() == producer.reads_aggregate_state()); + + // A canonical producer's flag is part of the node, so it survives the round trip; the + // decoder does not get to decide whether its prefix is partition-local. + let canonical = canonical_producer_node(); + let decoded = FusedSeries::deserialize(&canonical.serialize().unwrap()).unwrap(); + assert!(decoded.is_canonical_producer()); + assert_eq!(decoded.tree(), canonical.tree()); + assert_eq!(decoded.schema(), canonical.schema()); +} + #[test] fn fused_series_ordinary_encoding_round_trip_and_rejects_unsupported_payloads() { let tree = rate_tree(); @@ -1412,17 +1499,12 @@ fn fused_series_ordinary_encoding_round_trip_and_rejects_unsupported_payloads() let projected_decoded = FusedSeries::deserialize(&projected_bytes).unwrap(); assert_eq!(projected_decoded.schema(), projected.schema()); - // A state-exporting producer never crosses the wire: the frame's state content has no wire - // form, so the producer stays on the machine that reads the samples. + // A state-exporting producer encodes like any other node; where it may run is decided by the + // planner, not by the codec. let partial = partial_node(AggregateKind::Sum); - assert!( - partial - .serialize() - .unwrap_err() - .to_string() - .contains("exporting aggregate state"), - "a state-exporting producer must be refused by the serializer" - ); + let partial_decoded = FusedSeries::deserialize(&partial.serialize().unwrap()).unwrap(); + assert_eq!(partial_decoded.tree(), partial.tree()); + assert_eq!(partial_decoded.schema(), partial.schema()); let mut bad_version = bytes.clone(); bad_version[..4].copy_from_slice(&99u32.to_le_bytes()); assert!( @@ -2672,6 +2754,189 @@ fn repeated_source_bindings_validate_fields_and_second_ordering() { assert!(error.to_string().contains("ordering"), "{error}"); } +#[test] +fn fragmented_raw_input_is_reconciled_even_at_width_one() { + use crate::extension_plan::{IdentityCompletion, SeriesRepartitionExec, SeriesRouting}; + use common_query::series_frame::frame_schema_with; + + let make_input = |ordering| { + let declaration = SeriesFrameDeclaration::parse(frame_schema().as_ref()).unwrap(); + let schema = frame_schema_with( + declaration.series(), + declaration.labels(), + declaration.label_decode(), + ordering, + ) + .unwrap(); + memory_exec_with(schema, Vec::new()) + }; + for ordering in [SeriesOrdering::Contiguous, SeriesOrdering::Interleaved] { + let plan = fused(rate_tree()) + .to_execution_plan(vec![( + make_input(ordering), + RawLabelSource::Explicit, + ordering, + )]) + .unwrap(); + let child = plan.children()[0]; + if ordering == SeriesOrdering::Interleaved { + let router = child + .downcast_ref::() + .expect("fragmented input needs an owner even for one partition"); + assert_eq!(router.routing_policy(), &SeriesRouting::RawPrimaryKey); + assert_eq!( + router.identity_completion(), + IdentityCompletion::MergeInputs + ); + assert_eq!(router.outputs(), 1); + assert_eq!( + series_frame_ordering(child.schema().as_ref()).unwrap(), + SeriesOrdering::Contiguous + ); + } else { + assert!( + child.downcast_ref::().is_none(), + "disjoint input needs no router" + ); + } + } +} + +/// Disjoint regional streams keep their contiguous guarantee and need no raw owner. +#[tokio::test] +async fn contiguous_raw_input_runs_rate_directly_at_any_width() { + use crate::extension_plan::SeriesRepartitionExec; + + let samples = series_samples(1.0); + let region_batch = |key, samples: &[(i64, f64)]| { + let batch = frame(&series_chunk(key, samples, true)); + RecordBatch::try_new(frame_schema(), batch.columns().to_vec()).unwrap() + }; + let first = region_batch("web-1", &samples); + let second = region_batch("web-2", &samples); + for partitions in [ + vec![vec![first.clone(), second.clone()]], + vec![vec![first.clone()], vec![second.clone()]], + ] { + let input = memory_exec_partitioned_with(frame_schema(), partitions); + let exec = fused(rate_tree()) + .to_execution_plan(vec![( + input, + RawLabelSource::Explicit, + SeriesOrdering::Contiguous, + )]) + .unwrap(); + assert!( + exec.children()[0] + .downcast_ref::() + .is_none(), + "disjoint contiguous input needs no reconciliation" + ); + let batches = collect(exec, SessionContext::default().task_ctx()) + .await + .unwrap(); + assert_series_rates(&rows(&batches), &[(1.0, "web-1"), (1.0, "web-2")]); + } +} + +/// Two region-local chains of one key produce one rate series at either transport width. +#[tokio::test] +async fn fragmented_raw_input_merges_region_chains_before_rate() { + use common_query::series_frame::frame_schema_with; + + let declaration = SeriesFrameDeclaration::parse(frame_schema().as_ref()).unwrap(); + let schema = frame_schema_with( + declaration.series(), + declaration.labels(), + declaration.label_decode(), + SeriesOrdering::Interleaved, + ) + .unwrap(); + let samples = series_samples(1.0); + let region_batch = |samples: &[(i64, f64)]| { + let batch = frame(&series_chunk("web-1", samples, true)); + RecordBatch::try_new(schema.clone(), batch.columns().to_vec()).unwrap() + }; + let early = region_batch(&samples[..5]); + let late = region_batch(&samples[5..]); + for partitions in [ + vec![vec![early.clone(), late.clone()]], + vec![vec![early.clone()], vec![late.clone()]], + ] { + let input = memory_exec_partitioned_with(schema.clone(), partitions); + let exec = fused(rate_tree()) + .to_execution_plan(vec![( + input, + RawLabelSource::Explicit, + SeriesOrdering::Interleaved, + )]) + .unwrap(); + let batches = collect(exec, SessionContext::default().task_ctx()) + .await + .unwrap(); + assert_series_rates(&rows(&batches), &[(1.0, "web-1")]); + } +} + +#[test] +fn fragmented_raw_multi_input_is_reconciled_before_matching_router() { + use crate::extension_plan::{SeriesRepartitionExec, SeriesRouting}; + use common_query::series_frame::frame_schema_with; + let tree = binary_tree_over_sources(BinaryOp::Add, raw_schema(), raw_schema(), 0, 1); + let node = FusedSeries::try_new( + Arc::from("left + right"), + tree.clone(), + binding(&tree), + vec![input_plan(frame_schema()), input_plan(frame_schema())], + binary_output_schema().to_dfschema_ref().unwrap(), + ) + .unwrap(); + let declaration = SeriesFrameDeclaration::parse(frame_schema().as_ref()).unwrap(); + let schema = frame_schema_with( + declaration.series(), + declaration.labels(), + declaration.label_decode(), + SeriesOrdering::Interleaved, + ) + .unwrap(); + let input = || memory_exec_partitioned_with(schema.clone(), vec![vec![], vec![]]); + let exec = node + .to_execution_plan_with_parallelism( + vec![ + ( + input(), + RawLabelSource::Explicit, + SeriesOrdering::Interleaved, + ), + ( + input(), + RawLabelSource::Explicit, + SeriesOrdering::Interleaved, + ), + ], + 2, + ) + .unwrap(); + for child in exec.children() { + let matching = child + .downcast_ref::() + .expect("matching router"); + assert!(matches!( + matching.routing_policy(), + SeriesRouting::Matching(_) + )); + let matching_children = child.children(); + let owner = matching_children[0] + .downcast_ref::() + .expect("raw owner below matching router"); + assert_eq!(owner.routing_policy(), &SeriesRouting::RawPrimaryKey); + assert_eq!( + series_frame_ordering(child.schema().as_ref()).unwrap(), + SeriesOrdering::Contiguous + ); + } +} + /// Logical trees with distinct dense sources are accepted by the physical adapter. #[tokio::test] async fn logical_two_source_tree_is_accepted_by_physical_adapter() { diff --git a/src/promql/src/extension_plan/planner.rs b/src/promql/src/extension_plan/planner.rs index 9d1436bd622..4a5ec7b20f7 100644 --- a/src/promql/src/extension_plan/planner.rs +++ b/src/promql/src/extension_plan/planner.rs @@ -22,6 +22,10 @@ use datafusion::error::{DataFusionError, Result as DfResult}; use datafusion::logical_expr::physical_planning_context::PhysicalPlanningContext; use datafusion::logical_expr::{LogicalPlan, UserDefinedLogicalNode}; use datafusion::physical_plan::ExecutionPlan; +use datafusion::physical_plan::PhysicalExpr; +use datafusion::physical_plan::expressions::Column; +use datafusion::physical_plan::projection::ProjectionExec; +use datafusion::physical_plan::union::UnionExec; use datafusion::physical_planner::{ExtensionPlanner, PhysicalPlanner}; use datatypes::series::SeriesOrdering; use datatypes::series::frame::{FrameLabelMode, SeriesFrameDeclaration}; @@ -122,7 +126,11 @@ fn plan_fused_series( .to_execution_plan_with_parallelism(Vec::new(), target_partitions) .map(Some); } - if let Some(inputs) = physical_inputs + let explicit_inputs = physical_inputs + .iter() + .map(normalize_raw_union) + .collect::>>()?; + if let Some(inputs) = explicit_inputs .iter() .map(|input| { explicit_label_frame_ordering(input.schema().as_ref()) @@ -250,6 +258,65 @@ fn series_scan( } /// The ordering an input declares when it produces raw frames that carry their own labels. +/// Restate a raw union's ordering as the weakest guarantee its members make. +/// +/// `UnionExec` reports the frame metadata of its last child, so a fragmented member beside one +/// whose series are complete can look contiguous, and the fused node would skip the reconciliation +/// of the fragments. The union itself is not rewritten; only the declaration on this edge is +/// lowered, and the fused node's own interleaved-input path inserts the router. +fn normalize_raw_union(input: &Arc) -> DfResult> { + let Some(union) = input.downcast_ref::() else { + return Ok(Arc::clone(input)); + }; + if explicit_label_frame_ordering(input.schema().as_ref()) != Some(SeriesOrdering::Contiguous) + || weakest_union_ordering(union) != SeriesOrdering::Interleaved + { + return Ok(Arc::clone(input)); + } + let mut metadata = input.schema().metadata().clone(); + metadata.insert(RAW_SERIES_ORDERING_KEY.into(), "interleaved".into()); + let schema = Arc::new(Schema::new_with_metadata( + input.schema().fields().clone(), + metadata, + )); + let exprs = input + .schema() + .fields() + .iter() + .enumerate() + .map(|(index, field)| { + ( + Arc::new(Column::new(field.name(), index)) as Arc, + field.name().clone(), + ) + }) + .collect::>(); + Ok(Arc::new(ProjectionExec::try_new_with_schema_metadata( + exprs, + Arc::clone(input), + schema.as_ref(), + )?)) +} + +/// The schema metadata key a frame's ordering is declared under; see +/// [`common_query::series_frame`]. +const RAW_SERIES_ORDERING_KEY: &str = "greptime.series.ordering"; + +/// The weakest ordering any member of this union declares. A member that is itself a union is +/// asked the same question; a member that already reconciles keeps its own guarantee. +fn weakest_union_ordering(union: &UnionExec) -> SeriesOrdering { + union + .children() + .iter() + .map(|child| match child.downcast_ref::() { + Some(nested) => weakest_union_ordering(nested), + None => explicit_label_frame_ordering(child.schema().as_ref()) + .unwrap_or(SeriesOrdering::Contiguous), + }) + .find(|ordering| *ordering == SeriesOrdering::Interleaved) + .unwrap_or(SeriesOrdering::Contiguous) +} + fn explicit_label_frame_ordering(schema: &Schema) -> Option { let declaration = SeriesFrameDeclaration::parse(schema).ok()?; if declaration.labels() != FrameLabelMode::Explicit { @@ -257,3 +324,79 @@ fn explicit_label_frame_ordering(schema: &Schema) -> Option { } series_frame_ordering(schema).ok() } + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use common_query::series_frame::{ + raw_series_frame_schema_with_ordering, series_frame_ordering, + }; + use datafusion::physical_plan::ExecutionPlan; + use datafusion::physical_plan::empty::EmptyExec; + use datafusion::physical_plan::union::UnionExec; + use datatypes::series::SeriesOrdering; + use datatypes::series::samples::{FieldSpec, SeriesSchema}; + + use super::normalize_raw_union; + + fn raw_frame(ordering: SeriesOrdering) -> Arc { + let series = SeriesSchema { + fields: vec![FieldSpec { + name: Arc::from("val"), + }] + .into(), + eval_grid: None, + }; + raw_series_frame_schema_with_ordering( + &series, + &store_api::region_engine::RawLabelSource::Explicit, + ordering, + ) + .expect("a raw schema declares an explicit-label frame") + } + + fn union(children: &[SeriesOrdering]) -> Arc { + let children = children + .iter() + .map(|ordering| { + Arc::new(EmptyExec::new(raw_frame(*ordering))) as Arc + }) + .collect::>(); + UnionExec::try_new(children).expect("two framed children") + } + + /// A union reports the ordering of its last child. The declaration this edge hands to the + /// fused node must instead be the weakest of the members, in either order, and must stay the + /// union's own when every member is complete. + #[test] + fn raw_union_declaration_lowers_to_the_weakest_member() { + for members in [ + vec![SeriesOrdering::Interleaved, SeriesOrdering::Contiguous], + vec![SeriesOrdering::Contiguous, SeriesOrdering::Interleaved], + ] { + let union = union(&members); + assert_eq!( + series_frame_ordering(union.schema().as_ref()).unwrap(), + *members.last().unwrap(), + "the union itself keeps its last child's declaration" + ); + let normalized = + normalize_raw_union(&Arc::clone(&union)).expect("a raw union normalizes"); + assert_eq!( + series_frame_ordering(normalized.schema().as_ref()).unwrap(), + SeriesOrdering::Interleaved, + "the fused edge sees the weakest member" + ); + } + + let union = union(&[SeriesOrdering::Contiguous, SeriesOrdering::Contiguous]); + let normalized = normalize_raw_union(&(Arc::clone(&union) as Arc)) + .expect("a raw union normalizes"); + assert_eq!( + series_frame_ordering(normalized.schema().as_ref()).unwrap(), + SeriesOrdering::Contiguous, + "nothing is lowered when every member is complete" + ); + } +} diff --git a/src/promql/src/extension_plan/raw_series_source.rs b/src/promql/src/extension_plan/raw_series_source.rs index 68d0bb40bc8..d42c81367bd 100644 --- a/src/promql/src/extension_plan/raw_series_source.rs +++ b/src/promql/src/extension_plan/raw_series_source.rs @@ -52,6 +52,8 @@ use datatypes::series::frame::LabelDecodeSpec; use datatypes::series::raw::RawSeriesChunk; use datatypes::series::samples::{FieldSpec, SeriesSchema}; use futures::Stream; +use greptime_proto::substrait_extension::RawSeriesSource as RawSeriesSourceProto; +use prost::Message; use store_api::region_engine::{RawLabelSource, RawSeriesStream, SendableRawSeriesStream}; use table::table::scan::SeriesScanExec; @@ -64,6 +66,7 @@ use crate::source::materialize_raw_labels; /// output always keeps: one scan partition emits one series after another, so each series stays /// contiguous, while the finer key-then-time order of the scan is not repeated here. const ORDERING: SeriesOrdering = SeriesOrdering::Contiguous; +const WIRE_VERSION: u32 = 1; /// The logical node: one table scan bound to one metric's raw series. #[derive(Debug, PartialEq, Eq, Hash)] @@ -110,6 +113,40 @@ impl RawSeriesSource { &self.fields } + /// Encodes only the binding; Substrait carries the input plan separately. + pub fn serialize(&self) -> Vec { + RawSeriesSourceProto { + version: WIRE_VERSION, + metric_name: self.metric_name.to_string(), + tags: self.tags.clone(), + fields: self.fields.clone(), + } + .encode_to_vec() + } + + /// Decodes a binding with a placeholder, replaced when Substrait restores the child. + pub fn deserialize(bytes: &[u8]) -> DataFusionResult { + let binding = RawSeriesSourceProto::decode(bytes).map_err(|error| { + DataFusionError::Substrait(format!("Failed to deserialize RawSeriesSource: {error}")) + })?; + if binding.version != WIRE_VERSION { + return Err(DataFusionError::Substrait(format!( + "Unsupported RawSeriesSource version: {}", + binding.version + ))); + } + let input = LogicalPlan::EmptyRelation(datafusion::logical_expr::EmptyRelation { + produce_one_row: false, + schema: Arc::new(DFSchema::empty()), + }); + Self::try_new( + Arc::from(binding.metric_name), + binding.tags, + binding.fields, + input, + ) + } + /// The physical node over `series_scan`, the region's raw-series leaf for this binding. pub fn to_per_series_execution_plan( &self, @@ -382,3 +419,96 @@ impl ExecutionPlan for RawSeriesSourceExec { pack_raw_series(Box::pin(DeclaredOrdering(relabelled))) } } + +#[cfg(test)] +mod tests { + use datafusion::arrow::datatypes::DataType; + use datafusion::logical_expr::EmptyRelation; + + use super::*; + + const FIXTURE: &str = + include_str!("../../../../tests/compatibility/wire/raw_series_source/v1_payload.hex"); + + fn fixture_bytes() -> Vec { + let hex = FIXTURE.trim().as_bytes(); + assert_eq!(hex.len() % 2, 0); + hex.as_chunks::<2>() + .0 + .iter() + .map(|pair| u8::from_str_radix(std::str::from_utf8(pair).unwrap(), 16).unwrap()) + .collect() + } + + #[test] + fn raw_series_source_wire_fixture() { + let bytes = fixture_bytes(); + let source = RawSeriesSource::deserialize(&bytes).unwrap(); + assert_eq!(source.metric_name(), "http_requests_total"); + assert_eq!(source.tags(), ["z", "a"]); + assert_eq!(source.fields(), ["value_b", "value_a"]); + assert_eq!(source.serialize(), bytes); + assert!(matches!( + source.inputs()[0], + LogicalPlan::EmptyRelation(EmptyRelation { + produce_one_row: false, + .. + }) + )); + + let field = source.schema().field_with_name(None, "fields").unwrap(); + let DataType::Struct(fields) = field.data_type() else { + panic!("expected struct field in frame schema"); + }; + assert_eq!( + fields + .iter() + .map(|field| field.name().as_str()) + .collect::>(), + ["value_b", "value_a"] + ); + + let child = LogicalPlan::EmptyRelation(EmptyRelation { + produce_one_row: true, + schema: Arc::new(DFSchema::empty()), + }); + let rebound = source + .with_exprs_and_inputs(vec![], vec![child.clone()]) + .unwrap(); + assert_eq!(rebound.inputs(), vec![&child]); + assert_eq!(rebound.schema(), source.schema()); + assert_eq!(rebound.serialize(), bytes); + assert!(source.with_exprs_and_inputs(vec![], vec![]).is_err()); + assert!( + source + .with_exprs_and_inputs(vec![], vec![child.clone(), child]) + .is_err() + ); + } + + #[test] + fn raw_series_source_wire_rejects_unsupported_and_truncated_payloads() { + let fixture = fixture_bytes(); + for version in [0, 2] { + let mut bytes = fixture.clone(); + bytes[1] = version; + let error = RawSeriesSource::deserialize(&bytes).unwrap_err(); + assert!( + error + .to_string() + .contains("Unsupported RawSeriesSource version") + ); + } + let error = RawSeriesSource::deserialize(&fixture[..fixture.len() - 1]).unwrap_err(); + assert!( + error + .to_string() + .contains("Failed to deserialize RawSeriesSource") + ); + + // Unknown protobuf fields do not invalidate a known binding version. + let mut bytes = fixture; + bytes.extend([0x28, 0x01]); + assert!(RawSeriesSource::deserialize(&bytes).is_ok()); + } +} diff --git a/src/promql/src/extension_plan/series_repartition.rs b/src/promql/src/extension_plan/series_repartition.rs index 7db5613eb43..03f20681254 100644 --- a/src/promql/src/extension_plan/series_repartition.rs +++ b/src/promql/src/extension_plan/series_repartition.rs @@ -17,13 +17,15 @@ //! Canonical routing hashes complete labels; matching routing hashes the evaluator's own PromQL //! matching key. Routing groups are not merge identities: evaluated series merge only by exact name //! and tags. Raw ownership is the complete primary key plus exact label agreement; each input's -//! complete chain or EOF establishes its contribution to a raw identity. +//! complete chain or EOF establishes its contribution to a raw identity for contiguous inputs. +//! An interleaved raw frame here consists of concatenated, independently closed producer chains; +//! identities can recur, but open chains cannot be multiplexed. The owner retains those raw +//! identities until every input reaches normal EOF, then reconstructs contiguous output. //! //! Chains are transported intact to owners with their input-partition ID, followed by one charged -//! normal-EOF message per live output from each completed input. Owners group exact identities and -//! may publish an identity as soon as every input has contributed its final chain or normal EOF. The -//! frame is the child's own: evaluated chunks are decoded only to read routing labels; aggregate-state -//! batches are schema-checked and read only for routing labels. Outputs publish the child's layout. +//! normal-EOF message per live output from each completed input. Owners group exact identities and, +//! except for interleaved raw input, may publish an identity as soon as every input has contributed +//! its final chain or normal EOF. Evaluated chunks are decoded only to read routing labels. //! //! # Routing //! @@ -46,8 +48,9 @@ //! before routing it as one atomic unit. This prevents chains from interleaving during transport; it //! does not establish the output order or final series boundaries. For a full exact identity (metric //! name and every tag name/value), the input contract is that each identity closes at most once per -//! input. Each owner therefore waits only for each distinct input's final chain or normal EOF before -//! merging and publishing that identity. +//! input, except for the independently closed chains of an interleaved raw frame. Each owner waits +//! for each distinct input's final chain or normal EOF before merging a contiguous identity, and +//! for all input EOFs before merging an interleaved raw identity. //! //! What that costs is stated rather than hidden. Nothing of a chain is handed over before the chain //! closes, so the first chunk of a series reaches its output later than a chunk-at-a-time design would @@ -78,7 +81,8 @@ //! //! Producer queues are unbounded: unread owners do not stall routing, but their retained chains //! continue to consume pool-accounted memory. Owners publish each exact identity after its per-input -//! close/EOF barrier, with finality recomputed for that output series. +//! close/EOF barrier, or all input EOFs for interleaved raw frames, with finality recomputed for +//! that output series. //! //! # Memory, backpressure and end of stream //! @@ -194,7 +198,7 @@ pub enum IdentityCompletion { /// its own output from it. pub struct SeriesRepartitionExec { input: Arc, - /// The frame the child declares, re-declared by every output batch. + /// The child frame's series schema, re-declared by every output batch. series_schema: Arc, /// The one hash configuration of this node's execution. routing: Routing, @@ -254,7 +258,8 @@ impl SeriesRepartitionExec { FrameContent::Raw => SeriesRouting::RawPrimaryKey, FrameContent::AggregateState => { return Err(DataFusionError::NotImplemented( - "SeriesRepartition does not route aggregate state; use StateRepartitionExec" + "a complete-disjoint router cannot prove aggregate state ownership; use the \ + ordinary canonical-label routing for state frames" .into(), )); } @@ -330,6 +335,19 @@ impl SeriesRepartitionExec { } else { SeriesOrdering::Contiguous }; + if content == FrameContent::Raw + && ordering == SeriesOrdering::Interleaved + && identity_completion == IdentityCompletion::CompleteDisjoint + { + return Err(DataFusionError::Plan( + "SeriesRepartition cannot use CompleteDisjoint with interleaved raw input".into(), + )); + } + let output_ordering = if ordering == SeriesOrdering::Interleaved { + SeriesOrdering::Contiguous + } else { + ordering + }; let declared = match content { FrameContent::Evaluated => common_query::series_frame::frame_schema_with( &series_schema, @@ -340,7 +358,7 @@ impl SeriesRepartitionExec { FrameContent::Raw => raw_series_frame_schema_with_ordering( &series_schema, &store_api::region_engine::NO_BOUND_LABEL_SOURCE, - ordering, + output_ordering, )?, FrameContent::AggregateState => input.schema(), }; @@ -368,8 +386,12 @@ impl SeriesRepartitionExec { let properties = PlanProperties::new( EquivalenceProperties::new(declared), Partitioning::UnknownPartitioning(outputs), - // Each exact identity becomes final independently at its per-input close/EOF barrier. - EmissionType::Incremental, + // Interleaved raw identities can recur until every input has ended. + if ordering == SeriesOrdering::Interleaved { + EmissionType::Final + } else { + EmissionType::Incremental + }, // The node ends when its child does, and spends its life waiting until then. input.properties().boundedness, ) @@ -549,7 +571,11 @@ impl ExecutionPlan for SeriesRepartitionExec { let raw = RawOutputStream { inner: Some(Box::pin(inner)), schema: Arc::clone(&self.series_schema), - ordering: self.ordering, + ordering: if self.ordering == SeriesOrdering::Interleaved { + SeriesOrdering::Contiguous + } else { + self.ordering + }, }; pack_raw_series(Box::pin(raw))? } @@ -1973,7 +1999,8 @@ struct PendingGroup { /// A key-then-time raw frame promises its keys arrive in order, and this owner publishes in key /// order only when it publishes them together: an identity that is complete while a smaller one is /// still waiting would go out first and break that promise. Watermarks let it publish once every -/// input has advanced past the identity, without waiting for every input to end. +/// input has advanced past the identity, without waiting for every input to end. An interleaved +/// raw identity can recur even after an input contributed, so only all normal EOFs complete it. fn group_ready( group: &PendingGroup, eof: &[bool], @@ -1982,6 +2009,9 @@ fn group_ready( completion: IdentityCompletion, key: &OwnerKey, ) -> bool { + if ordering == SeriesOrdering::Interleaved && matches!(key, OwnerKey::Raw(_)) { + return eof.iter().all(|eof| *eof); + } if ordering == SeriesOrdering::KeyThenTime { let OwnerKey::Raw(key) = key else { return false; @@ -2106,7 +2136,7 @@ struct RepartitionStream { lease: OutputLease, schema: Arc, pool: Arc, - /// What the frame this stream emits declares about the order of its keys. + /// The input's ordering and identity completion guarantee. ordering: SeriesOrdering, identity_completion: IdentityCompletion, groups: BTreeMap, @@ -2253,10 +2283,10 @@ impl RepartitionStream { impl RepartitionStream { /// Publishes one complete raw identity. /// - /// Raw pieces are only published once every input reached its normal EOF, because a piece's - /// `is_last` closes that producer's stream, not the series. The workspace this reconstruction - /// needs is charged before it runs and rides with the output until the packer hands the batch - /// off, like any other owner output. + /// A piece's `is_last` closes that producer's chain, not the reconstructed series. For + /// interleaved input, pieces are retained until every input reaches normal EOF. The workspace + /// reconstruction needs is charged as it runs and rides with the output until the packer + /// hands the batch off, like any other owner output. fn finish_raw_group(&mut self, group: PendingGroup) -> DataFusionResult<()> { let labels = group .raw_chunks @@ -2458,6 +2488,12 @@ impl Stream for RepartitionStream { _metadata, })) => { drained += 1; + if input >= this.eof.len() { + this.lease.fail(Arc::new(DataFusionError::Execution( + "series repartition input index is out of range".into(), + ))); + continue; + } let (key, pieces) = match chain { RoutedChain::Evaluated(chain) => { let Some(first) = chain.first() else { @@ -2526,7 +2562,11 @@ impl Stream for RepartitionStream { ))); continue; }; - if input >= group.received.len() || group.received[input] { + if input >= group.received.len() + || (group.received[input] + && !(this.ordering == SeriesOrdering::Interleaved + && matches!(&key, OwnerKey::Raw(_)))) + { this.lease.fail(Arc::new(DataFusionError::Execution( "input repeated an exact series identity".into(), ))); diff --git a/src/promql/src/extension_plan/series_repartition/tests.rs b/src/promql/src/extension_plan/series_repartition/tests.rs index d5ef85e2182..d374594144b 100644 --- a/src/promql/src/extension_plan/series_repartition/tests.rs +++ b/src/promql/src/extension_plan/series_repartition/tests.rs @@ -648,6 +648,7 @@ struct RawScript { ordering: SeriesOrdering, gate: Option>, gate_chunks: bool, + fail_after_gate: bool, } impl Stream for RawScript { @@ -669,6 +670,11 @@ impl Stream for RawScript { gate.wait(cx); return Poll::Pending; } + if std::mem::take(&mut self.fail_after_gate) { + return Poll::Ready(Some(Err(boxed(DataFusionError::Execution( + "late raw scripted failure".into(), + ))))); + } Poll::Ready(None) } } @@ -694,6 +700,7 @@ struct RawScripted { series_schema: Arc, decode: Option, ordering: SeriesOrdering, + fail_after_gate: bool, properties: Arc, } @@ -706,6 +713,14 @@ impl RawScripted { fn plan_with_ordering( partitions: Vec, ordering: SeriesOrdering, + ) -> Arc { + Self::plan_with_ordering_and_failure(partitions, ordering, false) + } + + fn plan_with_ordering_and_failure( + partitions: Vec, + ordering: SeriesOrdering, + fail_after_gate: bool, ) -> Arc { let series_schema = raw_schema(); let frame = common_query::series_frame::raw_series_frame_schema_with_ordering( @@ -725,6 +740,7 @@ impl RawScripted { series_schema, decode: None, ordering, + fail_after_gate, properties, }) } @@ -754,6 +770,7 @@ impl RawScripted { series_schema, decode: Some(decode), ordering: SeriesOrdering::KeyThenTime, + fail_after_gate: false, properties, }) } @@ -815,6 +832,7 @@ impl ExecutionPlan for RawScripted { ordering: self.ordering, gate: spec.gate, gate_chunks: spec.gate_chunks, + fail_after_gate: self.fail_after_gate, })) } } diff --git a/src/query/src/datafusion.rs b/src/query/src/datafusion.rs index 7a037893f1b..b850525b028 100644 --- a/src/query/src/datafusion.rs +++ b/src/query/src/datafusion.rs @@ -75,6 +75,7 @@ use crate::options::ScheduledTimeExtension; use crate::physical_wrapper::PhysicalPlanWrapperRef; use crate::planner::{DfLogicalPlanner, LogicalPlanner}; use crate::query_engine::{DescribeResult, QueryEngineContext, QueryEngineState}; +use crate::region_query::RegionReadLimiter; use crate::{QueryEngine, metrics}; /// Query parallelism hint key. @@ -188,6 +189,18 @@ impl DatafusionQueryEngine { physical_plan }; + // A region read is a remote body that streams until drained, so a query reading several + // sources would otherwise run one body per source and partition. Bound the reads of the + // plan shape that can hold the budget: the native raw PromQL topology, whose only + // multi-input node polls every input at once. A plan with any other multi-input node (a + // join, or the union a discovered selector builds) keeps its per-scan bounds only rather + // than take a query-wide budget its topology has not been checked against. + if crate::promql::planner::native::native_raw_plan_bounds_region_reads(&physical_plan) { + let target_partitions = ctx.state().config().target_partitions(); + ctx.config_mut() + .set_extension(Arc::new(RegionReadLimiter::new(target_partitions))); + } + let stream = self.execute_stream(&ctx, &physical_plan)?; Ok(Output::new( diff --git a/src/query/src/dist_plan/analyzer.rs b/src/query/src/dist_plan/analyzer.rs index 8d747d5fd7d..e641579e12d 100644 --- a/src/query/src/dist_plan/analyzer.rs +++ b/src/query/src/dist_plan/analyzer.rs @@ -448,9 +448,6 @@ enum RewriterStatus { struct PlanRewriter { /// Whether the whole plan encodes, allowing per-node checks to be skipped. whole_plan_encodable: bool, - /// In-process root shapes can contain the `Final` half of a split aggregate, which reads every - /// partition's state and so has no Substrait serializer. - skip_in_process_encodability: bool, /// Whether an in-process root fused plan was recognized for placement-gate evaluation. in_process_fused_root: bool, /// Current level in the tree @@ -640,10 +637,8 @@ impl PlanRewriter { let whole_plan_encodable = DFLogicalSubstraitConvertor .encode(plan, DefaultSerializer) .is_ok(); - let skip_in_process_encodability = in_process_fused_root && !whole_plan_encodable; Self { in_process_fused_root, - skip_in_process_encodability, whole_plan_encodable, ..Default::default() } @@ -677,8 +672,7 @@ impl PlanRewriter { // When the root does not encode, the plan holds at least one node that has to stay // on the frontend and only the per-node check locates it. // - if !self.skip_in_process_encodability - && !self.whole_plan_encodable + if !self.whole_plan_encodable && let Err(e) = DFLogicalSubstraitConvertor.encode(plan, DefaultSerializer) { debug!( diff --git a/src/query/src/dist_plan/analyzer/test.rs b/src/query/src/dist_plan/analyzer/test.rs index b6e0ba1e9e9..033384474dc 100644 --- a/src/query/src/dist_plan/analyzer/test.rs +++ b/src/query/src/dist_plan/analyzer/test.rs @@ -80,7 +80,7 @@ fn analyzer() -> DistPlannerAnalyzer { } #[test] -fn ordinary_encodable_plan_keeps_in_process_encodability_gate() { +fn ordinary_encodable_plan_reports_encodability() { let table = TestTable::table_with_name(0, "t".to_string()); let table_source = Arc::new(DefaultTableSource::new(Arc::new( DfTableProviderAdapter::new(table), @@ -98,11 +98,9 @@ fn ordinary_encodable_plan_keeps_in_process_encodability_gate() { let in_process_rewriter = PlanRewriter::new(&plan, true); assert!(in_process_rewriter.whole_plan_encodable); - assert!(!in_process_rewriter.skip_in_process_encodability); let wire_rewriter = PlanRewriter::new(&plan, false); assert!(wire_rewriter.whole_plan_encodable); - assert!(!wire_rewriter.skip_in_process_encodability); } struct MergeScanRemoteDynFilterProducerIdCollector<'a> { diff --git a/src/query/src/dist_plan/commutativity.rs b/src/query/src/dist_plan/commutativity.rs index a5f546c46e5..4d727bae0e2 100644 --- a/src/query/src/dist_plan/commutativity.rs +++ b/src/query/src/dist_plan/commutativity.rs @@ -1038,9 +1038,9 @@ mod tests { let in_process = analyze(DistPlannerAnalyzer::new(true), plan.clone()); assert!(any_remote_input_holds(&in_process, holds_fused_series)); - // A partial producer exports aggregate state, which has no wire form: it serializes only - // inside the region that reads the samples, never across the boundary. Its final half is - // frontend-side for the same reason. + // A partial producer exports aggregate state, which the codec carries like any other + // frame; whether it may be pushed below a region boundary is decided by the analyzer's + // placement rules, not by the encoder. let split = split_aggregate_plan(table_scan_plan()); let final_node = as_final_split(&split).expect("the split's final half"); let [producer] = final_node.children() else { @@ -1049,8 +1049,8 @@ mod tests { assert!( DFLogicalSubstraitConvertor .encode(producer, DefaultSerializer) - .is_err(), - "a state-exporting producer must not cross the wire" + .is_ok(), + "a state-exporting producer encodes like any other node" ); let placed = analyze(DistPlannerAnalyzer::new(true), split); assert!(as_final_split(&placed).is_some()); @@ -1188,8 +1188,8 @@ mod tests { assert!( DFLogicalSubstraitConvertor .encode(&plan, DefaultSerializer) - .is_err(), - "the split plan must remain unencodable across the wire" + .is_ok(), + "a split plan encodes like any other plan; where it may run is a placement decision" ); let in_process = analyze(DistPlannerAnalyzer::new(true), plan.clone()); @@ -1214,9 +1214,11 @@ mod tests { assert!(holds_table_scan(merge_scan.input())); let encoded = analyze(DistPlannerAnalyzer::new(false), plan); + // The analyzer, not the codec, decides placement: a split aggregate's partial producer is + // region-local work and belongs below the boundary. assert!( - !any_remote_input_holds(&encoded, holds_fused_series), - "the analyzer placed a fused node although its plan has to encode: {encoded}" + any_remote_input_holds(&encoded, holds_fused_series), + "the analyzer keeps the partial producer below the region boundary: {encoded}" ); } diff --git a/src/query/src/dist_plan/merge_scan.rs b/src/query/src/dist_plan/merge_scan.rs index 534d306c84d..c6c508a9520 100644 --- a/src/query/src/dist_plan/merge_scan.rs +++ b/src/query/src/dist_plan/merge_scan.rs @@ -48,10 +48,12 @@ use datafusion_common::{DFSchemaRef, DataFusionError, Result, Statistics}; use datafusion_expr::{Expr, Extension, FetchType, LogicalPlan, UserDefinedLogicalNodeCore}; use datafusion_physical_expr::{EquivalenceProperties, PhysicalSortExpr}; use datatypes::extension::json::is_any_json_extension_type; +use datatypes::series::frame::SeriesFrameDeclaration; use futures_util::StreamExt; use greptime_proto::v1::region::RegionRequestHeader; use meter_core::data::ReadItem; use meter_macros::read_meter; +use promql::extension_plan::RawSeriesSource; use session::context::{ FLIGHT_METRICS_HEARTBEAT_INTERVAL, QueryContextRef, SUPPORT_FLIGHT_METRICS_BEFORE_BATCH_EXTENSION_KEY, @@ -75,7 +77,7 @@ use crate::dist_plan::{ use crate::metrics::{MERGE_SCAN_ERRORS_TOTAL, MERGE_SCAN_POLL_ELAPSED, MERGE_SCAN_REGIONS}; use crate::options::{FlowQueryExtensions, remote_dyn_filter_pushdown_enabled_from_extensions}; use crate::query_engine::QueryEngineState; -use crate::region_query::RegionQueryHandlerRef; +use crate::region_query::{RegionQueryHandlerRef, RegionReadLimiter}; fn query_engine_state_from_task_context(context: &TaskContext) -> Option> { context.session_config().get_extension() @@ -481,6 +483,7 @@ pub struct MergeScanExec { regions: Vec, plan: LogicalPlan, arrow_schema: ArrowSchemaRef, + remote_schema: ArrowSchemaRef, region_query_handler: RegionQueryHandlerRef, metric: ExecutionPlanMetricsSet, properties: Arc, @@ -520,6 +523,7 @@ impl MergeScanExec { remote_dyn_filter_producer_id: Option, enable_per_region_metrics: bool, ) -> Result { + let remote_schema = Arc::new(arrow_schema.clone()); let arrow_schema = Arc::new(arrow_schema.clone()); let output_partition_count = Self::output_partition_count(regions.len(), target_partition); @@ -567,6 +571,7 @@ impl MergeScanExec { regions, plan, arrow_schema, + remote_schema, region_query_handler, metric: ExecutionPlanMetricsSet::new(), sub_stage_metrics: Arc::default(), @@ -580,6 +585,35 @@ impl MergeScanExec { }) } + /// Redeclares only a direct raw source when its selected regions may split a key. + pub(crate) fn with_raw_series_disjoint(mut self, disjoint: bool) -> Result { + if !disjoint + && matches!(&self.plan, LogicalPlan::Extension(extension) + if extension.node.as_any().is::()) + { + SeriesFrameDeclaration::parse(self.remote_schema.as_ref()) + .map_err(|error| DataFusionError::Plan(error.to_string()))?; + let mut metadata = self.arrow_schema.metadata().clone(); + metadata.insert("greptime.series.ordering".into(), "interleaved".into()); + self.arrow_schema = Arc::new(arrow_schema::Schema::new_with_metadata( + self.arrow_schema.fields().clone(), + metadata, + )); + let equivalence = self + .properties + .equivalence_properties() + .clone() + .with_new_schema(self.arrow_schema.clone())?; + self.properties = Arc::new( + self.properties + .as_ref() + .clone() + .with_eq_properties(equivalence), + ); + } + Ok(self) + } + /// Conservative row-count upper bound for all selected regions. /// /// This is not an expected cardinality: DataFusion receives it as an @@ -612,6 +646,7 @@ impl MergeScanExec { let region_query_handler = self.region_query_handler.clone(); let metric = MergeScanMetric::new(&self.metric); let arrow_schema = self.arrow_schema.clone(); + let remote_schema = self.remote_schema.clone(); let query_ctx = self.query_ctx.clone(); let sub_stage_metrics_moved = self.sub_stage_metrics.clone(); let partition_metrics_moved = self.partition_metrics.clone(); @@ -635,6 +670,10 @@ impl MergeScanExec { &query_ctx, &captured_remote_dyn_filters, ); + // The query's own bound on region reads in flight; see [`RegionReadLimiter`]. + let region_read_limiter = context + .session_config() + .get_extension::(); let stream = Box::pin(stream!({ let remote_dyn_filter_registry_lease = remote_dyn_filter_registry_lease; @@ -722,6 +761,12 @@ impl MergeScanExec { ); } + // Hold the permit until this region's body is drained or dropped: the bound + // counts reads in flight, whichever scan or partition started them. + let _region_read_permit = match region_read_limiter.as_ref() { + Some(limiter) => Some(limiter.acquire().await), + None => None, + }; let do_get_start = Instant::now(); let do_get_result = region_query_handler .do_get(&target, request) @@ -740,7 +785,7 @@ impl MergeScanExec { } let mut advertised_schema = stream.schema().arrow_schema().clone(); validate_remote_schema( - arrow_schema.as_ref(), + remote_schema.as_ref(), advertised_schema.as_ref(), "advertised remote stream", ) @@ -806,7 +851,7 @@ impl MergeScanExec { let df_batch = batch.into_df_record_batch(); if !Arc::ptr_eq(&advertised_schema, df_batch.schema_ref()) { validate_remote_schema( - arrow_schema.as_ref(), + remote_schema.as_ref(), df_batch.schema_ref().as_ref(), "remote record batch", ) @@ -1359,6 +1404,7 @@ mod tests { }; use datatypes::prelude::{ConcreteDataType, VectorRef}; use datatypes::schema::{ColumnSchema, Schema}; + use datatypes::series::SeriesOrdering; use datatypes::series::frame::{self, FrameLabelMode}; use datatypes::series::raw::{RawSeriesChunk, RawTimestamps}; use datatypes::series::samples::{ @@ -3262,6 +3308,309 @@ mod tests { } } + /// Exercise the distributed analyzer's real recovery projection with the pinned physical + /// planner. This documents the declaration that the query planner must repair at Fused input. + #[tokio::test] + async fn analyzer_recovery_projection_stamps_logical_raw_ordering() { + use crate::dist_plan::DistPlannerAnalyzer; + use crate::optimizer::test_util::mock_table_provider; + use common_query::series_frame::series_frame_ordering; + use datafusion::catalog::Session; + use datafusion::logical_expr::physical_planning_context::PhysicalPlanningContext; + use datafusion::physical_planner::{ + DefaultPhysicalPlanner, ExtensionPlanner, PhysicalPlanner, + }; + use datafusion_expr::{Extension, UserDefinedLogicalNode}; + use datafusion_optimizer::analyzer::AnalyzerRule; + + struct RawMergePlanner; + #[async_trait] + impl ExtensionPlanner for RawMergePlanner { + async fn plan_extension( + &self, + _planner: &dyn PhysicalPlanner, + node: &dyn UserDefinedLogicalNode, + _logical_inputs: &[&LogicalPlan], + _physical_inputs: &[Arc], + session: &dyn Session, + _planning_ctx: &PhysicalPlanningContext, + ) -> Result>> { + let Some(scan) = node.as_any().downcast_ref::() else { + return Ok(None); + }; + let session = session.as_any().downcast_ref::().unwrap(); + let exec = MergeScanExec::new( + session, + TableName::new("c", "s", "t"), + vec![RegionId::new(1024, 1), RegionId::new(1024, 2)], + scan.input().clone(), + UserDefinedLogicalNode::schema(scan).as_arrow(), + Arc::new(TestRegionQueryHandler::default()), + QueryContext::arc(), + 2, + None, + false, + )? + .with_raw_series_disjoint(false)?; + Ok(Some(Arc::new(exec))) + } + } + let table = LogicalPlanBuilder::scan( + "metric", + Arc::new(datafusion::datasource::DefaultTableSource::new(Arc::new( + mock_table_provider(RegionId::new(1024, 1)), + ))), + None, + ) + .unwrap() + .build() + .unwrap(); + let raw = LogicalPlan::Extension(Extension { + node: Arc::new( + RawSeriesSource::try_new( + Arc::from("metric"), + vec!["host".into()], + vec!["v0".into()], + table, + ) + .unwrap(), + ), + }); + // The analyzer expands a raw source into a merge scan. The recovery projection the Fused + // planner repairs is the one the physical planner derives from the source's own frame + // schema, not an extra analyzer node. + let analyzed = DistPlannerAnalyzer::new(false) + .analyze(raw, &ConfigOptions::default()) + .unwrap(); + assert_eq!( + series_frame_ordering(analyzed.schema().as_arrow()).unwrap(), + SeriesOrdering::Contiguous + ); + let state = SessionStateBuilder::new() + .with_default_features() + .with_physical_optimizer_rules(vec![]) + .build(); + let planner = + DefaultPhysicalPlanner::with_extension_planners(vec![Arc::new(RawMergePlanner)]); + let physical = planner + .create_physical_plan(&analyzed, &state) + .await + .unwrap(); + // The analyzer hands the raw frame boundary to the physical planner unchanged: no recovery + // projection is inserted, so the merge scan's own declaration is what a fused consumer + // sees. + let merge = physical + .downcast_ref::() + .expect("the analyzed raw source plans as the merge scan itself"); + assert_eq!( + series_frame_ordering(merge.schema().as_ref()).unwrap(), + SeriesOrdering::Interleaved + ); + assert_eq!( + series_frame_ordering(physical.schema().as_ref()).unwrap(), + SeriesOrdering::Interleaved + ); + } + + #[tokio::test] + async fn raw_region_root_series_frame_output_preserves_chains() { + use crate::optimizer::series_frame_output::SeriesFrameOutput; + use datafusion::datasource::memory::MemorySourceConfig; + use datafusion::datasource::source::DataSourceExec; + use datafusion::physical_optimizer::PhysicalOptimizerRule; + use datatypes::series::SeriesLabels; + use promql::extension_plan::{IdentityCompletion, SeriesRepartitionExec}; + + let logical = RawSeriesSource::try_new( + Arc::from("metric"), + vec![], + vec!["value".into(), "other".into()], + LogicalPlanBuilder::empty(false).build().unwrap(), + ) + .unwrap(); + let remote_schema = Arc::new( + UserDefinedLogicalNodeCore::schema(&logical) + .as_arrow() + .clone(), + ); + let raw = raw_test_series_schema(); + let batch = |time, value| { + let chunk = RawSeriesChunk::try_new( + &raw, + Buffer::from(vec![1u8]), + Some(SeriesLabels::try_new(Some(Arc::from("metric")), vec![]).unwrap()), + RawTimestamps::try_new(ScalarBuffer::from(vec![time])).unwrap(), + SeriesFields::try_from_vec(vec![ + Samples::from_float(Float64Array::from(vec![value])), + Samples::from_float(Float64Array::from(vec![value])), + ]) + .unwrap(), + true, + ) + .unwrap(); + let packed = frame::pack_raw_series_chunk(&raw, FrameLabelMode::Explicit, None, &chunk) + .unwrap() + .remove(0); + DfRecordBatch::try_new(remote_schema.clone(), packed.columns().to_vec()).unwrap() + }; + let input = Arc::new(DataSourceExec::new(Arc::new( + MemorySourceConfig::try_new( + &[vec![batch(10, 1.0)], vec![batch(20, 2.0)]], + remote_schema.clone(), + None, + ) + .unwrap(), + ))) as Arc; + let root = logical.to_per_series_execution_plan(input).unwrap(); + let output = SeriesFrameOutput + .optimize(root, &ConfigOptions::default()) + .unwrap(); + let router = output.downcast_ref::().unwrap(); + assert_eq!( + router.identity_completion(), + IdentityCompletion::MergeInputs + ); + assert_eq!(output.schema(), remote_schema); + let batches = datafusion::physical_plan::collect(output, Arc::new(TaskContext::default())) + .await + .unwrap(); + let chunks = batches + .iter() + .flat_map(|batch| { + frame::unpack_raw_series_frame(&raw, FrameLabelMode::Explicit, None, batch).unwrap() + }) + .collect::>(); + let times = chunks + .iter() + .flat_map(|chunk| (0..chunk.time.len()).map(|i| chunk.time.timestamp(i).unwrap())) + .collect::>(); + assert_eq!(times, vec![10, 20]); + assert_eq!(chunks.iter().filter(|chunk| chunk.is_last).count(), 1); + } + + #[tokio::test] + async fn direct_raw_merge_validates_remote_then_exposes_fragmented_batches() { + use common_query::series_frame::series_frame_ordering; + use datafusion_expr::Extension; + use datatypes::series::SeriesLabels; + + let source = LogicalPlan::Extension(Extension { + node: Arc::new( + RawSeriesSource::try_new( + Arc::from("metric"), + vec![], + vec!["value".into(), "other".into()], + LogicalPlanBuilder::empty(false).build().unwrap(), + ) + .unwrap(), + ), + }); + let mut metadata = source.schema().as_arrow().metadata().clone(); + metadata.insert("test.frame.producer".into(), "preserve-me".into()); + let remote = Arc::new(ArrowSchema::new_with_metadata( + source.schema().as_arrow().fields().clone(), + metadata, + )); + let advertised = Arc::new(Schema::try_from(remote.clone()).unwrap()); + let raw = raw_test_series_schema(); + let chunk = RawSeriesChunk::try_new( + &raw, + Buffer::from(vec![1u8]), + Some(SeriesLabels::try_new(Some(Arc::from("metric")), vec![]).unwrap()), + RawTimestamps::try_new(ScalarBuffer::from(vec![10, 20])).unwrap(), + SeriesFields::try_from_vec(vec![ + Samples::from_float(Float64Array::from(vec![1.0, 2.0])), + Samples::from_float(Float64Array::from(vec![3.0, 4.0])), + ]) + .unwrap(), + true, + ) + .unwrap(); + let packed = frame::pack_raw_series_chunk(&raw, FrameLabelMode::Explicit, None, &chunk) + .unwrap() + .remove(0); + let packed = DfRecordBatch::try_new(remote.clone(), packed.columns().to_vec()).unwrap(); + let region = RegionId::new(1024, 1); + for disjoint in [true, false] { + let batch = RecordBatch::from_df_record_batch(advertised.clone(), packed.clone()); + let exec = MergeScanExec::new( + &SessionStateBuilder::new().build(), + TableName::new("c", "s", "t"), + vec![region, RegionId::new(1024, 2)], + source.clone(), + &remote, + Arc::new(TestRegionQueryHandler::with_responses(vec![( + region, + advertised.clone(), + vec![Ok(batch)], + )])), + QueryContext::arc(), + 2, + None, + false, + ) + .unwrap() + .with_raw_series_disjoint(disjoint) + .unwrap(); + assert_eq!(exec.region_count(), 2); + assert_eq!(exec.partition_count(), 2); + assert_eq!(exec.remote_schema.as_ref(), remote.as_ref()); + assert_eq!( + exec.schema().metadata().get("test.frame.producer"), + Some(&"preserve-me".to_string()) + ); + let expected = if disjoint { + SeriesOrdering::Contiguous + } else { + SeriesOrdering::Interleaved + }; + assert_eq!( + series_frame_ordering(exec.schema().as_ref()).unwrap(), + expected + ); + let schema = exec.schema(); + let batches = collect_merge_scan(exec).await.unwrap(); + assert_eq!(batches.len(), 1); + assert_eq!(batches[0].schema(), schema); + assert!(Arc::ptr_eq(&packed.columns()[0], &batches[0].columns()[0])); + } + let mut wrong_metadata = remote.metadata().clone(); + wrong_metadata.insert( + "greptime.series.ordering".into(), + "read_key_then_time".into(), + ); + let wrong = Arc::new( + Schema::try_from(Arc::new(ArrowSchema::new_with_metadata( + remote.fields().clone(), + wrong_metadata, + ))) + .unwrap(), + ); + let exec = MergeScanExec::new( + &SessionStateBuilder::new().build(), + TableName::new("c", "s", "t"), + vec![region], + source, + &remote, + Arc::new(TestRegionQueryHandler::with_responses(vec![( + region, + wrong, + vec![], + )])), + QueryContext::arc(), + 1, + None, + false, + ) + .unwrap() + .with_raw_series_disjoint(false) + .unwrap(); + assert!( + collect_merge_scan(exec).await.is_err(), + "the exposed schema must not weaken remote validation" + ); + } + #[tokio::test] async fn merge_scan_remote_schema_identity_rejects_later_raw_frame_inner_metadata_mismatch() { let region_id = RegionId::new(1024, 1); diff --git a/src/query/src/dist_plan/planner.rs b/src/query/src/dist_plan/planner.rs index 5cadb5ea8de..f2252d2fd8a 100644 --- a/src/query/src/dist_plan/planner.rs +++ b/src/query/src/dist_plan/planner.rs @@ -195,14 +195,25 @@ impl ExtensionPlanner for DistExtensionPlanner { } let optimized_plan = input_plan; + let direct_raw = matches!(input_plan, LogicalPlan::Extension(extension) + if extension.node.as_any().is::()); let Some(table_name) = Self::extract_full_table_name(input_plan)? else { + if direct_raw { + return Err(DataFusionError::Plan( + "raw series source has no region route table".into(), + )); + } // no relation found in input plan, going to execute them locally return fallback(optimized_plan).await; }; - let Ok(regions) = self.get_regions(&table_name, input_plan).await else { - // no peers found, going to execute them locally - return fallback(optimized_plan).await; + let (regions, series_disjoint) = match self.get_regions(&table_name, input_plan).await { + Ok(regions) => regions, + Err(error) if direct_raw => { + return Err(error); + } + // Existing non-raw plans may still execute locally when no peers are found. + Err(_) => return fallback(optimized_plan).await, }; // TODO(ruihang): generate different execution plans for different variant merge operation @@ -230,7 +241,8 @@ impl ExtensionPlanner for DistExtensionPlanner { session.config().target_partitions(), merge_scan.remote_dyn_filter_producer_id(), self.enable_per_region_metrics, - )?; + )? + .with_raw_series_disjoint(series_disjoint)?; Ok(Some(Arc::new(merge_scan_plan) as _)) } } @@ -248,7 +260,7 @@ impl DistExtensionPlanner { &self, table_name: &TableName, logical_plan: &LogicalPlan, - ) -> Result> { + ) -> Result<(Vec, bool)> { let mut extractor = TableScanExtractor::default(); let _ = logical_plan.visit(&mut extractor)?; // Resolving by name again could bind an authorized scan to a replacement table. @@ -380,7 +392,28 @@ impl DistExtensionPlanner { pruned_regions }; - Ok(regions) + // A selected region is trivially disjoint. For several regions the proof must + // use the captured scan and the physical route's table metadata, not a logical + // metric table's possibly incomplete partition columns. + let series_disjoint = if regions.len() <= 1 { + true + } else if captured_table.is_none() { + false + } else { + let physical_info = if physical_table_id == table_info.table_id() { + Some(table_info.clone()) + } else { + self.catalog_manager + .table_info_by_id(physical_table_id) + .await + .ok() + .flatten() + }; + physical_info.is_some_and(|info| { + physical_regions_disjoint(&info, &physical_table_route.region_routes, ®ions) + }) + }; + Ok((regions, series_disjoint)) } /// Resolves the partition-column types that are safe to use for region pruning. @@ -471,6 +504,64 @@ impl DistExtensionPlanner { } } +/// Prove that every physical routing column belongs to the complete raw primary key. +/// Unknown indices, missing route expressions, or route columns not represented in physical +/// partition metadata cannot establish disjointness. Reserved-looking names have no special status. +fn physical_regions_disjoint( + table_info: &TableInfo, + routes: &[common_meta::rpc::router::RegionRoute], + regions: &[RegionId], +) -> bool { + let columns = table_info.meta.schema.column_schemas(); + let partition_keys = &table_info.meta.partition_key_indices; + // Routing by any nonempty subset of the complete key keeps equal complete keys together. + // The reverse inclusion is not required: (host, rack) partitioned by host is disjoint. + if partition_keys.is_empty() + || table_info.meta.primary_key_indices.is_empty() + || partition_keys.iter().any(|index| { + columns.get(*index).is_none_or(|column| { + column.is_time_index() || !table_info.meta.primary_key_indices.contains(index) + }) + }) + || table_info + .meta + .primary_key_indices + .iter() + .any(|index| columns.get(*index).is_none()) + { + return false; + } + let partition_names = partition_keys + .iter() + .map(|index| columns[*index].name.as_str()) + .collect::>(); + for region in regions { + let mut matching = routes + .iter() + .filter(|route| route.region.id.region_number() == region.region_number()); + let Some(route) = matching.next() else { + return false; + }; + if matching.next().is_some() { + return false; + } + let Ok(Some(expression)) = PartitionExpr::from_json_str(&route.region.partition_expr()) + else { + return false; + }; + let mut names = std::collections::HashSet::new(); + expression.collect_column_names(&mut names); + if names.is_empty() + || names + .iter() + .any(|name| !partition_names.contains(name.as_str())) + { + return false; + } + } + true +} + fn partition_column_types(table_info: &TableInfo) -> Vec<(String, ConcreteDataType)> { table_info .meta @@ -578,7 +669,7 @@ mod tests { use table::table_name::TableName; use table::test_util::EmptyTable; - use super::DistExtensionPlanner; + use super::{DistExtensionPlanner, physical_regions_disjoint}; use crate::region_query::{RegionQueryHandler, RegionQueryTarget}; const LOGICAL_TABLE_ID: u32 = 1024; @@ -793,7 +884,7 @@ mod tests { async fn region_routing_uses_captured_table() { let (mut planner, plan, table_name) = planner_and_plan(vec![0], vec![None]).await; planner.catalog_manager = MemoryCatalogManager::with_default_setup(); - let regions = planner.get_regions(&table_name, &plan).await.unwrap(); + let (regions, _) = planner.get_regions(&table_name, &plan).await.unwrap(); assert_eq!(vec![RegionId::new(LOGICAL_TABLE_ID, 1)], regions); } @@ -802,7 +893,7 @@ mod tests { let (planner, plan, table_name) = planner_and_plan(vec![0, 1], physical_partition_expressions()).await; - let regions = planner.get_regions(&table_name, &plan).await.unwrap(); + let (regions, _) = planner.get_regions(&table_name, &plan).await.unwrap(); assert_eq!(vec![RegionId::new(LOGICAL_TABLE_ID, 1)], regions); } @@ -811,7 +902,7 @@ mod tests { let (planner, plan, table_name) = planner_and_plan(vec![0], physical_partition_expressions()).await; - let regions = planner.get_regions(&table_name, &plan).await.unwrap(); + let (regions, _) = planner.get_regions(&table_name, &plan).await.unwrap(); assert_all_logical_regions(regions); } @@ -821,10 +912,83 @@ mod tests { expressions[1] = None; let (planner, plan, table_name) = planner_and_plan(vec![0, 1], expressions).await; - let regions = planner.get_regions(&table_name, &plan).await.unwrap(); + let (regions, _) = planner.get_regions(&table_name, &plan).await.unwrap(); assert_all_logical_regions(regions); } + #[test] + fn disjoint_requires_raw_key_routing_and_valid_unique_routes() { + let regions = vec![ + RegionId::new(LOGICAL_TABLE_ID, 1), + RegionId::new(LOGICAL_TABLE_ID, 2), + ]; + let routes = vec![ + region_route(1, Some(partition_col("host").lt(Value::String("m".into())))), + region_route( + 2, + Some(partition_col("host").gt_eq(Value::String("m".into()))), + ), + ]; + let mut info = table_info(PHYSICAL_TABLE_ID, "physical", &["host", "rack"], vec![0]); + info.meta.primary_key_indices = vec![0]; + assert!(physical_regions_disjoint(&info, &routes, ®ions)); + info.meta.primary_key_indices = vec![0, 1]; + assert!(physical_regions_disjoint(&info, &routes, ®ions)); + info.meta.partition_key_indices = vec![0, 1]; + assert!(physical_regions_disjoint(&info, &routes, ®ions)); + info.meta.partition_key_indices = vec![0, 2]; + assert!(!physical_regions_disjoint(&info, &routes, ®ions)); + info.meta.partition_key_indices = vec![0]; + info.meta.primary_key_indices = vec![0]; + let mut duplicate = routes.clone(); + duplicate.push(routes[0].clone()); + assert!(!physical_regions_disjoint(&info, &duplicate, ®ions)); + let mut missing = routes.clone(); + missing[1] = region_route(2, None); + assert!(!physical_regions_disjoint(&info, &missing, ®ions)); + let mut unknown = routes.clone(); + unknown[1] = region_route(2, Some(partition_col("rack").lt(Value::String("m".into())))); + assert!(!physical_regions_disjoint(&info, &unknown, ®ions)); + let mut malformed = routes.clone(); + malformed[1].region.partition_expr = "{invalid".into(); + assert!(!physical_regions_disjoint(&info, &malformed, ®ions)); + assert!(!physical_regions_disjoint(&info, &routes[..1], ®ions)); + + info.meta.schema = Arc::new(Schema::new(vec![ + ColumnSchema::new("host", ConcreteDataType::string_datatype(), false), + ColumnSchema::new( + "timestamp", + ConcreteDataType::timestamp_millisecond_datatype(), + false, + ) + .with_time_index(true), + ])); + info.meta.partition_key_indices = vec![0, 1]; + info.meta.primary_key_indices = vec![0, 1]; + assert!(!physical_regions_disjoint(&info, &routes, ®ions)); + } + + #[tokio::test] + async fn disjoint_proof_uses_physical_not_logical_metadata() { + let (planner, plan, table_name) = + planner_and_plan(vec![0, 1], physical_partition_expressions()).await; + // The host predicate is selective; one selected region is always disjoint. + let (regions, disjoint) = planner.get_regions(&table_name, &plan).await.unwrap(); + assert_eq!(regions.len(), 1); + assert!(disjoint); + // With no pruning the fixture's physical metadata has no PK, so it cannot prove + // disjointness even though the logical partition keys name host. + let LogicalPlan::Filter(filter) = plan else { + panic!("expected filter") + }; + let (regions, disjoint) = planner + .get_regions(&table_name, &filter.input) + .await + .unwrap(); + assert_eq!(regions.len(), 3); + assert!(!disjoint); + } + fn assert_all_logical_regions(mut regions: Vec) { regions.sort_unstable(); assert_eq!( diff --git a/src/query/src/planner.rs b/src/query/src/planner.rs index a70e0108817..5741ac94a82 100644 --- a/src/query/src/planner.rs +++ b/src/query/src/planner.rs @@ -79,6 +79,32 @@ pub trait LogicalPlanner: Send + Sync { fn as_any(&self) -> &dyn Any; } +/// A remote native plan may place fused evaluation only above independent raw sources. +/// In particular, a bare scan under FusedSeries would require shipping the process-local +/// fused plan to a region, which this gate must not admit. +fn remote_native_raw_plan_supported(plan: &LogicalPlan) -> bool { + fn walk(plan: &LogicalPlan, found_raw: &mut bool) -> bool { + if matches!(plan, LogicalPlan::TableScan(_)) { + return false; + } + if let LogicalPlan::Extension(extension) = plan + && extension + .node + .as_any() + .is::() + { + *found_raw = true; + return matches!( + extension.node.inputs().as_slice(), + [LogicalPlan::TableScan(_)] + ); + } + plan.inputs().iter().all(|child| walk(child, found_raw)) + } + let mut found_raw = false; + walk(plan, &mut found_raw) && found_raw +} + pub struct DfLogicalPlanner { engine_state: Arc, session_state: SessionState, @@ -351,36 +377,53 @@ impl DfLogicalPlanner { scheduled_state.clone(), &query_ctx, )?); - let table_provider = DfTableSourceProvider::new( - self.engine_state.catalog_manager().clone(), - self.engine_state.disallow_cross_catalog_query(), - query_ctx.clone(), - plan_decoder, - scheduled_state - .config_options() - .sql_parser - .enable_ident_normalization, - ); + let table_provider = || { + DfTableSourceProvider::new( + self.engine_state.catalog_manager().clone(), + self.engine_state.disallow_cross_catalog_query(), + query_ctx.clone(), + plan_decoder.clone(), + scheduled_state + .config_options() + .sql_parser + .enable_ident_normalization, + ) + }; + let native_requested = native_route_allowed + && !allow_query_fallback + && self.engine_state.experimental_native_promql() + && crate::promql::planner::native::native_promql_requested(&query_ctx); let plan = PromPlanner::stmt_to_plan_with_annotations( - table_provider, + table_provider(), stmt, &self.engine_state, - promql_annotations, - // A query allowed to fall back keeps the existing plan. The native node's physical - // planner needs the bare region scan as its input; the fallback rewriter instead wraps - // every table scan in `MergeScan`, so the node above it would have no physical plan and - // the query would fail after the fallback was already taken. Declining here keeps the - // whole query on the legacy path. - native_route_allowed - && !allow_query_fallback - && self.engine_state.experimental_native_promql() - && self.engine_state.in_process_region_transport() - && crate::promql::planner::native::native_promql_requested(&query_ctx), + promql_annotations.clone(), + // A fallback rewriter can wrap a native region scan in an unusable MergeScan. + native_requested, ) .await .map_err(BoxedError::new) .context(QueryPlanSnafu)?; + // Only per-selector raw sources have a supported remote transport. Decide while the + // original statement is still available: physical planning cannot fall back safely. + let plan = if native_requested + && !self.engine_state.in_process_region_transport() + && !remote_native_raw_plan_supported(&plan) + { + PromPlanner::stmt_to_plan_with_annotations( + table_provider(), + stmt, + &self.engine_state, + promql_annotations, + false, + ) + .await + .map_err(BoxedError::new) + .context(QueryPlanSnafu)? + } else { + plan + }; let context = QueryEngineContext::new(scheduled_state, query_ctx); Ok(self .engine_state @@ -958,6 +1001,18 @@ mod tests { table: EmptyTable::from_table_info(&logical_info), }) .unwrap(); + let mut other_info = logical_info.clone(); + other_info.ident.table_id = 1025; + other_info.name = "other_metric".to_string(); + catalog_manager + .register_table_sync(RegisterTableRequest { + catalog: DEFAULT_CATALOG_NAME.to_string(), + schema: DEFAULT_SCHEMA_NAME.to_string(), + table_name: other_info.name.clone(), + table_id: other_info.ident.table_id, + table: EmptyTable::from_table_info(&other_info), + }) + .unwrap(); QueryEngineFactory::try_new_with_plugins_and_region_transport( catalog_manager, @@ -1085,6 +1140,53 @@ mod tests { } } + /// Remote native planning accepts independent raw sources only. Unsupported shapes are + /// replanned through the legacy route, while the in-process route remains unchanged. + #[tokio::test] + async fn test_remote_native_promql_admission_replans_unsupported_shapes() { + for (in_process, query, native) in [ + (false, "some_metric + other_metric", true), + (false, "rate(some_metric[5m])", false), + (true, "rate(some_metric[5m])", true), + ] { + let engine = create_promql_test_engine_with( + crate::options::QueryOptions { + experimental_native_promql: true, + ..Default::default() + }, + in_process, + ); + let query_ctx = Arc::new( + QueryContextBuilder::default() + .set_extension(NATIVE_PROMQL_EXTENSION_KEY.to_string(), "true".to_string()) + .build(), + ); + let stmt = QueryLanguageParser::parse_promql( + &PromQuery { + query: query.to_string(), + start: "0".to_string(), + end: "10".to_string(), + step: "5s".to_string(), + lookback: "300s".to_string(), + alias: None, + }, + &query_ctx, + ) + .unwrap(); + let plan = engine.planner().plan(&stmt, query_ctx).await.unwrap(); + let display = plan.display_indent().to_string(); + assert_eq!( + display.contains("FusedSeries"), + native, + "in_process={in_process}, query={query}: {display}" + ); + if native && !in_process { + assert!(remote_native_raw_plan_supported(&plan), "{display}"); + assert!(display.contains("RawSeriesSource"), "{display}"); + } + } + } + /// Plans `sql` and runs the DataFusion analyzer, which is where /// `InsertAssignmentRule` sits. Planning alone stops short of it, so these /// assertions would not see the assignment rewrite at all. diff --git a/src/query/src/promql/planner.rs b/src/query/src/promql/planner.rs index 1db774272c4..6cd5138d14b 100644 --- a/src/query/src/promql/planner.rs +++ b/src/query/src/promql/planner.rs @@ -22,6 +22,8 @@ pub use native::{NATIVE_PROMQL_EXTENSION_KEY, discovers_metric_name}; mod set_operator; use std::collections::{BTreeSet, HashSet, VecDeque}; +use std::future::Future; +use std::pin::Pin; use std::sync::Arc; use arrow::datatypes::IntervalDayTime; @@ -308,6 +310,11 @@ pub struct PromPlanner { type BinaryFieldPair<'a> = (&'a String, &'a String); +/// [`PromPlanner::try_plan_native_operand`]'s future, boxed; see +/// [`PromPlanner::native_operand_future`] for why it is not kept inline. +type NativeOperandFuture<'a> = + Pin>> + Send + 'a>>; + impl PromPlanner { pub async fn stmt_to_plan( table_provider: DfTableSourceProvider, @@ -342,7 +349,10 @@ impl PromPlanner { // a range function and the math functions over it into one tree: offered any later, the // expression has already been split into the nodes those functions would have shared. A // shape it does not accept is planned by the existing path exactly as if it were not here. - if let Some(plan) = planner.try_plan_native_fused(&stmt.expr).await? { + if let Some(plan) = planner + .try_plan_native_fused(&stmt.expr, query_engine_state) + .await? + { return planner.strip_tsid_column(plan); } let plan = planner @@ -1167,6 +1177,63 @@ impl PromPlanner { }) } + /// Boxes [`Self::try_plan_native_operand`]'s future. + /// + /// The planner re-enters [`Self::prom_expr_to_plan_inner`] and + /// [`Self::prom_binary_expr_to_plan`] once per nesting level of the statement, and both frames + /// are large in a debug build. The native route's future is large as well, so a caller that + /// also plans the same expression with the existing path would carry a copy of it on the stack + /// at every level. Built here, the future moves into the box before that recursion starts, and + /// only the attempt itself pays for it. + fn native_operand_future<'a>( + &'a mut self, + expr: &'a PromExpr, + query_engine_state: &'a QueryEngineState, + ) -> NativeOperandFuture<'a> { + Box::pin(self.try_plan_native_operand(expr, query_engine_state)) + } + + /// Re-plans one operand that [`matching_filters::propagate`] rewrote, publishing the plan and + /// its context through `context`. + /// + /// A copied matcher belongs to the scan, not to the operand's identity: `absent()` turns + /// `selector_matcher` into the labels it reports, so the re-planned context keeps the matchers + /// the operand was written with. + /// + /// A natively planned operand is re-planned natively: the matcher has to reach the fused node's + /// own scan, or the join keeps the non-joining rows that node reported. The route decides per + /// expression, so a decline falls back to the existing plan exactly as it would have on its own. + async fn replan_rewritten_operand( + &mut self, + rewritten: &PromExpr, + used_native: bool, + query_engine_state: &QueryEngineState, + context: &mut PromPlannerContext, + ) -> Result { + let selectors = std::mem::take(&mut context.selector_matcher); + let native = if used_native { + self.native_operand_future(rewritten, query_engine_state) + .await? + } else { + None + }; + let plan = match native { + Some((plan, replanned)) => { + *context = replanned; + plan + } + None => { + let plan = self + .prom_expr_to_plan(rewritten, query_engine_state) + .await?; + *context = self.ctx.clone(); + plan + } + }; + context.selector_matcher = selectors; + Ok(plan) + } + async fn prom_binary_expr_to_plan( &mut self, query_engine_state: &QueryEngineState, @@ -1378,8 +1445,10 @@ impl PromPlanner { self.native_fused && native::hybrid_binary_admitted(*op, modifier, lhs, rhs); let native = if native_pair { match ( - self.try_plan_native_operand(lhs).await?, - self.try_plan_native_operand(rhs).await?, + self.try_plan_native_operand(lhs, query_engine_state) + .await?, + self.try_plan_native_operand(rhs, query_engine_state) + .await?, ) { (Some(left), Some(right)) => Some((left, right)), _ => None, @@ -1414,33 +1483,32 @@ impl PromPlanner { // Both operands are planned first because only the planned contexts tell a tag // from a value field. The rewrite merely adds matchers to a selector, so the // table reference, time index and field columns captured above stay valid. - if !used_native - && let Some(rewritten) = matching_filters::propagate( - binary_expr, - &left_context.tag_columns, - &right_context.tag_columns, - &left_context.aggregation_field_labels, - &right_context.aggregation_field_labels, - ) - { - // A copied matcher belongs to the scan, not to the operand's identity: - // `absent()` turns `selector_matcher` into the labels it reports, so the - // re-planned context keeps the matchers the operand was written with. + if let Some(rewritten) = matching_filters::propagate( + binary_expr, + &left_context.tag_columns, + &right_context.tag_columns, + &left_context.aggregation_field_labels, + &right_context.aggregation_field_labels, + ) { if rewritten.lhs.as_ref() != lhs.as_ref() { - let selectors = std::mem::take(&mut left_context.selector_matcher); left_input = self - .prom_expr_to_plan(&rewritten.lhs, query_engine_state) + .replan_rewritten_operand( + &rewritten.lhs, + used_native, + query_engine_state, + &mut left_context, + ) .await?; - left_context = self.ctx.clone(); - left_context.selector_matcher = selectors; } if rewritten.rhs.as_ref() != rhs.as_ref() { - let selectors = std::mem::take(&mut right_context.selector_matcher); right_input = self - .prom_expr_to_plan(&rewritten.rhs, query_engine_state) + .replan_rewritten_operand( + &rewritten.rhs, + used_native, + query_engine_state, + &mut right_context, + ) .await?; - right_context = self.ctx.clone(); - right_context.selector_matcher = selectors; } // The code below reads `self.ctx` as the right operand's context. self.ctx = right_context.clone(); @@ -2460,7 +2528,10 @@ impl PromPlanner { ANALYZE_NODE_NAME | ANALYZE_VERBOSE_NODE_NAME | EXPLAIN_NODE_NAME - | EXPLAIN_VERBOSE_NODE_NAME => self.try_plan_native_fused(&children[0]).await?, + | EXPLAIN_VERBOSE_NODE_NAME => { + self.try_plan_native_fused(&children[0], query_engine_state) + .await? + } _ => None, }; let plan = match native_plan { diff --git a/src/query/src/promql/planner/native.rs b/src/query/src/promql/planner/native.rs index ac9f21a1710..dd6791493f0 100644 --- a/src/query/src/promql/planner/native.rs +++ b/src/query/src/promql/planner/native.rs @@ -49,6 +49,7 @@ use datafusion::logical_expr::UserDefinedLogicalNode; use datafusion::logical_expr::{ EmptyRelation, Extension, LogicalPlan, LogicalPlanBuilder, TableScanBuilder, Union, }; +use datafusion::physical_plan::ExecutionPlan; use datafusion::prelude::Expr as DfExpr; use datafusion_expr::Expr; use datatypes::data_type::DataType as _; @@ -56,8 +57,8 @@ use datatypes::series::SeriesOrdering; use datatypes::series::samples::{FieldSpec, SeriesSchema}; use datatypes::series::time::EvalGrid; use promql::extension_plan::{ - FieldKind, FusedOutputFormat, FusedSeries, FusedSeriesBinding, InputLocality, RawSeriesSource, - input_locality, matching_operands_drop_key, tree_source_fields, + FieldKind, FusedOutputFormat, FusedSeries, FusedSeriesBinding, FusedSeriesExec, InputLocality, + RawSeriesSource, input_locality, matching_operands_drop_key, tree_source_fields, }; use promql::native::execute::NativeExecutionState; use promql::native::plan::{ @@ -81,6 +82,7 @@ use crate::promql::native_compile::{ InfoInput, compile_selectors, compile_statement, info_input, statement_grid, }; use crate::promql::planner::{DEFAULT_FIELD_COLUMN, DEFAULT_TIME_INDEX_COLUMN, PromPlanner}; +use crate::query_engine::QueryEngineState; /// The query-context key that turns the native fused-series route on for one query. /// @@ -108,6 +110,58 @@ pub(crate) fn native_promql_requested(query_ctx: &QueryContextRef) -> bool { .is_some_and(|value| value.eq_ignore_ascii_case("true")) } +/// The analyzer rule an engine that plans distributed statements installs on its session; see +/// [`DistPlannerAnalyzer`](crate::dist_plan::analyzer::DistPlannerAnalyzer). +const DIST_PLANNER_RULE: &str = "DistPlannerAnalyzer"; + +/// Whether a plan built here is split into a frontend plan over regions reached over the wire. +/// +/// This is the one condition under which every scan this route prepares has to be a +/// [`RawSeriesSource`]. The remote transport carries a region's half as Substrait bytes, which can +/// only encode that source, so over the wire the single fused node over raw sources is the only +/// shape admitted; in process a region accepts a `LogicalPlan` and the split and segmented shapes +/// keep running region-locally, so those stay and this returns `false`. +/// +/// An engine that plans no distributed statement plans no region at all, and its plans are the +/// standalone ones: it installs the distributed planner as an analyzer rule exactly when it was +/// built to split statements, so the rule says whether this engine has a region to satisfy. +fn plans_over_remote_regions(query_engine_state: &QueryEngineState) -> bool { + !query_engine_state.in_process_region_transport() + && query_engine_state + .session_state() + .analyzer() + .rules + .iter() + .any(|rule| rule.name() == DIST_PLANNER_RULE) +} + +/// Whether this executable plan is the native raw PromQL topology, the one plan shape whose +/// region reads one query-wide body budget cannot deadlock. +/// +/// That topology is a chain of [`FusedSeriesExec`] nodes over region reads: the split aggregate's +/// final and partial halves are one unary chain, and each fused node polls its input while that +/// input is being drained, so a region body holding a permit keeps making progress. +/// Admission stops there: a plan with any other multi-input node (a join, or the union a +/// discovered selector builds) keeps its per-scan bounds only and is not counted against the +/// query-wide target until its own topology is checked against the budget. +pub(crate) fn native_raw_plan_bounds_region_reads(plan: &Arc) -> bool { + fn walk(node: &dyn ExecutionPlan, fused: &mut usize) -> bool { + let is_fused = node.is::(); + if is_fused { + *fused += 1; + } + if node.children().len() > 1 && !is_fused { + return false; + } + node.children() + .iter() + .all(|child| walk(child.as_ref(), fused)) + } + + let mut fused = 0; + walk(plan.as_ref(), &mut fused) && fused > 0 +} + /// The ordering this route compiles its trees against. /// /// Which ordering a raw-series scan declares is decided when the region scanner is prepared, during @@ -176,9 +230,13 @@ impl PromPlanner { pub(super) async fn try_plan_native_operand( &mut self, expr: &PromExpr, + query_engine_state: &QueryEngineState, ) -> Result> { let saved = self.ctx.clone(); - let (plan, operand_ctx) = match self.try_plan_native_fused_with_context(expr).await? { + let (plan, operand_ctx) = match self + .try_plan_native_fused_with_context(expr, query_engine_state) + .await? + { Some((plan, Some(operand_ctx))) => (plan, operand_ctx), _ => { self.ctx = saved; @@ -213,6 +271,7 @@ impl PromPlanner { /// Builds the scan of the one logical table the current context is bound to. The caller has /// already preprocessed this selector's matchers and set the context to its table. + #[allow(clippy::too_many_arguments)] async fn prepare_one_scan( &mut self, matchers: Matchers, @@ -221,6 +280,7 @@ impl PromPlanner { logical_scan_id: &mut Option, logical_ids_differ: &mut bool, statement_kind: &mut Option, + self_contained: bool, ) -> Result> { let (Some(metric), Some(time)) = ( self.ctx.table_name.clone(), @@ -343,20 +403,19 @@ impl PromPlanner { { return Ok(None); } - // Preserve the existing single-selector guard that its partition keys are tags. + // Preserve the existing single-selector guard that its partition keys are tags. A partition + // column that is not a tag is the time index, so one series spans several regions; a bare + // scan cannot reconcile the fragments, which is why this route kept the existing plan for + // it. The raw source can, so the guard only holds the shapes that read a bare scan - the + // ones a region can run in process. if selector_count == 1 + && !self_contained && !table_meta .partition_column_names() .all(|column| tags.iter().any(|tag| tag == column)) { return Ok(None); } - // A multi-scan plan has no placement over a table split into several regions: the - // dist analyzer refuses a multi-child node there, so such a query keeps the - // existing plan instead of failing. - if selector_count > 1 && table_meta.partition_column_names().next().is_some() { - return Ok(None); - } // This route declares one output column per field, so every field it binds carries // one kind: `Float64`, or the canonical native histogram struct. A field of any // other type - an integer, a `Float32`, a decimal, a string - keeps the existing @@ -410,9 +469,10 @@ impl PromPlanner { pub(super) async fn try_plan_native_fused( &mut self, prom_expr: &PromExpr, + query_engine_state: &QueryEngineState, ) -> Result> { Ok(self - .try_plan_native_fused_with_context(prom_expr) + .try_plan_native_fused_with_context(prom_expr, query_engine_state) .await? .map(|(plan, _)| plan)) } @@ -436,10 +496,16 @@ impl PromPlanner { async fn try_plan_native_fused_with_context( &mut self, prom_expr: &PromExpr, + query_engine_state: &QueryEngineState, ) -> Result)>> { if !self.native_fused { return Ok(None); } + // Over the wire this route plans the whole statement as one fused node over raw sources: + // each region answers the series it holds, and the node reconciles them before evaluating. + // In process a region can also run a split or a segmented tree over its own scan, so those + // shapes stay there. This is a planning choice, not a limit of what the node can encode. + let self_contained = plans_over_remote_regions(query_engine_state); // Only the statement root is offered: the tree is compiled against the statement's grid, // and a subquery's expression is evaluated on its own, smaller one. A range-vector root is // the instant query's raw sample result, which the existing path reports as a matrix rather @@ -668,6 +734,7 @@ impl PromPlanner { &mut logical_scan_id, &mut logical_ids_differ, &mut statement_kind, + self_contained, ) .await? else { @@ -765,6 +832,7 @@ impl PromPlanner { &mut logical_scan_id, &mut logical_ids_differ, &mut statement_kind, + self_contained, ) .await? else { @@ -801,6 +869,17 @@ impl PromPlanner { .map(|(scan, ..)| scan) .filter(|scan| !is_empty_discovered_input(scan)), ) || logical_ids_differ; + // A multi-selector tree over a partitioned table has no in-process placement whose matching + // and uniqueness semantics equal the frontend route. One node over several scans of one + // partitioned table reads neither the other scans nor the fragments another region holds, + // and one node over several tables' sources matches every series those sources delivered, + // where the frontend route copies the operands' matchers into their scans first and checks + // uniqueness above the join. Keep the existing plan in process; the hybrid route lifts such + // a tree one operand at a time. Over the wire every occurrence is already its own raw source + // reconciled above the regions, so the route keeps those trees. + if selectors.len() > 1 && !self_contained && prepared.iter().any(|input| input.5) { + return Ok(None); + } // The first input names the output's time index and, on one table, binds every scan. let Some((_, _, metric, time, tags, _)) = prepared.first() else { return Ok(None); @@ -1004,7 +1083,11 @@ impl PromPlanner { LogicalPlan::Extension(extension) if extension.node.as_any().is::() ); - if !cross_table || already_sourced { + // A scan stays bare only where a region runs the node over it in process. Over the + // wire every input is a raw source, whichever table it reads: the source is what the + // transport carries, and it is also what reconciles the fragments of a series that + // several regions hold. + if (!cross_table && !self_contained) || already_sourced { return Ok(scan); } let Some(metric) = metric else { @@ -1111,7 +1194,13 @@ impl PromPlanner { // The aggregate split keeps its prefix per-series, which is why it declines an operation // whose answer depends on the order its input arrives in. A multi-input node reads its // inputs' partitions in the order they became ready, so that refusal is repeated here. - if multi_input && depends_on_input_order(root) { + if (multi_input || (self_contained && children.len() > 1)) && depends_on_input_order(root) { + return Ok(None); + } + // Two sources that report groups by metric name need a column for that name: without one, + // groups that differ only by metric would be reported as the same label set. A discovered + // selector carries that column itself; several explicit selectors do not. + if (multi_input || (self_contained && children.len() > 1)) && groups_by_metric_name(root) { return Ok(None); } // The native output schema can name only compiled value fields, the time index and the tag @@ -1126,8 +1215,9 @@ impl PromPlanner { // Catch construction-time refusals before choosing native execution: errors raised during // physical planning cannot fall back. This includes unsupported aggregates and `topk`, // `limitk` or CountValues groupings; it does not cover data-dependent errors raised while - // executing the tree. - if multi_input + // executing the tree. A tree planned over the wire commits to the fused node without the + // split or a segment above it, so it validates itself the same way before that choice. + if (multi_input || self_contained) && NativeExecutionState::try_new(&tree, Arc::new(UnboundedMemoryPool::default()), None) .is_err() { @@ -1169,7 +1259,9 @@ impl PromPlanner { // would. The general segmentation below is the fallback for the trees it declines, // which are the ones its per-series prefix cannot express. The split is decided before // anything consumes a child, so a tree it declines keeps the plan it would have built - // without this route. + // without this route. Its producer reads whatever input the statement prepared: over + // the wire that is the raw series source, and the partial/final halves stay on the + // frontend above the regions, so per-series work keeps the scan width. let split = if !multi_input && selectors.len() == 1 { FusedSeries::split_aggregate(&tree, &time).context(DataFusionPlanningSnafu)? } else { @@ -1216,6 +1308,9 @@ impl PromPlanner { return Ok(None); } } + // A segment over the wire keeps the raw source as its input rather than a bare scan: the + // segment's prefixes run on the frontend above the regions, so the raw series source is + // what each of them reads. if required_placement || matches!(locality, InputLocality::SinglePartition) { let segment_metric = if cross_table { None } else { metric.clone() }; let plan = Box::pin(segment_tree( @@ -1232,6 +1327,7 @@ impl PromPlanner { FusedOutputFormat::PlainRows, contains_canonical_merge(root), root_kind, + self_contained, )) .await?; if let Some(plan) = plan { @@ -1277,8 +1373,9 @@ impl PromPlanner { // already carry their own labels, so it binds neither tags nor one metric name of its own - // each child names the metric it reads. A multi-input plan whose children stay direct // scans reads one table through the one metric and tag set they share, and keeps this - // binding, which is the same identity those scans carry. - let (tags, metric) = if cross_table { + // binding, which is the same identity those scans carry. The same holds over the wire, + // where every input is a raw source. + let (tags, metric) = if cross_table || self_contained { (Vec::new(), None) } else { (tags, metric) @@ -2113,6 +2210,7 @@ async fn segment_tree( format: FusedOutputFormat, canonical_segmentation: bool, root_kind: FieldKind, + remote_raw_boundary: bool, ) -> Result> { if !matches!(input_locality(tree.root()), InputLocality::SinglePartition) { return Ok(None); @@ -2183,6 +2281,7 @@ async fn segment_tree( FusedOutputFormat::SeriesFrame, canonical_segmentation, root_kind, + remote_raw_boundary, )) .await?; match plan { @@ -2194,7 +2293,7 @@ async fn segment_tree( } None => None, } - } else if first_iteration && !canonical { + } else if first_iteration && !canonical && !remote_raw_boundary { build_inner_segment(cut, bare_scans, per_source, grid) } else { None @@ -3197,6 +3296,7 @@ mod tests { use std::time::{Duration, UNIX_EPOCH}; + use datafusion::physical_plan::ExecutionPlan; use datatypes::series::SeriesOrdering; use datatypes::series::samples::{FieldSpec, SeriesSchema}; use promql::native::plan::{NativeExpr, NativeNode, NativeTree}; @@ -3205,9 +3305,33 @@ mod tests { use super::{ ArrowDataType, ArrowTimeUnit, FieldKind, METRIC_NAME, NATIVE_PROMQL_EXTENSION_KEY, NativeType, collect_selectors, cut_segments, fused_output_schema, hybrid_binary_admitted, - independent_scan_pair, native_output_tags, native_promql_requested, scan_time_filter, + independent_scan_pair, native_output_tags, native_promql_requested, + native_raw_plan_bounds_region_reads, scan_time_filter, }; + #[test] + fn native_raw_region_read_budget_needs_the_native_topology() { + let schema = Arc::new(datafusion::arrow::datatypes::Schema::new(vec![ + datafusion::arrow::datatypes::Field::new( + "ts", + datafusion::arrow::datatypes::DataType::Int64, + false, + ), + ])); + let scan = || { + Arc::new(datafusion::physical_plan::empty::EmptyExec::new( + schema.clone(), + )) as Arc + }; + + // No `FusedSeriesExec`: nothing here reads regions the way the budget assumes. + assert!(!native_raw_plan_bounds_region_reads(&scan())); + // A union drains its inputs one after another, so a body budget could stall it. + let union = datafusion::physical_plan::union::UnionExec::try_new(vec![scan(), scan()]) + .expect("two inputs"); + assert!(!native_raw_plan_bounds_region_reads(&union)); + } + fn compiled_test_tree(query: &str) -> NativeTree { compiled_test_tree_with_fields(query, &["v0"]) } diff --git a/src/query/src/promql/planner/test.rs b/src/query/src/promql/planner/test.rs index 50c38650e57..72ce3ba97d3 100644 --- a/src/query/src/promql/planner/test.rs +++ b/src/query/src/promql/planner/test.rs @@ -3757,17 +3757,65 @@ async fn native_fused_same_table_nested_match_keeps_prior_admission() { ); } -/// Two selectors over tables split into regions are not one two-input node, across tables as on -/// one; the hybrid route may still plan each operand natively under the existing join. +/// On the wire, partitioned cross-table operands are independently transported by raw sources: +/// the pair is one fused node whose two inputs each name the metric they read. In process the same +/// pair keeps the frontend hybrid route instead, because only that route copies the matcher's +/// labels into each operand's scan and checks uniqueness above the join. Repeated scans of one +/// partitioned table retain the region-local multi-scan refusal on both routes. #[tokio::test] -async fn native_fused_cross_table_pair_on_partitioned_tables_falls_back() { - let plan = build_native_fused_plan_with_provider( +async fn native_fused_partitioned_pair_requires_per_selector_raw_sources() { + let state = QueryEngineState::try_new_with_region_transport( + new_memory_catalog_manager().unwrap(), + None, + None, + None, + None, + None, + true, + false, + Plugins::default(), + QueryOptions::default(), + ) + .unwrap(); + let eval_stmt = build_eval_stmt("some_metric / other_metric"); + let plan = PromPlanner::stmt_to_plan_with_annotations( + native_two_table_provider(vec![0]).await, + &eval_stmt, + &state, + None, + true, + ) + .await + .unwrap(); + let fused = find_fused_series(&plan).expect("cross-table pair is native on the wire"); + assert_eq!(fused.inputs().len(), 2, "{plan}"); + for input in fused.inputs() { + assert!( + matches!(input, LogicalPlan::Extension(extension) + if extension.node.as_any().is::()), + "{plan}" + ); + } + // The same pair in process must not become one two-input node: the frontend hybrid route is + // what the matcher propagation and the uniqueness check live in, and that is the plan the + // partitioned-RHS hybrid cases assert. + let in_process = build_native_fused_plan_with_provider( "some_metric / other_metric", true, native_two_table_provider(vec![0]).await, ) .await; - assert!(!has_pair_node(&plan), "{plan}"); + assert!( + !has_pair_node(&in_process), + "an in-process partitioned pair keeps the hybrid route: {in_process}" + ); + let repeated = build_native_fused_plan_with_provider( + "some_metric / some_metric", + true, + native_two_table_provider(vec![0]).await, + ) + .await; + assert!(!has_pair_node(&repeated), "{repeated}"); } /// `some_metric` as [`native_two_table_provider`] builds it, and `other_metric` whose tags are @@ -4113,22 +4161,17 @@ async fn native_fused_three_selector_trees_bind_every_occurrence() { } } -/// More than two selectors over tables split into regions are not one multi-input node, on one -/// table as across two. +/// More than two same-table selectors on a partitioned table must not be placed as a +/// multi-child region-local node. Cross-table occurrences may each use a raw source. #[tokio::test] -async fn native_fused_three_selectors_on_partitioned_tables_fall_back() { - for query in [ +async fn native_fused_same_table_three_selectors_on_partitioned_table_fall_back() { + let plan = build_native_fused_plan_with_provider( "some_metric + some_metric + some_metric", - "some_metric / other_metric * some_metric", - ] { - let plan = build_native_fused_plan_with_provider( - query, - true, - native_two_table_provider(vec![0]).await, - ) - .await; - assert!(!has_pair_node(&plan), "{query}: {plan}"); - } + true, + native_two_table_provider(vec![0]).await, + ) + .await; + assert!(!has_pair_node(&plan), "{plan}"); } /// Find the final half of a split aggregate. @@ -4865,9 +4908,10 @@ async fn native_fused_histogram_quantile_binary_drops_le_from_operand_matching() else { unreachable!() }; + let query_engine_state = build_query_engine_state(); for operand in [&binary.lhs, &binary.rhs] { let (_, context) = planner - .try_plan_native_operand(operand) + .try_plan_native_operand(operand, &query_engine_state) .await .unwrap() .expect("each histogram call is admitted as one native operand"); diff --git a/src/query/src/query_engine/context.rs b/src/query/src/query_engine/context.rs index 3386a38e238..1430c4ee7c8 100644 --- a/src/query/src/query_engine/context.rs +++ b/src/query/src/query_engine/context.rs @@ -42,6 +42,13 @@ impl QueryEngineContext { self.query_ctx.clone() } + /// The session configuration the execution task context is built from, so that a plan may + /// extend it before execution. + #[inline] + pub fn config_mut(&mut self) -> &mut datafusion::execution::config::SessionConfig { + self.state.config_mut() + } + pub fn build_task_ctx(&self) -> Arc { let dbname = self.query_ctx.get_db_string(); let state = &self.state; diff --git a/src/query/src/query_engine/state.rs b/src/query/src/query_engine/state.rs index 1b2fd6ea85e..d8b6914b692 100644 --- a/src/query/src/query_engine/state.rs +++ b/src/query/src/query_engine/state.rs @@ -748,15 +748,189 @@ mod tests { use datafusion::error::DataFusionError; use datafusion::execution::memory_pool::{GreedyMemoryPool, MemoryLimit as DfMemoryLimit}; use datafusion::execution::runtime_env::{RuntimeEnv, RuntimeEnvBuilder}; + use datafusion::logical_expr::physical_planning_context::PhysicalPlanningContext; use datafusion_common::config::SpillCompression; + use promql::extension_plan::{FusedSeries, RawSeriesSource}; use session::context::QueryContext; use super::*; + use crate::dist_plan::{MergeScanExec, MergeScanLogicalPlan}; use crate::options::{QueryOptions, QuerySpillCompression, QuerySpillMode}; use crate::query_engine::runtime::{ DefaultQueryRuntimeProvider, QueryRuntimeContext, QueryRuntimeProvider, QueryRuntimeProviderRef, }; + use datafusion_expr::UserDefinedLogicalNode; + + #[derive(Default)] + struct TestRawMergePlanner { + disjoint: bool, + } + + #[async_trait] + impl ExtensionPlanner for TestRawMergePlanner { + async fn plan_extension( + &self, + _planner: &dyn PhysicalPlanner, + node: &dyn UserDefinedLogicalNode, + _logical_inputs: &[&DfLogicalPlan], + _physical_inputs: &[Arc], + session: &dyn Session, + _planning_ctx: &PhysicalPlanningContext, + ) -> DfResult>> { + let Some(scan) = node.as_any().downcast_ref::() else { + return Ok(None); + }; + let session = session.as_any().downcast_ref::().unwrap(); + let merge = MergeScanExec::new( + session, + table::table_name::TableName::new("c", "s", "metric"), + vec![ + store_api::storage::RegionId::new(1, 1), + store_api::storage::RegionId::new(1, 2), + ], + scan.input().clone(), + scan.schema().as_arrow(), + Arc::new(crate::region_query::tests::PlanningOnlyRegionQueryHandler), + QueryContext::arc(), + session.config().target_partitions(), + None, + false, + )? + .with_raw_series_disjoint(self.disjoint)?; + Ok(Some(Arc::new(merge))) + } + } + + /// Run the real analyzer and normal DataFusion optimizer pipeline, not a hand-built projection. + #[tokio::test] + async fn analyzer_to_fused_reconciles_only_fragmented_raw_frames() { + use common_query::series_frame::series_frame_ordering; + use datafusion::datasource::DefaultTableSource; + use datafusion_expr::{Extension, LogicalPlanBuilder}; + use datafusion_optimizer::analyzer::AnalyzerRule; + use datatypes::series::SeriesOrdering; + use datatypes::series::samples::{FieldSpec, SeriesSchema}; + use datatypes::series::time::{EvalGrid, GridSpec}; + use promql::extension_plan::{FusedSeriesBinding, SeriesRepartitionExec}; + use promql::native::plan::{ + BoundInput, BoundInstant, InstantValue, NativeExpr, NativeNode, NativeTree, NativeType, + }; + use store_api::storage::RegionId; + + let table = LogicalPlanBuilder::scan( + "metric", + Arc::new(DefaultTableSource::new(Arc::new( + crate::optimizer::test_util::mock_table_provider(RegionId::new(1, 1)), + ))), + None, + ) + .unwrap() + .build() + .unwrap(); + let raw = RawSeriesSource::try_new( + Arc::from("metric"), + vec!["host".into()], + vec!["v0".into()], + table, + ) + .unwrap(); + let grid = Arc::new(EvalGrid::try_new(GridSpec::try_new(0, 1, 1).unwrap()).unwrap()); + let raw_type = NativeType::Samples(Arc::new(SeriesSchema { + fields: vec![FieldSpec { name: "v0".into() }].into(), + eval_grid: None, + })); + let evaluated = NativeType::Samples(Arc::new(SeriesSchema { + fields: vec![FieldSpec { name: "v0".into() }].into(), + eval_grid: Some(Arc::clone(&grid)), + })); + let tree = NativeTree::try_new(NativeNode { + expr: NativeExpr::Instant { + input: Box::new(NativeNode { + expr: NativeExpr::Input(BoundInput { + source_index: 0, + output: raw_type.clone(), + ordering: SeriesOrdering::Contiguous, + }), + output: raw_type, + }), + op: BoundInstant { + lookback_ms: 0, + offset_ms: 0, + at_ms: None, + value: InstantValue::Sample, + output_grid: Arc::clone(&grid), + }, + }, + output: evaluated, + }) + .unwrap(); + let output = datafusion_common::DFSchema::from_unqualified_fields( + vec![ + arrow_schema::Field::new( + "time", + arrow_schema::DataType::Timestamp(arrow_schema::TimeUnit::Millisecond, None), + false, + ), + arrow_schema::Field::new("v0", arrow_schema::DataType::Float64, true), + arrow_schema::Field::new("host", arrow_schema::DataType::Utf8, true), + ] + .into(), + Default::default(), + ) + .unwrap(); + let raw_plan = DfLogicalPlan::Extension(Extension { + node: Arc::new(raw), + }); + for (disjoint, needs_router) in [(true, false), (false, true)] { + let fused = FusedSeries::try_new( + Arc::from("metric"), + tree.clone(), + FusedSeriesBinding { + grid: Arc::clone(&grid), + time_index: "time".into(), + tags: vec!["host".into()], + metric_name: Some(Arc::from("metric")), + }, + vec![raw_plan.clone()], + Arc::new(output.clone()), + ) + .unwrap(); + let logical = DfLogicalPlan::Extension(Extension { + node: Arc::new(fused), + }); + let analyzed = DistPlannerAnalyzer::new(false) + .analyze( + logical, + &datafusion_common::config::ConfigOptions::default(), + ) + .unwrap(); + let session = SessionStateBuilder::new().with_default_features().build(); + let physical = DefaultPhysicalPlanner::with_extension_planners(vec![ + Arc::new(PromExtensionPlanner), + Arc::new(TestRawMergePlanner { disjoint }), + ]) + .create_physical_plan(&analyzed, &session) + .await + .unwrap(); + let child = physical.children()[0]; + assert_eq!( + child.downcast_ref::().is_some(), + needs_router, + "disjoint={disjoint}: {analyzed}" + ); + if let Some(router) = child.downcast_ref::() { + assert_eq!( + series_frame_ordering(router.children()[0].schema().as_ref()).unwrap(), + SeriesOrdering::Interleaved + ); + } + assert_eq!( + series_frame_ordering(child.schema().as_ref()).unwrap(), + SeriesOrdering::Contiguous + ); + } + } fn new_query_engine_state() -> QueryEngineState { new_query_engine_state_with(Plugins::default(), QueryOptions::default()) diff --git a/src/query/src/region_query.rs b/src/query/src/region_query.rs index 4d2dfb68d60..109d00d9b45 100644 --- a/src/query/src/region_query.rs +++ b/src/query/src/region_query.rs @@ -22,9 +22,36 @@ use common_query::request::QueryRequest; use common_recordbatch::SendableRecordBatchStream; use partition::manager::PartitionRuleManagerRef; use session::ReadPreference; +use tokio::sync::{Semaphore, SemaphorePermit}; use crate::error::Result; +/// Caps the region reads one query keeps in flight. +/// +/// A region read is a `DoGet` whose body streams until that region is drained, so a query +/// reading several sources would otherwise run one body per source and partition at once. +/// The bound belongs to the query, not to one scan: its permit count is the query's target +/// partitions, so two scans of three regions no longer read four bodies at once. +pub(crate) struct RegionReadLimiter { + permits: Semaphore, +} + +impl RegionReadLimiter { + pub(crate) fn new(permits: usize) -> Self { + Self { + permits: Semaphore::new(permits.max(1)), + } + } + + /// Waits for one region read to be allowed; the read stays counted until the permit drops. + pub(crate) async fn acquire(&self) -> SemaphorePermit<'_> { + self.permits + .acquire() + .await + .expect("the region read limiter is never closed") + } +} + /// The peer selected to serve a region query. /// /// The target is frozen when the query is dispatched. Follow-up controls must @@ -86,10 +113,52 @@ pub trait RegionQueryHandler: Send + Sync { pub type RegionQueryHandlerRef = Arc; #[cfg(test)] -mod tests { +pub(crate) mod tests { + use async_trait::async_trait; use common_meta::peer::Peer; + use session::ReadPreference; + use store_api::storage::RegionId; - use super::RegionQueryTarget; + use super::{RegionQueryHandler, RegionQueryTarget}; + + pub(crate) struct PlanningOnlyRegionQueryHandler; + + #[async_trait] + impl RegionQueryHandler for PlanningOnlyRegionQueryHandler { + async fn select_target( + &self, + _read_preference: ReadPreference, + _region_id: RegionId, + ) -> crate::error::Result { + unimplemented!("planning test does not dispatch regions") + } + + async fn do_get( + &self, + _target: &RegionQueryTarget, + _request: common_query::request::QueryRequest, + ) -> crate::error::Result { + unimplemented!("planning test does not dispatch regions") + } + + async fn handle_remote_dyn_filter_update( + &self, + _target: &RegionQueryTarget, + _query_id: String, + _update: api::v1::region::RemoteDynFilterUpdate, + ) -> crate::error::Result<()> { + unimplemented!("planning test does not dispatch regions") + } + + async fn handle_remote_dyn_filter_unregister( + &self, + _target: &RegionQueryTarget, + _query_id: String, + _unregister: api::v1::region::RemoteDynFilterUnregister, + ) -> crate::error::Result<()> { + unimplemented!("planning test does not dispatch regions") + } + } #[test] fn region_query_target_exposes_immutable_peer() { diff --git a/src/table/src/table/scan.rs b/src/table/src/table/scan.rs index 7eadec286b5..ca4644424c2 100644 --- a/src/table/src/table/scan.rs +++ b/src/table/src/table/scan.rs @@ -614,6 +614,14 @@ impl RegionScanExec { let ordering = scanner .raw_series_ordering() .map_err(|e| DataFusionError::External(Box::new(e)))?; + // A scan's planned ordering is a guarantee its own partitions keep. Interleaved is a + // transport annotation for fragments several producers contribute; it is not something a + // single scanner can promise, so a scan that planned it is refused here. + if ordering == SeriesOrdering::Interleaved { + return Err(DataFusionError::Plan( + "a scan cannot plan interleaved raw series ordering".into(), + )); + } let arrow_schema = raw_series_frame_schema_with_ordering(&schema, &label_source, ordering)?; let partition_count = scanner.properties().num_partitions().max(1); let properties = Arc::new(PlanProperties::new( diff --git a/tests-integration/src/cluster.rs b/tests-integration/src/cluster.rs index e74a53b21bb..6b31c706fe5 100644 --- a/tests-integration/src/cluster.rs +++ b/tests-integration/src/cluster.rs @@ -14,10 +14,12 @@ use std::collections::{BTreeSet, HashMap}; use std::env; +use std::future::Future; use std::net::TcpListener; -use std::ops::RangeInclusive; -use std::sync::Arc; +use std::ops::{Deref, DerefMut, RangeInclusive}; +use std::pin::Pin; use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; use std::task::{Context, Poll}; use std::time::Duration; @@ -88,21 +90,61 @@ use crate::test_util::{ create_tmp_dir_and_datanode_opts, }; -/// Flight `DoGet` requests another node sent to a datanode over its network address (see -/// [`GreptimeDbClusterBuilder::with_real_datanode_grpc_addr`]). -/// -/// The frontend and datanodes inside the test process use in-process clients, so counted requests -/// come from remote nodes querying regions owned by this datanode. +/// Flight `DoGet` requests sent to a datanode over its network address (see +/// [`GreptimeDbClusterBuilder::with_real_datanode_grpc_addr`]). In-process duplex requests are not +/// counted. Request totals are per datanode; active and peak counts are shared by all datanode +/// listeners in the cluster. By default, the frontend uses duplex, but it can opt into TCP with +/// [`GreptimeDbClusterBuilder::with_frontend_real_datanode_grpc`]. #[derive(Debug, Default)] pub struct DatanodeRpcStats { do_get_requests: AtomicUsize, + active: Arc>, +} + +#[derive(Debug, Default)] +struct ActiveDoGet { + current: usize, + peak: usize, } impl DatanodeRpcStats { - /// The number of Flight `DoGet` requests another node sent to the datanode. + /// The total number of Flight `DoGet` requests received over TCP. pub fn requests(&self) -> usize { self.do_get_requests.load(Ordering::Relaxed) } + + /// The cluster-wide number of TCP `DoGet` calls with a pending response or live response body. + pub fn active(&self) -> usize { + self.active.lock().unwrap().current + } + + /// The cluster-wide peak number of concurrently active TCP `DoGet` calls since the last reset. + pub fn peak_active(&self) -> usize { + self.active.lock().unwrap().peak + } + + /// Reset the peak to the number of currently active calls. + pub fn reset_peak_active(&self) { + let mut active = self.active.lock().unwrap(); + active.peak = active.current; + } + + fn start(self: &Arc) -> DoGetGuard { + self.do_get_requests.fetch_add(1, Ordering::Relaxed); + let mut active = self.active.lock().unwrap(); + active.current += 1; + active.peak = active.peak.max(active.current); + DoGetGuard(self.clone()) + } +} + +/// Keeps a `DoGet` active until its response body is dropped, including cancellation and errors. +struct DoGetGuard(Arc); + +impl Drop for DoGetGuard { + fn drop(&mut self) { + self.0.active.lock().unwrap().current -= 1; + } } pub struct GreptimeDbCluster { @@ -113,6 +155,7 @@ pub struct GreptimeDbCluster { /// The stats of the network address of every datanode, empty unless the cluster serves the /// datanodes at their own addresses. pub datanode_rpc_stats: HashMap>, + network_do_get: Arc>, pub kv_backend: KvBackendRef, pub metasrv: Arc, pub frontend: Arc, @@ -130,6 +173,22 @@ impl GreptimeDbCluster { self.datanode_rpc_stats.get(&datanode_id) } + /// Number of active TCP `DoGet` calls across all datanodes in this cluster. + pub fn network_do_get_active(&self) -> usize { + self.network_do_get.lock().unwrap().current + } + + /// Peak active TCP `DoGet` calls across all datanodes since the last reset. + pub fn network_do_get_peak_active(&self) -> usize { + self.network_do_get.lock().unwrap().peak + } + + /// Reset the cluster-wide peak to the number of currently active calls. + pub fn reset_network_do_get_peak(&self) { + let mut active = self.network_do_get.lock().unwrap(); + active.peak = active.current; + } + /// List all SST files from all datanodes. pub async fn list_sst_files_from_all_datanodes(&self) -> BTreeSet { let mut sst_files = BTreeSet::new(); @@ -209,6 +268,8 @@ pub struct GreptimeDbClusterBuilder { local_file_access: LocalFileAccess, event_recorder_options: EventRecorderOptions, real_datanode_grpc_addr: bool, + frontend_real_datanode_grpc: bool, + query_options: query::options::QueryOptions, } impl GreptimeDbClusterBuilder { @@ -247,6 +308,8 @@ impl GreptimeDbClusterBuilder { local_file_access: LocalFileAccess::default(), event_recorder_options: EventRecorderOptions::default(), real_datanode_grpc_addr: false, + frontend_real_datanode_grpc: false, + query_options: query::options::QueryOptions::default(), } } @@ -347,6 +410,21 @@ impl GreptimeDbClusterBuilder { self } + /// Routes frontend-to-datanode RPCs through real TCP clients instead of duplex clients. + /// This only has an effect when `with_real_datanode_grpc_addr(true)` is also set. + #[must_use] + pub fn with_frontend_real_datanode_grpc(mut self, enabled: bool) -> Self { + self.frontend_real_datanode_grpc = enabled; + self + } + + /// Overrides query options for this test cluster's frontend. + #[must_use] + pub fn with_query_options(mut self, options: query::options::QueryOptions) -> Self { + self.query_options = options; + self + } + pub async fn build_with( &self, datanode_options: Vec, @@ -356,7 +434,7 @@ impl GreptimeDbClusterBuilder { let datanodes = datanode_options.len(); let channel_config = ChannelConfig::new().timeout(Some(Duration::from_secs(20))); - let datanode_clients = Arc::new(NodeClients::new(channel_config)); + let datanode_clients = Arc::new(NodeClients::new(channel_config.clone())); let opt = MetasrvOptions { procedure: ProcedureConfig { @@ -394,10 +472,19 @@ impl GreptimeDbClusterBuilder { .build_datanodes_with_options(&metasrv, &datanode_options) .await; + let network_do_get = Arc::new(Mutex::new(ActiveDoGet::default())); let datanode_rpc_stats = if self.real_datanode_grpc_addr { datanode_options .iter() - .map(|opts| (opts.node_id.unwrap(), Arc::new(DatanodeRpcStats::default()))) + .map(|opts| { + ( + opts.node_id.unwrap(), + Arc::new(DatanodeRpcStats { + active: network_do_get.clone(), + ..Default::default() + }), + ) + }) .collect::>() } else { HashMap::new() @@ -414,12 +501,15 @@ impl GreptimeDbClusterBuilder { self.wait_datanodes_alive(metasrv.metasrv.meta_peer_client(), datanodes) .await; + // Metasrv keeps its duplex clients; the frontend gets an empty cache so its misses + // construct TCP clients using the addresses registered by the datanodes. + let frontend_clients = if self.real_datanode_grpc_addr && self.frontend_real_datanode_grpc { + Arc::new(NodeClients::new(channel_config)) + } else { + datanode_clients.clone() + }; let mut frontend = self - .build_frontend( - metasrv.clone(), - datanode_clients.clone(), - start_frontend_servers, - ) + .build_frontend(metasrv.clone(), frontend_clients, start_frontend_servers) .await; frontend.start().await.unwrap(); @@ -429,6 +519,7 @@ impl GreptimeDbClusterBuilder { guards, datanode_instances, datanode_rpc_stats, + network_do_get, kv_backend: self.kv_backend.clone(), metasrv: metasrv.metasrv, frontend: Arc::new(frontend), @@ -653,6 +744,7 @@ impl GreptimeDbClusterBuilder { let mut fe_opts = FrontendOptions { auto_create_table: self.frontend_auto_create_table, event_recorder: self.event_recorder_options.clone(), + query: self.query_options.clone(), ..Default::default() }; @@ -771,14 +863,12 @@ fn serve_datanode_region_server( /// Serves the region server of `datanode` and returns the address and the client of the address. /// -/// The returned client is always an in-process client: the frontend and the datanodes of the test -/// process reach the region server through a duplex stream, no matter which address they use. This -/// keeps the in-process traffic out of `rpc_stats`. +/// The returned client is always an in-process duplex client, keeping its traffic out of +/// `rpc_stats`. The frontend can instead use separate TCP clients when opted in. /// /// [`test_util::PEER_PLACEHOLDER_ADDR`] is not a real address, so it cannot be served over the /// network at all. Any other address is a real one: the region server is additionally served on -/// its local TCP port (`rpc_stats` counts the requests of the remote nodes that reach it, e.g. the -/// region query that a datanode sends for the regions of another datanode). +/// its local TCP port, and `rpc_stats` counts requests reaching that port. async fn create_datanode_client( datanode: &Datanode, addr: &str, @@ -831,24 +921,61 @@ struct CountRequests { impl Service> for CountRequests where - S: Service>, + S: Service, Response = http::Response>, + S::Future: Send + 'static, + S::Error: Send + 'static, { - type Response = S::Response; + type Response = http::Response; type Error = S::Error; - type Future = S::Future; + type Future = Pin> + Send>>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { self.inner.poll_ready(cx) } fn call(&mut self, request: http::Request) -> Self::Future { - if request.uri().path() == "/arrow.flight.protocol.FlightService/DoGet" - && let Some(rpc_stats) = &self.rpc_stats - { - rpc_stats.do_get_requests.fetch_add(1, Ordering::Relaxed); - } + let guard = if request.uri().path() == "/arrow.flight.protocol.FlightService/DoGet" { + self.rpc_stats.as_ref().map(DatanodeRpcStats::start) + } else { + None + }; + let future = self.inner.call(request); - self.inner.call(request) + Box::pin(async move { + let response = future.await?; + Ok(response.map(|body| match guard { + Some(guard) => { + // The pinned body delegates HTTP frames (including gRPC trailers) while the + // pointer owns the guard until the body is dropped. + tonic::body::Body::new(Pin::new(GuardedBody { + body: Box::new(body), + _guard: guard, + })) + } + None => body, + })) + }) + } +} + +// Dereferencing to the inner body lets tonic wrap it while keeping the guard alive until the +// streaming body is completed and dropped, or the caller cancels the response. +struct GuardedBody { + body: Box, + _guard: DoGetGuard, +} + +impl Deref for GuardedBody { + type Target = tonic::body::Body; + + fn deref(&self) -> &Self::Target { + &self.body + } +} + +impl DerefMut for GuardedBody { + fn deref_mut(&mut self) -> &mut Self::Target { + &mut self.body } } @@ -893,6 +1020,104 @@ mod tests { use super::*; + #[tokio::test] + async fn test_do_get_stats_follow_response_body_lifetime() { + let stats = Arc::new(DatanodeRpcStats::default()); + let mut service = CountRequests { + inner: service_fn(|_: http::Request<()>| async { + let stream = futures::stream::once(async { + Ok::<_, std::io::Error>(axum::body::Bytes::from_static(b"data")) + }); + let body = tonic::body::Body::new(axum::body::Body::from_stream(stream)); + Ok::<_, std::convert::Infallible>(http::Response::new(body)) + }), + rpc_stats: Some(stats.clone()), + }; + let request = || { + http::Request::builder() + .uri("/arrow.flight.protocol.FlightService/DoGet") + .body(()) + .unwrap() + }; + + let first = service.call(request()).await.unwrap(); + let other_stats = Arc::new(DatanodeRpcStats { + active: stats.active.clone(), + ..Default::default() + }); + service.rpc_stats = Some(other_stats.clone()); + let second = service.call(request()).await.unwrap(); + assert_eq!( + ( + stats.requests(), + other_stats.requests(), + stats.active(), + stats.peak_active() + ), + (1, 1, 2, 2) + ); + assert_eq!((other_stats.active(), other_stats.peak_active()), (2, 2)); + stats.reset_peak_active(); + assert_eq!(stats.peak_active(), 2); + + // Completing one body and dropping another both release their guards. + let body = axum::body::Body::new(first.into_body()); + assert_eq!( + axum::body::to_bytes(body, usize::MAX).await.unwrap(), + "data" + ); + assert_eq!(stats.active(), 1); + stats.reset_peak_active(); + assert_eq!(stats.peak_active(), 1); + drop(second); + assert_eq!(stats.active(), 0); + stats.reset_peak_active(); + assert_eq!(stats.peak_active(), 0); + + let other = http::Request::builder().uri("/other").body(()).unwrap(); + let other = service.call(other).await.unwrap(); + assert_eq!( + (stats.requests(), other_stats.requests(), stats.active()), + (1, 1, 0) + ); + drop(other); + } + + #[tokio::test] + async fn test_do_get_stats_release_on_future_cancel_or_error() { + let stats = Arc::new(DatanodeRpcStats::default()); + let request = || { + http::Request::builder() + .uri("/arrow.flight.protocol.FlightService/DoGet") + .body(()) + .unwrap() + }; + let mut pending = CountRequests { + inner: service_fn(|_: http::Request<()>| { + std::future::pending::< + Result, std::convert::Infallible>, + >() + }), + rpc_stats: Some(stats.clone()), + }; + let future = pending.call(request()); + assert_eq!(stats.active(), 1); + drop(future); + assert_eq!(stats.active(), 0); + + let mut failing = CountRequests { + inner: service_fn(|_: http::Request<()>| async { + Err::, _>(std::io::Error::other("failed")) + }), + rpc_stats: Some(stats.clone()), + }; + assert!(failing.call(request()).await.is_err()); + assert_eq!( + (stats.requests(), stats.active(), stats.peak_active()), + (2, 0, 1) + ); + } + const HEALTH_REFRESH_INTERVAL: Duration = Duration::from_millis(10); const HEALTH_REFRESH_TIMEOUT: Duration = Duration::from_secs(5); diff --git a/tests-integration/src/tests/promql_test.rs b/tests-integration/src/tests/promql_test.rs index 56d23014453..19df9b06139 100644 --- a/tests-integration/src/tests/promql_test.rs +++ b/tests-integration/src/tests/promql_test.rs @@ -54,6 +54,7 @@ use table::table::scan::SeriesScanExec; use super::test_util::{ both_instances_cases, check_unordered_output_stream, distributed, standalone, }; +use crate::cluster::GreptimeDbClusterBuilder; use crate::standalone::GreptimeDbStandaloneBuilder; use crate::tests::test_util::MockInstance; @@ -1944,6 +1945,57 @@ async fn collect_error(output: Output) -> String { } } +/// Like [`native_result_rows`], with both label columns of the discovery fixture. +async fn native_site_rows(output: Output) -> Vec<(i64, String, String, f64)> { + let batches = match output.data { + OutputData::Stream(stream) => collect_batches(stream).await.unwrap(), + OutputData::RecordBatches(batches) => batches, + _ => unreachable!("TQL EVAL returns record batches"), + }; + let mut rows = batches + .iter() + .flat_map(|batch| { + let timestamps = batch + .column_by_name("ts") + .unwrap() + .as_any() + .downcast_ref::() + .unwrap(); + let host = cast( + batch.column_by_name("host").unwrap().as_ref(), + &DataType::Utf8, + ) + .unwrap(); + let host = host.as_any().downcast_ref::().unwrap(); + let site = cast( + batch.column_by_name("site").unwrap().as_ref(), + &DataType::Utf8, + ) + .unwrap(); + let site = site.as_any().downcast_ref::().unwrap(); + let values = batch + .columns() + .iter() + .filter(|column| column.data_type() == &DataType::Float64) + .collect::>(); + assert_eq!(values.len(), 1, "expected one Float64 value column"); + let values = values[0].as_any().downcast_ref::().unwrap(); + (0..batch.num_rows()) + .map(|row| { + ( + timestamps.value(row), + host.value(row).to_string(), + site.value(row).to_string(), + values.value(row), + ) + }) + .collect::>() + }) + .collect::>(); + rows.sort_by(|left, right| left.partial_cmp(right).unwrap()); + rows +} + async fn native_result_rows(output: Output) -> Vec<(i64, String, f64)> { let batches = match output.data { OutputData::Stream(stream) => collect_batches(stream).await.unwrap(), @@ -2400,6 +2452,1164 @@ async fn native_test_instance_with_options( (standalone, observer) } +async fn native_scalar_rows(output: Output) -> Vec<(i64, f64)> { + let batches = match output.data { + OutputData::Stream(stream) => collect_batches(stream).await.unwrap(), + OutputData::RecordBatches(batches) => batches, + _ => unreachable!("PromQL query returns record batches"), + }; + let mut rows = Vec::new(); + for batch in batches { + let timestamps = batch + .column_by_name("ts") + .unwrap() + .as_any() + .downcast_ref::() + .unwrap(); + let values = batch + .columns() + .iter() + .filter(|column| column.data_type() == &DataType::Float64) + .collect::>(); + assert_eq!(values.len(), 1, "one result value column"); + assert_eq!(batch.num_columns(), 2, "scalar output has no labels"); + let values = values[0].as_any().downcast_ref::().unwrap(); + for row in 0..batch.num_rows() { + rows.push((timestamps.value(row), values.value(row))); + } + } + rows.sort_by_key(|row| row.0); + rows +} + +/// The shape a native distributed plan is asserted on: its fused producer, the region set every +/// merge scan selects, the routers that reconcile series several regions hold, and the per-series +/// order every merge scan declares. +struct NativePlanShape { + fused: usize, + regions_per_scan: Vec, + routers: usize, + /// `SeriesRepartitionExec` nodes inside the subtree of the single `FusedSeriesExec`, i.e. the + /// routers that have to reconcile fragments of one series before the fused node reads them. + /// A router above the fused node (the coalescer of its output) is not one of them; `routers` + /// counts those too. + routers_below_fused: usize, + /// The `greptime.series.ordering` every merge scan declares, in traversal order. `contiguous` + /// means one region holds each series whole; `interleaved` means a series may be split. + scan_orderings: Vec>, +} + +/// Every node of the tree rooted at `root`, the root included. +fn native_plan_nodes(root: &Arc) -> Vec> { + let mut nodes = Vec::new(); + let mut stack = vec![Arc::clone(root)]; + while let Some(node) = stack.pop() { + stack.extend(node.children().into_iter().map(Arc::clone)); + nodes.push(node); + } + nodes +} + +fn native_plan_shape(plan: &Arc) -> NativePlanShape { + let nodes = native_plan_nodes(plan); + let mut shape = NativePlanShape { + fused: 0, + regions_per_scan: Vec::new(), + routers: 0, + routers_below_fused: 0, + scan_orderings: Vec::new(), + }; + for node in &nodes { + shape.fused += usize::from(node.name() == "FusedSeriesExec"); + shape.routers += usize::from(node.name() == "SeriesRepartitionExec"); + if let Some(scan) = node.downcast_ref::() { + shape.regions_per_scan.push( + scan.regions() + .iter() + .copied() + .collect::>() + .len(), + ); + shape.scan_orderings.push( + scan.schema() + .metadata() + .get("greptime.series.ordering") + .cloned(), + ); + } + } + // Count the routers below the outermost fused node only. A split aggregate nests a second + // fused producer under the first, and walking both subtrees would count its routers twice. + fn count_below_fused(node: &Arc, inside: bool, count: &mut usize) { + let fused = node.name() == "FusedSeriesExec"; + if fused && !inside { + for child in node.children() { + for nested in native_plan_nodes(child) { + *count += usize::from(nested.name() == "SeriesRepartitionExec"); + } + } + return; + } + for child in node.children() { + count_below_fused(child, inside || fused, count); + } + } + count_below_fused(plan, false, &mut shape.routers_below_fused); + shape +} + +fn assert_native_merge_scans( + plan: &Arc, + expected_scans: usize, + expected_regions: usize, +) { + let shape = native_plan_shape(plan); + assert!( + shape.fused >= 1, + "a native plan keeps at least one fused producer: {plan:?}" + ); + assert_eq!( + shape.regions_per_scan.len(), + expected_scans, + "merge scans: {plan:?}" + ); + assert_eq!( + shape.regions_per_scan, + vec![expected_regions; expected_scans], + "all time partitions must be selected: {plan:?}" + ); + assert!( + shape.routers > 0, + "fragmented raw inputs need reconciliation: {plan:?}" + ); +} + +/// The shape every disjoint plan has: one fused producer over one merge scan per selector, and every +/// scan selecting one region per partition value. Whether a node above the scans has to move frames +/// is what the two disjoint cases differ in - a global fold gathers, a per-series match does not - +/// so that stays with the caller. +fn assert_native_disjoint_shape( + plan: &Arc, + expected_scans: usize, + expected_regions: usize, +) -> NativePlanShape { + let shape = native_plan_shape(plan); + assert!( + shape.fused >= 1, + "a native plan keeps at least one fused producer: {plan:?}" + ); + assert_eq!( + shape.regions_per_scan.len(), + expected_scans, + "merge scans: {plan:?}" + ); + assert_eq!( + shape.regions_per_scan, + vec![expected_regions; expected_scans], + "every disjoint region must be selected: {plan:?}" + ); + shape +} + +/// The rows of the cross-region fixture, inserted into the logical tables `{prefix}_a`, +/// `{prefix}_b` and `{prefix}_reset`. The partitioned fixture and its control hold the same rows, +/// so the two differ only in how the engine has to reach them. +fn cross_region_fixture_inserts(prefix: &str) -> String { + format!( + "INSERT INTO {prefix}_a (host, val, ts) VALUES ('x', 2, 60000), ('x', 4, 120000), ('x', 6, 180000), ('x', 8, 240000), ('y', 4, 60000), ('y', 6, 120000), ('y', 8, 180000), ('y', 10, 240000); INSERT INTO {prefix}_b (host, val, ts) VALUES ('x', 1, 60000), ('x', 2, 120000), ('x', 3, 180000), ('x', 4, 240000), ('y', 2, 60000), ('y', 3, 120000), ('y', 4, 180000), ('y', 5, 240000); INSERT INTO {prefix}_reset (host, val, ts) VALUES ('x', 0, 0), ('x', 5, 60000), ('x', 10, 120000), ('x', 1, 180000), ('x', 3, 240000), ('x', 5, 300000), ('y', 0, 0), ('y', 1, 60000), ('y', 2, 120000), ('y', 3, 180000), ('y', 4, 240000), ('y', 5, 300000)" + ) +} + +/// Real two-datanode TCP acceptance for raw series fragmented by time. Ratios alone can hide +/// history dropped on both sides, so an absolute increase is checked separately as well. +#[tokio::test(flavor = "multi_thread")] +async fn distributed_native_promql_cross_region_targets_match_expected_values() { + common_telemetry::init_default_ut_logging(); + let cluster = GreptimeDbClusterBuilder::new("distributed_native_promql_cross_region") + .await + .with_datanodes(2) + .with_real_datanode_grpc_addr(true) + .with_frontend_real_datanode_grpc(true) + .with_query_options(QueryOptions { + experimental_native_promql: true, + ..Default::default() + }) + .build(false) + .await; + let instance = cluster.fe_instance().clone(); + execute_all( + &instance, + "CREATE TABLE dist_native_phy (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) PARTITION ON COLUMNS (ts) (ts < '1970-01-01 00:02:00', ts >= '1970-01-01 00:02:00' AND ts < '1970-01-01 00:04:00', ts >= '1970-01-01 00:04:00') ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + for table in ["dist_native_a", "dist_native_b", "dist_native_reset"] { + execute_all( + &instance, + &format!( + "CREATE TABLE {table} (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('on_physical_table'='dist_native_phy')" + ), + QueryContext::arc(), + ) + .await; + } + execute_all( + &instance, + &cross_region_fixture_inserts("dist_native"), + QueryContext::arc(), + ) + .await; + + // The semantic reference: the same rows in one unpartitioned physical table. The distributed + // legacy path evaluates every region fragment on its own, so on the partitioned fixture it is + // not an oracle for these expressions and is deliberately not compared here. The engine over + // the complete series is the oracle, and the native distributed plan must agree with it. + execute_all( + &instance, + "CREATE TABLE dist_native_ctl_phy (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + for table in [ + "dist_native_ctl_a", + "dist_native_ctl_b", + "dist_native_ctl_reset", + ] { + execute_all( + &instance, + &format!( + "CREATE TABLE {table} (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('on_physical_table'='dist_native_ctl_phy')" + ), + QueryContext::arc(), + ) + .await; + } + execute_all( + &instance, + &cross_region_fixture_inserts("dist_native_ctl"), + QueryContext::arc(), + ) + .await; + + for (expression, expected) in [ + ( + "sum(increase(dist_native_a[5m])) / sum(increase(dist_native_b[5m]))", + vec![(180_000, 2.0), (240_000, 2.0)], + ), + ( + "sum(max(dist_native_a)) / sum(dist_native_b)", + vec![(180_000, 8.0 / 7.0), (240_000, 10.0 / 9.0)], + ), + ( + "sum(increase(dist_native_b[5m]))", + vec![(180_000, 5.0), (240_000, 7.0)], + ), + ( + "sum(increase(dist_native_reset[5m]))", + vec![(180_000, 14.0), (240_000, 17.0)], + ), + ] { + let query = PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + // The control tables hold the complete series, so the engine's own evaluation over them + // defines the expected values; the native distributed plan has to reproduce them. + let control = expression.replace("dist_native_", "dist_native_ctl_"); + let control_rows = native_scalar_rows( + instance + .do_promql_query( + &PromQuery { + query: control.clone(), + ..query.clone() + }, + native_query_context(false, 2), + ) + .await + .remove(0) + .unwrap(), + ) + .await; + assert_eq!( + control_rows.len(), + expected.len(), + "the control defines every row: {control}" + ); + for (actual, expected) in control_rows.iter().zip(expected.iter()) { + assert_eq!(actual.0, expected.0, "control row timestamp: {control}"); + assert!( + (actual.1 - expected.1).abs() < 1e-9, + "control row value: {control}: {control_rows:?}" + ); + } + + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + assert_native_merge_scans(plan, usize::from(expression.contains(" / ")) + 1, 3); + // A global aggregate keeps its split: the partial half runs per partition and the final + // half folds the exported states, so the window work is not serialized into one instance. + assert!( + native_plan_shape(plan).fused >= 2, + "a global aggregate runs as partial and final halves: {plan:?}" + ); + let rows = native_scalar_rows(output).await; + assert_eq!( + cluster.network_do_get_active(), + 0, + "every response body is finished: {expression}" + ); + assert_eq!( + cluster.network_do_get_peak_active(), + 2, + "three region streams must use exactly the target-partition bound: {expression}" + ); + assert_eq!(rows.len(), expected.len(), "all rows: {expression}"); + for (actual, expected) in rows.iter().zip(expected) { + assert_eq!(actual.0, expected.0, "{expression}"); + assert!( + (actual.1 - expected.1).abs() < 1e-9, + "{expression}: {rows:?}" + ); + } + } + + // A per-series operation on the fragmented fixture: every series is split across the three + // time partitions, so no region holds a series whole and none can answer for a host alone. + // What comes back is per-series rows - two hosts at two timestamps - which a scalar helper + // cannot read, so this case compares labels as well as values. + let expression = "increase(dist_native_b[5m])"; + let query = PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + let control = expression.replace("dist_native_", "dist_native_ctl_"); + let control_rows = native_result_rows( + instance + .do_promql_query( + &PromQuery { + query: control.clone(), + ..query.clone() + }, + native_query_context(false, 2), + ) + .await + .remove(0) + .unwrap(), + ) + .await; + assert_eq!( + control_rows.len(), + 4, + "the control over the complete series defines every row: {control}" + ); + + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + let shape = native_plan_shape(plan); + assert!( + shape.fused >= 1, + "a native plan keeps at least one fused producer: {plan:?}" + ); + assert_eq!( + shape.regions_per_scan, + vec![3], + "the selector reads all three time partitions: {plan:?}" + ); + assert!( + shape.routers_below_fused >= 1, + "time partitioning splits every series across regions, so the region fragments must be \ + reconciled before the fused node reads them: {plan:?}" + ); + assert!( + shape + .scan_orderings + .iter() + .all(|ordering| ordering.as_deref() == Some("interleaved")), + "the frontend cannot prove a series stays in one time partition, so the scans must not \ + claim contiguous per-series order: {:?}: {plan:?}", + shape.scan_orderings + ); + let rows = native_result_rows(output).await; + assert_eq!( + cluster.network_do_get_active(), + 0, + "every response body is finished: {expression}" + ); + let peak = cluster.network_do_get_peak_active(); + assert!( + (1..=2).contains(&peak), + "fragmented region streams stay within the target-partition bound: {expression}: {peak}" + ); + assert_eq!(control_rows, rows, "{expression}"); +} + +/// The rows of the repeated-selector fixture, inserted into the one logical table +/// `{prefix}_b`. Both hosts are counters sampled every minute for ten minutes, longer than the +/// widest window the test reads, so a 5m window and a 10m window over the same series cover +/// different sample sets. +fn repeated_selector_fixture_inserts(prefix: &str) -> String { + let host = |host: char, first: usize| { + (0..10) + .map(|step| format!("('{host}', {}.0, {})", first + step, (step + 1) * 60_000)) + .collect::>() + }; + format!( + "INSERT INTO {prefix}_b (host, val, ts) VALUES {}", + host('x', 1) + .into_iter() + .chain(host('y', 2)) + .collect::>() + .join(", ") + ) +} + +/// Real two-datanode TCP acceptance for a repeated selector over ONE partitioned metric table. +/// Over the wire every prepared scan becomes its own raw source with its own time bounds, so two +/// occurrences of the same fragmented table - a ratio of two windows, or a binary expression over +/// two identical ones - stay independent instead of falling back. In process the same expression +/// would place one node region-locally over both scans of the one table, which no region can serve, +/// so this admission is remote-only. +#[tokio::test(flavor = "multi_thread")] +async fn distributed_native_promql_repeated_selector_over_partitioned_table() { + common_telemetry::init_default_ut_logging(); + let cluster = GreptimeDbClusterBuilder::new("distributed_native_promql_repeated") + .await + .with_datanodes(2) + .with_real_datanode_grpc_addr(true) + .with_frontend_real_datanode_grpc(true) + .with_query_options(QueryOptions { + experimental_native_promql: true, + ..Default::default() + }) + .build(false) + .await; + let instance = cluster.fe_instance().clone(); + execute_all( + &instance, + "CREATE TABLE dist_repeat_phy (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) PARTITION ON COLUMNS (ts) (ts < '1970-01-01 00:02:00', ts >= '1970-01-01 00:02:00' AND ts < '1970-01-01 00:04:00', ts >= '1970-01-01 00:04:00') ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + "CREATE TABLE dist_repeat_b (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('on_physical_table'='dist_repeat_phy')", + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + &repeated_selector_fixture_inserts("dist_repeat"), + QueryContext::arc(), + ) + .await; + + // The semantic reference: the same rows in one unpartitioned physical table. The engine's own + // evaluation over the complete series is the oracle, so a plan that reconciled the fragments + // wrongly cannot agree with it. + execute_all( + &instance, + "CREATE TABLE dist_repeat_ctl_phy (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + "CREATE TABLE dist_repeat_ctl_b (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('on_physical_table'='dist_repeat_ctl_phy')", + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + &repeated_selector_fixture_inserts("dist_repeat_ctl"), + QueryContext::arc(), + ) + .await; + + for expression in [ + // The two occurrences read different windows of the one table, so a plan that bound both to + // one window would answer 1 at every step. + "increase(dist_repeat_b[5m]) / increase(dist_repeat_b[10m])", + // Two identical occurrences, which the per-series match must still keep apart. + "increase(dist_repeat_b[5m]) + increase(dist_repeat_b[5m])", + ] { + let query = PromQuery { + query: expression.to_string(), + start: "480".to_string(), + end: "600".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + let control = expression.replace("dist_repeat_", "dist_repeat_ctl_"); + let control_rows = native_result_rows( + instance + .do_promql_query( + &PromQuery { + query: control.clone(), + ..query.clone() + }, + native_query_context(false, 2), + ) + .await + .remove(0) + .unwrap(), + ) + .await; + assert_eq!( + control_rows.len(), + 6, + "two hosts over three steps define every row: {control}" + ); + + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + let shape = native_plan_shape(plan); + assert!( + shape.fused >= 1, + "a native plan keeps at least one fused producer: {expression}: {plan:?}" + ); + assert_eq!( + shape.regions_per_scan, + vec![3, 3], + "one raw source per occurrence, each read through every time partition: \ + {expression}: {plan:?}" + ); + assert!( + shape.routers_below_fused >= shape.regions_per_scan.len(), + "every occurrence is a series split by time, so each one's fragments are reconciled \ + before the fused node reads them: {expression}: {plan:?}" + ); + assert!( + shape + .scan_orderings + .iter() + .all(|ordering| ordering.as_deref() == Some("interleaved")), + "the frontend cannot prove a series stays in one time partition, so neither scan may \ + claim contiguous per-series order: {expression}: {:?}: {plan:?}", + shape.scan_orderings + ); + let rows = native_result_rows(output).await; + assert_eq!( + cluster.network_do_get_active(), + 0, + "every response body is finished: {expression}" + ); + let peak = cluster.network_do_get_peak_active(); + assert!( + (1..=2).contains(&peak), + "two occurrences still read within the target-partition bound: {expression}: {peak}" + ); + if expression.contains(" / ") { + assert!( + rows.iter().all(|row| (row.2 - 1.0).abs() > 1e-9), + "a 5m window over a 10m one is not 1, so both occurrences were read: \ + {expression}: {rows:?}" + ); + } + assert_eq!(control_rows, rows, "{expression}"); + } +} + +/// The rows of the disjoint fixture, inserted into the logical tables `{prefix}_a` and +/// `{prefix}_b`. Both hosts carry the same shape and land in different partitions. +fn disjoint_fixture_inserts(prefix: &str) -> String { + format!( + "INSERT INTO {prefix}_a (host, val, ts) VALUES ('a', 2, 60000), ('a', 4, 120000), ('a', 6, 180000), ('a', 8, 240000), ('z', 4, 60000), ('z', 6, 120000), ('z', 8, 180000), ('z', 10, 240000); INSERT INTO {prefix}_b (host, val, ts) VALUES ('a', 1, 60000), ('a', 2, 120000), ('a', 3, 180000), ('a', 4, 240000), ('z', 2, 60000), ('z', 3, 120000), ('z', 4, 180000), ('z', 5, 240000)" + ) +} + +/// Real two-datanode TCP acceptance for raw series that no region shares: partitioning on the raw +/// primary key puts every series in exactly one region, so the native plan must read all of them +/// and reconcile none of them. +#[tokio::test(flavor = "multi_thread")] +async fn distributed_native_promql_disjoint_regions_do_not_repartition() { + common_telemetry::init_default_ut_logging(); + let cluster = GreptimeDbClusterBuilder::new("distributed_native_promql_disjoint") + .await + .with_datanodes(2) + .with_real_datanode_grpc_addr(true) + .with_frontend_real_datanode_grpc(true) + .with_query_options(QueryOptions { + experimental_native_promql: true, + ..Default::default() + }) + .build(false) + .await; + let instance = cluster.fe_instance().clone(); + execute_all( + &instance, + "CREATE TABLE dist_native_disjoint_phy (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) PARTITION ON COLUMNS (host) (host < 'm', host >= 'm') ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + for table in ["dist_native_disjoint_a", "dist_native_disjoint_b"] { + execute_all( + &instance, + &format!( + "CREATE TABLE {table} (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('on_physical_table'='dist_native_disjoint_phy')" + ), + QueryContext::arc(), + ) + .await; + } + execute_all( + &instance, + &disjoint_fixture_inserts("dist_native_disjoint"), + QueryContext::arc(), + ) + .await; + + // The semantic reference over the complete series, as in the fragmented case: the engine's own + // evaluation of the unpartitioned fixture defines the expected values. + execute_all( + &instance, + "CREATE TABLE dist_native_disjoint_ctl_phy (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + for table in ["dist_native_disjoint_ctl_a", "dist_native_disjoint_ctl_b"] { + execute_all( + &instance, + &format!( + "CREATE TABLE {table} (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=metric WITH ('on_physical_table'='dist_native_disjoint_ctl_phy')" + ), + QueryContext::arc(), + ) + .await; + } + execute_all( + &instance, + &disjoint_fixture_inserts("dist_native_disjoint_ctl"), + QueryContext::arc(), + ) + .await; + + for (expression, expected, expected_scans) in [ + ( + "sum(increase(dist_native_disjoint_a[5m])) / sum(increase(dist_native_disjoint_b[5m]))", + vec![(180_000, 2.0), (240_000, 2.0)], + 2, + ), + ( + "sum(increase(dist_native_disjoint_a[5m]))", + vec![(180_000, 10.0), (240_000, 14.0)], + 1, + ), + ] { + let query = PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + let control = expression.replace("dist_native_disjoint_", "dist_native_disjoint_ctl_"); + let control_rows = native_scalar_rows( + instance + .do_promql_query( + &PromQuery { + query: control.clone(), + ..query.clone() + }, + native_query_context(false, 2), + ) + .await + .remove(0) + .unwrap(), + ) + .await; + assert_eq!( + control_rows.len(), + expected.len(), + "the control defines every row: {control}" + ); + for (actual, expected) in control_rows.iter().zip(expected.iter()) { + assert_eq!(actual.0, expected.0, "control row timestamp: {control}"); + assert!( + (actual.1 - expected.1).abs() < 1e-9, + "control row value: {control}: {control_rows:?}" + ); + } + + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + // A global fold normalizes every input to one partition, so the gather it needs is the + // frames of complete series moving, not fragments of one series being put back together. + assert_native_disjoint_shape(plan, expected_scans, 2); + let rows = native_scalar_rows(output).await; + assert_eq!( + cluster.network_do_get_active(), + 0, + "every response body is finished: {expression}" + ); + let peak = cluster.network_do_get_peak_active(); + assert!( + (1..=2).contains(&peak), + "disjoint region streams stay within the target-partition bound: {expression}: {peak}" + ); + assert_eq!(rows.len(), expected.len(), "all rows: {expression}"); + for (actual, expected) in rows.iter().zip(expected) { + assert_eq!(actual.0, expected.0, "{expression}"); + assert!( + (actual.1 - expected.1).abs() < 1e-9, + "{expression}: {rows:?}" + ); + } + } + + // A per-series operation reads the two tables host by host: no series crosses a region, so + // nothing in the native plan has to put one back together. A global fold above would gather + // complete series instead, which is why this case is the one that states the disjoint claim. + let expression = "increase(dist_native_disjoint_a[5m]) / increase(dist_native_disjoint_b[5m])"; + let query = PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + let expected = vec![ + (180_000, "a".to_string(), 2.0), + (180_000, "z".to_string(), 2.0), + (240_000, "a".to_string(), 2.0), + (240_000, "z".to_string(), 2.0), + ]; + let control = expression.replace("dist_native_disjoint_", "dist_native_disjoint_ctl_"); + let control_rows = native_result_rows( + instance + .do_promql_query( + &PromQuery { + query: control.clone(), + ..query.clone() + }, + native_query_context(false, 2), + ) + .await + .remove(0) + .unwrap(), + ) + .await; + assert_eq!( + expected, control_rows, + "the control over the complete series defines every row: {control}" + ); + + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + let shape = assert_native_disjoint_shape(plan, 2, 2); + assert!( + shape + .scan_orderings + .iter() + .all(|ordering| ordering.as_deref() == Some("contiguous")), + "the frontend proved each series lives in one region, so every merge scan keeps its \ + declared contiguous per-series order: {:?}: {plan:?}", + shape.scan_orderings + ); + // The fused node emits one partition, so each side of the match is gathered to it. That moves + // complete series, not fragments of one: no series crosses a region here. + assert_eq!( + shape.routers_below_fused, 2, + "one gather per side of the match below the fused node: {plan:?}" + ); + let rows = native_result_rows(output).await; + assert_eq!( + cluster.network_do_get_active(), + 0, + "every response body is finished: {expression}" + ); + let peak = cluster.network_do_get_peak_active(); + assert!( + (1..=2).contains(&peak), + "disjoint region streams stay within the target-partition bound: {expression}: {peak}" + ); + assert_eq!(expected, rows, "{expression}"); + + // The same claim for a per-series operation with nothing to match: each series is complete in + // the region that holds it, so the fused node reads the merge scans directly and no router sits + // between them. + let expression = "increase(dist_native_disjoint_a[5m])"; + let query = PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + let control = expression.replace("dist_native_disjoint_", "dist_native_disjoint_ctl_"); + let control_rows = native_result_rows( + instance + .do_promql_query( + &PromQuery { + query: control.clone(), + ..query.clone() + }, + native_query_context(false, 2), + ) + .await + .remove(0) + .unwrap(), + ) + .await; + assert_eq!( + control_rows.len(), + 4, + "the control over the complete series defines every row: {control}" + ); + + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + let shape = assert_native_disjoint_shape(plan, 1, 2); + assert!( + shape + .scan_orderings + .iter() + .all(|ordering| ordering.as_deref() == Some("contiguous")), + "the frontend proved each series lives in one region, so the merge scan keeps its declared \ + contiguous per-series order: {:?}: {plan:?}", + shape.scan_orderings + ); + assert_eq!( + shape.routers_below_fused, 0, + "each series is complete in one region, so the fused node reads the merge scans directly \ + and nothing has to reconcile fragments of one: {plan:?}" + ); + let rows = native_result_rows(output).await; + assert_eq!( + cluster.network_do_get_active(), + 0, + "every response body is finished: {expression}" + ); + let peak = cluster.network_do_get_peak_active(); + assert!( + (1..=2).contains(&peak), + "disjoint region streams stay within the target-partition bound: {expression}: {peak}" + ); + assert_eq!(control_rows, rows, "{expression}"); +} + +/// A nameless selector discovers every metric table it matches and reads them as one `Union`. +/// `UnionExec` reports the frame metadata of its last child, so a time-partitioned metric named +/// before a host-partitioned one must still be reconciled: otherwise the union claims contiguous +/// order and `increase` folds each region fragment as its own series. +#[tokio::test(flavor = "multi_thread")] +async fn distributed_native_promql_metric_discovery_reconciles_mixed_ordering() { + common_telemetry::init_default_ut_logging(); + let cluster = GreptimeDbClusterBuilder::new("distributed_native_promql_discovery") + .await + .with_datanodes(2) + .with_real_datanode_grpc_addr(true) + .with_frontend_real_datanode_grpc(true) + .with_query_options(QueryOptions { + experimental_native_promql: true, + ..Default::default() + }) + .build(false) + .await; + let instance = cluster.fe_instance().clone(); + // The names sort so the contiguous (host-partitioned) metric is the union's last child, which + // is exactly the ordering a union would otherwise claim for the whole input. + execute_all( + &instance, + "CREATE TABLE dist_native_disc_a_frag_phy (host STRING, site STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host, site)) PARTITION ON COLUMNS (ts) (ts < '1970-01-01 00:02:00', ts >= '1970-01-01 00:02:00' AND ts < '1970-01-01 00:04:00', ts >= '1970-01-01 00:04:00') ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + "CREATE TABLE dist_native_disc_z_wide_phy (host STRING, site STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host, site)) PARTITION ON COLUMNS (host) (host < 'm', host >= 'm') ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + // Both metrics carry the same samples under their own `site`, so each contributes the same + // increase and the two rows stay distinct after the metric name is folded away. + for (table, physical, site) in [ + ( + "dist_native_disc_a_frag", + "dist_native_disc_a_frag_phy", + "left", + ), + ( + "dist_native_disc_z_wide", + "dist_native_disc_z_wide_phy", + "right", + ), + ] { + execute_all( + &instance, + &format!( + "CREATE TABLE {table} (host STRING, site STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host, site)) ENGINE=metric WITH ('on_physical_table'='{physical}')" + ), + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + &format!( + "INSERT INTO {table} (host, site, val, ts) VALUES ('a', '{site}', 2, 60000), ('a', '{site}', 4, 120000), ('a', '{site}', 6, 180000), ('a', '{site}', 8, 240000)" + ), + QueryContext::arc(), + ) + .await; + } + + let query = PromQuery { + query: r#"sum by (host, site) (increase({host="a"}[5m]))"#.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }; + cluster.reset_network_do_get_peak(); + let output = instance + .do_promql_query(&query, native_query_context(true, 2)) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + let shape = native_plan_shape(plan); + assert!(shape.fused >= 1, "discovery stays native: {plan:?}"); + // The split adds a state router between the final and partial halves; the raw reconciliation + // below the partial half is what must not be skipped. + assert!( + shape.routers_below_fused >= 1, + "the lowered union is reconciled before evaluation: {plan:?}" + ); + assert!( + shape + .scan_orderings + .iter() + .any(|ordering| ordering.as_deref() == Some("interleaved")), + "the time-partitioned scan declares fragments: {:?}: {plan:?}", + shape.scan_orderings + ); + assert!( + shape + .scan_orderings + .iter() + .any(|ordering| ordering.as_deref() == Some("contiguous")), + "the host-partitioned scan declares complete series: {:?}: {plan:?}", + shape.scan_orderings + ); + let rows = native_site_rows(output).await; + // `increase` extrapolates the 2,4,6 window to the 5m boundary, as the cross-region fixture + // also expects: each metric contributes 5 at 180s and 7 at 240s, under its own `site`. + let expected = vec![ + (180_000, "a".to_string(), "left".to_string(), 5.0), + (180_000, "a".to_string(), "right".to_string(), 5.0), + (240_000, "a".to_string(), "left".to_string(), 7.0), + (240_000, "a".to_string(), "right".to_string(), 7.0), + ]; + assert_eq!(expected, rows); + assert_eq!(cluster.network_do_get_active(), 0, "every body is drained"); + // The discovered union feeds one reader per member partition: two from the time-partitioned + // metric and one from the host-partitioned metric. That is the per-scan bound summed: the + // query-wide budget is installed only for the single-fused plan, and a plan with a union is + // not counted against it. + let peak = cluster.network_do_get_peak_active(); + assert!((1..=3).contains(&peak), "region reads stay bounded: {peak}"); + + // An aggregate over a discovered selector reads the metric name from each source's own frames, + // not from one bound metric. Folding without grouping adds them, and grouping by the name keeps + // the two metrics apart even though their ordinary labels are identical. A window function drops + // the name, so the grouping case reads the raw selector. + for (expression, expected) in [ + ( + r#"sum(increase({host="a"}[5m]))"#, + vec![(None, 10.0), (None, 14.0)], + ), + ( + r#"sum by (__name__) ({host="a"})"#, + vec![ + (Some("dist_native_disc_a_frag".to_string()), 6.0), + (Some("dist_native_disc_a_frag".to_string()), 8.0), + (Some("dist_native_disc_z_wide".to_string()), 6.0), + (Some("dist_native_disc_z_wide".to_string()), 8.0), + ], + ), + ] { + let output = instance + .do_promql_query( + &PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }, + native_query_context(true, 2), + ) + .await + .remove(0) + .unwrap(); + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + assert!( + native_plan_shape(plan).fused >= 1, + "a discovery aggregate stays native: {plan:?}" + ); + let batches = match output.data { + OutputData::Stream(stream) => collect_batches(stream).await.unwrap(), + OutputData::RecordBatches(batches) => batches, + _ => unreachable!("PromQL returns record batches"), + }; + // Neither column is located by position: the result puts `__name__` last, and an aggregate + // that folds the name away drops the column instead of emptying it, so a missing `__name__` + // is exactly "no metric name". + let mut rows = Vec::new(); + for batch in batches { + let names = batch.column_by_name("__name__").map(|column| { + cast(column.as_ref(), &DataType::Utf8) + .unwrap() + .as_any() + .downcast_ref::() + .unwrap() + .clone() + }); + let values = batch + .column_by_name("val") + .expect("one value column") + .as_any() + .downcast_ref::() + .unwrap(); + for row in 0..batch.num_rows() { + rows.push(( + names.as_ref().map(|names| names.value(row).to_string()), + values.value(row), + )); + } + } + // The name travels with the value: a plan that grouped by the wrong name, or dropped the + // name, would still report the same numbers, so the assertion is on the (name, value) pairs. + rows.sort_by(|left, right| { + left.0 + .as_deref() + .cmp(&right.0.as_deref()) + .then(left.1.total_cmp(&right.1)) + }); + assert_eq!(expected, rows, "{expression}"); + } +} + +/// Remote admission refusals that used to be made by `segment_tree` must survive its bypass: +/// several sources cannot report groups that differ only by metric name, and an order-dependent +/// operation over discovered metrics cannot be answered by a union that reads in arrival order. +#[tokio::test(flavor = "multi_thread")] +async fn distributed_native_promql_remote_refuses_unsupported_discovery_and_name_grouping() { + common_telemetry::init_default_ut_logging(); + let cluster = GreptimeDbClusterBuilder::new("distributed_native_promql_refusal") + .await + .with_datanodes(2) + .with_real_datanode_grpc_addr(true) + .with_frontend_real_datanode_grpc(true) + .with_query_options(QueryOptions { + experimental_native_promql: true, + ..Default::default() + }) + .build(false) + .await; + let instance = cluster.fe_instance().clone(); + execute_all( + &instance, + "CREATE TABLE dist_native_refuse_phy (host STRING, site STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host, site)) PARTITION ON COLUMNS (ts) (ts < '1970-01-01 00:02:00', ts >= '1970-01-01 00:02:00') ENGINE=metric WITH ('physical_metric_table'='true')", + QueryContext::arc(), + ) + .await; + for table in ["dist_native_refuse_a", "dist_native_refuse_b"] { + execute_all( + &instance, + &format!( + "CREATE TABLE {table} (host STRING, site STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host, site)) ENGINE=metric WITH ('on_physical_table'='dist_native_refuse_phy')" + ), + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + &format!( + "INSERT INTO {table} (host, site, val, ts) VALUES ('a', '{table}', 2, 60000), ('a', '{table}', 4, 120000), ('a', '{table}', 6, 180000)" + ), + QueryContext::arc(), + ) + .await; + } + // An ordinary Mito table beside a metric one: no logical id, so a tree reading both is several + // inputs even though only one of them carries a metric logical id. + execute_all( + &instance, + "CREATE TABLE dist_native_refuse_mito (host STRING, val DOUBLE, ts TIMESTAMP TIME INDEX, PRIMARY KEY(host)) ENGINE=mito", + QueryContext::arc(), + ) + .await; + execute_all( + &instance, + "INSERT INTO dist_native_refuse_mito (host, val, ts) VALUES ('a', 2, 60000), ('a', 4, 120000), ('a', 6, 180000)", + QueryContext::arc(), + ) + .await; + + for expression in [r#"sum by (__name__) (dist_native_refuse_a or dist_native_refuse_mito)"#] { + let output = instance + .do_promql_query( + &PromQuery { + query: expression.to_string(), + start: "180".to_string(), + end: "240".to_string(), + step: "60s".to_string(), + ..PromQuery::default() + }, + native_query_context(true, 2), + ) + .await + .remove(0); + let Ok(output) = output else { + // Legacy planning is allowed to decline this shape too; what must not happen is a + // native plan that reports two metric groups it cannot name. + continue; + }; + let plan = output.meta.plan.as_ref().expect("frontend physical plan"); + assert_eq!( + native_plan_shape(plan).fused, + 0, + "two sources cannot report groups that differ only by metric name: {plan:?}" + ); + } +} + #[tokio::test(flavor = "multi_thread")] async fn native_promql_label_rewrites_reach_the_native_route_and_keep_prometheus_answers() { common_telemetry::init_default_ut_logging(); diff --git a/tests/compatibility/wire/raw_series_ordering/README.md b/tests/compatibility/wire/raw_series_ordering/README.md index 2ddc1463dd2..ce54838048a 100644 --- a/tests/compatibility/wire/raw_series_ordering/README.md +++ b/tests/compatibility/wire/raw_series_ordering/README.md @@ -5,21 +5,23 @@ for the v2 series frame. It records the established layout/content/labels/time metadata and mandatory ordering entry, for raw frames and for evaluated ones. The Rust unit test parses these literal maps through `series_frame_ordering` and through `SeriesFrameDeclaration::parse`; the fixture is not produced by the -schema builder. +schema builder. It covers the original `contiguous` and `read_key_then_time` +values, not the newer `interleaved` value. -Run the focused check: +Run the focused checks for the frame codec, streaming adapter, and fixture: ```shell -cargo nextest run -p common-query -E 'test(raw_series_ordering_metadata_fixture)' +cargo nextest run -p datatypes -E 'test(series::frame)' +cargo nextest run -p common-query -E 'test(series_frame)' ``` The fixture proves that missing ordering metadata and unknown values are rejected, -the two known values decode, and that a whole declaration is accepted or refused -consistently with its layout and content: a -`v3` layout, an unregistered `greptime.series.*` key, a raw frame that declares a -grid, and any content/time or content/labels contradiction are refusals. -Evaluated declarations use explicit `contiguous` ordering; streaming round trips -for evaluated frames are covered by the crate's evaluated tests. +the two original values decode, and that a whole declaration is accepted or +refused consistently with its layout and content: a `v3` layout, an unregistered +`greptime.series.*` key, a raw frame that declares a grid, and any content/time or +content/labels contradiction are refusals. Evaluated declarations use explicit +`contiguous` ordering; streaming round trips for evaluated frames are covered by +the crate's evaluated tests. Because the declaration is cross-checked, a frame that names `evaluated` content is only an evaluated frame when it also declares `explicit` labels, `grid_spans` @@ -30,8 +32,18 @@ schema builder and `unpack_evaluated_series` refuse it. The fixture keeps a hand-written evaluated frame that states it and verifies that declaration parsing refuses it. -The fixture also pins rejection of evaluated `read_key_then_time` metadata. It -does not prove interoperability with an old binary or test an end-to-end client -or service. Separate pack/IPC tests check the declared -ordering schema and batch schema agreement for both orderings, including empty -streams, and check the same for the evaluated frame across Arrow IPC. +Raw frames may also declare `greptime.series.ordering=interleaved`, using the full +spelling. The raw streaming adapter supports sequential independently closed +producer fragment chains under that declaration. A key may recur across fragments +with overlapping or reversed timestamps; `is_last` closes a producer fragment, not +necessarily the logical series. The adapter rejects switching keys while a fragment +is still open and an unfinished fragment at EOF, so it does not support arbitrary +multiplexing of open chains. Evaluated frames reject `interleaved`. The direct +codec tests and streaming pack/Arrow IPC/unpack tests cover this value; the frozen +fixture does not. + +These tests do not prove interoperability with an old binary or test an end-to-end +client or service. Older readers that do not recognize `interleaved` reject it; +remote acceptance must not be assumed. The pack/IPC tests check declared stream and +batch schema agreement for all three raw orderings, including empty streams, and +check the same for evaluated frames. diff --git a/tests/compatibility/wire/raw_series_source/README.md b/tests/compatibility/wire/raw_series_source/README.md new file mode 100644 index 00000000000..92915a99ccd --- /dev/null +++ b/tests/compatibility/wire/raw_series_source/README.md @@ -0,0 +1,23 @@ +# RawSeriesSource Substrait payload, version 1 + +`v1_payload.hex` is an independently hand-authored protobuf payload for version 1 +of `greptime_proto::substrait_extension::RawSeriesSource` from greptime-proto #349 +(revision `9b1dbfb`). It is not a capture from a released binary. It encodes metric +`http_requests_total`, tags `z`, `a`, and fields `value_b`, `value_a` in deliberately +unsorted order. The field numbers are version=1, metric_name=2, tags=3 (repeated), +and fields=4 (repeated). Substrait carries the child plan separately. + +The owning promql tests decode this immutable fixture, check binding and schema +order, and compare exact re-encoding. They also check unsupported versions and +truncated bytes. The Substrait test verifies restoration of a real table-scan +child. Older receivers do not recognize the new extension node; this fixture does +not demonstrate mixed-version fallback or distributed acceptance. + +```shell +cargo nextest run -p promql -p substrait@1.4.0-alpha.0 -E 'test(raw_series_source)' +``` + +The bytes are the literal protobuf encoding: `08 01` (version 1), `12 13` plus +UTF-8 metric bytes, `1a 01 7a`, `1a 01 61`, `22 07` plus `value_b`, and `22 07` +plus `value_a`. SHA-256 of the hex file including its trailing newline: +`5d748968ec8817762b63b6d3d0127fd7c9f606c05c25ac88aa0c2bc8700eae51`. diff --git a/tests/compatibility/wire/raw_series_source/v1_payload.hex b/tests/compatibility/wire/raw_series_source/v1_payload.hex new file mode 100644 index 00000000000..fc39bf72e86 --- /dev/null +++ b/tests/compatibility/wire/raw_series_source/v1_payload.hex @@ -0,0 +1 @@ +08011213687474705f72657175657374735f746f74616c1a017a1a0161220776616c75655f62220776616c75655f61