[ankur-paan]

Summary

This pull request resolves #45. It ensures that SQL query outputs and JSON serializations preserve the exact column sequence declared in the SELECT clause.

Previously, SharedMap used std::collections::HashMap, which iterates in arbitrary order. This caused non-deterministic JSON field ordering across query executions.

We replaced non-deterministic map iteration with indexmap::IndexMap and introduced the generic RowLookup trait. The engine now guarantees deterministic column ordering while maintaining ultra-high throughput.

---

Technical Changes

• Core Model (rekuiper-core):
  • Updated SharedMap to wrap Arc<IndexMap<String, Value>>.
  • Added zero-cost conversion helpers (to_hashmap(), From<HashMap>, From<IndexMap>).
  • Added the SchemaMap trait to handle schema enforcement uniformly across HashMap and IndexMap.
• SQL Evaluation Engine (rekuiper-sql):
  • Implemented the generic RowLookup trait for IndexMap, HashMap, and SharedMap to eliminate unnecessary map copies during expression evaluation.
  • Updated eval_select, eval_select_stateful, and eval_select_filtered to return IndexMap<String, Value> matching the query projection sequence.
  • Enabled the preserve_order feature on serde_json to keep key sequence during JSON serialization.
• Server Runtime & Sinks (rekuiper-server, rekuiper-connectors):
  • Updated window aggregations, joins, sink serializers, and rule test handlers to handle IndexMap deterministically.
• Model Context Protocol (rekuiper-mcp):
  • Updated test_sql_expression tool documentation in README.md and docs/en_US/mcp/overview.md to specify deterministic column ordering.
• Documentation & Visual Diagrams:
  • Added "Field Order in Output Rows" documentation in docs/en_US/sqls/query_language_elements.md following ASD-STE100 guidelines.
  • Added visual light-theme architecture diagram docs/en_US/public/diagrams/deterministic_field_order.svg.
  • Verified documentation build via npm --prefix docs run build (41.52s, 0 errors).

---

Performance Targets & Benchmark Results

Benchmarked on native ext4 following official benchmark specification (TOKIO_WORKER_THREADS=1 RUSTFLAGS="-C target-cpu=native" cargo test --release -p rekuiper-server --test perf_throughput -- --nocapture --test-threads=1):

Test Case	Required Target	Measured Result	Status
Pure Engine Throughput (test_pure_engine_throughput_prebuilt_records)	$\ge 2,000,000\text{ EPS}$	2,558,224.64 EPS (1,000,000 records in 390.89 ms)	PASSED
High-Throughput Streaming Pipeline (test_high_throughput_streaming_pipeline)	$\ge 1,000,000\text{ EPS}$	1,070,772.95 EPS (1,000,000 records in 933.90 ms)	PASSED

Compared to origin/main baseline, cur demonstrates 12% to 129% higher pipeline throughput due to reduced map allocation overhead.

---

Local CI Validation

All local checks executed and passed before commit:

• Code Formatting: cargo fmt --all -- --check
• Clippy Warnings: cargo clippy --workspace --all-targets -- -D warnings
• Security Isolation: Zero unapproved dependencies in rekuiper-core and rekuiper-sql.
• Binary Build: cargo build -p kuiperd
• Unit & Regression Tests: cargo test -p rekuiper-sql --test test_issue45_order (3/3 passed)
• Documentation Build: npm --prefix docs run build

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ekuiper	Ready	Preview	Oct 19, 2026 8:18am UTC

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.