Enum StreamingQueryResult 

#[non_exhaustive]
pub enum StreamingQueryResult {
    SelectStreaming {
        columns: Vec<String>,
        rows: Box<dyn Iterator<Item = Result<Vec<Value>>> + Send>,
        order_by: Option<Vec<OrderByExpr>>,
        limit: Option<usize>,
        offset: Option<usize>,
        distinct: bool,
        max_result_rows: Option<usize>,
        size_hint: Option<usize>,
    },
    SelectReady {
        columns: Vec<String>,
        rows: Vec<Vec<Value>>,
    },
    SelectColumnar {
        columns: Vec<String>,
        segments: Vec<ColumnarSeg>,
        row_indices: Option<Vec<usize>>,
        num_rows: usize,
        row_map: RowMap,
        order_by: Option<Vec<OrderByExpr>>,
    },
    Modification {
        affected_rows: usize,
    },
    Definition {
        message: String,
    },
}

🚀 流式查询结果（方案 C：零内存开销）

返回迭代器而不是 Vec，实现真正的流式查询。

#[non_exhaustive]: new variants may be added in future minor versions. Prefer materialize() / for_each() / row_count() over matching the enum directly — those accessors are stable across versions.

示例

// 新 API：流式迭代
let result = db.execute_streaming("SELECT * FROM robots WHERE age < 25")?;
result.for_each(|columns, row| {
    println!("{:?}: {:?}", columns, row);
    Ok(())
})?;

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

SelectStreaming

SELECT 流式结果

Fields

columns: Vec<String>

rows: Box<dyn Iterator<Item = Result<Vec<Value>>> + Send>

order_by: Option<Vec<OrderByExpr>>

🔧 ORDER BY 子句（在 materialize() 时应用）

limit: Option<usize>

🔧 LIMIT 子句（在 materialize() 时应用）

offset: Option<usize>

🔧 OFFSET 子句（在 materialize() 时应用）

distinct: bool

🔧 DISTINCT 标志（在 materialize() 时应用）

max_result_rows: Option<usize>

Safety limit: max rows to collect during materialize(). Truncates gracefully.

size_hint: Option<usize>

Capacity hint for materialize() — avoids repeated Vec reallocations. Populated from fast_row_count() when available.

SelectReady

🚀 Pre-materialized SELECT result (zero-overhead for fast PK paths)

Fields

columns: Vec<String>

rows: Vec<Vec<Value>>

SelectColumnar

🚀 Columnar result — typed arrays, zero per-row Vec allocation. Converted to Vec<Vec> lazily in materialize().

Fields

columns: Vec<String>

segments: Vec<ColumnarSeg>

Column segments (Fixed or Text), one per output column

row_indices: Option<Vec<usize>>

Row indices to include (None = all rows)

num_rows: usize

row_map: RowMap

order_by: Option<Vec<OrderByExpr>>

ORDER BY clauses to apply during materialization (None = no sort). Carried here so the zero-copy columnar scan path can still honor ORDER BY (expression/alias/ordinal) at materialize time.

Modification

INSERT/UPDATE/DELETE result

Fields

affected_rows: usize

Definition

CREATE/DROP result

Fields

message: String

Implementations

impl StreamingQueryResult

pub fn materialize(self) -> Result<QueryResult>

🔥 物化结果集（供向后兼容的 execute() 使用）

将流式结果立即加载到内存中，转换为 QueryResult。

pub fn materialize_with_hint( self, size_hint: Option<usize>, ) -> Result<QueryResult>

🚀 优化版物化：支持容量预分配

优化点

• Vec::with_capacity() 预分配容量，避免多次扩容
• 减少内存重分配次数，提升性能 20-30%
• 🔧 在物化时应用 ORDER BY、LIMIT、OFFSET、DISTINCT

参数

• size_hint: 预估的结果行数（来自优化器统计信息）

pub fn affected_rows(&self) -> usize

便利方法：逐行处理（零内存开销） 获取影响行数

pub fn row_count(&self) -> usize

Get row count without full materialization. O(1) for columnar/ready results.

pub fn columns(&self) -> Option<&[String]>

获取列名（仅 SELECT）

pub fn materialize_with_limit( self, max_rows: Option<usize>, ) -> Result<(QueryResult, bool)>

Materialize with an explicit row limit. Returns (QueryResult, has_more). has_more is true when the limit was hit (more rows exist in storage).

pub fn for_each<F>( self, callback: F, max_rows: Option<usize>, ) -> Result<ForEachResult>

where F: FnMut(&[String], &Vec<Value>) -> Result<StreamingControl>,

Process rows one at a time with a callback. O(1) memory for simple queries.

• No ORDER BY/DISTINCT: true streaming, O(1) memory, callback per-row
• ORDER BY + LIMIT: Top-K heap, O(LIMIT) memory
• ORDER BY no LIMIT: full sort, O(N) memory
• DISTINCT: O(unique rows) memory

When max_rows is hit, iteration stops and has_more is set to true.