From d639f1569e317ef32c11b1b588f44048d93f0054 Mon Sep 17 00:00:00 2001 From: discord9 <55937128+discord9@users.noreply.github.com> Date: Fri, 16 Oct 2026 15:00:04 +0800 Subject: [PATCH 1/4] feat(storage): separate prepared series selection from raw readers Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com> --- src/datatypes/src/series/raw.rs | 101 ++--- src/datatypes/src/series/raw/tests.rs | 51 +-- src/store-api/src/region_engine.rs | 75 +++- .../region_engine/prepared_series_tests.rs | 405 ++++++++++++++++++ 4 files changed, 546 insertions(+), 86 deletions(-) create mode 100644 src/store-api/src/region_engine/prepared_series_tests.rs diff --git a/src/datatypes/src/series/raw.rs b/src/datatypes/src/series/raw.rs index 6c5b04ceac7..9c18ae2941a 100644 --- a/src/datatypes/src/series/raw.rs +++ b/src/datatypes/src/series/raw.rs @@ -22,59 +22,51 @@ use crate::error::{InvalidSeriesSnafu, Result}; use crate::series::samples::{SeriesFields, SeriesSchema}; use crate::series::{MetricName, invalid_series}; -/// Explicit source timestamps in milliseconds for a raw series chunk. -#[non_exhaustive] +/// Strictly increasing source timestamps in milliseconds for a raw series chunk. +/// +/// Its private buffer ensures timestamps are validated once at construction. Direct +/// construction is intentionally unavailable: +/// +/// ```compile_fail +/// use arrow::buffer::ScalarBuffer; +/// use datatypes::series::raw::RawTimestamps; +/// +/// let timestamps = RawTimestamps { +/// values: ScalarBuffer::from(vec![1_i64, 2]), +/// }; +/// ``` #[derive(Clone, Debug)] -pub enum RawTimeAxis { - /// Source timestamps in strictly increasing order. - Explicit(ScalarBuffer), +pub struct RawTimestamps { + values: ScalarBuffer, } -impl RawTimeAxis { - /// Validates and wraps strictly increasing timestamps; an empty axis is valid on its own. - pub fn try_new(timestamps: ScalarBuffer) -> Result { - let axis = Self::Explicit(timestamps); - axis.try_len()?; - Ok(axis) +impl RawTimestamps { + /// Validates and wraps strictly increasing timestamps; an empty wrapper is valid. + pub fn try_new(values: ScalarBuffer) -> Result { + if values.windows(2).any(|pair| pair[0] >= pair[1]) { + return invalid_series("raw timestamps must be strictly increasing"); + } + Ok(Self { values }) } - /// Returns the explicit timestamp buffer, if this axis uses explicit timestamps. - /// - /// Future axis variants may not have an explicit buffer. - pub fn as_explicit(&self) -> Option<&ScalarBuffer> { - match self { - Self::Explicit(values) => Some(values), - } - } - - fn try_len(&self) -> Result { - match self { - Self::Explicit(values) => { - if values.windows(2).any(|pair| pair[0] >= pair[1]) { - return invalid_series("raw timestamps must be strictly increasing"); - } - Ok(values.len()) - } - } + /// Returns the underlying timestamp buffer. + pub fn as_buffer(&self) -> &ScalarBuffer { + &self.values } /// Returns the number of timestamps. pub fn len(&self) -> usize { - match self { - Self::Explicit(values) => values.len(), - } + self.values.len() } - /// Returns whether the axis has no timestamps. + /// Returns whether there are no timestamps. pub fn is_empty(&self) -> bool { - self.len() == 0 + self.values.is_empty() } /// Returns the timestamp at `index`, or `None` when out of bounds. pub fn timestamp(&self, index: usize) -> Option { - match self { - Self::Explicit(values) => values.get(index).copied(), - } + self.values.get(index).copied() } /// Returns a zero-copy slice, reporting overflowing or out-of-range bounds as an error. @@ -82,23 +74,23 @@ impl RawTimeAxis { let end = offset .checked_add(len) .with_context(|| InvalidSeriesSnafu { - reason: "raw time axis slice bounds overflow".to_string(), + reason: "raw timestamps slice bounds overflow".to_string(), })?; if end > self.len() { - return invalid_series("raw time axis slice is out of bounds"); - } - match self { - Self::Explicit(values) => Ok(Self::Explicit(values.slice(offset, len))), + return invalid_series("raw timestamps slice is out of bounds"); } + Ok(Self { + values: self.values.slice(offset, len), + }) } } /// Ordering guarantee for chunks in one input stream. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum RawSeriesOrdering { - /// Each read key's chunks are contiguous; distinct read keys need not be ordered. + /// Each complete primary key's chunks are contiguous; distinct keys need not be ordered. Contiguous, - /// Chunks are ordered by read key and then by timestamp. + /// Chunks are ordered by complete primary key and then by timestamp. ReadKeyThenTime, } @@ -109,27 +101,29 @@ pub enum RawSeriesOrdering { #[derive(Clone, Debug)] pub struct RawSeriesChunk { /// Complete encoded identity of the source series, not a TSID or hash alone. - pub read_key: Buffer, - /// `None` leaves labels unmaterialized in the complete read key; `Some` contains - /// complete explicit labels. + pub primary_key: Buffer, + /// `None` denotes an encoded key under bound-label mode; `Some` contains complete + /// explicit labels and retains their identity. pub metric: Option, /// Source timestamps aligned with every field. - pub time: RawTimeAxis, + pub time: RawTimestamps, /// Field values aligned with the source timestamps. pub fields: SeriesFields, - /// Whether this is the final chunk for this input stream's series, not all regions. + /// Whether this is the final chunk for this series in the input stream exposing it. + /// Merge code must recompute finalization globally across all relevant inputs before + /// downstream finalization. pub is_last: bool, } impl RawSeriesChunk { - /// Creates a nonempty chunk after checking its explicit time axis and schema alignment. + /// Creates a nonempty chunk after checking its time axis and schema alignment. /// /// Validation is local to this chunk and does not verify ordering between chunks. pub fn try_new( schema: &SeriesSchema, - read_key: Buffer, + primary_key: Buffer, metric: Option, - time: RawTimeAxis, + time: RawTimestamps, fields: SeriesFields, is_last: bool, ) -> Result { @@ -145,9 +139,8 @@ impl RawSeriesChunk { if time.is_empty() { return invalid_series("raw series chunks must not be empty"); } - time.try_len()?; Ok(Self { - read_key, + primary_key, metric, time, fields, diff --git a/src/datatypes/src/series/raw/tests.rs b/src/datatypes/src/series/raw/tests.rs index ee982148d73..ea2d4f80193 100644 --- a/src/datatypes/src/series/raw/tests.rs +++ b/src/datatypes/src/series/raw/tests.rs @@ -46,8 +46,8 @@ fn metric() -> MetricName { .unwrap() } -fn times(values: Vec) -> RawTimeAxis { - RawTimeAxis::try_new(values.into()).unwrap() +fn times(values: Vec) -> RawTimestamps { + RawTimestamps::try_new(values.into()).unwrap() } fn float_fields(first: Vec>, second: Option>>) -> SeriesFields { @@ -64,8 +64,13 @@ fn constructors_reject_invalid_chunk_boundaries_and_unordered_timestamps() { let key = Buffer::from(vec![1_u8]); let fields = float_fields(vec![Some(1.0), Some(2.0)], None); - assert!(RawTimeAxis::try_new(vec![1_i64, 1].into()).is_err()); - assert!(RawTimeAxis::try_new(vec![2_i64, 1].into()).is_err()); + assert!(RawTimestamps::try_new(vec![1_i64, 1].into()).is_err()); + assert!(RawTimestamps::try_new(vec![2_i64, 1].into()).is_err()); + assert!( + RawTimestamps::try_new(ScalarBuffer::from(Vec::::new())) + .unwrap() + .is_empty() + ); assert!( RawSeriesChunk::try_new( @@ -101,22 +106,6 @@ fn constructors_reject_invalid_chunk_boundaries_and_unordered_timestamps() { .is_err() ); - // Public enum construction bypasses RawTimeAxis::try_new, so chunk construction - // must independently reject duplicate and descending timestamps. - for unordered in [vec![1_i64, 1], vec![2_i64, 1]] { - assert!( - RawSeriesChunk::try_new( - &schema, - key.clone(), - None, - RawTimeAxis::Explicit(unordered.into()), - fields.clone(), - true, - ) - .is_err() - ); - } - let grid = Arc::new(EvalGrid::try_new(GridSpec::try_new(10, 5, 2).unwrap()).unwrap()); let grid_schema = SeriesSchema { fields: schema.fields.clone(), @@ -131,9 +120,9 @@ fn constructors_reject_invalid_chunk_boundaries_and_unordered_timestamps() { #[test] fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { let time_owner: ScalarBuffer = vec![0, 10, 20, 30, 40, 80].into(); - let time_source = RawTimeAxis::try_new(time_owner.clone()).unwrap(); + let time_source = RawTimestamps::try_new(time_owner.clone()).unwrap(); let time = time_source.slice(1, 4).unwrap(); - let time_buffer = time.as_explicit().unwrap(); + let time_buffer = time.as_buffer(); assert_eq!(time_buffer.as_ptr(), time_owner.as_ptr().wrapping_add(1)); let nan_payload = f64::from_bits(0x7ff8_0000_0000_0042); @@ -160,12 +149,12 @@ fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { ]) .unwrap(); let key_source = Buffer::from(vec![0_u8, 0xA1, 0xB2, 0xC3, 0xD4, 0xFF]); - let read_key = key_source.slice_with_length(1, 4); - assert_eq!(read_key.as_ptr(), key_source.as_ptr().wrapping_add(1)); + let primary_key = key_source.slice_with_length(1, 4); + assert_eq!(primary_key.as_ptr(), key_source.as_ptr().wrapping_add(1)); let schema = schema(&["first", "second"]); let chunk = - RawSeriesChunk::try_new(&schema, read_key, Some(metric()), time, fields, true).unwrap(); + RawSeriesChunk::try_new(&schema, primary_key, Some(metric()), time, fields, true).unwrap(); let Some(crate::series::samples::DenseSamplesRef::Float(first)) = chunk.fields.get(0).unwrap().dense() else { @@ -181,7 +170,7 @@ fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { drop(time_owner); drop(float_owner); drop(second_owner); - assert_eq!(chunk.read_key.as_slice(), &[0xA1, 0xB2, 0xC3, 0xD4]); + assert_eq!(chunk.primary_key.as_slice(), &[0xA1, 0xB2, 0xC3, 0xD4]); assert_eq!( (0..4) .map(|i| chunk.time.timestamp(i).unwrap()) @@ -224,9 +213,9 @@ fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { } #[test] -fn raw_time_axis_checks_bounds_and_retains_exact_end_slices() { +fn raw_timestamps_check_bounds_and_retain_exact_end_slices() { let source: ScalarBuffer = vec![4, 8, 12].into(); - let axis = RawTimeAxis::try_new(source.clone()).unwrap(); + let axis = RawTimestamps::try_new(source.clone()).unwrap(); assert!(axis.slice(usize::MAX, 1).is_err()); assert!(axis.slice(2, usize::MAX).is_err()); assert!(axis.slice(3, 1).is_err()); @@ -272,11 +261,11 @@ fn raw_chunks_preserve_native_unmaterialized_and_explicit_metrics() { false, ) .unwrap(); - assert_eq!(native.read_key.as_slice(), &[0, 0x12, 0x34, 0x56]); + assert_eq!(native.primary_key.as_slice(), &[0, 0x12, 0x34, 0x56]); assert!(native.metric.is_none()); - assert!(tagless.read_key.is_empty()); + assert!(tagless.primary_key.is_empty()); assert!(tagless.metric.is_none()); - assert_eq!(explicit.read_key.as_slice(), &[0, 0xAB, 0xCD, 0xEF]); + assert_eq!(explicit.primary_key.as_slice(), &[0, 0xAB, 0xCD, 0xEF]); assert_eq!(explicit.metric.as_ref().unwrap().name(), Some("cpu")); assert_eq!( explicit.metric.as_ref().unwrap().get("host"), diff --git a/src/store-api/src/region_engine.rs b/src/store-api/src/region_engine.rs index 48017c94f0f..d9c4fa477f6 100644 --- a/src/store-api/src/region_engine.rs +++ b/src/store-api/src/region_engine.rs @@ -499,7 +499,11 @@ pub enum RawLabelSource { /// A stream of raw series chunks with stable schema, label binding, and ordering. /// /// Chunks for a read key are contiguous, with strictly increasing timestamps within and across -/// chunks. `is_last` marks the last chunk of that key in this stream, not across streams. +/// chunks. `is_last` marks the last chunk of that key in this stream, not across streams; merge +/// code must recompute finalization globally across all relevant inputs before downstream +/// per-input-series finalization (not aggregate or vector-match state). `RawLabelSource` keeps +/// the stream's label interpretation self-contained through transport rather than relying on a +/// local source handle. pub trait RawSeriesStream: Stream> + Send { /// Returns the schema shared by all chunks; raw schemas have no evaluation grid. fn schema(&self) -> &Arc; @@ -514,6 +518,48 @@ pub trait RawSeriesStream: Stream> + S /// A pinned raw-series stream that can be sent between threads. pub type SendableRawSeriesStream = Pin>; +/// Stable identity metadata for one ordinal in a prepared series source. +#[derive(Clone, Debug)] +pub struct SeriesInfo { + /// Complete encoded primary key, not a TSID or hash alone. + pub primary_key: datatypes::arrow::buffer::Buffer, + /// Complete explicit metric and labels, or `None` for primary-key label binding. + pub metric: Option, +} + +/// An immutable, finite selected set of series prepared for independent range reads. +/// +/// The count may include series with no samples after filtering. Ordinals are stable local +/// indexes, not protocol identifiers; each has exactly one complete identity returned by +/// [`PreparedSeriesSource::series_info`], and that identity matches chunks for that ordinal. +/// Every reader exposes the same fixed schema, label binding, and ordering before polling, +/// including for an empty range, and describes labels independently of this source's lifetime. `PrimaryKey` output has `metric: None`; `Explicit` output has a +/// complete `Some(metric)` matching each chunk. [`RawSeriesOrdering::Contiguous`] and +/// [`RawSeriesOrdering::ReadKeyThenTime`] describe stream order, not ordinal enumeration order. +/// +/// Preparation, identity lookup, and reader creation do not load sample payloads or perform +/// hidden blocking I/O. The selected set is bound to the partition's immutable MVCC view, +/// predicates, authorization, projection, labels, and existing scan resources. Readers own +/// resources needed to continue after this source or scanner is dropped. Dropping one reader +/// does not cancel sibling readers; normal ownership cleanup applies without detached work. +/// +/// A range must satisfy `start <= end <= num_series()`. Invalid ranges and invalid ordinals +/// return errors; an empty in-bounds range returns an ordinary empty stream. Repeated and +/// overlapping reads are independent and do not consume shared iteration state. +pub trait PreparedSeriesSource: Send + Sync { + /// Returns the exact, stable number of selected local series ordinals. + fn num_series(&self) -> usize; + + /// Returns identity metadata for an ordinal without polling sample data. + fn series_info(&self, ordinal: usize) -> Result; + + /// Creates an independent reader for the half-open ordinal range. + fn read_series( + &self, + range: std::ops::Range, + ) -> Result; +} + /// A scanner that provides a way to scan the region concurrently. /// /// The scanner splits the region into partitions so that each partition can be scanned concurrently. @@ -566,6 +612,22 @@ pub trait RegionScanner: Debug + DisplayAs + Send { todo!() } + /// Prepares a finite, stable set of series for independent ordinal-range reads. + /// + /// `None` means unsupported before consumption, so callers may use the legacy record-batch + /// scan. `Some`, including a source with zero series, selects this path; errors propagate + /// without replay. Choose exactly one entrypoint per partition per execution: this prepared + /// source, [`Self::scan_series_partition`], or [`Self::scan_partition`]. In particular, do + /// not call the legacy raw-scan default merely because this returns `None`. + fn prepare_series_partition( + &self, + _ctx: &QueryScanContext, + _metrics_set: &ExecutionPlanMetricsSet, + _partition: usize, + ) -> Result>, BoxedError> { + Ok(None) + } + /// Check if there is any predicate exclude region partition exprs that may be executed in this scanner. fn has_predicate_without_region(&self) -> bool; @@ -804,6 +866,10 @@ impl RegionStatistic { } } +#[cfg(test)] +#[path = "region_engine/prepared_series_tests.rs"] +mod prepared_series_tests; + #[cfg(test)] mod tests { use common_recordbatch::{RecordBatch, RecordBatches}; @@ -859,6 +925,13 @@ mod tests { let ctx = QueryScanContext::default(); let metrics = ExecutionPlanMetricsSet::new(); + assert!( + scanner + .prepare_series_partition(&ctx, &metrics, 0) + .unwrap() + .is_none() + ); + // SinglePartitionScanner uses the default raw-scan implementation, which panics. let raw_scan = catch_unwind(AssertUnwindSafe(|| { scanner.scan_series_partition(&ctx, &metrics, 0) diff --git a/src/store-api/src/region_engine/prepared_series_tests.rs b/src/store-api/src/region_engine/prepared_series_tests.rs new file mode 100644 index 00000000000..05882ddcc70 --- /dev/null +++ b/src/store-api/src/region_engine/prepared_series_tests.rs @@ -0,0 +1,405 @@ +// Copyright 2023 Greptime Team +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +use std::collections::VecDeque; +use std::pin::Pin; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; +use std::task::{Context, Poll}; + +use api::v1::SemanticType; +use common_error::ext::BoxedError; +use datatypes::arrow::array::Float64Array; +use datatypes::arrow::buffer::Buffer; +use datatypes::error::InvalidSeriesSnafu; +use datatypes::prelude::ConcreteDataType; +use datatypes::schema::ColumnSchema; +use datatypes::series::raw::{RawSeriesChunk, RawSeriesOrdering, RawTimestamps}; +use datatypes::series::samples::{FieldSpec, Samples, SeriesFields, SeriesSchema}; +use datatypes::series::{Label, MetricName}; +use futures::{Stream, StreamExt}; + +use crate::region_engine::{ + PreparedSeriesSource, RawLabelSource, RawSeriesStream, SendableRawSeriesStream, SeriesInfo, +}; + +#[derive(Clone)] +struct TestSeries { + info: SeriesInfo, + chunks: Vec, +} + +struct MemorySource { + series: Arc<[TestSeries]>, + schema: Arc, + label_source: RawLabelSource, + polls: Arc, + drops: Arc, +} + +impl PreparedSeriesSource for MemorySource { + fn num_series(&self) -> usize { + self.series.len() + } + + fn series_info(&self, ordinal: usize) -> Result { + self.series + .get(ordinal) + .map(|series| series.info.clone()) + .ok_or_else(|| { + BoxedError::new( + InvalidSeriesSnafu { + reason: "invalid series ordinal".to_string(), + } + .build(), + ) + }) + } + + fn read_series( + &self, + range: std::ops::Range, + ) -> Result { + if range.start > range.end || range.end > self.series.len() { + return Err(BoxedError::new( + InvalidSeriesSnafu { + reason: "invalid series range".to_string(), + } + .build(), + )); + } + let chunks = self.series[range] + .iter() + .flat_map(|series| series.chunks.iter().cloned()) + .collect(); + Ok(Box::pin(MemoryReader { + chunks, + schema: self.schema.clone(), + label_source: self.label_source.clone(), + polls: self.polls.clone(), + drops: self.drops.clone(), + })) + } +} + +struct MemoryReader { + chunks: VecDeque, + schema: Arc, + label_source: RawLabelSource, + polls: Arc, + drops: Arc, +} + +impl Stream for MemoryReader { + type Item = Result; + + fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll> { + let chunk = self.chunks.pop_front(); + if chunk.is_some() { + self.polls.fetch_add(1, Ordering::SeqCst); + } + Poll::Ready(chunk.map(Ok)) + } +} + +impl Drop for MemoryReader { + fn drop(&mut self) { + self.drops.fetch_add(1, Ordering::SeqCst); + } +} + +impl RawSeriesStream for MemoryReader { + fn schema(&self) -> &Arc { + &self.schema + } + + fn label_source(&self) -> &RawLabelSource { + &self.label_source + } + + fn ordering(&self) -> RawSeriesOrdering { + RawSeriesOrdering::Contiguous + } +} + +fn metric(host: &str) -> MetricName { + MetricName::try_new( + Some(Arc::from("cpu")), + vec![Label { + name: Arc::from("host"), + value: Arc::from(host), + }], + ) + .unwrap() +} + +fn schema() -> Arc { + Arc::new(SeriesSchema { + fields: vec![FieldSpec { + name: Arc::from("usage"), + }] + .into(), + eval_grid: None, + }) +} + +fn chunk( + key: &[u8], + metric: Option, + timestamp: i64, + value: f64, + last: bool, +) -> RawSeriesChunk { + RawSeriesChunk::try_new( + &schema(), + Buffer::from(key), + metric, + RawTimestamps::try_new(vec![timestamp].into()).unwrap(), + SeriesFields::one(Samples::from_float(Float64Array::from(vec![value]))), + last, + ) + .unwrap() +} + +fn primary_key_metadata() -> crate::metadata::RegionMetadata { + let mut builder = + crate::metadata::RegionMetadataBuilder::new(crate::storage::RegionId::new(1, 1)); + builder.push_column_metadata(crate::metadata::ColumnMetadata { + column_schema: ColumnSchema::new("host", ConcreteDataType::string_datatype(), false), + semantic_type: SemanticType::Tag, + column_id: 1, + }); + builder.push_column_metadata(crate::metadata::ColumnMetadata { + column_schema: ColumnSchema::new( + "ts", + ConcreteDataType::timestamp_millisecond_datatype(), + false, + ), + semantic_type: SemanticType::Timestamp, + column_id: 2, + }); + builder.primary_key(vec![1]); + builder.build().unwrap() +} + +fn empty_source() -> Arc { + Arc::new(MemorySource { + series: Arc::from([]), + schema: schema(), + label_source: RawLabelSource::Explicit, + polls: Arc::new(AtomicUsize::new(0)), + drops: Arc::new(AtomicUsize::new(0)), + }) +} + +fn source(explicit: bool) -> Arc { + source_from_keys( + explicit, + vec![ + Buffer::from(vec![0x10, 0x01]), + Buffer::from(vec![0x10, 0x02]), + ] + .into(), + ) +} + +fn source_from_keys(explicit: bool, keys: Arc<[Buffer]>) -> Arc { + assert_eq!(keys.len(), 2); + let first_metric = explicit.then(|| metric("a")); + let second_metric = explicit.then(|| metric("b")); + let series = vec![ + TestSeries { + info: SeriesInfo { + primary_key: keys[0].clone(), + metric: first_metric.clone(), + }, + chunks: vec![chunk(keys[0].as_slice(), first_metric, 10, 1.0, true)], + }, + TestSeries { + info: SeriesInfo { + primary_key: keys[1].clone(), + metric: second_metric.clone(), + }, + chunks: vec![ + chunk(keys[1].as_slice(), second_metric.clone(), 10, 2.0, false), + chunk(keys[1].as_slice(), second_metric, 20, 3.0, true), + ], + }, + ]; + Arc::new(MemorySource { + series: series.into(), + schema: schema(), + label_source: if explicit { + RawLabelSource::Explicit + } else { + RawLabelSource::PrimaryKey { + metric_name: Arc::from("cpu"), + physical_metadata: Arc::new(primary_key_metadata()), + logical_tags: Arc::from([]), + } + }, + polls: Arc::new(AtomicUsize::new(0)), + drops: Arc::new(AtomicUsize::new(0)), + }) +} + +#[tokio::test] +async fn prepared_identity_matches_chunks_in_both_label_modes_including_empty_reader() { + for explicit in [false, true] { + let source = source(explicit); + assert_eq!(source.num_series(), 2); + let first = source.series_info(0).unwrap(); + let second = source.series_info(1).unwrap(); + assert_eq!(first.primary_key, Buffer::from(vec![0x10, 0x01])); + assert_eq!(second.primary_key, Buffer::from(vec![0x10, 0x02])); + assert_eq!( + first.metric.as_ref().and_then(MetricName::name), + if explicit { Some("cpu") } else { None } + ); + assert_eq!( + first.metric.as_ref().and_then(|m| m.get("host")), + explicit.then_some("a") + ); + assert_eq!( + second.metric.as_ref().and_then(|m| m.get("host")), + explicit.then_some("b") + ); + + let empty = source.read_series(1..1).unwrap(); + assert_eq!(empty.schema().fields.len(), 1); + assert_eq!(empty.ordering(), RawSeriesOrdering::Contiguous); + assert_eq!( + matches!(empty.label_source(), RawLabelSource::Explicit), + explicit + ); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); + assert!( + futures::TryStreamExt::try_collect::>(empty) + .await + .unwrap() + .is_empty() + ); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); + let end = source.read_series(2..2).unwrap(); + assert_eq!(end.schema().fields.len(), 1); + assert_eq!( + matches!(end.label_source(), RawLabelSource::Explicit), + explicit + ); + + let chunks = + futures::TryStreamExt::try_collect::>(source.read_series(0..2).unwrap()) + .await + .unwrap(); + assert_eq!(chunks.len(), 3); + assert_eq!(source.polls.load(Ordering::SeqCst), 3); + assert_eq!(chunks[1].time.timestamp(0), Some(10)); + assert_eq!(chunks[2].time.timestamp(0), Some(20)); + assert!( + matches!(chunks[1].fields.get(0).unwrap().sample(0), datatypes::series::samples::SampleRef::Float(value) if value == 2.0) + ); + assert!( + matches!(chunks[2].fields.get(0).unwrap().sample(0), datatypes::series::samples::SampleRef::Float(value) if value == 3.0) + ); + for chunk in &chunks { + let ordinal = if chunk.primary_key == first.primary_key { + 0 + } else { + 1 + }; + let info = source.series_info(ordinal).unwrap(); + assert_eq!(chunk.primary_key, info.primary_key); + assert_eq!(chunk.metric, info.metric); + } + assert_eq!(chunks[0].metric.is_some(), explicit); + assert!(!chunks[1].is_last); + assert!(chunks[2].is_last); + } +} + +#[tokio::test] +async fn empty_prepared_source_supports_its_empty_range() { + let source = empty_source(); + assert_eq!(source.num_series(), 0); + let stream = source.read_series(0..0).unwrap(); + assert_eq!(stream.schema().fields.len(), 1); + assert!( + futures::TryStreamExt::try_collect::>(stream) + .await + .unwrap() + .is_empty() + ); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); +} + +#[test] +fn invalid_ordinals_and_ranges_fail_without_polling_samples() { + let source = source(false); + assert!(source.series_info(2).is_err()); + assert!(source.read_series(2..3).is_err()); + assert!(source.read_series(2..1).is_err()); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); +} + +#[tokio::test] +async fn overlapping_readers_are_independent_across_source_and_reader_drops() { + let source = source(false); + let drops = source.drops.clone(); + let mut left = source.read_series(0..2).unwrap(); + let mut right = source.read_series(1..2).unwrap(); + drop(source); + assert!(left.next().await.unwrap().unwrap().is_last); + assert_eq!( + right.next().await.unwrap().unwrap().primary_key, + Buffer::from(vec![0x10, 0x02]) + ); + drop(left); + assert_eq!( + futures::TryStreamExt::try_collect::>(right) + .await + .unwrap() + .len(), + 1 + ); + assert_eq!(drops.load(Ordering::SeqCst), 2); +} + +#[tokio::test] +async fn prepared_selection_is_independent_of_later_mutable_selection_changes() { + let selected = Arc::new(Mutex::new(vec![ + Buffer::from(vec![1_u8]), + Buffer::from(vec![2_u8]), + ])); + let prepared = source_from_keys(false, selected.lock().unwrap().clone().into()); + selected.lock().unwrap().push(Buffer::from(vec![3_u8])); + + assert_eq!(prepared.num_series(), 2); + assert_eq!( + prepared.series_info(0).unwrap().primary_key, + Buffer::from(vec![1_u8]) + ); + assert_eq!( + prepared.series_info(1).unwrap().primary_key, + Buffer::from(vec![2_u8]) + ); + let chunks = futures::TryStreamExt::try_collect::>(prepared.read_series(0..2).unwrap()) + .await + .unwrap(); + assert_eq!(chunks.len(), 3); + assert!( + chunks + .iter() + .all(|chunk| chunk.primary_key != Buffer::from(vec![3_u8])) + ); +} From 1284c043e5a07b8d42536ee1d89396c552e34716 Mon Sep 17 00:00:00 2001 From: discord9 <55937128+discord9@users.noreply.github.com> Date: Fri, 16 Oct 2026 15:00:04 +0800 Subject: [PATCH 2/4] feat(storage): separate prepared series selection from raw readers Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com> --- src/datatypes/src/series/raw.rs | 101 ++--- src/datatypes/src/series/raw/tests.rs | 51 +-- src/store-api/src/region_engine.rs | 75 +++- .../region_engine/prepared_series_tests.rs | 405 ++++++++++++++++++ 4 files changed, 546 insertions(+), 86 deletions(-) create mode 100644 src/store-api/src/region_engine/prepared_series_tests.rs diff --git a/src/datatypes/src/series/raw.rs b/src/datatypes/src/series/raw.rs index 6c5b04ceac7..9c18ae2941a 100644 --- a/src/datatypes/src/series/raw.rs +++ b/src/datatypes/src/series/raw.rs @@ -22,59 +22,51 @@ use crate::error::{InvalidSeriesSnafu, Result}; use crate::series::samples::{SeriesFields, SeriesSchema}; use crate::series::{MetricName, invalid_series}; -/// Explicit source timestamps in milliseconds for a raw series chunk. -#[non_exhaustive] +/// Strictly increasing source timestamps in milliseconds for a raw series chunk. +/// +/// Its private buffer ensures timestamps are validated once at construction. Direct +/// construction is intentionally unavailable: +/// +/// ```compile_fail +/// use arrow::buffer::ScalarBuffer; +/// use datatypes::series::raw::RawTimestamps; +/// +/// let timestamps = RawTimestamps { +/// values: ScalarBuffer::from(vec![1_i64, 2]), +/// }; +/// ``` #[derive(Clone, Debug)] -pub enum RawTimeAxis { - /// Source timestamps in strictly increasing order. - Explicit(ScalarBuffer), +pub struct RawTimestamps { + values: ScalarBuffer, } -impl RawTimeAxis { - /// Validates and wraps strictly increasing timestamps; an empty axis is valid on its own. - pub fn try_new(timestamps: ScalarBuffer) -> Result { - let axis = Self::Explicit(timestamps); - axis.try_len()?; - Ok(axis) +impl RawTimestamps { + /// Validates and wraps strictly increasing timestamps; an empty wrapper is valid. + pub fn try_new(values: ScalarBuffer) -> Result { + if values.windows(2).any(|pair| pair[0] >= pair[1]) { + return invalid_series("raw timestamps must be strictly increasing"); + } + Ok(Self { values }) } - /// Returns the explicit timestamp buffer, if this axis uses explicit timestamps. - /// - /// Future axis variants may not have an explicit buffer. - pub fn as_explicit(&self) -> Option<&ScalarBuffer> { - match self { - Self::Explicit(values) => Some(values), - } - } - - fn try_len(&self) -> Result { - match self { - Self::Explicit(values) => { - if values.windows(2).any(|pair| pair[0] >= pair[1]) { - return invalid_series("raw timestamps must be strictly increasing"); - } - Ok(values.len()) - } - } + /// Returns the underlying timestamp buffer. + pub fn as_buffer(&self) -> &ScalarBuffer { + &self.values } /// Returns the number of timestamps. pub fn len(&self) -> usize { - match self { - Self::Explicit(values) => values.len(), - } + self.values.len() } - /// Returns whether the axis has no timestamps. + /// Returns whether there are no timestamps. pub fn is_empty(&self) -> bool { - self.len() == 0 + self.values.is_empty() } /// Returns the timestamp at `index`, or `None` when out of bounds. pub fn timestamp(&self, index: usize) -> Option { - match self { - Self::Explicit(values) => values.get(index).copied(), - } + self.values.get(index).copied() } /// Returns a zero-copy slice, reporting overflowing or out-of-range bounds as an error. @@ -82,23 +74,23 @@ impl RawTimeAxis { let end = offset .checked_add(len) .with_context(|| InvalidSeriesSnafu { - reason: "raw time axis slice bounds overflow".to_string(), + reason: "raw timestamps slice bounds overflow".to_string(), })?; if end > self.len() { - return invalid_series("raw time axis slice is out of bounds"); - } - match self { - Self::Explicit(values) => Ok(Self::Explicit(values.slice(offset, len))), + return invalid_series("raw timestamps slice is out of bounds"); } + Ok(Self { + values: self.values.slice(offset, len), + }) } } /// Ordering guarantee for chunks in one input stream. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum RawSeriesOrdering { - /// Each read key's chunks are contiguous; distinct read keys need not be ordered. + /// Each complete primary key's chunks are contiguous; distinct keys need not be ordered. Contiguous, - /// Chunks are ordered by read key and then by timestamp. + /// Chunks are ordered by complete primary key and then by timestamp. ReadKeyThenTime, } @@ -109,27 +101,29 @@ pub enum RawSeriesOrdering { #[derive(Clone, Debug)] pub struct RawSeriesChunk { /// Complete encoded identity of the source series, not a TSID or hash alone. - pub read_key: Buffer, - /// `None` leaves labels unmaterialized in the complete read key; `Some` contains - /// complete explicit labels. + pub primary_key: Buffer, + /// `None` denotes an encoded key under bound-label mode; `Some` contains complete + /// explicit labels and retains their identity. pub metric: Option, /// Source timestamps aligned with every field. - pub time: RawTimeAxis, + pub time: RawTimestamps, /// Field values aligned with the source timestamps. pub fields: SeriesFields, - /// Whether this is the final chunk for this input stream's series, not all regions. + /// Whether this is the final chunk for this series in the input stream exposing it. + /// Merge code must recompute finalization globally across all relevant inputs before + /// downstream finalization. pub is_last: bool, } impl RawSeriesChunk { - /// Creates a nonempty chunk after checking its explicit time axis and schema alignment. + /// Creates a nonempty chunk after checking its time axis and schema alignment. /// /// Validation is local to this chunk and does not verify ordering between chunks. pub fn try_new( schema: &SeriesSchema, - read_key: Buffer, + primary_key: Buffer, metric: Option, - time: RawTimeAxis, + time: RawTimestamps, fields: SeriesFields, is_last: bool, ) -> Result { @@ -145,9 +139,8 @@ impl RawSeriesChunk { if time.is_empty() { return invalid_series("raw series chunks must not be empty"); } - time.try_len()?; Ok(Self { - read_key, + primary_key, metric, time, fields, diff --git a/src/datatypes/src/series/raw/tests.rs b/src/datatypes/src/series/raw/tests.rs index ee982148d73..ea2d4f80193 100644 --- a/src/datatypes/src/series/raw/tests.rs +++ b/src/datatypes/src/series/raw/tests.rs @@ -46,8 +46,8 @@ fn metric() -> MetricName { .unwrap() } -fn times(values: Vec) -> RawTimeAxis { - RawTimeAxis::try_new(values.into()).unwrap() +fn times(values: Vec) -> RawTimestamps { + RawTimestamps::try_new(values.into()).unwrap() } fn float_fields(first: Vec>, second: Option>>) -> SeriesFields { @@ -64,8 +64,13 @@ fn constructors_reject_invalid_chunk_boundaries_and_unordered_timestamps() { let key = Buffer::from(vec![1_u8]); let fields = float_fields(vec![Some(1.0), Some(2.0)], None); - assert!(RawTimeAxis::try_new(vec![1_i64, 1].into()).is_err()); - assert!(RawTimeAxis::try_new(vec![2_i64, 1].into()).is_err()); + assert!(RawTimestamps::try_new(vec![1_i64, 1].into()).is_err()); + assert!(RawTimestamps::try_new(vec![2_i64, 1].into()).is_err()); + assert!( + RawTimestamps::try_new(ScalarBuffer::from(Vec::::new())) + .unwrap() + .is_empty() + ); assert!( RawSeriesChunk::try_new( @@ -101,22 +106,6 @@ fn constructors_reject_invalid_chunk_boundaries_and_unordered_timestamps() { .is_err() ); - // Public enum construction bypasses RawTimeAxis::try_new, so chunk construction - // must independently reject duplicate and descending timestamps. - for unordered in [vec![1_i64, 1], vec![2_i64, 1]] { - assert!( - RawSeriesChunk::try_new( - &schema, - key.clone(), - None, - RawTimeAxis::Explicit(unordered.into()), - fields.clone(), - true, - ) - .is_err() - ); - } - let grid = Arc::new(EvalGrid::try_new(GridSpec::try_new(10, 5, 2).unwrap()).unwrap()); let grid_schema = SeriesSchema { fields: schema.fields.clone(), @@ -131,9 +120,9 @@ fn constructors_reject_invalid_chunk_boundaries_and_unordered_timestamps() { #[test] fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { let time_owner: ScalarBuffer = vec![0, 10, 20, 30, 40, 80].into(); - let time_source = RawTimeAxis::try_new(time_owner.clone()).unwrap(); + let time_source = RawTimestamps::try_new(time_owner.clone()).unwrap(); let time = time_source.slice(1, 4).unwrap(); - let time_buffer = time.as_explicit().unwrap(); + let time_buffer = time.as_buffer(); assert_eq!(time_buffer.as_ptr(), time_owner.as_ptr().wrapping_add(1)); let nan_payload = f64::from_bits(0x7ff8_0000_0000_0042); @@ -160,12 +149,12 @@ fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { ]) .unwrap(); let key_source = Buffer::from(vec![0_u8, 0xA1, 0xB2, 0xC3, 0xD4, 0xFF]); - let read_key = key_source.slice_with_length(1, 4); - assert_eq!(read_key.as_ptr(), key_source.as_ptr().wrapping_add(1)); + let primary_key = key_source.slice_with_length(1, 4); + assert_eq!(primary_key.as_ptr(), key_source.as_ptr().wrapping_add(1)); let schema = schema(&["first", "second"]); let chunk = - RawSeriesChunk::try_new(&schema, read_key, Some(metric()), time, fields, true).unwrap(); + RawSeriesChunk::try_new(&schema, primary_key, Some(metric()), time, fields, true).unwrap(); let Some(crate::series::samples::DenseSamplesRef::Float(first)) = chunk.fields.get(0).unwrap().dense() else { @@ -181,7 +170,7 @@ fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { drop(time_owner); drop(float_owner); drop(second_owner); - assert_eq!(chunk.read_key.as_slice(), &[0xA1, 0xB2, 0xC3, 0xD4]); + assert_eq!(chunk.primary_key.as_slice(), &[0xA1, 0xB2, 0xC3, 0xD4]); assert_eq!( (0..4) .map(|i| chunk.time.timestamp(i).unwrap()) @@ -224,9 +213,9 @@ fn sliced_axes_and_chunks_keep_shared_buffers_and_values_alive() { } #[test] -fn raw_time_axis_checks_bounds_and_retains_exact_end_slices() { +fn raw_timestamps_check_bounds_and_retain_exact_end_slices() { let source: ScalarBuffer = vec![4, 8, 12].into(); - let axis = RawTimeAxis::try_new(source.clone()).unwrap(); + let axis = RawTimestamps::try_new(source.clone()).unwrap(); assert!(axis.slice(usize::MAX, 1).is_err()); assert!(axis.slice(2, usize::MAX).is_err()); assert!(axis.slice(3, 1).is_err()); @@ -272,11 +261,11 @@ fn raw_chunks_preserve_native_unmaterialized_and_explicit_metrics() { false, ) .unwrap(); - assert_eq!(native.read_key.as_slice(), &[0, 0x12, 0x34, 0x56]); + assert_eq!(native.primary_key.as_slice(), &[0, 0x12, 0x34, 0x56]); assert!(native.metric.is_none()); - assert!(tagless.read_key.is_empty()); + assert!(tagless.primary_key.is_empty()); assert!(tagless.metric.is_none()); - assert_eq!(explicit.read_key.as_slice(), &[0, 0xAB, 0xCD, 0xEF]); + assert_eq!(explicit.primary_key.as_slice(), &[0, 0xAB, 0xCD, 0xEF]); assert_eq!(explicit.metric.as_ref().unwrap().name(), Some("cpu")); assert_eq!( explicit.metric.as_ref().unwrap().get("host"), diff --git a/src/store-api/src/region_engine.rs b/src/store-api/src/region_engine.rs index 48017c94f0f..d9c4fa477f6 100644 --- a/src/store-api/src/region_engine.rs +++ b/src/store-api/src/region_engine.rs @@ -499,7 +499,11 @@ pub enum RawLabelSource { /// A stream of raw series chunks with stable schema, label binding, and ordering. /// /// Chunks for a read key are contiguous, with strictly increasing timestamps within and across -/// chunks. `is_last` marks the last chunk of that key in this stream, not across streams. +/// chunks. `is_last` marks the last chunk of that key in this stream, not across streams; merge +/// code must recompute finalization globally across all relevant inputs before downstream +/// per-input-series finalization (not aggregate or vector-match state). `RawLabelSource` keeps +/// the stream's label interpretation self-contained through transport rather than relying on a +/// local source handle. pub trait RawSeriesStream: Stream> + Send { /// Returns the schema shared by all chunks; raw schemas have no evaluation grid. fn schema(&self) -> &Arc; @@ -514,6 +518,48 @@ pub trait RawSeriesStream: Stream> + S /// A pinned raw-series stream that can be sent between threads. pub type SendableRawSeriesStream = Pin>; +/// Stable identity metadata for one ordinal in a prepared series source. +#[derive(Clone, Debug)] +pub struct SeriesInfo { + /// Complete encoded primary key, not a TSID or hash alone. + pub primary_key: datatypes::arrow::buffer::Buffer, + /// Complete explicit metric and labels, or `None` for primary-key label binding. + pub metric: Option, +} + +/// An immutable, finite selected set of series prepared for independent range reads. +/// +/// The count may include series with no samples after filtering. Ordinals are stable local +/// indexes, not protocol identifiers; each has exactly one complete identity returned by +/// [`PreparedSeriesSource::series_info`], and that identity matches chunks for that ordinal. +/// Every reader exposes the same fixed schema, label binding, and ordering before polling, +/// including for an empty range, and describes labels independently of this source's lifetime. `PrimaryKey` output has `metric: None`; `Explicit` output has a +/// complete `Some(metric)` matching each chunk. [`RawSeriesOrdering::Contiguous`] and +/// [`RawSeriesOrdering::ReadKeyThenTime`] describe stream order, not ordinal enumeration order. +/// +/// Preparation, identity lookup, and reader creation do not load sample payloads or perform +/// hidden blocking I/O. The selected set is bound to the partition's immutable MVCC view, +/// predicates, authorization, projection, labels, and existing scan resources. Readers own +/// resources needed to continue after this source or scanner is dropped. Dropping one reader +/// does not cancel sibling readers; normal ownership cleanup applies without detached work. +/// +/// A range must satisfy `start <= end <= num_series()`. Invalid ranges and invalid ordinals +/// return errors; an empty in-bounds range returns an ordinary empty stream. Repeated and +/// overlapping reads are independent and do not consume shared iteration state. +pub trait PreparedSeriesSource: Send + Sync { + /// Returns the exact, stable number of selected local series ordinals. + fn num_series(&self) -> usize; + + /// Returns identity metadata for an ordinal without polling sample data. + fn series_info(&self, ordinal: usize) -> Result; + + /// Creates an independent reader for the half-open ordinal range. + fn read_series( + &self, + range: std::ops::Range, + ) -> Result; +} + /// A scanner that provides a way to scan the region concurrently. /// /// The scanner splits the region into partitions so that each partition can be scanned concurrently. @@ -566,6 +612,22 @@ pub trait RegionScanner: Debug + DisplayAs + Send { todo!() } + /// Prepares a finite, stable set of series for independent ordinal-range reads. + /// + /// `None` means unsupported before consumption, so callers may use the legacy record-batch + /// scan. `Some`, including a source with zero series, selects this path; errors propagate + /// without replay. Choose exactly one entrypoint per partition per execution: this prepared + /// source, [`Self::scan_series_partition`], or [`Self::scan_partition`]. In particular, do + /// not call the legacy raw-scan default merely because this returns `None`. + fn prepare_series_partition( + &self, + _ctx: &QueryScanContext, + _metrics_set: &ExecutionPlanMetricsSet, + _partition: usize, + ) -> Result>, BoxedError> { + Ok(None) + } + /// Check if there is any predicate exclude region partition exprs that may be executed in this scanner. fn has_predicate_without_region(&self) -> bool; @@ -804,6 +866,10 @@ impl RegionStatistic { } } +#[cfg(test)] +#[path = "region_engine/prepared_series_tests.rs"] +mod prepared_series_tests; + #[cfg(test)] mod tests { use common_recordbatch::{RecordBatch, RecordBatches}; @@ -859,6 +925,13 @@ mod tests { let ctx = QueryScanContext::default(); let metrics = ExecutionPlanMetricsSet::new(); + assert!( + scanner + .prepare_series_partition(&ctx, &metrics, 0) + .unwrap() + .is_none() + ); + // SinglePartitionScanner uses the default raw-scan implementation, which panics. let raw_scan = catch_unwind(AssertUnwindSafe(|| { scanner.scan_series_partition(&ctx, &metrics, 0) diff --git a/src/store-api/src/region_engine/prepared_series_tests.rs b/src/store-api/src/region_engine/prepared_series_tests.rs new file mode 100644 index 00000000000..05882ddcc70 --- /dev/null +++ b/src/store-api/src/region_engine/prepared_series_tests.rs @@ -0,0 +1,405 @@ +// Copyright 2023 Greptime Team +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +use std::collections::VecDeque; +use std::pin::Pin; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; +use std::task::{Context, Poll}; + +use api::v1::SemanticType; +use common_error::ext::BoxedError; +use datatypes::arrow::array::Float64Array; +use datatypes::arrow::buffer::Buffer; +use datatypes::error::InvalidSeriesSnafu; +use datatypes::prelude::ConcreteDataType; +use datatypes::schema::ColumnSchema; +use datatypes::series::raw::{RawSeriesChunk, RawSeriesOrdering, RawTimestamps}; +use datatypes::series::samples::{FieldSpec, Samples, SeriesFields, SeriesSchema}; +use datatypes::series::{Label, MetricName}; +use futures::{Stream, StreamExt}; + +use crate::region_engine::{ + PreparedSeriesSource, RawLabelSource, RawSeriesStream, SendableRawSeriesStream, SeriesInfo, +}; + +#[derive(Clone)] +struct TestSeries { + info: SeriesInfo, + chunks: Vec, +} + +struct MemorySource { + series: Arc<[TestSeries]>, + schema: Arc, + label_source: RawLabelSource, + polls: Arc, + drops: Arc, +} + +impl PreparedSeriesSource for MemorySource { + fn num_series(&self) -> usize { + self.series.len() + } + + fn series_info(&self, ordinal: usize) -> Result { + self.series + .get(ordinal) + .map(|series| series.info.clone()) + .ok_or_else(|| { + BoxedError::new( + InvalidSeriesSnafu { + reason: "invalid series ordinal".to_string(), + } + .build(), + ) + }) + } + + fn read_series( + &self, + range: std::ops::Range, + ) -> Result { + if range.start > range.end || range.end > self.series.len() { + return Err(BoxedError::new( + InvalidSeriesSnafu { + reason: "invalid series range".to_string(), + } + .build(), + )); + } + let chunks = self.series[range] + .iter() + .flat_map(|series| series.chunks.iter().cloned()) + .collect(); + Ok(Box::pin(MemoryReader { + chunks, + schema: self.schema.clone(), + label_source: self.label_source.clone(), + polls: self.polls.clone(), + drops: self.drops.clone(), + })) + } +} + +struct MemoryReader { + chunks: VecDeque, + schema: Arc, + label_source: RawLabelSource, + polls: Arc, + drops: Arc, +} + +impl Stream for MemoryReader { + type Item = Result; + + fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll> { + let chunk = self.chunks.pop_front(); + if chunk.is_some() { + self.polls.fetch_add(1, Ordering::SeqCst); + } + Poll::Ready(chunk.map(Ok)) + } +} + +impl Drop for MemoryReader { + fn drop(&mut self) { + self.drops.fetch_add(1, Ordering::SeqCst); + } +} + +impl RawSeriesStream for MemoryReader { + fn schema(&self) -> &Arc { + &self.schema + } + + fn label_source(&self) -> &RawLabelSource { + &self.label_source + } + + fn ordering(&self) -> RawSeriesOrdering { + RawSeriesOrdering::Contiguous + } +} + +fn metric(host: &str) -> MetricName { + MetricName::try_new( + Some(Arc::from("cpu")), + vec![Label { + name: Arc::from("host"), + value: Arc::from(host), + }], + ) + .unwrap() +} + +fn schema() -> Arc { + Arc::new(SeriesSchema { + fields: vec![FieldSpec { + name: Arc::from("usage"), + }] + .into(), + eval_grid: None, + }) +} + +fn chunk( + key: &[u8], + metric: Option, + timestamp: i64, + value: f64, + last: bool, +) -> RawSeriesChunk { + RawSeriesChunk::try_new( + &schema(), + Buffer::from(key), + metric, + RawTimestamps::try_new(vec![timestamp].into()).unwrap(), + SeriesFields::one(Samples::from_float(Float64Array::from(vec![value]))), + last, + ) + .unwrap() +} + +fn primary_key_metadata() -> crate::metadata::RegionMetadata { + let mut builder = + crate::metadata::RegionMetadataBuilder::new(crate::storage::RegionId::new(1, 1)); + builder.push_column_metadata(crate::metadata::ColumnMetadata { + column_schema: ColumnSchema::new("host", ConcreteDataType::string_datatype(), false), + semantic_type: SemanticType::Tag, + column_id: 1, + }); + builder.push_column_metadata(crate::metadata::ColumnMetadata { + column_schema: ColumnSchema::new( + "ts", + ConcreteDataType::timestamp_millisecond_datatype(), + false, + ), + semantic_type: SemanticType::Timestamp, + column_id: 2, + }); + builder.primary_key(vec![1]); + builder.build().unwrap() +} + +fn empty_source() -> Arc { + Arc::new(MemorySource { + series: Arc::from([]), + schema: schema(), + label_source: RawLabelSource::Explicit, + polls: Arc::new(AtomicUsize::new(0)), + drops: Arc::new(AtomicUsize::new(0)), + }) +} + +fn source(explicit: bool) -> Arc { + source_from_keys( + explicit, + vec![ + Buffer::from(vec![0x10, 0x01]), + Buffer::from(vec![0x10, 0x02]), + ] + .into(), + ) +} + +fn source_from_keys(explicit: bool, keys: Arc<[Buffer]>) -> Arc { + assert_eq!(keys.len(), 2); + let first_metric = explicit.then(|| metric("a")); + let second_metric = explicit.then(|| metric("b")); + let series = vec![ + TestSeries { + info: SeriesInfo { + primary_key: keys[0].clone(), + metric: first_metric.clone(), + }, + chunks: vec![chunk(keys[0].as_slice(), first_metric, 10, 1.0, true)], + }, + TestSeries { + info: SeriesInfo { + primary_key: keys[1].clone(), + metric: second_metric.clone(), + }, + chunks: vec![ + chunk(keys[1].as_slice(), second_metric.clone(), 10, 2.0, false), + chunk(keys[1].as_slice(), second_metric, 20, 3.0, true), + ], + }, + ]; + Arc::new(MemorySource { + series: series.into(), + schema: schema(), + label_source: if explicit { + RawLabelSource::Explicit + } else { + RawLabelSource::PrimaryKey { + metric_name: Arc::from("cpu"), + physical_metadata: Arc::new(primary_key_metadata()), + logical_tags: Arc::from([]), + } + }, + polls: Arc::new(AtomicUsize::new(0)), + drops: Arc::new(AtomicUsize::new(0)), + }) +} + +#[tokio::test] +async fn prepared_identity_matches_chunks_in_both_label_modes_including_empty_reader() { + for explicit in [false, true] { + let source = source(explicit); + assert_eq!(source.num_series(), 2); + let first = source.series_info(0).unwrap(); + let second = source.series_info(1).unwrap(); + assert_eq!(first.primary_key, Buffer::from(vec![0x10, 0x01])); + assert_eq!(second.primary_key, Buffer::from(vec![0x10, 0x02])); + assert_eq!( + first.metric.as_ref().and_then(MetricName::name), + if explicit { Some("cpu") } else { None } + ); + assert_eq!( + first.metric.as_ref().and_then(|m| m.get("host")), + explicit.then_some("a") + ); + assert_eq!( + second.metric.as_ref().and_then(|m| m.get("host")), + explicit.then_some("b") + ); + + let empty = source.read_series(1..1).unwrap(); + assert_eq!(empty.schema().fields.len(), 1); + assert_eq!(empty.ordering(), RawSeriesOrdering::Contiguous); + assert_eq!( + matches!(empty.label_source(), RawLabelSource::Explicit), + explicit + ); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); + assert!( + futures::TryStreamExt::try_collect::>(empty) + .await + .unwrap() + .is_empty() + ); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); + let end = source.read_series(2..2).unwrap(); + assert_eq!(end.schema().fields.len(), 1); + assert_eq!( + matches!(end.label_source(), RawLabelSource::Explicit), + explicit + ); + + let chunks = + futures::TryStreamExt::try_collect::>(source.read_series(0..2).unwrap()) + .await + .unwrap(); + assert_eq!(chunks.len(), 3); + assert_eq!(source.polls.load(Ordering::SeqCst), 3); + assert_eq!(chunks[1].time.timestamp(0), Some(10)); + assert_eq!(chunks[2].time.timestamp(0), Some(20)); + assert!( + matches!(chunks[1].fields.get(0).unwrap().sample(0), datatypes::series::samples::SampleRef::Float(value) if value == 2.0) + ); + assert!( + matches!(chunks[2].fields.get(0).unwrap().sample(0), datatypes::series::samples::SampleRef::Float(value) if value == 3.0) + ); + for chunk in &chunks { + let ordinal = if chunk.primary_key == first.primary_key { + 0 + } else { + 1 + }; + let info = source.series_info(ordinal).unwrap(); + assert_eq!(chunk.primary_key, info.primary_key); + assert_eq!(chunk.metric, info.metric); + } + assert_eq!(chunks[0].metric.is_some(), explicit); + assert!(!chunks[1].is_last); + assert!(chunks[2].is_last); + } +} + +#[tokio::test] +async fn empty_prepared_source_supports_its_empty_range() { + let source = empty_source(); + assert_eq!(source.num_series(), 0); + let stream = source.read_series(0..0).unwrap(); + assert_eq!(stream.schema().fields.len(), 1); + assert!( + futures::TryStreamExt::try_collect::>(stream) + .await + .unwrap() + .is_empty() + ); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); +} + +#[test] +fn invalid_ordinals_and_ranges_fail_without_polling_samples() { + let source = source(false); + assert!(source.series_info(2).is_err()); + assert!(source.read_series(2..3).is_err()); + assert!(source.read_series(2..1).is_err()); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); +} + +#[tokio::test] +async fn overlapping_readers_are_independent_across_source_and_reader_drops() { + let source = source(false); + let drops = source.drops.clone(); + let mut left = source.read_series(0..2).unwrap(); + let mut right = source.read_series(1..2).unwrap(); + drop(source); + assert!(left.next().await.unwrap().unwrap().is_last); + assert_eq!( + right.next().await.unwrap().unwrap().primary_key, + Buffer::from(vec![0x10, 0x02]) + ); + drop(left); + assert_eq!( + futures::TryStreamExt::try_collect::>(right) + .await + .unwrap() + .len(), + 1 + ); + assert_eq!(drops.load(Ordering::SeqCst), 2); +} + +#[tokio::test] +async fn prepared_selection_is_independent_of_later_mutable_selection_changes() { + let selected = Arc::new(Mutex::new(vec![ + Buffer::from(vec![1_u8]), + Buffer::from(vec![2_u8]), + ])); + let prepared = source_from_keys(false, selected.lock().unwrap().clone().into()); + selected.lock().unwrap().push(Buffer::from(vec![3_u8])); + + assert_eq!(prepared.num_series(), 2); + assert_eq!( + prepared.series_info(0).unwrap().primary_key, + Buffer::from(vec![1_u8]) + ); + assert_eq!( + prepared.series_info(1).unwrap().primary_key, + Buffer::from(vec![2_u8]) + ); + let chunks = futures::TryStreamExt::try_collect::>(prepared.read_series(0..2).unwrap()) + .await + .unwrap(); + assert_eq!(chunks.len(), 3); + assert!( + chunks + .iter() + .all(|chunk| chunk.primary_key != Buffer::from(vec![3_u8])) + ); +} From 650ee58c226e827b21f9f75a3961f60e6102c5c8 Mon Sep 17 00:00:00 2001 From: discord9 <55937128+discord9@users.noreply.github.com> Date: Fri, 16 Oct 2026 15:45:42 +0800 Subject: [PATCH 3/4] feat(datatypes): share series ordering and expose source label binding Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com> --- src/datatypes/src/series.rs | 21 ++++ src/datatypes/src/series/raw.rs | 12 +-- src/store-api/src/region_engine.rs | 40 +++++--- .../region_engine/prepared_series_tests.rs | 97 +++++++++++++++---- 4 files changed, 129 insertions(+), 41 deletions(-) diff --git a/src/datatypes/src/series.rs b/src/datatypes/src/series.rs index ad3bf52aa52..860358eff20 100644 --- a/src/datatypes/src/series.rs +++ b/src/datatypes/src/series.rs @@ -24,6 +24,27 @@ use std::sync::Arc; use crate::error::{InvalidSeriesSnafu, Result}; +/// Ordering guarantee within one stream and each of its output partitions. +/// +/// 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: +/// 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. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum SeriesOrdering { + /// Series chunks may interleave; positions within each series remain strictly increasing. + Interleaved, + /// Each series is contiguous; distinct series need not be ordered. + Contiguous, + /// Series are ordered by stream identity and then by strictly increasing position. + KeyThenTime, +} + /// A label with shared UTF-8 name and value strings. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Label { diff --git a/src/datatypes/src/series/raw.rs b/src/datatypes/src/series/raw.rs index 9c18ae2941a..da4ba487204 100644 --- a/src/datatypes/src/series/raw.rs +++ b/src/datatypes/src/series/raw.rs @@ -85,17 +85,11 @@ impl RawTimestamps { } } -/// Ordering guarantee for chunks in one input stream. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub enum RawSeriesOrdering { - /// Each complete primary key's chunks are contiguous; distinct keys need not be ordered. - Contiguous, - /// Chunks are ordered by complete primary key and then by timestamp. - ReadKeyThenTime, -} - /// One raw source batch, with fields aligned to its timestamps. /// +/// `metric: None` means labels are not yet decoded because identity is bound by the source; it +/// does not mean the metric name is absent. An explicit `Some(metric)` is always complete. +/// /// Public fields allow direct access and construction, which bypasses the checks in /// [`RawSeriesChunk::try_new`]; callers crossing a trust boundary must validate input. #[derive(Clone, Debug)] diff --git a/src/store-api/src/region_engine.rs b/src/store-api/src/region_engine.rs index d9c4fa477f6..59a959c09f5 100644 --- a/src/store-api/src/region_engine.rs +++ b/src/store-api/src/region_engine.rs @@ -30,7 +30,8 @@ use common_time::Timestamp; use datafusion_physical_plan::metrics::ExecutionPlanMetricsSet; use datafusion_physical_plan::{DisplayAs, DisplayFormatType, PhysicalExpr}; use datatypes::schema::SchemaRef; -use datatypes::series::raw::{RawSeriesChunk, RawSeriesOrdering}; +use datatypes::series::SeriesOrdering; +use datatypes::series::raw::RawSeriesChunk; use datatypes::series::samples::SeriesSchema; use futures::Stream; use futures::future::join_all; @@ -492,27 +493,33 @@ pub enum RawLabelSource { /// Logical tag names mapped to physical column identifiers. logical_tags: Arc<[BoundTag]>, }, - /// The stream supplies a complete metric name and label set in each chunk. + /// The stream supplies a complete metric name and label set in each chunk, not a partial + /// label projection; `Some(metric)` is a complete name/label set (the name itself may be + /// absent). Explicit, } /// A stream of raw series chunks with stable schema, label binding, and ordering. /// -/// Chunks for a read key are contiguous, with strictly increasing timestamps within and across -/// chunks. `is_last` marks the last chunk of that key in this stream, not across streams; merge -/// code must recompute finalization globally across all relevant inputs before downstream -/// per-input-series finalization (not aggregate or vector-match state). `RawLabelSource` keeps -/// the stream's label interpretation self-contained through transport rather than relying on a -/// local source handle. +/// Every series has strictly increasing timestamps within and across chunks; timestamps are +/// unique per series. `Interleaved` permits a series to resume after another series; `Contiguous` +/// and `KeyThenTime` guarantee each series' chunks are contiguous. `KeyThenTime` uses the complete +/// stream identity compatible with its label binding, not just a TSID or hash. These are +/// per-stream guarantees, not query-global order, partition ownership, or finality. `is_last` +/// marks the last chunk of that series in this stream only; merging requires recomputing +/// per-input-series finalization across all related inputs, not aggregate-group finality. +/// `RawLabelSource` keeps label interpretation self-contained through transport. Stream finality +/// applies to all related input series, not aggregate groups or vector-match state. pub trait RawSeriesStream: Stream> + Send { /// Returns the schema shared by all chunks; raw schemas have no evaluation grid. fn schema(&self) -> &Arc; /// Returns scan-bound label metadata. `PrimaryKey` chunks leave `metric` as `None`, meaning /// labels are undecoded, not that the metric name is missing; `Explicit` chunks supply - /// `Some` with a complete metric name and labels. + /// `Some` with the complete name/label set, not a partial projection. The metric name itself + /// may be absent. fn label_source(&self) -> &RawLabelSource; /// Returns this stream's ordering guarantee. - fn ordering(&self) -> RawSeriesOrdering; + fn ordering(&self) -> SeriesOrdering; } /// A pinned raw-series stream that can be sent between threads. @@ -523,7 +530,8 @@ pub type SendableRawSeriesStream = Pin>; pub struct SeriesInfo { /// Complete encoded primary key, not a TSID or hash alone. pub primary_key: datatypes::arrow::buffer::Buffer, - /// Complete explicit metric and labels, or `None` for primary-key label binding. + /// Complete explicit metric name and labels, not a partial label projection; or `None` for + /// primary-key label binding (undecoded, not nameless). The metric name itself may be absent. pub metric: Option, } @@ -533,9 +541,9 @@ pub struct SeriesInfo { /// indexes, not protocol identifiers; each has exactly one complete identity returned by /// [`PreparedSeriesSource::series_info`], and that identity matches chunks for that ordinal. /// Every reader exposes the same fixed schema, label binding, and ordering before polling, -/// including for an empty range, and describes labels independently of this source's lifetime. `PrimaryKey` output has `metric: None`; `Explicit` output has a -/// complete `Some(metric)` matching each chunk. [`RawSeriesOrdering::Contiguous`] and -/// [`RawSeriesOrdering::ReadKeyThenTime`] describe stream order, not ordinal enumeration order. +/// including for an empty range, and describes labels independently of this source's lifetime. +/// `PrimaryKey` output has `metric: None` (undecoded); `Explicit` output has a complete +/// `Some(metric)` matching each chunk. Ordering describes the stream, not ordinal enumeration. /// /// Preparation, identity lookup, and reader creation do not load sample payloads or perform /// hidden blocking I/O. The selected set is bound to the partition's immutable MVCC view, @@ -550,6 +558,10 @@ pub trait PreparedSeriesSource: Send + Sync { /// Returns the exact, stable number of selected local series ordinals. fn num_series(&self) -> usize; + /// Returns label binding shared by series metadata and every reader, without opening or + /// polling a reader; the binding is self-contained for remote consumers. + fn label_source(&self) -> &RawLabelSource; + /// Returns identity metadata for an ordinal without polling sample data. fn series_info(&self, ordinal: usize) -> Result; diff --git a/src/store-api/src/region_engine/prepared_series_tests.rs b/src/store-api/src/region_engine/prepared_series_tests.rs index 05882ddcc70..a489598b567 100644 --- a/src/store-api/src/region_engine/prepared_series_tests.rs +++ b/src/store-api/src/region_engine/prepared_series_tests.rs @@ -25,7 +25,8 @@ use datatypes::arrow::buffer::Buffer; use datatypes::error::InvalidSeriesSnafu; use datatypes::prelude::ConcreteDataType; use datatypes::schema::ColumnSchema; -use datatypes::series::raw::{RawSeriesChunk, RawSeriesOrdering, RawTimestamps}; +use datatypes::series::SeriesOrdering; +use datatypes::series::raw::{RawSeriesChunk, RawTimestamps}; use datatypes::series::samples::{FieldSpec, Samples, SeriesFields, SeriesSchema}; use datatypes::series::{Label, MetricName}; use futures::{Stream, StreamExt}; @@ -53,6 +54,10 @@ impl PreparedSeriesSource for MemorySource { self.series.len() } + fn label_source(&self) -> &RawLabelSource { + &self.label_source + } + fn series_info(&self, ordinal: usize) -> Result { self.series .get(ordinal) @@ -128,8 +133,8 @@ impl RawSeriesStream for MemoryReader { &self.label_source } - fn ordering(&self) -> RawSeriesOrdering { - RawSeriesOrdering::Contiguous + fn ordering(&self) -> SeriesOrdering { + SeriesOrdering::Contiguous } } @@ -144,6 +149,33 @@ fn metric(host: &str) -> MetricName { .unwrap() } +fn assert_same_label_source(expected: &RawLabelSource, actual: &RawLabelSource) { + match (expected, actual) { + (RawLabelSource::Explicit, RawLabelSource::Explicit) => {} + ( + RawLabelSource::PrimaryKey { + metric_name: expected_name, + physical_metadata: expected_metadata, + logical_tags: expected_tags, + }, + RawLabelSource::PrimaryKey { + metric_name: actual_name, + physical_metadata: actual_metadata, + logical_tags: actual_tags, + }, + ) => { + assert_eq!(expected_name, actual_name); + assert!(Arc::ptr_eq(expected_metadata, actual_metadata)); + assert_eq!(expected_tags.len(), actual_tags.len()); + for (expected, actual) in expected_tags.iter().zip(actual_tags.iter()) { + assert_eq!(expected.name, actual.name); + assert_eq!(expected.column_id, actual.column_id); + } + } + _ => panic!("label source differs"), + } +} + fn schema() -> Arc { Arc::new(SeriesSchema { fields: vec![FieldSpec { @@ -246,7 +278,11 @@ fn source_from_keys(explicit: bool, keys: Arc<[Buffer]>) -> Arc { RawLabelSource::PrimaryKey { metric_name: Arc::from("cpu"), physical_metadata: Arc::new(primary_key_metadata()), - logical_tags: Arc::from([]), + logical_tags: vec![crate::region_engine::BoundTag { + column_id: 1, + name: Arc::from("host"), + }] + .into(), } }, polls: Arc::new(AtomicUsize::new(0)), @@ -255,10 +291,36 @@ fn source_from_keys(explicit: bool, keys: Arc<[Buffer]>) -> Arc { } #[tokio::test] -async fn prepared_identity_matches_chunks_in_both_label_modes_including_empty_reader() { +async fn prepared_source_label_binding_is_available_before_readers_and_matches_chunks() { for explicit in [false, true] { let source = source(explicit); assert_eq!(source.num_series(), 2); + match (explicit, source.label_source()) { + (true, RawLabelSource::Explicit) => {} + ( + false, + RawLabelSource::PrimaryKey { + metric_name, + physical_metadata, + logical_tags, + }, + ) => { + assert_eq!(metric_name.as_ref(), "cpu"); + assert_eq!( + physical_metadata + .column_by_id(1) + .unwrap() + .column_schema + .name, + "host" + ); + assert_eq!(logical_tags.len(), 1); + assert_eq!(logical_tags[0].column_id, 1); + assert_eq!(logical_tags[0].name.as_ref(), "host"); + } + _ => panic!("unexpected source label binding"), + } + assert_eq!(source.polls.load(Ordering::SeqCst), 0); let first = source.series_info(0).unwrap(); let second = source.series_info(1).unwrap(); assert_eq!(first.primary_key, Buffer::from(vec![0x10, 0x01])); @@ -278,11 +340,8 @@ async fn prepared_identity_matches_chunks_in_both_label_modes_including_empty_re let empty = source.read_series(1..1).unwrap(); assert_eq!(empty.schema().fields.len(), 1); - assert_eq!(empty.ordering(), RawSeriesOrdering::Contiguous); - assert_eq!( - matches!(empty.label_source(), RawLabelSource::Explicit), - explicit - ); + assert_eq!(empty.ordering(), SeriesOrdering::Contiguous); + assert_same_label_source(source.label_source(), empty.label_source()); assert_eq!(source.polls.load(Ordering::SeqCst), 0); assert!( futures::TryStreamExt::try_collect::>(empty) @@ -293,15 +352,16 @@ async fn prepared_identity_matches_chunks_in_both_label_modes_including_empty_re assert_eq!(source.polls.load(Ordering::SeqCst), 0); let end = source.read_series(2..2).unwrap(); assert_eq!(end.schema().fields.len(), 1); - assert_eq!( - matches!(end.label_source(), RawLabelSource::Explicit), - explicit - ); + assert_eq!(end.ordering(), SeriesOrdering::Contiguous); + assert_same_label_source(source.label_source(), end.label_source()); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); - let chunks = - futures::TryStreamExt::try_collect::>(source.read_series(0..2).unwrap()) - .await - .unwrap(); + let reader = source.read_series(0..2).unwrap(); + assert_same_label_source(source.label_source(), reader.label_source()); + assert_eq!(source.polls.load(Ordering::SeqCst), 0); + let chunks = futures::TryStreamExt::try_collect::>(reader) + .await + .unwrap(); assert_eq!(chunks.len(), 3); assert_eq!(source.polls.load(Ordering::SeqCst), 3); assert_eq!(chunks[1].time.timestamp(0), Some(10)); @@ -331,6 +391,7 @@ async fn prepared_identity_matches_chunks_in_both_label_modes_including_empty_re #[tokio::test] async fn empty_prepared_source_supports_its_empty_range() { let source = empty_source(); + assert!(matches!(source.label_source(), RawLabelSource::Explicit)); assert_eq!(source.num_series(), 0); let stream = source.read_series(0..0).unwrap(); assert_eq!(stream.schema().fields.len(), 1); From 3406a5334574a518924c67c319e2d92b6cac943b Mon Sep 17 00:00:00 2001 From: discord9 <55937128+discord9@users.noreply.github.com> Date: Fri, 16 Oct 2026 16:32:50 +0800 Subject: [PATCH 4/4] perf(datatypes): encode bounded multirow series frames Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com> --- src/datatypes/src/series/frame.rs | 964 ++++++++++++++++++------ src/datatypes/src/series/frame/tests.rs | 882 ++++++++++++++++++++-- src/datatypes/src/series/samples.rs | 12 +- 3 files changed, 1544 insertions(+), 314 deletions(-) diff --git a/src/datatypes/src/series/frame.rs b/src/datatypes/src/series/frame.rs index d9f9c1ee347..27902ecf805 100644 --- a/src/datatypes/src/series/frame.rs +++ b/src/datatypes/src/series/frame.rs @@ -13,6 +13,12 @@ // limitations under the License. //! Finite Arrow batches for raw series chunks. Field names preserve the logical series schema in order. +//! +//! Packing accumulates bounded multi-row batches: [`RawSeriesChunkCursor`] walks one validated +//! chunk and [`RawSeriesFrameBuilder`] emits rows directly as Arrow arrays once a row or estimated +//! byte bound is reached. Decoding reuses one prepared schema per stream through +//! [`RawSeriesFrameDecoder`]. Column layout, metadata, and wire strings stay on the frozen `v1` +//! contract. #[cfg(test)] mod tests; @@ -24,12 +30,13 @@ use arrow::array::{ StructArray, UInt32Array, }; use arrow::buffer::{Buffer, NullBuffer, OffsetBuffer, ScalarBuffer}; +use arrow::compute::concat; use arrow::datatypes::{DataType, Field, Fields, Schema, SchemaRef}; use arrow::record_batch::{RecordBatch, RecordBatchOptions}; use crate::error::{InvalidSeriesSnafu, Result}; use crate::series::histogram::{HistogramBatch, fields as histogram_fields}; -use crate::series::raw::{RawSeriesChunk, RawTimeAxis}; +use crate::series::raw::{RawSeriesChunk, RawTimestamps}; use crate::series::samples::{ DenseSamplesRef, HistogramSamples, Samples, SeriesFields, SeriesSchema, }; @@ -130,66 +137,714 @@ pub fn raw_series_frame_schema(schema: &SeriesSchema, mode: RawLabelMode) -> Res Ok(Arc::new(Schema::new_with_metadata(columns, metadata))) } -/// Packs one raw chunk into one-row batches at the union of field segment boundaries. +/// Bounded multi-row builder for finite raw frame batches. +/// +/// Rows accumulate until the row limit or the estimated byte limit is reached; the next +/// [`RawSeriesChunkCursor::append_to`] call then emits them as one batch. `max_bytes` is stored as +/// the effective group cap `min(requested, i32::MAX)`, and each row carries a measure that +/// dominates every cumulative Arrow offset domain, so any admitted group can be encoded. The +/// measure is an internal work estimate, not an exact IPC size and not a resident-memory cap: one +/// individually representable row that exceeds the requested cap is still accepted and emitted +/// alone, because that slice cannot be split into smaller legal rows. +pub struct RawSeriesFrameBuilder { + schema: SeriesSchema, + frame_schema: SchemaRef, + mode: RawLabelMode, + max_rows: usize, + max_bytes: usize, + rows: Vec, + bytes: usize, +} + +impl RawSeriesFrameBuilder { + /// Default maximum rows in one packed batch when no explicit bound is needed. + pub const DEFAULT_MAX_ROWS: usize = 256; + /// Default maximum estimated encoded bytes in one packed batch when no explicit bound is + /// needed. + pub const DEFAULT_MAX_BYTES: usize = 1024 * 1024; + + /// Creates an empty builder for the given schema, label mode, and nonzero bounds. + /// + /// The frame schema is built once here and reused for every emitted batch. + pub fn try_new( + schema: &SeriesSchema, + mode: RawLabelMode, + max_rows: usize, + max_bytes: usize, + ) -> Result { + if max_rows == 0 || max_bytes == 0 { + return invalid_series("raw series frame limits must be nonzero"); + } + Ok(Self { + schema: schema.clone(), + frame_schema: raw_series_frame_schema(schema, mode)?, + mode, + max_rows, + max_bytes: max_bytes.min(i32::MAX as usize), + rows: Vec::new(), + bytes: 0, + }) + } + + /// The frame schema of every batch this builder emits. + pub fn schema(&self) -> &SchemaRef { + &self.frame_schema + } + + /// Emits the accumulated rows as one batch, or `None` when nothing is buffered. + pub fn flush(&mut self) -> Result> { + if self.rows.is_empty() { + return Ok(None); + } + let batch = encode_rows(&self.frame_schema, self.mode, &self.rows)?; + self.rows.clear(); + self.bytes = 0; + Ok(Some(batch)) + } + + /// Whether the buffered rows reached either bound. + fn is_full(&self) -> bool { + self.rows.len() >= self.max_rows || self.bytes >= self.max_bytes + } + + /// Whether `row` may join the buffered rows without crossing either bound. + /// + /// An empty builder accepts any individually measured row; a group total that would overflow + /// or exceed the cap flushes the buffered rows before this row is consumed, never dropping or + /// splitting the row. + fn accepts(&self, row: &RawFrameRow) -> bool { + self.rows.is_empty() + || (self.bytes < self.max_bytes + && self.rows.len() < self.max_rows + && self + .bytes + .checked_add(row.bytes) + .is_some_and(|total| total <= self.max_bytes)) + } + + /// Buffers one individually measured row. + fn push(&mut self, row: RawFrameRow) -> Result<()> { + self.bytes = add_checked(self.bytes, row.bytes)?; + self.rows.push(row); + Ok(()) + } +} + +/// One validated chunk walked segment by segment into a bounded builder. +pub struct RawSeriesChunkCursor { + schema: SeriesSchema, + mode: RawLabelMode, + chunk: RawSeriesChunk, + segments: Vec, + offsets: Vec, + pos: usize, + pending: Option, +} + +impl RawSeriesChunkCursor { + /// Validates one public chunk's shape and label mode once, taking ownership of it. + pub fn try_new( + schema: &SeriesSchema, + mode: RawLabelMode, + chunk: RawSeriesChunk, + ) -> Result { + let RawSeriesChunk { + primary_key, + metric, + time, + fields, + is_last, + } = chunk; + let chunk = RawSeriesChunk::try_new(schema, primary_key, metric, time, fields, is_last)?; + match (mode, &chunk.metric) { + (RawLabelMode::Key, None) | (RawLabelMode::Explicit, Some(_)) => {} + _ => return invalid_series("raw chunk label mode does not match frame mode"), + } + let segments = vec![0usize; chunk.fields.len()]; + let offsets = vec![0usize; chunk.fields.len()]; + Ok(Self { + schema: schema.clone(), + mode, + chunk, + segments, + offsets, + pos: 0, + pending: None, + }) + } + + /// Appends rows to the builder until one batch is ready or this chunk is exhausted. + /// + /// `None` means the cursor is exhausted; calling again returns `None` without touching the + /// builder. The single pending row is measured once by [`Self::next_row`] and retried after the + /// buffered rows are emitted. + pub fn append_to( + &mut self, + builder: &mut RawSeriesFrameBuilder, + ) -> Result> { + self.compatible(builder)?; + loop { + let row = match self.pending.take() { + Some(row) => row, + None => match self.next_row()? { + Some(row) => { + self.pending = Some(row); + continue; + } + None => return Ok(None), + }, + }; + if !builder.accepts(&row) { + // Reinstate the row before flushing so a flush error cannot consume it. + self.pending = Some(row); + let batch = builder + .flush()? + .ok_or_else(|| err("raw frame builder rejected a row without buffered rows"))?; + return Ok(Some(batch)); + } + builder.push(row)?; + if builder.is_full() { + if let Some(batch) = builder.flush()? { + return Ok(Some(batch)); + } + } + } + } + + /// The cursor and builder must describe the same fields and label mode. + fn compatible(&self, builder: &RawSeriesFrameBuilder) -> Result<()> { + let same_fields = self.schema.fields.len() == builder.schema.fields.len() + && self + .schema + .fields + .iter() + .zip(builder.schema.fields.iter()) + .all(|(left, right)| left.name == right.name); + if self.mode != builder.mode + || self.schema.eval_grid.is_some() != builder.schema.eval_grid.is_some() + || !same_fields + { + return invalid_series("raw frame cursor and builder schema mismatch"); + } + Ok(()) + } + + /// Builds and measures the next union-of-segment row, or `None` when the chunk is exhausted. + /// + /// The chunk fields are walked three times so no per-row temporary vectors are allocated; the + /// offsets advance only after the row measure succeeded. + fn next_row(&mut self) -> Result> { + if self.pos >= self.chunk.time.len() { + return Ok(None); + } + let time_axis = self.chunk.time.as_buffer(); + let mut take = time_axis.len() - self.pos; + for (index, field) in self.chunk.fields.iter().enumerate() { + let part = segment(field, self.segments[index])?; + take = take.min(part.len().saturating_sub(self.offsets[index])); + } + if take == 0 { + return invalid_series("empty sample segment"); + } + let mut samples = Vec::with_capacity(self.chunk.fields.len()); + for (index, field) in self.chunk.fields.iter().enumerate() { + let part = segment(field, self.segments[index])?; + samples.push(part.slice(self.offsets[index], take)?); + } + let mut row = RawFrameRow { + primary_key: self.chunk.primary_key.clone(), + metric: self.chunk.metric.clone(), + is_last: self.chunk.is_last && self.pos + take == self.chunk.time.len(), + times: time_axis.slice(self.pos, take), + samples, + bytes: 0, + }; + row.bytes = measure_row(&row)?; + self.pos += take; + for (index, field) in self.chunk.fields.iter().enumerate() { + let length = segment(field, self.segments[index])?.len(); + self.offsets[index] += take; + if self.offsets[index] == length { + self.segments[index] += 1; + self.offsets[index] = 0; + } + } + Ok(Some(row)) + } +} + +/// The next dense segment of one field, or an error when the walk left the segment list. +fn segment(field: &Samples, index: usize) -> Result<&Samples> { + field + .segments() + .get(index) + .ok_or_else(|| err("empty sample segment")) +} + +/// Packs one raw chunk, retaining the `Vec` compatibility signature. +/// +/// The chunk packs into bounded multi-row batches; callers that need streaming behavior should +/// drive [`RawSeriesChunkCursor`] and [`RawSeriesFrameBuilder`] directly instead of collecting. pub fn pack_raw_series_chunk( schema: &SeriesSchema, mode: RawLabelMode, chunk: &RawSeriesChunk, ) -> Result> { - let checked = RawSeriesChunk::try_new( + let mut builder = RawSeriesFrameBuilder::try_new( schema, - chunk.read_key.clone(), - chunk.metric.clone(), - chunk.time.clone(), - chunk.fields.clone(), - chunk.is_last, + mode, + RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, )?; - match (mode, &checked.metric) { - (RawLabelMode::Key, None) | (RawLabelMode::Explicit, Some(_)) => {} - _ => return invalid_series("raw chunk label mode does not match frame mode"), - } - let frame_schema = raw_series_frame_schema(schema, mode)?; - let RawTimeAxis::Explicit(times) = &checked.time; - let all: Vec<&[Samples]> = checked.fields.iter().map(Samples::segments).collect(); - let mut segment = vec![0usize; all.len()]; - let mut offset = vec![0usize; all.len()]; - let mut pos = 0usize; + let mut cursor = RawSeriesChunkCursor::try_new(schema, mode, chunk.clone())?; let mut batches = Vec::new(); - while pos < times.len() { - let take = all - .iter() - .enumerate() - .map(|(i, parts)| parts[segment[i]].len() - offset[i]) - .min() - .unwrap_or(times.len()) - .min(times.len() - pos); - if take == 0 { - return invalid_series("empty sample segment"); - } - let pieces = all - .iter() - .enumerate() - .map(|(i, parts)| parts[segment[i]].slice(offset[i], take)) - .collect::>>()?; - batches.push(encode_row( - &frame_schema, - mode, - &checked.read_key, - checked.metric.as_ref(), - checked.is_last && pos + take == times.len(), - times.slice(pos, take), - &pieces, - )?); - pos += take; - for (i, parts) in all.iter().enumerate() { - offset[i] += take; - if offset[i] == parts[segment[i]].len() { - segment[i] += 1; - offset[i] = 0; + while let Some(batch) = cursor.append_to(&mut builder)? { + batches.push(batch); + } + if let Some(batch) = builder.flush()? { + batches.push(batch); + } + Ok(batches) +} + +/// One pending output row: a complete key with one dense sample slice per field and its checked +/// encoded-size measure. +struct RawFrameRow { + primary_key: Buffer, + metric: Option, + is_last: bool, + times: ScalarBuffer, + samples: Vec, + bytes: usize, +} + +/// Per-row encoded-size measure, computed once per row when the cursor produces it. +/// +/// The measure dominates every cumulative offset domain the encoder writes: binary/UTF-8 child +/// bytes, list element counts, bitmap bytes, and the visible extent of each histogram table list. +/// A group total of `min(max_bytes, i32::MAX)` therefore guarantees that all Arrow offsets and +/// lengths stay representable, without tracking a separate offset counter. This is a bound used +/// for batching work, not the exact encoded size. +fn measure_row(row: &RawFrameRow) -> Result { + checked_offset(row.primary_key.len())?; + checked_offset(row.times.len())?; + let mut bytes = add_checked(ROW_CHARGE, row.primary_key.len())?; + bytes = add_checked(bytes, mul_checked(row.times.len(), 8)?)?; + for samples in &row.samples { + bytes = add_checked(bytes, FIELD_CHARGE)?; + match samples + .dense() + .ok_or_else(|| err("sample segment is not dense"))? + { + DenseSamplesRef::Float(values) => { + bytes = add_checked(bytes, float_charge(values.len())?)? + } + DenseSamplesRef::Histogram(values) => { + bytes = add_checked(bytes, histogram_charge(values)?)? + } + DenseSamplesRef::Mixed(values) => { + bytes = add_checked(bytes, float_charge(values.floats().len())?)?; + bytes = add_checked(bytes, histogram_charge(values.histograms())?)?; } } } - Ok(batches) + if let Some(metric) = &row.metric { + if let Some(name) = metric.name() { + checked_offset(name.len())?; + bytes = add_checked(bytes, name.len())?; + } + checked_offset(metric.tags().len())?; + bytes = add_checked(bytes, mul_checked(metric.tags().len(), 16)?)?; + let mut names = 0usize; + let mut values = 0usize; + for label in metric.tags() { + names = add_checked(names, label.name.len())?; + values = add_checked(values, label.value.len())?; + } + checked_offset(names)?; + checked_offset(values)?; + bytes = add_checked(bytes, names)?; + bytes = add_checked(bytes, values)?; + } + Ok(bytes) +} + +/// Float values plus their validity bitmap. +fn float_charge(len: usize) -> Result { + checked_offset(len)?; + add_checked(mul_checked(len, 8)?, bitmap_bytes(len)) +} + +/// Reference indices plus their bitmap and the full referenced histogram table. +fn histogram_charge(values: &HistogramSamples) -> Result { + let indices = values.indices(); + checked_offset(indices.len())?; + let mut bytes = add_checked(mul_checked(indices.len(), 4)?, bitmap_bytes(indices.len()))?; + let table = values.batch().as_arrow(); + checked_offset(table.len())?; + bytes = add_checked( + bytes, + add_checked( + HISTOGRAM_TABLE_CHARGE, + mul_checked(table.len(), HISTOGRAM_ROW_CHARGE)?, + )?, + )?; + for (position, width) in HISTOGRAM_LIST_WIDTHS.iter().enumerate() { + let list = table + .column(7 + position) + .as_any() + .downcast_ref::() + .ok_or_else(|| err("histogram table schema mismatch"))?; + // `value_offsets` is already a view of the visible slice; the retained child array may be + // wider than the offsets span, so charge the visible extent rather than its length. + let offsets = list.value_offsets(); + let first = offsets + .first() + .copied() + .ok_or_else(|| err("histogram table schema mismatch"))?; + let last = offsets + .get(list.len()) + .copied() + .ok_or_else(|| err("histogram table schema mismatch"))?; + let span = last + .checked_sub(first) + .and_then(|span| usize::try_from(span).ok()) + .ok_or_else(|| err("histogram table offsets are invalid"))?; + bytes = add_checked(bytes, mul_checked(span, *width)?)?; + } + Ok(bytes) +} + +/// Encodes buffered rows as one batch with direct N-row Arrow array construction. +/// +/// Row-local histogram indices stay exactly as encoded: physical tables are concatenated under +/// cumulative row list offsets, so no index is remapped. Each histogram-bearing row carries its +/// complete table, including unreferenced entries; many segments referencing one large table can +/// therefore repeat that table in the encoded batch. A single constituent child array is reused +/// by clone (sharing its buffers); multiple constituents are concatenated, which copies. +fn encode_rows( + schema: &SchemaRef, + mode: RawLabelMode, + rows: &[RawFrameRow], +) -> Result { + let count = rows.len(); + let DataType::Struct(time_fields) = schema.field(2).data_type() else { + return invalid_series("time schema mismatch"); + }; + let DataType::List(time_item) = time_fields[0].data_type() else { + return invalid_series("time schema mismatch"); + }; + let DataType::Struct(field_types) = schema.field(3).data_type() else { + return invalid_series("fields schema mismatch"); + }; + let mut time_lengths = Vec::with_capacity(count); + let mut time_parts: Vec = Vec::with_capacity(count); + for row in rows { + time_lengths.push(row.times.len()); + time_parts.push(Arc::new(Int64Array::new(row.times.clone(), None))); + } + let time_child = materialize_parts(&time_parts, || { + Ok(Arc::new(Int64Array::new_null(0)) as ArrayRef) + })?; + let times = list_array(&time_lengths, time_child, time_item.as_ref().clone(), None)?; + let time = struct_array(time_fields.clone(), vec![Arc::new(times)])?; + + let mut empty_table: Option = None; + let mut field_arrays = Vec::with_capacity(field_types.len()); + for (index, field) in field_types.iter().enumerate() { + let DataType::Struct(payload) = field.data_type() else { + return invalid_series("payload schema mismatch"); + }; + let DataType::List(float_item) = payload[0].data_type() else { + return invalid_series("float values schema mismatch"); + }; + let DataType::Struct(histogram_fields) = payload[1].data_type() else { + return invalid_series("histogram schema mismatch"); + }; + let DataType::List(index_item) = histogram_fields[0].data_type() else { + return invalid_series("histogram index schema mismatch"); + }; + let DataType::List(table_item) = histogram_fields[1].data_type() else { + return invalid_series("histogram table schema mismatch"); + }; + let DataType::Struct(table_fields) = table_item.data_type() else { + return invalid_series("histogram table schema mismatch"); + }; + let mut float_lengths = Vec::with_capacity(count); + let mut float_parts: Vec = Vec::new(); + let mut float_valid = Vec::with_capacity(count); + let mut index_lengths = Vec::with_capacity(count); + let mut index_parts: Vec = Vec::new(); + let mut table_lengths = Vec::with_capacity(count); + let mut table_parts: Vec = Vec::new(); + let mut histogram_valid = Vec::with_capacity(count); + for row in rows { + let dense = row + .samples + .get(index) + .ok_or_else(|| err("raw frame row field count mismatch"))? + .dense() + .ok_or_else(|| err("sample segment is not dense"))?; + match dense { + DenseSamplesRef::Float(values) => { + float_lengths.push(values.len()); + float_parts.push(Arc::new(values.clone())); + float_valid.push(true); + index_lengths.push(0); + table_lengths.push(0); + histogram_valid.push(false); + } + DenseSamplesRef::Histogram(values) => { + float_lengths.push(0); + float_valid.push(false); + index_lengths.push(values.len()); + index_parts.push(Arc::new(values.indices().clone())); + table_lengths.push(values.batch().len()); + table_parts.push(Arc::new(values.batch().as_arrow().clone())); + histogram_valid.push(true); + } + DenseSamplesRef::Mixed(values) => { + float_lengths.push(values.floats().len()); + float_parts.push(Arc::new(values.floats().clone())); + float_valid.push(true); + index_lengths.push(values.histograms().len()); + index_parts.push(Arc::new(values.histograms().indices().clone())); + table_lengths.push(values.histograms().batch().len()); + table_parts.push(Arc::new(values.histograms().batch().as_arrow().clone())); + histogram_valid.push(true); + } + } + } + let float_child = materialize_parts(&float_parts, || { + Ok(Arc::new(Float64Array::new_null(0)) as ArrayRef) + })?; + let floats = list_array( + &float_lengths, + float_child, + float_item.as_ref().clone(), + validity(&float_valid), + )?; + let index_child = materialize_parts(&index_parts, || { + Ok(Arc::new(UInt32Array::new_null(0)) as ArrayRef) + })?; + let indices = list_array( + &index_lengths, + index_child, + index_item.as_ref().clone(), + None, + )?; + // A batch without histogram tables shares one empty schema-typed table, built once here + // instead of per float-only row. + let table_child = if table_parts.is_empty() { + match &empty_table { + Some(table) => table.clone(), + None => { + let table = empty_histogram_table(table_fields)?; + empty_table = Some(table.clone()); + table + } + } + } else { + materialize_parts(&table_parts, || Err(err("missing histogram table values")))? + }; + let tables = list_array( + &table_lengths, + table_child, + table_item.as_ref().clone(), + None, + )?; + let histogram = arrow(StructArray::try_new( + histogram_fields.clone(), + vec![Arc::new(indices), Arc::new(tables)], + validity(&histogram_valid), + ))?; + field_arrays.push(Arc::new(struct_array( + payload.clone(), + vec![Arc::new(floats), Arc::new(histogram)], + )?) as ArrayRef); + } + let fields = struct_array(field_types.clone(), field_arrays)?; + + let mut columns: Vec = vec![ + Arc::new(binary_array(rows)?), + Arc::new(BooleanArray::from( + rows.iter().map(|row| row.is_last).collect::>(), + )), + Arc::new(time), + Arc::new(fields), + ]; + if mode == RawLabelMode::Explicit { + columns.push(Arc::new( + rows.iter() + .map(|row| row.metric.as_ref().and_then(MetricName::name)) + .collect::(), + )); + let DataType::List(label_item) = schema.field(5).data_type() else { + return invalid_series("labels schema mismatch"); + }; + let DataType::Struct(label_fields) = label_item.data_type() else { + return invalid_series("labels schema mismatch"); + }; + let mut label_lengths = Vec::with_capacity(count); + let mut tag_names: Vec<&str> = Vec::new(); + let mut tag_values: Vec<&str> = Vec::new(); + for row in rows { + let metric = row + .metric + .as_ref() + .ok_or_else(|| err("explicit labels missing"))?; + label_lengths.push(metric.tags().len()); + for label in metric.tags() { + tag_names.push(label.name.as_ref()); + tag_values.push(label.value.as_ref()); + } + } + let labels = struct_array( + label_fields.clone(), + vec![ + Arc::new(StringArray::from_iter_values(tag_names)), + Arc::new(StringArray::from_iter_values(tag_values)), + ], + )?; + columns.push(Arc::new(list_array( + &label_lengths, + Arc::new(labels), + label_item.as_ref().clone(), + None, + )?)); + } + + arrow(RecordBatch::try_new_with_options( + schema.clone(), + columns, + &RecordBatchOptions::new().with_row_count(Some(count)), + )) +} + +/// Row-level binary keys; keys are copied exactly like the previous single-row encoder. +fn binary_array(rows: &[RawFrameRow]) -> Result { + let mut offsets = Vec::with_capacity(rows.len() + 1); + let mut total = 0usize; + offsets.push(0); + for row in rows { + total = add_checked(total, row.primary_key.len())?; + offsets.push(checked_offset(total)?); + } + let mut values = Vec::with_capacity(total); + for row in rows { + values.extend_from_slice(row.primary_key.as_slice()); + } + arrow(BinaryArray::try_new( + OffsetBuffer::new(ScalarBuffer::from(offsets)), + Buffer::from_vec(values), + None, + )) +} + +/// Per-row charge for key/time/nullable overhead shared by every row. +const ROW_CHARGE: usize = 64; +/// Per-field charge for the payload struct, nested list and validity overhead. +const FIELD_CHARGE: usize = 64; +/// Conservative per-table-row charge: the fixed fourteen-column histogram schema has seven +/// primitive columns plus seven list columns whose item widths are [`HISTOGRAM_LIST_WIDTHS`]. +const HISTOGRAM_ROW_CHARGE: usize = 128; +/// Fixed per-histogram charge for the seven list columns' offset and validity overhead. +const HISTOGRAM_TABLE_CHARGE: usize = 28; +/// Item widths of histogram table list columns `7..=13`, in that order. +const HISTOGRAM_LIST_WIDTHS: [usize; 7] = [8, 4, 4, 8, 4, 4, 8]; + +fn list_array( + lengths: &[usize], + values: ArrayRef, + item: Field, + nulls: Option, +) -> Result { + arrow(ListArray::try_new( + Arc::new(item), + offset_buffer(lengths)?, + values, + nulls, + )) +} + +fn offset_buffer(lengths: &[usize]) -> Result> { + let mut offsets = Vec::with_capacity(lengths.len() + 1); + let mut total = 0usize; + offsets.push(0); + for length in lengths { + total = add_checked(total, *length)?; + offsets.push(checked_offset(total)?); + } + Ok(OffsetBuffer::new(ScalarBuffer::from(offsets))) +} + +/// Materializes one list child: a single constituent is cloned to keep its buffers shared. +fn materialize_parts( + parts: &[ArrayRef], + empty: impl FnOnce() -> Result, +) -> Result { + match parts { + [] => empty(), + [only] => Ok(only.clone()), + _ => arrow(concat( + &parts.iter().map(|array| &**array).collect::>(), + )), + } +} + +fn empty_histogram_table(fields: &Fields) -> Result { + let columns = fields + .iter() + .map(|field| arrow::array::new_null_array(field.data_type(), 0)) + .collect(); + arrow(StructArray::try_new(fields.clone(), columns, None)) + .map(|table| Arc::new(table) as ArrayRef) +} + +fn validity(valid: &[bool]) -> Option { + if valid.iter().all(|valid| *valid) { + None + } else { + Some(NullBuffer::from(valid.to_vec())) + } +} + +fn bitmap_bytes(len: usize) -> usize { + len.div_ceil(8) +} + +fn add_checked(total: usize, amount: usize) -> Result { + total + .checked_add(amount) + .ok_or_else(|| err("raw series frame offset overflow")) +} + +fn mul_checked(len: usize, width: usize) -> Result { + len.checked_mul(width) + .ok_or_else(|| err("raw series frame offset overflow")) +} + +/// Reuses one prepared frame schema while decoding all batches of a stream. +pub struct RawSeriesFrameDecoder { + schema: SeriesSchema, + mode: RawLabelMode, + expected: SchemaRef, +} + +impl RawSeriesFrameDecoder { + /// Builds the expected frame schema once from the series schema and label mode. + pub fn try_new(schema: &SeriesSchema, mode: RawLabelMode) -> Result { + Ok(Self { + schema: schema.clone(), + mode, + expected: raw_series_frame_schema(schema, mode)?, + }) + } + + /// Decodes all rows of one batch, checking its reserved metadata, declared fields, and rows. + pub fn decode(&self, batch: &RecordBatch) -> Result> { + decode_raw_series_frame(&self.schema, self.mode, &self.expected, batch) + } } /// Decodes all rows of a raw frame; any malformed row makes the entire call fail. @@ -198,7 +853,15 @@ pub fn unpack_raw_series_frame( mode: RawLabelMode, batch: &RecordBatch, ) -> Result> { - let expected = raw_series_frame_schema(schema, mode)?; + RawSeriesFrameDecoder::try_new(schema, mode)?.decode(batch) +} + +fn decode_raw_series_frame( + schema: &SeriesSchema, + mode: RawLabelMode, + expected: &SchemaRef, + batch: &RecordBatch, +) -> Result> { let actual = batch.schema(); for key in [LAYOUT, CONTENT, LABELS, TIME] { if actual.metadata().get(key) != expected.metadata().get(key) { @@ -307,18 +970,17 @@ pub fn unpack_raw_series_frame( } let table = down::(&tables.value(row), "histogram table")?.clone(); let batch = Arc::new(HistogramBatch::try_from_arrow(table)?); - let hs = HistogramSamples::try_new(indices, batch)?; if has_float { - Samples::try_from_mixed(floats, hs)? + Samples::try_from_mixed(floats, HistogramSamples::try_new(indices, batch)?)? } else { - Samples::try_from_histogram(hs.indices().clone(), hs.batch().clone())? + Samples::try_from_histogram(indices, batch)? } }; decoded.push(samples); } let fields = SeriesFields::try_from_vec(decoded)?; let key = binary_slice(keys, row)?; - let raw_time = RawTimeAxis::try_new(time)?; + let raw_time = RawTimestamps::try_new(time)?; out.push(RawSeriesChunk::try_new( schema, key, @@ -331,149 +993,6 @@ pub fn unpack_raw_series_frame( Ok(out) } -fn encode_row( - schema: &SchemaRef, - mode: RawLabelMode, - key: &Buffer, - metric: Option<&MetricName>, - last: bool, - times: ScalarBuffer, - samples: &[Samples], -) -> Result { - let mut arrays: Vec = vec![ - Arc::new(binary_one(key.as_slice())?), - Arc::new(BooleanArray::from(vec![last])), - ]; - let ts = wrap_list( - Arc::new(Int64Array::new(times, None)), - DataType::Int64, - false, - )?; - let DataType::Struct(time_fields) = schema.field(2).data_type() else { - return invalid_series("time schema mismatch"); - }; - arrays.push(Arc::new(struct_array( - time_fields.clone(), - vec![Arc::new(ts)], - )?)); - let DataType::Struct(field_schema) = schema.field(3).data_type() else { - return invalid_series("fields schema mismatch"); - }; - let DataType::Struct(first_payload) = field_schema[0].data_type() else { - return invalid_series("payload schema mismatch"); - }; - let DataType::Struct(histogram_fields) = first_payload[1].data_type() else { - return invalid_series("histogram schema mismatch"); - }; - let mut field_arrays = Vec::new(); - for sample in samples { - let DataType::Struct(dtype) = field_schema[field_arrays.len()].data_type() else { - return invalid_series("payload schema mismatch"); - }; - let (floats, hist) = encode_payload(sample, histogram_fields)?; - field_arrays.push(Arc::new(struct_array(dtype.clone(), vec![floats, hist])?) as ArrayRef); - } - arrays.push(Arc::new(struct_array(field_schema.clone(), field_arrays)?)); - if mode == RawLabelMode::Explicit { - let metric = metric.ok_or_else(|| err("explicit labels missing"))?; - checked_offset(metric.name().map_or(0, str::len))?; - arrays.push(Arc::new(StringArray::from(vec![metric.name()]))); - checked_offset(metric.tags().len())?; - checked_offset( - metric - .tags() - .iter() - .try_fold(0usize, |n, l| n.checked_add(l.name.len())) - .ok_or_else(|| err("label name length overflow"))?, - )?; - checked_offset( - metric - .tags() - .iter() - .try_fold(0usize, |n, l| n.checked_add(l.value.len())) - .ok_or_else(|| err("label value length overflow"))?, - )?; - let names: StringArray = metric - .tags() - .iter() - .map(|l| Some(l.name.as_ref())) - .collect(); - let values: StringArray = metric - .tags() - .iter() - .map(|l| Some(l.value.as_ref())) - .collect(); - let DataType::List(label_list) = schema.field(5).data_type() else { - return invalid_series("labels schema mismatch"); - }; - let DataType::Struct(label_fields) = label_list.data_type() else { - return invalid_series("label struct schema mismatch"); - }; - let labels = struct_array( - label_fields.clone(), - vec![Arc::new(names), Arc::new(values)], - )?; - arrays.push(Arc::new(wrap_list( - Arc::new(labels), - DataType::Struct(label_fields.clone()), - false, - )?)); - } - arrow(RecordBatch::try_new_with_options( - schema.clone(), - arrays, - &RecordBatchOptions::new().with_row_count(Some(1)), - )) -} - -fn encode_payload(samples: &Samples, histogram_fields: &Fields) -> Result<(ArrayRef, ArrayRef)> { - let (floats, histograms) = match samples - .dense() - .ok_or_else(|| err("sample segment is not dense"))? - { - DenseSamplesRef::Float(values) => (Some(values), None), - DenseSamplesRef::Histogram(values) => (None, Some(values)), - DenseSamplesRef::Mixed(values) => (Some(values.floats()), Some(values.histograms())), - }; - let float_array = match floats { - Some(values) => Arc::new(wrap_list( - Arc::new(values.clone()), - DataType::Float64, - true, - )?) as ArrayRef, - None => Arc::new(ListArray::new_null( - Arc::new(Field::new("item", DataType::Float64, true)), - 1, - )) as ArrayRef, - }; - let hist_array = match histograms { - Some(values) => { - let DataType::List(indices_field) = histogram_fields[0].data_type() else { - return invalid_series("histogram index schema mismatch"); - }; - let DataType::List(table_field) = histogram_fields[1].data_type() else { - return invalid_series("histogram table schema mismatch"); - }; - let indices = wrap_list( - Arc::new(values.indices().clone()), - indices_field.data_type().clone(), - true, - )?; - let table = wrap_list( - Arc::new(values.batch().as_arrow().clone()), - table_field.data_type().clone(), - false, - )?; - Arc::new(struct_array( - histogram_fields.clone(), - vec![Arc::new(indices), Arc::new(table)], - )?) as ArrayRef - } - None => null_histogram(histogram_fields)?, - }; - Ok((float_array, hist_array)) -} - fn binary_slice(array: &BinaryArray, row: usize) -> Result { let offsets = array.value_offsets(); let start = usize::try_from(offsets[row]).map_err(|_| err("negative binary offset"))?; @@ -483,68 +1002,29 @@ fn binary_slice(array: &BinaryArray, row: usize) -> Result { .ok_or_else(|| err("invalid binary offsets"))?; Ok(array.values().slice_with_length(start, len)) } -fn binary_one(value: &[u8]) -> Result { - checked_offset(value.len())?; - Ok(BinaryArray::from(vec![Some(value)])) -} + fn checked_offset(len: usize) -> Result { i32::try_from(len).map_err(|_| err("Arrow offset limit exceeded")) } -fn offsets(len: usize) -> Result> { - let len = checked_offset(len)?; - Ok(OffsetBuffer::new(ScalarBuffer::from(vec![0, len]))) -} -fn wrap_list(values: ArrayRef, item: DataType, nullable: bool) -> Result { - let len = values.len(); - arrow(ListArray::try_new( - Arc::new(Field::new("item", item, nullable)), - offsets(len)?, - values, - None, - )) -} -fn null_histogram(fields: &Fields) -> Result { - let DataType::List(indices_field) = fields[0].data_type() else { - return invalid_series("histogram index schema mismatch"); - }; - let DataType::List(table_field) = fields[1].data_type() else { - return invalid_series("histogram table schema mismatch"); - }; - let DataType::Struct(table_fields) = table_field.data_type() else { - return invalid_series("histogram table schema mismatch"); - }; - let indices = wrap_list( - Arc::new(UInt32Array::new_null(0)), - indices_field.data_type().clone(), - true, - )?; - let columns = table_fields - .iter() - .map(|f| arrow::array::new_null_array(f.data_type(), 0)) - .collect(); - let table = arrow(StructArray::try_new(table_fields.clone(), columns, None))?; - let table = wrap_list(Arc::new(table), table_field.data_type().clone(), false)?; - Ok(Arc::new(arrow(StructArray::try_new( - fields.clone(), - vec![Arc::new(indices), Arc::new(table)], - Some(NullBuffer::new_null(1)), - ))?)) -} + fn struct_array(fields: Fields, arrays: Vec) -> Result { arrow(StructArray::try_new(fields, arrays, None)) } + fn down<'a, T: Array + 'static>(array: &'a ArrayRef, label: &str) -> Result<&'a T> { array .as_any() .downcast_ref() .ok_or_else(|| err(format!("{label} type mismatch"))) } + fn err(reason: impl Into) -> crate::error::Error { InvalidSeriesSnafu { reason: reason.into(), } .build() } + fn arrow(result: std::result::Result) -> Result { result.map_err(|e| err(e.to_string())) } diff --git a/src/datatypes/src/series/frame/tests.rs b/src/datatypes/src/series/frame/tests.rs index 7edc38168b5..976a433ee27 100644 --- a/src/datatypes/src/series/frame/tests.rs +++ b/src/datatypes/src/series/frame/tests.rs @@ -15,11 +15,13 @@ use std::sync::Arc; use arrow::array::{ - Array, Float64Array, Int64Array, ListArray, StringArray, StructArray, UInt32Array, + Array, BinaryArray, BooleanArray, Float64Array, Int64Array, ListArray, StringArray, + StructArray, UInt32Array, }; use arrow::buffer::{Buffer, OffsetBuffer, ScalarBuffer}; use arrow::compute::concat_batches; use arrow::datatypes::{DataType, Field, Schema}; +use arrow::ipc::{reader::StreamReader, writer::StreamWriter}; use super::*; use crate::series::histogram::{BucketSideView, CounterResetHint, HistogramBatchBuilder}; @@ -67,7 +69,7 @@ fn float_chunk( schema, Buffer::from(key.to_vec()), metric, - RawTimeAxis::try_new(times.into()).unwrap(), + RawTimestamps::try_new(times.into()).unwrap(), SeriesFields::one(Samples::from_float(Float64Array::from(values))), is_last, ) @@ -247,6 +249,107 @@ fn assert_float_bits(actual: &Samples, expected: &[Option]) { } } +/// Packs one owned chunk through the public cursor/builder pair, mirroring the explicit +/// single-chunk wrapper: every batch the walk produces, then the final flush. +fn pack_chunk_with_budget( + schema: &SeriesSchema, + mode: RawLabelMode, + chunk: &RawSeriesChunk, + max_rows: usize, + max_bytes: usize, +) -> crate::error::Result> { + let mut builder = RawSeriesFrameBuilder::try_new(schema, mode, max_rows, max_bytes)?; + let mut cursor = RawSeriesChunkCursor::try_new(schema, mode, chunk.clone())?; + let mut batches = Vec::new(); + while let Some(batch) = cursor.append_to(&mut builder)? { + batches.push(batch); + } + if let Some(batch) = builder.flush()? { + batches.push(batch); + } + Ok(batches) +} + +/// Advances one owned chunk through an existing builder. A partially filled buffer stays buffered +/// instead of becoming a batch of its own, which is what makes cross-chunk grouping observable. +fn append_chunk( + builder: &mut RawSeriesFrameBuilder, + schema: &SeriesSchema, + mode: RawLabelMode, + chunk: &RawSeriesChunk, +) -> crate::error::Result> { + let mut cursor = RawSeriesChunkCursor::try_new(schema, mode, chunk.clone())?; + let mut batches = Vec::new(); + while let Some(batch) = cursor.append_to(builder)? { + batches.push(batch); + } + Ok(batches) +} + +/// Decodes every batch with one reused decoder, so repeated calls exercise the cached schema. +fn decode_batches( + schema: &SeriesSchema, + mode: RawLabelMode, + batches: &[RecordBatch], +) -> Vec { + let decoder = RawSeriesFrameDecoder::try_new(schema, mode).unwrap(); + batches + .iter() + .flat_map(|batch| decoder.decode(batch).unwrap()) + .collect() +} + +/// Row-local histogram index and table lists of one field payload of a frame batch. +fn frame_histogram_lists(batch: &RecordBatch, field: usize) -> (ListArray, ListArray) { + let histogram = frame_field_payload(batch, field) + .column(1) + .as_any() + .downcast_ref::() + .unwrap(); + let indices = histogram + .column(0) + .as_any() + .downcast_ref::() + .unwrap() + .clone(); + let tables = histogram + .column(1) + .as_any() + .downcast_ref::() + .unwrap() + .clone(); + (indices, tables) +} + +/// Every row is expected to resolve index 0 inside its own table only, with the whole table +/// retained and the other index entry null. +fn assert_row_local_histogram_rows(rows: &[RawSeriesChunk]) { + assert_eq!(rows.len(), 2); + assert_eq!(rows[0].time.as_buffer().as_ref(), &[1_i64, 2]); + assert_eq!(rows[1].time.as_buffer().as_ref(), &[3_i64, 4]); + + let DenseSamplesRef::Histogram(first) = rows[0].fields.get(0).unwrap().dense().unwrap() else { + panic!("expected histogram samples"); + }; + assert_eq!(first.batch().len(), 2); + assert_eq!(first.indices().len(), 2); + assert_eq!(first.indices().value(0), 0); + assert!(!first.indices().is_valid(1)); + assert_histogram(first.view_at(0).unwrap(), -9.5); + assert_unreferenced_histogram(first.batch().view(1).unwrap()); + + let DenseSamplesRef::Histogram(second) = rows[1].fields.get(0).unwrap().dense().unwrap() else { + panic!("expected histogram samples"); + }; + assert_eq!(second.batch().len(), 2); + assert_eq!(second.indices().len(), 2); + assert!(!second.indices().is_valid(0)); + assert_eq!(second.indices().value(1), 0); + // A global index remap would resolve index 0 into the first row's table instead. + assert_histogram(second.view_at(1).unwrap(), 42.25); + assert_histogram_with_start(second.batch().view(1).unwrap(), 142.25, None); +} + #[test] fn sliced_histogram_frames_densify_without_duplicating_shared_table() { let schema = test_schema(&["histogram"]); @@ -263,13 +366,22 @@ fn sliced_histogram_frames_densify_without_duplicating_shared_table() { &schema, Buffer::from(vec![0x42_u8]), None, - RawTimeAxis::try_new((0_i64..64).collect::>().into()).unwrap(), + RawTimestamps::try_new((0_i64..64).collect::>().into()).unwrap(), SeriesFields::one(samples), true, ) .unwrap(); - let frames = pack_raw_series_chunk(&schema, RawLabelMode::Key, &chunk).unwrap(); + // One row per batch keeps the original segment-boundary granularity, so the shared-table fast + // paths below stay observable; the default budget coalesces the same rows later on. + let frames = pack_chunk_with_budget( + &schema, + RawLabelMode::Key, + &chunk, + 1, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, + ) + .unwrap(); assert_eq!(frames.len(), 64); let mut decoded_chunks = Vec::with_capacity(frames.len()); for frame in &frames { @@ -305,6 +417,24 @@ fn sliced_histogram_frames_densify_without_duplicating_shared_table() { second_values.values().as_ptr() ); + // The default budget groups the same 64 rows into one multirow batch; every row still decodes + // to its own slice of the shared table with bit-exact values. + let coalesced = pack_raw_series_chunk(&schema, RawLabelMode::Key, &chunk).unwrap(); + assert_eq!(coalesced.len(), 1); + assert_eq!(coalesced[0].num_rows(), 64); + let coalesced_rows = decode_batches(&schema, RawLabelMode::Key, &coalesced); + assert_eq!(coalesced_rows.len(), 64); + for (position, row) in coalesced_rows.iter().enumerate() { + assert_eq!(row.primary_key.as_slice(), &[0x42]); + assert_eq!(row.time.timestamp(0), Some(position as i64)); + let DenseSamplesRef::Histogram(histograms) = row.fields.get(0).unwrap().dense().unwrap() + else { + panic!("expected histogram samples"); + }; + assert_eq!(histograms.batch().len(), first_table.len()); + assert_histogram(histograms.view_at(0).unwrap(), -9.5); + } + let samples = Samples::try_from_chunks( decoded_chunks .iter() @@ -354,7 +484,7 @@ fn raw_frame_field_names_bind_payloads_to_their_schema() { &schema, Buffer::from(vec![0xaa_u8]), metric, - RawTimeAxis::try_new(vec![100, 200].into()).unwrap(), + RawTimestamps::try_new(vec![100, 200].into()).unwrap(), fields.clone(), true, ) @@ -375,9 +505,9 @@ fn raw_frame_field_names_bind_payloads_to_their_schema() { ); let decoded = unpack_raw_series_frame(&schema, mode, batch).unwrap(); - assert_eq!(decoded[0].read_key.as_slice(), &[0xaa]); + assert_eq!(decoded[0].primary_key.as_slice(), &[0xaa]); assert!(decoded[0].is_last); - let RawTimeAxis::Explicit(times) = &decoded[0].time; + let times = decoded[0].time.as_buffer(); assert_eq!(times.as_ref(), &[100, 200]); assert_float_bits(decoded[0].fields.get(0).unwrap(), &[Some(1.0), Some(2.0)]); assert_float_bits(decoded[0].fields.get(1).unwrap(), &[Some(10.0), Some(20.0)]); @@ -499,7 +629,7 @@ fn schema_and_key_explicit_round_trips_preserve_identity_and_bits() { assert_eq!(packed.len(), 1); let decoded = unpack_raw_series_frame(&schema, RawLabelMode::Key, &packed[0]).unwrap(); assert_eq!(decoded.len(), 1); - assert_eq!(decoded[0].read_key.as_slice(), &[0, 0xff, 0, 0x80]); + assert_eq!(decoded[0].primary_key.as_slice(), &[0, 0xff, 0, 0x80]); assert!(decoded[0].metric.is_none()); assert!(decoded[0].is_last); assert_eq!( @@ -520,7 +650,7 @@ fn schema_and_key_explicit_round_trips_preserve_identity_and_bits() { ); let packed = pack_raw_series_chunk(&schema, RawLabelMode::Explicit, &explicit).unwrap(); let decoded = unpack_raw_series_frame(&schema, RawLabelMode::Explicit, &packed[0]).unwrap(); - assert_eq!(decoded[0].read_key.as_slice(), &[0x80, 0, 0xff]); + assert_eq!(decoded[0].primary_key.as_slice(), &[0x80, 0, 0xff]); assert!(!decoded[0].is_last); let labels = decoded[0].metric.as_ref().unwrap(); assert_eq!(labels.name(), None); @@ -577,28 +707,31 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { &schema, Buffer::from(vec![0_u8, 0x91, 0xfe]), None, - RawTimeAxis::try_new(vec![10_i64, 20, 30, 40].into()).unwrap(), + RawTimestamps::try_new(vec![10_i64, 20, 30, 40].into()).unwrap(), SeriesFields::try_from_vec(vec![first, second]).unwrap(), true, ) .unwrap(); + // Variable field boundaries now group every aligned interval into one multirow batch instead + // of one batch per boundary, so decode the actual rows that batch carries. let frames = pack_raw_series_chunk(&schema, RawLabelMode::Key, &chunk).unwrap(); - assert_eq!(frames.len(), 4); + assert_eq!(frames.len(), 1); + assert_eq!(frames[0].num_rows(), 4); let mut observed_times = Vec::new(); let mut observed_first = Vec::new(); let mut observed_second = Vec::new(); let mut observed_keys = Vec::new(); let mut observed_markers = Vec::new(); - for (frame_index, frame) in frames.iter().enumerate() { - let decoded = unpack_raw_series_frame(&schema, RawLabelMode::Key, frame).unwrap(); - assert_eq!(decoded.len(), 1); - assert_eq!(decoded[0].is_last, frame_index == frames.len() - 1); - observed_markers.push(decoded[0].is_last); - assert_eq!(decoded[0].read_key.as_slice(), &[0, 0x91, 0xfe]); - observed_keys.push(decoded[0].read_key.as_slice().to_vec()); - for position in 0..decoded[0].time.len() { - observed_times.push(decoded[0].time.timestamp(position).unwrap()); - match decoded[0].fields.get(0).unwrap().sample(position) { + let rows = unpack_raw_series_frame(&schema, RawLabelMode::Key, &frames[0]).unwrap(); + assert_eq!(rows.len(), 4); + for (row_index, row) in rows.iter().enumerate() { + assert_eq!(row.is_last, row_index == rows.len() - 1); + observed_markers.push(row.is_last); + assert_eq!(row.primary_key.as_slice(), &[0, 0x91, 0xfe]); + observed_keys.push(row.primary_key.as_slice().to_vec()); + for position in 0..row.time.len() { + observed_times.push(row.time.timestamp(position).unwrap()); + match row.fields.get(0).unwrap().sample(position) { SampleRef::Missing => observed_first.push(("m", 0.0_f64.to_bits())), SampleRef::Float(value) => observed_first.push(("f", value.to_bits())), SampleRef::Histogram(histogram) => { @@ -606,7 +739,7 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { observed_first.push(("h", histogram.sum.to_bits())); } } - match decoded[0].fields.get(1).unwrap().sample(position) { + match row.fields.get(1).unwrap().sample(position) { SampleRef::Missing => observed_second.push(("m", 0.0_f64.to_bits())), SampleRef::Float(value) => observed_second.push(("f", value.to_bits())), SampleRef::Histogram(histogram) => { @@ -657,59 +790,59 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { &aligned_schema, Buffer::from(vec![0xa1_u8]), None, - RawTimeAxis::try_new(vec![101_i64, 102, 103, 104, 105].into()).unwrap(), + RawTimestamps::try_new(vec![101_i64, 102, 103, 104, 105].into()).unwrap(), SeriesFields::try_from_vec(vec![a, b]).unwrap(), true, ) .unwrap(); let aligned_frames = pack_raw_series_chunk(&aligned_schema, RawLabelMode::Key, &aligned_chunk).unwrap(); + assert_eq!(aligned_frames.len(), 1); + assert_eq!(aligned_frames[0].num_rows(), 3); + let aligned_rows = + unpack_raw_series_frame(&aligned_schema, RawLabelMode::Key, &aligned_frames[0]).unwrap(); + assert_eq!(aligned_rows.len(), 3); let mut interval_lengths = Vec::new(); let mut aligned_times = Vec::new(); let mut aligned_a = Vec::new(); let mut aligned_b = Vec::new(); - for (i, batch) in aligned_frames.iter().enumerate() { - let decoded = unpack_raw_series_frame(&aligned_schema, RawLabelMode::Key, batch).unwrap(); - assert_eq!(decoded[0].is_last, i == 2); - interval_lengths.push(decoded[0].time.len()); + for (i, row) in aligned_rows.iter().enumerate() { + assert_eq!(row.is_last, i == aligned_rows.len() - 1); + interval_lengths.push(row.time.len()); let start = aligned_times.len(); - let DenseSamplesRef::Float(decoded_a) = decoded[0].fields.get(0).unwrap().dense().unwrap() - else { + let DenseSamplesRef::Float(decoded_a) = row.fields.get(0).unwrap().dense().unwrap() else { panic!("expected float field"); }; - let DenseSamplesRef::Float(decoded_b) = decoded[0].fields.get(1).unwrap().dense().unwrap() - else { + let DenseSamplesRef::Float(decoded_b) = row.fields.get(1).unwrap().dense().unwrap() else { panic!("expected float field"); }; - assert_eq!( - decoded_a.values().as_ptr(), - a_owner.values().as_ptr().wrapping_add(start) - ); - assert_eq!( - decoded_b.values().as_ptr(), - b_owner.values().as_ptr().wrapping_add(start) - ); + // Grouping several constituents into one row may copy their payloads, so compare values + // and validity bit-exactly instead of requiring the source buffers by pointer. for (decoded_values, owner) in [(&decoded_a, &a_owner), (&decoded_b, &b_owner)] { - match (decoded_values.nulls(), owner.nulls()) { - (Some(decoded_nulls), Some(owner_nulls)) => { - assert_eq!( - decoded_nulls.buffer().as_ptr(), - owner_nulls.buffer().as_ptr() - ); - assert_eq!(decoded_nulls.offset(), owner_nulls.offset() + start); + assert_eq!(decoded_values.len(), row.time.len()); + for position in 0..decoded_values.len() { + match ( + decoded_values.is_valid(position), + owner.is_valid(start + position), + ) { + (true, true) => assert_eq!( + decoded_values.value(position).to_bits(), + owner.value(start + position).to_bits(), + "grouping changed a value" + ), + (false, false) => {} + _ => panic!("grouping changed validity representation"), } - (None, None) => {} - _ => panic!("fragment changed validity representation"), } } - for position in 0..decoded[0].time.len() { - aligned_times.push(decoded[0].time.timestamp(position).unwrap()); - aligned_a.push(match decoded[0].fields.get(0).unwrap().sample(position) { + for position in 0..row.time.len() { + aligned_times.push(row.time.timestamp(position).unwrap()); + aligned_a.push(match row.fields.get(0).unwrap().sample(position) { SampleRef::Missing => None, SampleRef::Float(value) => Some(value.to_bits()), SampleRef::Histogram(_) => panic!("expected float field"), }); - aligned_b.push(match decoded[0].fields.get(1).unwrap().sample(position) { + aligned_b.push(match row.fields.get(1).unwrap().sample(position) { SampleRef::Missing => None, SampleRef::Float(value) => Some(value.to_bits()), SampleRef::Histogram(_) => panic!("expected float field"), @@ -757,7 +890,7 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { &alternate_schema, Buffer::from(vec![0xde_u8, 0xad]), None, - RawTimeAxis::try_new(vec![100_i64].into()).unwrap(), + RawTimestamps::try_new(vec![100_i64].into()).unwrap(), SeriesFields::try_from_vec(vec![first_distinct, second_distinct]).unwrap(), false, ) @@ -781,7 +914,7 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { .collect::>(), [10, 20, 30, 40, 100] ); - assert_eq!(decoded[4].read_key.as_slice(), &[0xde, 0xad]); + assert_eq!(decoded[4].primary_key.as_slice(), &[0xde, 0xad]); assert!( matches!(decoded[4].fields.get(0).unwrap().sample(0), SampleRef::Histogram(h) if h.sum.to_bits() == 123.0_f64.to_bits()) ); @@ -807,7 +940,7 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { assert_eq!( sliced_rows .iter() - .map(|row| row.read_key.as_slice()) + .map(|row| row.primary_key.as_slice()) .collect::>(), [&[0xee][..], &[0xef][..], &[0xed][..]] ); @@ -837,7 +970,7 @@ fn segmented_mixed_fields_emit_every_aligned_position_and_marker() { &schema, Buffer::from(vec![0_u8, 0x91, 0xfe]), None, - RawTimeAxis::try_new(vec![50_i64, 60, 70, 80].into()).unwrap(), + RawTimestamps::try_new(vec![50_i64, 60, 70, 80].into()).unwrap(), chunk.fields.clone(), false, ) @@ -898,7 +1031,7 @@ fn histogram_payload_and_present_all_null_representation_survive() { &schema, Buffer::from(vec![0x12_u8, 0x00]), None, - RawTimeAxis::try_new(vec![1_i64, 2].into()).unwrap(), + RawTimestamps::try_new(vec![1_i64, 2].into()).unwrap(), fields, false, ) @@ -950,7 +1083,7 @@ fn histogram_payload_and_present_all_null_representation_survive() { &mixed_schema, Buffer::from(vec![0x42_u8]), None, - RawTimeAxis::try_new(vec![5_i64, 6].into()).unwrap(), + RawTimestamps::try_new(vec![5_i64, 6].into()).unwrap(), SeriesFields::one(mixed), false, ) @@ -1089,6 +1222,9 @@ fn rejects_invalid_schema_and_metadata_and_accepts_valid_empty() { #[test] fn rejects_invalid_timestamps_and_empty_raw_payloads() { + assert!(RawTimestamps::try_new(vec![1_i64, 1].into()).is_err()); + assert!(RawTimestamps::try_new(vec![2_i64, 1].into()).is_err()); + let schema = test_schema(&["value"]); let chunk = float_chunk(&schema, &[1], None, vec![1], vec![Some(2.0)], false); let valid = pack_raw_series_chunk(&schema, RawLabelMode::Key, &chunk) @@ -1335,7 +1471,7 @@ fn rejects_malformed_histogram_and_payload_encodings() { &hist_schema, Buffer::from(vec![1_u8]), None, - RawTimeAxis::try_new(vec![1_i64].into()).unwrap(), + RawTimestamps::try_new(vec![1_i64].into()).unwrap(), SeriesFields::one( Samples::try_from_histogram(UInt32Array::from(vec![Some(0)]), histogram_batch()) .unwrap(), @@ -1705,7 +1841,7 @@ fn decoded_key_and_payload_slices_keep_buffers_alive() { &schema, Buffer::from(vec![0xaa_u8, 0x10, 0x20, 0xbb]), None, - RawTimeAxis::try_new(vec![0_i64, 11, 22, 33].into()) + RawTimestamps::try_new(vec![0_i64, 11, 22, 33].into()) .unwrap() .slice(1, 2) .unwrap(), @@ -1776,9 +1912,9 @@ fn decoded_key_and_payload_slices_keep_buffers_alive() { .as_any() .downcast_ref::() .unwrap(); - let crate::series::raw::RawTimeAxis::Explicit(decoded_time) = &decoded[0].time; + let decoded_time = decoded[0].time.as_buffer(); assert_eq!(decoded_time.as_ptr(), time_values.values().as_ptr()); - let crate::series::raw::RawTimeAxis::Explicit(source_time) = &chunk.time; + let source_time = chunk.time.as_buffer(); assert_eq!(decoded_time.as_ptr(), source_time.as_ptr()); drop(owner); drop(chunk); @@ -1790,7 +1926,7 @@ fn decoded_key_and_payload_slices_keep_buffers_alive() { decoded[0].fields.get(0).unwrap().sample(1), SampleRef::Missing )); - assert_eq!(decoded[0].read_key.as_slice(), &[0xaa, 0x10, 0x20, 0xbb]); + assert_eq!(decoded[0].primary_key.as_slice(), &[0xaa, 0x10, 0x20, 0xbb]); } #[test] @@ -1855,7 +1991,7 @@ fn sliced_canonical_mixed_histogram_round_trip_keeps_buffers_alive() { &schema, Buffer::from(vec![0x42_u8]), None, - RawTimeAxis::try_new(vec![0_i64, 11, 22, 33].into()) + RawTimestamps::try_new(vec![0_i64, 11, 22, 33].into()) .unwrap() .slice(1, 2) .unwrap(), @@ -1948,9 +2084,19 @@ fn sliced_canonical_mixed_histogram_round_trip_keeps_buffers_alive() { .values() .as_ptr() ); - let crate::series::raw::RawTimeAxis::Explicit(source_times) = &chunk.time; + let source_times = chunk.time.as_buffer(); - let frames = pack_raw_series_chunk(&schema, RawLabelMode::Key, &chunk).unwrap(); + // One row per batch keeps this fixture's single constituents and their nonzero offsets + // observable: the default budget could coalesce several rows and copy their payloads. + let frames = pack_chunk_with_budget( + &schema, + RawLabelMode::Key, + &chunk, + 1, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, + ) + .unwrap(); + assert_eq!(frames.len(), 1); let packed = &frames[0]; let packed_times = packed .column(2) @@ -2064,7 +2210,7 @@ fn sliced_canonical_mixed_histogram_round_trip_keeps_buffers_alive() { else { panic!("histogram representation was normalized"); }; - let crate::series::raw::RawTimeAxis::Explicit(decoded_time_values) = &decoded[0].time; + let decoded_time_values = decoded[0].time.as_buffer(); assert_eq!(decoded_time_values.as_ptr(), packed_times.values().as_ptr()); assert_eq!(decoded_time_values, source_times); for (decoded_indices, source_indices) in [ @@ -2310,3 +2456,605 @@ fn public_segments_are_flat_ordered_and_retain_empty_dense_kinds() { Some(DenseSamplesRef::Float(_)) )); } + +#[test] +fn cross_chunk_rows_coalesce_into_one_multirow_batch() { + let schema = test_schema(&["value"]); + let first = float_chunk( + &schema, + &[0xaa], + None, + vec![10, 20], + vec![Some(1.0), None], + false, + ); + let second = float_chunk( + &schema, + &[0xbb], + None, + vec![30, 40, 50], + vec![Some(3.0), Some(4.0), None], + true, + ); + assert_eq!(RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, 256); + assert_eq!(RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, 1 << 20); + let expected = raw_series_frame_schema(&schema, RawLabelMode::Key).unwrap(); + + let mut builder = RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, + ) + .unwrap(); + assert_eq!(builder.schema(), &expected); + + let mut batches = append_chunk(&mut builder, &schema, RawLabelMode::Key, &first).unwrap(); + batches.extend(append_chunk(&mut builder, &schema, RawLabelMode::Key, &second).unwrap()); + if let Some(batch) = builder.flush().unwrap() { + batches.push(batch); + } + // Rows of both chunks coalesce into one batch: a partially filled buffer must survive the + // cursor boundary instead of becoming a batch of its own. + assert_eq!(batches.len(), 1); + let batch = &batches[0]; + assert_eq!(batch.num_rows(), 2); + assert_eq!(batch.schema(), expected); + assert_eq!( + batch + .schema() + .fields() + .iter() + .map(|field| field.name().as_str()) + .collect::>(), + ["read_key", "is_last", "time", "fields"] + ); + for (key, value) in [ + ("greptime.series.layout", "v1"), + ("greptime.series.content", "raw"), + ("greptime.series.labels", "key"), + ("greptime.series.time", "timestamps"), + ] { + assert_eq!( + batch.schema().metadata().get(key).map(String::as_str), + Some(value) + ); + } + + let keys = batch + .column(0) + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!(keys.value(0), &[0xaa]); + assert_eq!(keys.value(1), &[0xbb]); + let lasts = batch + .column(1) + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!( + (0..2).map(|row| lasts.value(row)).collect::>(), + [false, true] + ); + let times = batch + .column(2) + .as_any() + .downcast_ref::() + .unwrap() + .column(0) + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!(times.value_offsets(), [0, 2, 5]); + assert_eq!( + times + .values() + .as_any() + .downcast_ref::() + .unwrap() + .values() + .as_ref(), + &[10_i64, 20, 30, 40, 50] + ); + let floats = frame_field_payload(batch, 0) + .column(0) + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!(floats.value_offsets(), [0, 2, 5]); + let float_values = floats + .values() + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!( + (0..float_values.len()) + .map(|position| float_values.is_valid(position)) + .collect::>(), + [true, false, true, true, false] + ); + assert_eq!(float_values.value(0).to_bits(), 1.0_f64.to_bits()); + assert_eq!(float_values.value(2).to_bits(), 3.0_f64.to_bits()); + assert_eq!(float_values.value(3).to_bits(), 4.0_f64.to_bits()); + + let decoded = decode_batches(&schema, RawLabelMode::Key, &batches); + assert_eq!(decoded.len(), 2); + assert_eq!(decoded[0].primary_key.as_slice(), &[0xaa]); + assert!(!decoded[0].is_last); + assert_eq!( + (0..decoded[0].time.len()) + .map(|position| decoded[0].time.timestamp(position).unwrap()) + .collect::>(), + [10, 20] + ); + assert_float_bits(decoded[0].fields.get(0).unwrap(), &[Some(1.0), None]); + assert_eq!(decoded[1].primary_key.as_slice(), &[0xbb]); + assert!(decoded[1].is_last); + assert_eq!( + (0..decoded[1].time.len()) + .map(|position| decoded[1].time.timestamp(position).unwrap()) + .collect::>(), + [30, 40, 50] + ); + assert_float_bits( + decoded[1].fields.get(0).unwrap(), + &[Some(3.0), Some(4.0), None], + ); + assert_eq!(decoded.iter().map(|row| row.time.len()).sum::(), 5); +} + +#[test] +fn raw_frame_builder_emits_at_the_row_budget_without_another_cursor() { + let schema = test_schema(&["value"]); + let chunks = [ + float_chunk(&schema, &[1], None, vec![1], vec![Some(1.0)], false), + float_chunk(&schema, &[2], None, vec![2], vec![Some(2.0)], false), + float_chunk(&schema, &[3], None, vec![3], vec![Some(3.0)], true), + ]; + + for max_rows in [2usize, 3] { + let mut builder = RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + max_rows, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, + ) + .unwrap(); + let mut emitted_at = None; + let mut batches = Vec::new(); + for (index, chunk) in chunks.iter().enumerate() { + let produced = append_chunk(&mut builder, &schema, RawLabelMode::Key, chunk).unwrap(); + assert!(produced.len() <= 1, "one cursor emits at most one batch"); + if let Some(batch) = produced.first() { + assert!( + emitted_at.replace(index).is_none(), + "the row bound is reached once, without another cursor" + ); + batches.push(batch.clone()); + } + } + if let Some(batch) = builder.flush().unwrap() { + batches.push(batch); + } + // Three one-row chunks emit at the max_rows-th row: a budget of two is reached during the + // second chunk and a budget of three during the third, so no further cursor is needed. + assert_eq!(emitted_at, Some(max_rows - 1)); + assert_eq!(batches[0].num_rows(), max_rows); + assert_eq!( + batches.iter().map(|batch| batch.num_rows()).sum::(), + 3 + ); + assert!(batches.iter().all(|batch| batch.num_rows() <= max_rows)); + let keys = batches[0] + .column(0) + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!( + (0..max_rows) + .map(|row| keys.value(row).to_vec()) + .collect::>(), + (1..=max_rows) + .map(|key| vec![key as u8]) + .collect::>() + ); + + let decoded = decode_batches(&schema, RawLabelMode::Key, &batches); + assert_eq!(decoded.len(), 3); + assert_eq!( + decoded + .iter() + .map(|row| row.time.timestamp(0).unwrap()) + .collect::>(), + [1, 2, 3] + ); + assert_eq!( + decoded.iter().map(|row| row.is_last).collect::>(), + [false, false, true] + ); + } +} + +#[test] +fn raw_frame_builder_rejects_zero_budgets_and_bounds_offsets() { + let schema = test_schema(&["value"]); + // Zero in either budget is not a legal configuration; the literals take the parameter's type. + assert!( + RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + 0, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, + ) + .is_err() + ); + assert!( + RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, + 0, + ) + .is_err() + ); + assert!(RawSeriesFrameBuilder::try_new(&schema, RawLabelMode::Key, 0, 0).is_err()); + assert!( + RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + 1, + RawSeriesFrameBuilder::DEFAULT_MAX_BYTES, + ) + .is_ok() + ); + + // Cumulative Arrow list offsets are bounded through the shared helper, so the limit is proven + // without allocating a two-gigabyte fixture. + assert_eq!(checked_offset(i32::MAX as usize).unwrap(), i32::MAX); + assert!(checked_offset(i32::MAX as usize + 1).is_err()); + assert!(checked_offset(usize::MAX).is_err()); +} + +#[test] +fn byte_budget_emits_legal_oversized_rows_without_dropping_them() { + let schema = test_schema(&["value"]); + let owner = Float64Array::from(vec![Some(1.0), Some(2.0), Some(3.0)]); + let samples = Samples::try_from_chunks( + (0..3) + .map(|position| Samples::from_float(owner.slice(position, 1))) + .collect(), + ) + .unwrap(); + let chunk = RawSeriesChunk::try_new( + &schema, + Buffer::from(vec![0x9a_u8]), + None, + RawTimestamps::try_new(vec![7_i64, 8, 9].into()).unwrap(), + SeriesFields::one(samples), + true, + ) + .unwrap(); + + // A one-byte budget cannot hold any row, yet every legal row is still emitted as its own + // batch instead of being dropped or merged. + let batches = pack_chunk_with_budget( + &schema, + RawLabelMode::Key, + &chunk, + RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, + 1, + ) + .unwrap(); + assert_eq!(batches.len(), 3); + assert!( + batches + .iter() + .all(|batch| batch.num_rows() == 1 && batch.schema() == batches[0].schema()), + "an oversized row is emitted alone, never dropped" + ); + + let decoded = decode_batches(&schema, RawLabelMode::Key, &batches); + assert_eq!(decoded.len(), 3); + for (position, row) in decoded.iter().enumerate() { + assert_eq!(row.primary_key.as_slice(), &[0x9a]); + assert_eq!(row.time.timestamp(0), Some(7 + position as i64)); + assert_eq!(row.is_last, position == 2); + assert_float_bits(row.fields.get(0).unwrap(), &[Some(position as f64 + 1.0)]); + } +} + +#[test] +fn byte_budget_flushes_before_exceeding_and_retries_the_pending_row() { + let schema = test_schema(&["value"]); + let chunks = [ + float_chunk(&schema, &[1], None, vec![10], vec![Some(1.0)], false), + float_chunk(&schema, &[2], None, vec![20], vec![Some(2.0)], true), + ]; + // The bound comes from the real rows instead of a fabricated counter: one byte less than + // both rows together fits the first row alone, so the second one must not join it. + let mut measured = Vec::with_capacity(chunks.len()); + for chunk in &chunks { + let mut cursor = + RawSeriesChunkCursor::try_new(&schema, RawLabelMode::Key, chunk.clone()).unwrap(); + measured.push(cursor.next_row().unwrap().unwrap().bytes); + } + let budget = measured[0] + measured[1] - 1; + + let mut builder = RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, + budget, + ) + .unwrap(); + let mut first = + RawSeriesChunkCursor::try_new(&schema, RawLabelMode::Key, chunks[0].clone()).unwrap(); + assert!(first.append_to(&mut builder).unwrap().is_none()); + + let mut second = + RawSeriesChunkCursor::try_new(&schema, RawLabelMode::Key, chunks[1].clone()).unwrap(); + let emitted = second.append_to(&mut builder).unwrap().unwrap(); + assert_eq!(emitted.num_rows(), 1, "the first row is flushed alone"); + // The second row stays pending across the flush and is retried, never dropped. + assert!(second.append_to(&mut builder).unwrap().is_none()); + let remainder = builder.flush().unwrap().unwrap(); + assert_eq!(remainder.num_rows(), 1); + + let decoded = decode_batches(&schema, RawLabelMode::Key, &[emitted, remainder]); + assert_eq!(decoded.len(), 2); + assert_eq!(decoded[0].primary_key.as_slice(), &[1]); + assert_eq!(decoded[1].primary_key.as_slice(), &[2]); + assert_eq!(decoded[0].time.timestamp(0), Some(10)); + assert_eq!(decoded[1].time.timestamp(0), Some(20)); + assert_eq!( + decoded.iter().map(|row| row.is_last).collect::>(), + [false, true] + ); + assert_float_bits(decoded[0].fields.get(0).unwrap(), &[Some(1.0)]); + assert_float_bits(decoded[1].fields.get(0).unwrap(), &[Some(2.0)]); + + // A requested byte bound is clamped to the representable cumulative offset range, and that + // range is rejected before any child array is allocated. + let clamped = RawSeriesFrameBuilder::try_new( + &schema, + RawLabelMode::Key, + RawSeriesFrameBuilder::DEFAULT_MAX_ROWS, + usize::MAX, + ) + .unwrap(); + assert_eq!(clamped.max_bytes, i32::MAX as usize); + assert!(offset_buffer(&[i32::MAX as usize, 1]).is_err()); +} + +#[test] +fn multirow_histogram_rows_keep_row_local_indices_and_tables() { + let schema = test_schema(&["histogram"]); + let first_table = histogram_batch(); + let second_table = histogram_batch_with_sum(42.25); + let first_row = + Samples::try_from_histogram(UInt32Array::from(vec![Some(0), None]), first_table).unwrap(); + let second_row = + Samples::try_from_histogram(UInt32Array::from(vec![None, Some(0)]), second_table).unwrap(); + let fields = SeriesFields::one(Samples::try_from_chunks(vec![first_row, second_row]).unwrap()); + let chunk = RawSeriesChunk::try_new( + &schema, + Buffer::from(vec![0x5a_u8]), + None, + RawTimestamps::try_new(vec![1_i64, 2, 3, 4].into()).unwrap(), + fields, + true, + ) + .unwrap(); + + // The public wrapper groups two independent rows into one multirow batch. + let packed = pack_raw_series_chunk(&schema, RawLabelMode::Key, &chunk).unwrap(); + assert_eq!(packed.len(), 1); + assert_eq!(packed[0].num_rows(), 2); + + let (indices, tables) = frame_histogram_lists(&packed[0], 0); + let encoded_first = indices.value(0); + let encoded_first = encoded_first + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!(encoded_first.value(0), 0); + assert!(!encoded_first.is_valid(1)); + let encoded_second = indices.value(1); + let encoded_second = encoded_second + .as_any() + .downcast_ref::() + .unwrap(); + assert!(!encoded_second.is_valid(0)); + assert_eq!( + encoded_second.value(1), + 0, + "row-local indices must not be remapped" + ); + // The second row references its own table through a nonzero slice of the concatenated child. + assert_eq!(tables.value_offsets(), [0, 2, 4]); + let concatenated = tables + .values() + .as_any() + .downcast_ref::() + .unwrap(); + assert_eq!(concatenated.len(), 4); + + let decoded = decode_batches(&schema, RawLabelMode::Key, std::slice::from_ref(&packed[0])); + assert_row_local_histogram_rows(&decoded); + + // A real Arrow IPC round trip keeps the schema, the whole tables, the null index entries and + // the bit-exact payloads. + let mut ipc = Vec::new(); + { + let mut writer = StreamWriter::try_new(&mut ipc, &packed[0].schema()).unwrap(); + writer.write(&packed[0]).unwrap(); + writer.finish().unwrap(); + } + let reader = StreamReader::try_new(std::io::Cursor::new(ipc), None).unwrap(); + let restored = reader.map(|batch| batch.unwrap()).collect::>(); + assert_eq!(restored.len(), 1); + assert_eq!(restored[0].schema(), packed[0].schema()); + assert_eq!(restored[0].num_rows(), 2); + let (restored_indices, restored_tables) = frame_histogram_lists(&restored[0], 0); + assert_eq!(restored_tables.value_offsets(), tables.value_offsets()); + let restored_second = restored_indices.value(1); + assert_eq!( + restored_second + .as_any() + .downcast_ref::() + .unwrap() + .value(1), + 0 + ); + let restored_rows = decode_batches(&schema, RawLabelMode::Key, &restored); + assert_row_local_histogram_rows(&restored_rows); +} + +#[test] +fn decoder_reuses_cached_schema_and_rejects_schema_evolution() { + let schema = test_schema(&["value"]); + let expected = raw_series_frame_schema(&schema, RawLabelMode::Key).unwrap(); + let first = pack_raw_series_chunk( + &schema, + RawLabelMode::Key, + &float_chunk( + &schema, + &[1], + None, + vec![1, 2], + vec![Some(1.0), Some(2.0)], + false, + ), + ) + .unwrap() + .remove(0); + let second = pack_raw_series_chunk( + &schema, + RawLabelMode::Key, + &float_chunk(&schema, &[2], None, vec![3], vec![Some(3.0)], true), + ) + .unwrap() + .remove(0); + + let key_decoder = RawSeriesFrameDecoder::try_new(&schema, RawLabelMode::Key).unwrap(); + let decoded = key_decoder.decode(&first).unwrap(); + assert_eq!(decoded.len(), 1); + assert_eq!(decoded[0].primary_key.as_slice(), &[1]); + assert_eq!( + (0..decoded[0].time.len()) + .map(|position| decoded[0].time.timestamp(position).unwrap()) + .collect::>(), + [1, 2] + ); + // The same decoder accepts a later valid batch before the malformed ones below. + let decoded = key_decoder.decode(&second).unwrap(); + assert_eq!(decoded.len(), 1); + assert_eq!(decoded[0].primary_key.as_slice(), &[2]); + assert!(decoded[0].is_last); + + // Unrelated metadata is not part of the raw frame contract. + let mut unrelated_metadata = second.schema().metadata().clone(); + unrelated_metadata.insert("application.note".to_string(), "ignored".to_string()); + let unrelated = arrow::record_batch::RecordBatch::try_new( + Arc::new(Schema::new_with_metadata( + expected.fields().clone(), + unrelated_metadata, + )), + second.columns().to_vec(), + ) + .unwrap(); + assert_eq!(key_decoder.decode(&unrelated).unwrap().len(), 1); + + // Reserved metadata and evolved fields are rejected, including by a zero-row batch. + for (key, value) in [ + ("greptime.series.layout", "v2"), + ("greptime.series.content", "evaluated"), + ("greptime.series.labels", "explicit"), + ("greptime.series.time", "grid"), + ] { + let mut metadata = second.schema().metadata().clone(); + metadata.insert(key.to_string(), value.to_string()); + let contaminated = arrow::record_batch::RecordBatch::try_new( + Arc::new(Schema::new_with_metadata( + expected.fields().clone(), + metadata, + )), + second.columns().to_vec(), + ) + .unwrap(); + assert!( + key_decoder.decode(&contaminated).is_err(), + "{key} must be rejected" + ); + } + let evolved_schema = test_schema(&["other"]); + let evolved = pack_raw_series_chunk( + &evolved_schema, + RawLabelMode::Key, + &float_chunk(&evolved_schema, &[3], None, vec![4], vec![Some(4.0)], false), + ) + .unwrap() + .remove(0); + assert!(key_decoder.decode(&evolved).is_err()); + let empty_evolved = arrow::record_batch::RecordBatch::new_empty( + raw_series_frame_schema(&evolved_schema, RawLabelMode::Key).unwrap(), + ); + assert!(key_decoder.decode(&empty_evolved).is_err()); + // Rejections leave the cached schema usable, and a valid zero-row batch stays valid. + assert_eq!(key_decoder.decode(&first).unwrap().len(), 1); + assert!( + key_decoder + .decode(&arrow::record_batch::RecordBatch::new_empty( + expected.clone() + )) + .unwrap() + .is_empty() + ); + + // Explicit mode reuses one decoder for a present but nameless metric and a named one. + let explicit_decoder = RawSeriesFrameDecoder::try_new(&schema, RawLabelMode::Explicit).unwrap(); + let nameless = pack_raw_series_chunk( + &schema, + RawLabelMode::Explicit, + &float_chunk( + &schema, + &[7], + Some(metric(None, &[("zone", "west")])), + vec![5], + vec![Some(5.0)], + true, + ), + ) + .unwrap() + .remove(0); + let named = pack_raw_series_chunk( + &schema, + RawLabelMode::Explicit, + &float_chunk( + &schema, + &[8], + Some(metric(Some("cpu"), &[])), + vec![6], + vec![Some(6.0)], + false, + ), + ) + .unwrap() + .remove(0); + let decoded = explicit_decoder.decode(&nameless).unwrap(); + let labels = decoded[0].metric.as_ref().unwrap(); + assert_eq!(labels.name(), None); + assert_eq!(labels.get("zone"), Some("west")); + assert_eq!( + explicit_decoder.decode(&named).unwrap()[0] + .metric + .as_ref() + .unwrap() + .name(), + Some("cpu") + ); + // Label modes are not interchangeable. + assert!(explicit_decoder.decode(&first).is_err()); + assert!(key_decoder.decode(&nameless).is_err()); +} diff --git a/src/datatypes/src/series/samples.rs b/src/datatypes/src/series/samples.rs index 12e3e17eaac..42b1d4bba0b 100644 --- a/src/datatypes/src/series/samples.rs +++ b/src/datatypes/src/series/samples.rs @@ -389,13 +389,15 @@ impl Samples { SampleStorage::Mixed(mixed) => Some(&mixed.histograms.batch), SampleStorage::Float(_) | SampleStorage::Chunks(_, _) => None, }); + let mut first_data = None; let shared_batch = histogram_batches.next().filter(|first| { histogram_batches.all(|batch| { - Arc::ptr_eq(first, batch) - || first - .as_arrow() - .to_data() - .ptr_eq(&batch.as_arrow().to_data()) + if Arc::ptr_eq(first, batch) { + return true; + } + first_data + .get_or_insert_with(|| first.as_arrow().to_data()) + .ptr_eq(&batch.as_arrow().to_data()) }) }); let needs_float = chunks.iter().any(|chunk| {