feat(query): execute native raw promql over real datanodes (#10150)

* feat(promql): serialize raw series source bindings through Substrait

Signed-off-by: discord9 <discord9@163.com>

* feat(query): transport interleaved raw series fragments

Signed-off-by: discord9 <discord9@163.com>

* feat(promql): reconstruct interleaved raw series at repartition

Signed-off-by: discord9 <discord9@163.com>

* feat(query): plan distributed native raw series

Signed-off-by: discord9 <discord9@163.com>

* chore: satisfy clippy for the raw series transport

The workspace clippy run rejects a redundant rebinding, a constant-size
`chunks_exact`, and an implicit `String` clone in the tests these
commits carry. No behavior changes.

Signed-off-by: discord9 <discord9@163.com>

* feat(query): execute native raw promql over real datanodes

Plan a whole native statement as one fused node over raw series
sources when the frontend reaches regions over the wire, including
single-selector statements, while keeping the in-process split and
segment shapes unchanged. Validate the whole tree with the runtime
constructor before committing to that plan, so unsupported shapes
still fall back to the legacy route.

Bound the region reads of that topology with a query-wide permit
budget of target_partitions, held until each region body is drained;
other plan shapes keep unbounded reads rather than risk a body budget
they could deadlock.

Acceptance on a real two-datanode cluster with TCP frontend clients:
time-partitioned series are reconciled before the fused node and match
the unpartitioned control, with the DoGet peak at the target bound;
series that no region shares keep contiguous per-series order and
reach the fused node without a reconciling router.

Signed-off-by: discord9 <discord9@163.com>

* chore(deps): pin greptime-proto to the raw series transport PR

The raw series Substrait message lives in greptime-proto PR #349, which
is not merged, so pin its head commit instead of carrying a local path
patch. Move the rev to the merge commit once #349 lands.

    https://github.com/GreptimeTeam/greptime-proto/pull/349

Signed-off-by: discord9 <discord9@163.com>

* fix(promql): reconcile a discovered union of raw series

A nameless selector reads its matches as one `Union`, and `UnionExec`
reports the frame metadata of its last child. A time-partitioned metric
sorted before a host-partitioned one therefore looked contiguous, and
the fused node skipped the reconciliation of the fragmented member's
series, silently folding region fragments as separate series.

Lower the declaration on the fused edge to the weakest ordering any
member declares, before the fused node reads it. The union itself is
unchanged; the fused node's existing interleaved-input path inserts the
router. A projection carries the lowered declaration because the
pinned physical planner ignores a union's own schema.

Cover it with a planner regression for both member orders and an
all-complete control, and with a real two-datanode acceptance case that
mixes a time-partitioned and a host-partitioned metric and checks the
extrapolated increase per series.

Signed-off-by: discord9 <discord9@163.com>

* test(promql): cover aggregates over discovered metrics

A nameless selector's metric comes from its own frames, so a folding
aggregate is a multi-input tree even with one selector: apply the same
preflight and order-dependent refusals on the remote route. Cover
`sum(increase(...))` and grouping by the metric name over the mixed
discovery fixture.

A grouping that names only `__name__` stays declined, since the output
schema cannot name that group: here the metrics also differ by `site`,
so grouping by the name and `site` exercises the two groups.

Signed-off-by: discord9 <discord9@163.com>

* fix(query): keep remote multi-source refusals the split made

Skipping the aggregate split and `segment_tree` over the wire must not
drop their admission refusals. Two sources that fold groups by metric
name would report groups that differ only by name under one label set,
and an order-dependent operation over a discovered selector's union
would answer in arrival order.

Scope both refusals to the actual multi-source inputs rather than to
the logical-table-id heuristic: a discovered selector reads several
metrics through one selector, and a Mito table beside a metric one
carries no logical id.

Cover the Mito-plus-metric grouping refusal on a real two-datanode
cluster, and cover a discovered `sum by (__name__)` over a raw selector
(the name survives it) and a folding `sum(increase(...))`.

Signed-off-by: discord9 <discord9@163.com>

* docs: drop the local proto patch prerequisite

The dependency is pinned to greptime-proto PR #349's commit, so the wire
fixture no longer needs a local path patch.

Signed-off-by: discord9 <discord9@163.com>

* chore: finish the narthex rebase resolution

Keep the upstream aggregate split (`FusedSeries::split_aggregate`) and
pass the engine state through the native planner's callers, while the
remote route still declines the split it cannot carry.

Signed-off-by: discord9 <discord9@163.com>

* test: pass the engine state to the native operand test

The native operand planner now takes the engine state, which decides
whether a statement is planned for remote regions. Keep the histogram
operand contract test on that signature.

Signed-off-by: discord9 <discord9@163.com>

* fix(query): keep the split and segment plans over the wire

Remote planning disabled the aggregate split and segmentation because
the split's producer read a bare scan. The producer reads whatever the
statement prepared, and over the wire that is the raw series source:
the partial half runs per partition on the frontend, the final half
folds the exported states, and no aggregate state crosses the wire.

Keep the split and let segmentation build evaluated segments from the
raw sources instead of bare scans, so per-series window work keeps the
scan width. Admit the resulting fused chain to the query-wide read
budget, since each fused node polls its input while it is drained.

Remove the recovery-projection wrapper: the analyzer no longer inserts
that projection, and the physical planner consumes the frame boundary
as it is. Serialization is now only the node's encoding: the codec no
longer decides placement, and the metric-name binding is checked
against the declared frames rather than the node types below.

Signed-off-by: discord9 <discord9@163.com>

* refactor(query): drop the in-process encodability exception

A split aggregate encodes now, so the analyzer no longer needs a
special case that skipped the encoding gate for it. The gate itself
stays: every plan a region receives still has to encode.

Signed-off-by: discord9 <discord9@163.com>

* test: cover a repeated selector over one partitioned table

Two occurrences of one time-partitioned metric keep their own raw
source, time bounds and identity over the wire, so a ratio of two
windows and a binary expression over two identical ones stay native and
reconcile each occurrence's fragments before the fused node reads them.
Compare both against the unpartitioned control.

Signed-off-by: discord9 <discord9@163.com>

* fix(table): refuse a scan that plans interleaved ordering

A scan's planned ordering is a guarantee its own partitions keep.
Interleaved is the transport annotation for fragments several producers
contribute, so a scanner that planned it has no raw-series read whose
frame would honour that declaration. Reject it in the scan conversion,
while the frame codec keeps accepting interleaved raw frames from the
router that reconciles them.

Signed-off-by: discord9 <discord9@163.com>

* test(promql): assert the metric name beside the value

`sum by (__name__)` over a discovered selector was asserted as a bare sorted
list of values, so a plan that grouped by the wrong metric name - or dropped
the name and folded everything into one series - could produce those same
numbers. Read `__name__` and `val` by column name (the result puts `__name__`
last, and a fold that drops the name drops the column rather than emptying it)
and compare the `(name, value)` pairs against the fixture's own metric names.

Signed-off-by: discord9 <discord9@163.com>

* fix(query): keep the hybrid route for a partitioned pair

A multi-selector tree over a partitioned table was admitted as one fused node
for any pair of tables, not only for scans of one table. That preempted the
frontend hybrid route, which copies the matcher's labels into each operand's
scan and checks uniqueness above the join. `native_hybrid_binary_05_06_08`
depends on exactly that plan: its partitioned RHS holds a duplicated
`job="other"` group, so the whole-native binary reports the duplicate instead
of the value the hybrid route returns. Refuse the whole-fused plan for that
shape in process again; the remote raw-source admission is unchanged, since a
remote multi-selector tree over a partitioned table is the point of this
branch and the distributed acceptance tests read it.

The hybrid route then has to behave the same way it does without native
operands: `matching_filters::propagate` now runs for them too, and a rewritten
operand is re-planned through `try_plan_native_operand` with its original
`selector_matcher` preserved, falling back to the ordinary plan when the
native route declines. The unpartitioned case, whose duplicate group the
whole-native binary is expected to report, is unchanged.

The two new re-plan call sites put the native route's large future inside the
recursive planner frame at every nesting level (~178 KB became ~209 KB), which
overflowed the 2 MiB test-thread stack in `test_parse_or_operator` even where
the new branch never ran. Box the future in a non-async helper and move the
re-plan into `replan_rewritten_operand`, which brings the frame back to the
old size without changing the behaviour.

The partitioned-pair unit test asserted the removed shape. It now asks for the
remote engine state, where a cross-table pair really is one fused node over
two raw sources, and asserts that the same pair in process keeps the hybrid
route.

Signed-off-by: discord9 <discord9@163.com>

* chore(deps): pin greptime-proto to the merged raw series transport

GreptimeTeam/greptime-proto#349 has been merged into `narthex-proto` as
`f51cb5312bf7`. Move the rev from that PR's head commit to its merge commit,
in `Cargo.toml` and `Cargo.lock` together, so the pin no longer points at an
unmerged ref.

Signed-off-by: discord9 <discord9@163.com>

---------

Signed-off-by: discord9 <discord9@163.com>
This commit is contained in:
discord9
2026-11-06 10:31:52 +08:00
committed by GitHub
parent fb4f08a2b8
commit 58a67a47c3
34 changed files with 3834 additions and 388 deletions
Generated
+2 -1
View File
@@ -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]]
+1 -1
View File
@@ -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"
+37 -44
View File
@@ -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<DfSendableRecordBatchStream> {
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<LabelDecodeSpec>) -> 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<String>) -> 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<Vec<u8>>,
@@ -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(())
}
}
+254 -55
View File
@@ -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::<crate::error::Error>(&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::<crate::error::Error>(&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::<crate::error::Error>(&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<datatypes::arrow::datatypes::Schema>, bool); 3] = [
let cases: [(&str, Arc<datatypes::arrow::datatypes::Schema>, 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(),
+3
View File
@@ -20,3 +20,6 @@ datafusion-substrait.workspace = true
promql.workspace = true
prost.workspace = true
snafu.workspace = true
[dev-dependencies]
tokio.workspace = true
@@ -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::<RawSeriesSource>()
.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::<RawSeriesSource>()
.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);
}
}
+10 -5
View File
@@ -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.
+5 -3
View File
@@ -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")),
}
+2 -1
View File
@@ -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"),
] {
+39 -81
View File
@@ -365,6 +365,10 @@ struct FusedSeriesPayload {
format: FusedOutputFormat,
promql: Arc<str>,
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<Vec<u8>> {
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<LogicalPlan>,
) -> DataFusionResult<Self> {
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<dyn ExecutionPlan>;
(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::<super::RawSeriesSource>()
{
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::<FusedSeries>()
.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.
@@ -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::<SeriesRepartitionExec>()
.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::<SeriesRepartitionExec>().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::<SeriesRepartitionExec>()
.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::<SeriesRepartitionExec>()
.expect("matching router");
assert!(matches!(
matching.routing_policy(),
SeriesRouting::Matching(_)
));
let matching_children = child.children();
let owner = matching_children[0]
.downcast_ref::<SeriesRepartitionExec>()
.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() {
+144 -1
View File
@@ -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::<DfResult<Vec<_>>>()?;
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<dyn ExecutionPlan>) -> DfResult<Arc<dyn ExecutionPlan>> {
let Some(union) = input.downcast_ref::<UnionExec>() 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<dyn PhysicalExpr>,
field.name().clone(),
)
})
.collect::<Vec<_>>();
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::<UnionExec>() {
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<SeriesOrdering> {
let declaration = SeriesFrameDeclaration::parse(schema).ok()?;
if declaration.labels() != FrameLabelMode::Explicit {
@@ -257,3 +324,79 @@ fn explicit_label_frame_ordering(schema: &Schema) -> Option<SeriesOrdering> {
}
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<datafusion::arrow::datatypes::Schema> {
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<dyn ExecutionPlan> {
let children = children
.iter()
.map(|ordering| {
Arc::new(EmptyExec::new(raw_frame(*ordering))) as Arc<dyn ExecutionPlan>
})
.collect::<Vec<_>>();
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<dyn ExecutionPlan>))
.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"
);
}
}
@@ -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<u8> {
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<Self> {
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<u8> {
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::<Vec<_>>(),
["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());
}
}
@@ -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<dyn ExecutionPlan>,
/// 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<SeriesSchema>,
/// 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<SeriesSchema>,
pool: Arc<dyn MemoryPool>,
/// 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<OwnerKey, PendingGroup>,
@@ -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(),
)));
@@ -648,6 +648,7 @@ struct RawScript {
ordering: SeriesOrdering,
gate: Option<Arc<Switch>>,
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<SeriesSchema>,
decode: Option<LabelDecodeSpec>,
ordering: SeriesOrdering,
fail_after_gate: bool,
properties: Arc<PlanProperties>,
}
@@ -706,6 +713,14 @@ impl RawScripted {
fn plan_with_ordering(
partitions: Vec<RawPartition>,
ordering: SeriesOrdering,
) -> Arc<dyn ExecutionPlan> {
Self::plan_with_ordering_and_failure(partitions, ordering, false)
}
fn plan_with_ordering_and_failure(
partitions: Vec<RawPartition>,
ordering: SeriesOrdering,
fail_after_gate: bool,
) -> Arc<dyn ExecutionPlan> {
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,
}))
}
}
+13
View File
@@ -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(
+1 -7
View File
@@ -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!(
+1 -3
View File
@@ -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> {
+11 -9
View File
@@ -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}"
);
}
+352 -3
View File
@@ -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<Arc<QueryEngineState>> {
context.session_config().get_extension()
@@ -481,6 +483,7 @@ pub struct MergeScanExec {
regions: Vec<RegionId>,
plan: LogicalPlan,
arrow_schema: ArrowSchemaRef,
remote_schema: ArrowSchemaRef,
region_query_handler: RegionQueryHandlerRef,
metric: ExecutionPlanMetricsSet,
properties: Arc<PlanProperties>,
@@ -520,6 +523,7 @@ impl MergeScanExec {
remote_dyn_filter_producer_id: Option<RemoteDynFilterProducerId>,
enable_per_region_metrics: bool,
) -> Result<Self> {
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<Self> {
if !disjoint
&& matches!(&self.plan, LogicalPlan::Extension(extension)
if extension.node.as_any().is::<RawSeriesSource>())
{
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::<RegionReadLimiter>();
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<dyn ExecutionPlan>],
session: &dyn Session,
_planning_ctx: &PhysicalPlanningContext,
) -> Result<Option<Arc<dyn ExecutionPlan>>> {
let Some(scan) = node.as_any().downcast_ref::<MergeScanLogicalPlan>() else {
return Ok(None);
};
let session = session.as_any().downcast_ref::<SessionState>().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::<MergeScanExec>()
.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<dyn ExecutionPlan>;
let root = logical.to_per_series_execution_plan(input).unwrap();
let output = SeriesFrameOutput
.optimize(root, &ConfigOptions::default())
.unwrap();
let router = output.downcast_ref::<SeriesRepartitionExec>().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::<Vec<_>>();
let times = chunks
.iter()
.flat_map(|chunk| (0..chunk.time.len()).map(|i| chunk.time.timestamp(i).unwrap()))
.collect::<Vec<_>>();
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);
+175 -11
View File
@@ -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::<promql::extension_plan::RawSeriesSource>());
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<Vec<RegionId>> {
) -> Result<(Vec<RegionId>, 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, &regions)
})
};
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::<std::collections::HashSet<_>>();
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, &regions));
info.meta.primary_key_indices = vec![0, 1];
assert!(physical_regions_disjoint(&info, &routes, &regions));
info.meta.partition_key_indices = vec![0, 1];
assert!(physical_regions_disjoint(&info, &routes, &regions));
info.meta.partition_key_indices = vec![0, 2];
assert!(!physical_regions_disjoint(&info, &routes, &regions));
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, &regions));
let mut missing = routes.clone();
missing[1] = region_route(2, None);
assert!(!physical_regions_disjoint(&info, &missing, &regions));
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, &regions));
let mut malformed = routes.clone();
malformed[1].region.partition_expr = "{invalid".into();
assert!(!physical_regions_disjoint(&info, &malformed, &regions));
assert!(!physical_regions_disjoint(&info, &routes[..1], &regions));
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, &regions));
}
#[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<RegionId>) {
regions.sort_unstable();
assert_eq!(
+124 -22
View File
@@ -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::<promql::extension_plan::RawSeriesSource>()
{
*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<QueryEngineState>,
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.
+95 -24
View File
@@ -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<Box<dyn Future<Output = Result<Option<(LogicalPlan, PromPlannerContext)>>> + 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<LogicalPlan> {
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 {
+144 -20
View File
@@ -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<dyn ExecutionPlan>) -> bool {
fn walk(node: &dyn ExecutionPlan, fused: &mut usize) -> bool {
let is_fused = node.is::<FusedSeriesExec>();
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<Option<(LogicalPlan, super::PromPlannerContext)>> {
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<u32>,
logical_ids_differ: &mut bool,
statement_kind: &mut Option<FieldKind>,
self_contained: bool,
) -> Result<Option<PreparedInput>> {
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<Option<LogicalPlan>> {
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<Option<(LogicalPlan, Option<super::PromPlannerContext>)>> {
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::<RawSeriesSource>()
);
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<Option<LogicalPlan>> {
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<dyn ExecutionPlan>
};
// 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"])
}
+64 -20
View File
@@ -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::<RawSeriesSource>()),
"{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");
+7
View File
@@ -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<TaskContext> {
let dbname = self.query_ctx.get_db_string();
let state = &self.state;
+174
View File
@@ -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<dyn ExecutionPlan>],
session: &dyn Session,
_planning_ctx: &PhysicalPlanningContext,
) -> DfResult<Option<Arc<dyn ExecutionPlan>>> {
let Some(scan) = node.as_any().downcast_ref::<MergeScanLogicalPlan>() else {
return Ok(None);
};
let session = session.as_any().downcast_ref::<SessionState>().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::<SeriesRepartitionExec>().is_some(),
needs_router,
"disjoint={disjoint}: {analyzed}"
);
if let Some(router) = child.downcast_ref::<SeriesRepartitionExec>() {
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())
+71 -2
View File
@@ -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<dyn RegionQueryHandler>;
#[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<RegionQueryTarget> {
unimplemented!("planning test does not dispatch regions")
}
async fn do_get(
&self,
_target: &RegionQueryTarget,
_request: common_query::request::QueryRequest,
) -> crate::error::Result<common_recordbatch::SendableRecordBatchStream> {
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() {
+8
View File
@@ -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(
+254 -29
View File
@@ -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<Mutex<ActiveDoGet>>,
}
#[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<Self>) -> 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<DatanodeRpcStats>);
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<DatanodeId, Arc<DatanodeRpcStats>>,
network_do_get: Arc<Mutex<ActiveDoGet>>,
pub kv_backend: KvBackendRef,
pub metasrv: Arc<Metasrv>,
pub frontend: Arc<Frontend>,
@@ -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<String> {
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<DatanodeOptions>,
@@ -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::<HashMap<_, _>>()
} 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<I, IO>(
/// 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<S> {
impl<S, ReqBody> Service<http::Request<ReqBody>> for CountRequests<S>
where
S: Service<http::Request<ReqBody>>,
S: Service<http::Request<ReqBody>, Response = http::Response<tonic::body::Body>>,
S::Future: Send + 'static,
S::Error: Send + 'static,
{
type Response = S::Response;
type Response = http::Response<tonic::body::Body>;
type Error = S::Error;
type Future = S::Future;
type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
self.inner.poll_ready(cx)
}
fn call(&mut self, request: http::Request<ReqBody>) -> 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<tonic::body::Body>,
_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<http::Response<tonic::body::Body>, 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::<http::Response<tonic::body::Body>, _>(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);
File diff suppressed because it is too large Load Diff
@@ -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.
@@ -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`.
@@ -0,0 +1 @@
08011213687474705f72657175657374735f746f74616c1a017a1a0161220776616c75655f62220776616c75655f61