From 3948eeb62192b481c93cac92f671df877837742c Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 17:34:00 -0800 Subject: [PATCH 01/14] Store notebook results in a process-wide Arrow cache Small results stay in memory; larger ones are written as Arrow IPC files in a locked per-process session directory, renamed into place once complete. Limits per result and for the whole cache keep a readable prefix, evicting the oldest other results first. The C ABI in sidequery_http.h exchanges batches through the Arrow C Data Interface. --- http/Cargo.lock | 273 ++++++++- http/Cargo.toml | 4 + http/src/cache_location.rs | 4 + http/src/lib.rs | 1 + http/src/results.rs | 1055 ++++++++++++++++++++++++++++++++++ http/src/results/tests.rs | 349 +++++++++++ src/include/sidequery_http.h | 42 ++ 7 files changed, 1727 insertions(+), 1 deletion(-) create mode 100644 http/src/results.rs create mode 100644 http/src/results/tests.rs diff --git a/http/Cargo.lock b/http/Cargo.lock index ef1c262..219809b 100644 --- a/http/Cargo.lock +++ b/http/Cargo.lock @@ -2,6 +2,20 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "ahash" +version = "0.8.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75" +dependencies = [ + "cfg-if", + "const-random", + "getrandom 0.3.4", + "once_cell", + "version_check", + "zerocopy", +] + [[package]] name = "android_system_properties" version = "0.1.6" @@ -11,6 +25,99 @@ dependencies = [ "libc", ] +[[package]] +name = "arrow-array" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0f3d22a41d3df78b71df0b685af219ae3a94188ab98d6fb29c958eb55c3247f4" +dependencies = [ + "ahash", + "arrow-buffer", + "arrow-data", + "arrow-schema", + "chrono", + "half", + "hashbrown", + "libc", + "num-complex", + "num-integer", + "num-traits", +] + +[[package]] +name = "arrow-buffer" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7bd46a530bc1a8e763102fc36c1dc0f51f3ffa150c78e7f5658ccb54b1458ade" +dependencies = [ + "bytes", + "half", + "num-bigint", + "num-traits", +] + +[[package]] +name = "arrow-cmp" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1913e57a64fbf2c4502fa6d54b547d6a1ae59e3146cbc15321d47468c937abd1" +dependencies = [ + "arrow-array", + "arrow-buffer", + "arrow-schema", +] + +[[package]] +name = "arrow-data" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "415b7fbc4cf56b080bb5677a4ae74211b5c79e571ed37a1d547633ec07f3b43b" +dependencies = [ + "arrow-buffer", + "arrow-schema", + "half", + "num-integer", + "num-traits", +] + +[[package]] +name = "arrow-ipc" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "45f3e766bccf5a0cb57a5de52a4cba450dea5171547c2cb5939b486d08887cba" +dependencies = [ + "arrow-array", + "arrow-buffer", + "arrow-data", + "arrow-schema", + "arrow-select", + "flatbuffers", +] + +[[package]] +name = "arrow-schema" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "de2c8e714b466404cdc1189e89f892426efea614d938e16c15518c340cd43ba3" +dependencies = [ + "bitflags", +] + +[[package]] +name = "arrow-select" +version = "60.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5af3f6656c5f2c6944f93d9a357a7f204c93d5f349385a44cf46c4a26fbcf30" +dependencies = [ + "ahash", + "arrow-array", + "arrow-buffer", + "arrow-cmp", + "arrow-data", + "arrow-schema", + "num-traits", +] + [[package]] name = "async-trait" version = "0.1.92" @@ -175,6 +282,26 @@ dependencies = [ "windows-link", ] +[[package]] +name = "const-random" +version = "0.1.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "87e00182fe74b066627d63b85fd550ac2998d4b0bd86bfed477a0ae4c7c71359" +dependencies = [ + "const-random-macro", +] + +[[package]] +name = "const-random-macro" +version = "0.1.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9d839f2a20b0aee515dc581a6172f2321f96cab76c1a38a4c584a194955390e" +dependencies = [ + "getrandom 0.2.17", + "once_cell", + "tiny-keccak", +] + [[package]] name = "core-foundation-sys" version = "0.8.7" @@ -199,6 +326,12 @@ dependencies = [ "libc", ] +[[package]] +name = "crunchy" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5" + [[package]] name = "crypto-common" version = "0.1.7" @@ -264,6 +397,16 @@ version = "0.1.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3e0f1c7c3a72c66fd80abe965175f7523475c0489a87d3ff9d6e8c87d87a9d2d" +[[package]] +name = "flatbuffers" +version = "25.12.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "35f6839d7b3b98adde531effaf34f0c2badc6f4735d26fe74709d8e513a96ef3" +dependencies = [ + "bitflags", + "rustc_version", +] + [[package]] name = "form_urlencoded" version = "1.2.2" @@ -384,6 +527,18 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi 5.3.0", + "wasip2", +] + [[package]] name = "getrandom" version = "0.4.3" @@ -393,7 +548,7 @@ dependencies = [ "cfg-if", "js-sys", "libc", - "r-efi", + "r-efi 6.0.0", "rand_core", "wasm-bindgen", ] @@ -411,6 +566,18 @@ dependencies = [ "url", ] +[[package]] +name = "half" +version = "2.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b" +dependencies = [ + "cfg-if", + "crunchy", + "num-traits", + "zerocopy", +] + [[package]] name = "hashbrown" version = "0.17.1" @@ -713,6 +880,12 @@ dependencies = [ "pkg-config", ] +[[package]] +name = "libm" +version = "0.2.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981" + [[package]] name = "libz-sys" version = "1.1.29" @@ -788,6 +961,34 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "num-bigint" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93e7820bc0a80a0238e650327316f929ba18d5be054b647490a3a6a339f3e7c0" +dependencies = [ + "num-integer", + "num-traits", +] + +[[package]] +name = "num-complex" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-integer" +version = "0.1.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" +dependencies = [ + "num-traits", +] + [[package]] name = "num-traits" version = "0.2.19" @@ -795,6 +996,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" dependencies = [ "autocfg", + "libm", ] [[package]] @@ -910,6 +1112,12 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + [[package]] name = "r-efi" version = "6.0.0" @@ -1053,6 +1261,15 @@ version = "2.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d" +[[package]] +name = "rustc_version" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92" +dependencies = [ + "semver", +] + [[package]] name = "rustix" version = "1.1.4" @@ -1139,6 +1356,12 @@ dependencies = [ "syn 3.0.5", ] +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" + [[package]] name = "serde" version = "1.0.229" @@ -1237,6 +1460,10 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" name = "sidequery-ui-http" version = "0.1.0" dependencies = [ + "arrow-array", + "arrow-data", + "arrow-ipc", + "arrow-schema", "axum", "bytes", "git2", @@ -1380,6 +1607,15 @@ dependencies = [ "syn 3.0.5", ] +[[package]] +name = "tiny-keccak" +version = "2.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c9d3793400a45f954c52e73d068316d76b6f4e36977e3fcebb13a2721e80237" +dependencies = [ + "crunchy", +] + [[package]] name = "tinystr" version = "0.8.4" @@ -1630,6 +1866,15 @@ version = "0.11.1+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + [[package]] name = "wasm-bindgen" version = "0.2.127" @@ -1855,6 +2100,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + [[package]] name = "writeable" version = "0.6.4" @@ -1884,6 +2135,26 @@ dependencies = [ "synstructure", ] +[[package]] +name = "zerocopy" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "zerofrom" version = "0.1.8" diff --git a/http/Cargo.toml b/http/Cargo.toml index cd08e7b..319ed6b 100644 --- a/http/Cargo.toml +++ b/http/Cargo.toml @@ -10,6 +10,10 @@ name = "sidequery_http" crate-type = ["staticlib", "rlib"] [dependencies] +arrow-array = { version = "=60.1.0", default-features = false, features = ["ffi"] } +arrow-data = { version = "=60.1.0", default-features = false } +arrow-ipc = { version = "=60.1.0", default-features = false } +arrow-schema = { version = "=60.1.0", default-features = false } axum = { version = "0.7", features = ["json", "query"] } bytes = "1" git2 = { version = "0.20", default-features = false, features = ["vendored-libgit2"] } diff --git a/http/src/cache_location.rs b/http/src/cache_location.rs index d1219f6..6b7a537 100644 --- a/http/src/cache_location.rs +++ b/http/src/cache_location.rs @@ -16,6 +16,10 @@ pub(super) fn notebook_state_path(root: &std::path::Path) -> Result Result { + Ok(cache_root()?.join("sidequery/sqlnb-extension/results")) +} + fn cache_root() -> Result { #[cfg(target_os = "macos")] let root = PathBuf::from( diff --git a/http/src/lib.rs b/http/src/lib.rs index 8620158..e72a90f 100644 --- a/http/src/lib.rs +++ b/http/src/lib.rs @@ -20,6 +20,7 @@ mod duckdb_ui; mod history; mod mcp; mod project_git; +mod results; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; use std::{ diff --git a/http/src/results.rs b/http/src/results.rs new file mode 100644 index 0000000..546b9ec --- /dev/null +++ b/http/src/results.rs @@ -0,0 +1,1055 @@ +//! Result cache behind `sqlnb_result_tee` and its readers (docs/results.md). +//! +//! The registry is process-global. Results small enough stay in memory; the +//! others are Arrow IPC files in one session directory per process, which a +//! lock file claims for the life of the process. +use crate::platform::{open_lease_file, open_lock_file, private_new_file, try_lock_file, LOCK_EX}; +use arrow_array::ffi::{from_ffi_and_data_type, FFI_ArrowArray, FFI_ArrowSchema}; +use arrow_array::ffi_stream::FFI_ArrowArrayStream; +use arrow_array::{ + Array, ArrayRef, BooleanArray, Int64Array, RecordBatch, RecordBatchIterator, + RecordBatchOptions, RecordBatchReader, StringArray, StructArray, +}; +use arrow_data::ArrayData; +use arrow_ipc::reader::{FileReader, FileReaderBuilder}; +use arrow_ipc::writer::{FileWriter, IpcWriteOptions}; +use arrow_schema::{ArrowError, DataType, Field, Schema, SchemaRef}; +use std::collections::HashMap; +use std::ffi::{c_char, CStr}; +use std::fs::{self, File}; +use std::io::{BufReader, BufWriter, Write}; +use std::path::{Path, PathBuf}; +use std::sync::{Arc, LazyLock, Mutex, MutexGuard}; +use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; + +/// A result with at most `head_rows` rows and this many bytes of Arrow buffers +/// is kept in memory and never written to a file. +const MEMORY_RESULT_BYTES: u64 = 1024 * 1024; +const MAX_META_BYTES: usize = 64 * 1024; +const SESSION_LOCK: &str = "session.lock"; +/// A live process locks its session directory moments after creating it, so an +/// unlocked directory older than this belongs to a process that is gone. +const SESSION_CLAIM_GRACE: Duration = Duration::from_secs(60); +const FILE_BUFFER_BYTES: usize = 1024 * 1024; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum LimitReason { + ResultBytes, + CacheBytes, + Io, +} + +impl LimitReason { + fn as_str(self) -> &'static str { + match self { + LimitReason::ResultBytes => "result-bytes", + LimitReason::CacheBytes => "cache-bytes", + LimitReason::Io => "io", + } + } +} + +#[derive(Clone, Copy, Debug)] +pub(crate) struct ResultLimits { + pub head_rows: u64, + pub max_result_bytes: u64, + pub max_cache_bytes: u64, +} + +pub(crate) struct ResultStore { + /// Parent of the session directories; unavailable without a cache root. + directory: Result, + state: Mutex, +} + +#[derive(Default)] +struct StoreState { + /// Databases that loaded the extension. The last one to close removes everything. + retained: usize, + session: Option, + next_sequence: u64, + entries: HashMap, +} + +struct Session { + directory: PathBuf, + /// Held open, and therefore locked, until the session ends. + _lock: File, +} + +struct Entry { + sequence: u64, + created_ms: i64, + meta: String, + schema: SchemaRef, + stored_bytes: u64, + /// Set once the writer finished; an unfinished result is never readable. + stored: Option>, +} + +struct StoredResult { + rows: u64, + /// False when the statement stopped reading at a limit: `rows` is then a lower bound. + rows_exact: bool, + stored_rows: u64, + limit_reason: Option, + elapsed_ms: u64, + /// The cumulative row count at the end of each stored batch. + batch_ends: Vec, + data: StoredData, +} + +enum StoredData { + Memory(Vec), + File(PathBuf), +} + +impl Entry { + fn remove_file(&self) { + if let Some(StoredData::File(path)) = self.stored.as_ref().map(|stored| &stored.data) { + let _ = fs::remove_file(path); + } + } +} + +impl ResultStore { + pub(crate) fn new(directory: Result) -> Self { + Self { + directory, + state: Mutex::new(StoreState::default()), + } + } + + fn lock(&self) -> MutexGuard<'_, StoreState> { + self.state.lock().unwrap_or_else(|poisoned| poisoned.into_inner()) + } + + pub(crate) fn retain(&self) { + self.lock().retained += 1; + } + + pub(crate) fn release(&self) { + let (entries, session) = { + let mut state = self.lock(); + state.retained = state.retained.saturating_sub(1); + if state.retained > 0 { + return; + } + (std::mem::take(&mut state.entries), state.session.take()) + }; + for entry in entries.values() { + entry.remove_file(); + } + if let Some(session) = session { + let directory = session.directory.clone(); + // Windows cannot remove a directory while the lock file is open. + drop(session); + let _ = fs::remove_dir_all(directory); + } + } + + /// Validates a result before its statement runs. + pub(crate) fn check(&self, id: &str, meta: &str, schema: &Schema) -> Result<(), String> { + validate_new_result(id, meta, schema)?; + if self.lock().entries.contains_key(id) { + return Err(exists(id)); + } + Ok(()) + } + + pub(crate) fn begin( + self: &Arc, + id: &str, + meta: &str, + schema: Schema, + limits: ResultLimits, + ) -> Result { + validate_new_result(id, meta, &schema)?; + let schema = Arc::new(schema); + { + let mut state = self.lock(); + if state.entries.contains_key(id) { + return Err(exists(id)); + } + state.next_sequence += 1; + let entry = Entry { + sequence: state.next_sequence, + created_ms: unix_ms(), + meta: meta.to_string(), + schema: schema.clone(), + stored_bytes: 0, + stored: None, + }; + state.entries.insert(id.to_string(), entry); + } + Ok(ResultWriter { + store: self.clone(), + id: id.to_string(), + batch_type: DataType::Struct(schema.fields().clone()), + schema, + limits, + started: Instant::now(), + stored_rows: 0, + stored_bytes: 0, + batch_ends: Vec::new(), + memory: Vec::new(), + file: None, + limit_reason: None, + finished: false, + }) + } + + /// Grants up to `requested` more stored bytes to the result `id`, evicting the + /// oldest other readable results when the whole cache would exceed its limit. + fn reserve( + &self, + id: &str, + stored_bytes: u64, + requested: u64, + limits: &ResultLimits, + ) -> (u64, Option) { + let result_room = limits.max_result_bytes.saturating_sub(stored_bytes); + let needed = requested.min(result_room); + let mut evicted = Vec::new(); + let granted = { + let mut state = self.lock(); + if !state.entries.contains_key(id) { + // The cache closed while this statement ran. + return (0, Some(LimitReason::Io)); + } + let mut used: u64 = state.entries.values().map(|entry| entry.stored_bytes).sum(); + while used.saturating_add(needed) > limits.max_cache_bytes { + let oldest = state + .entries + .iter() + .filter(|(other, entry)| other.as_str() != id && entry.stored.is_some()) + .min_by_key(|(_, entry)| entry.sequence) + .map(|(other, _)| other.clone()); + let Some(oldest) = oldest else { break }; + let entry = state.entries.remove(&oldest).expect("oldest entry exists"); + used -= entry.stored_bytes; + evicted.push(entry); + } + needed.min(limits.max_cache_bytes.saturating_sub(used)) + }; + for entry in evicted { + entry.remove_file(); + } + let reason = if granted == requested { + None + } else if granted == result_room { + Some(LimitReason::ResultBytes) + } else { + Some(LimitReason::CacheBytes) + }; + (granted, reason) + } + + fn record_stored_bytes(&self, id: &str, stored_bytes: u64) { + if let Some(entry) = self.lock().entries.get_mut(id) { + entry.stored_bytes = stored_bytes; + } + } + + fn complete(&self, id: &str, stored: StoredResult, stored_bytes: u64) { + let mut state = self.lock(); + match state.entries.get_mut(id) { + Some(entry) => { + entry.stored_bytes = stored_bytes; + entry.stored = Some(Arc::new(stored)); + } + None => { + if let StoredData::File(path) = stored.data { + let _ = fs::remove_file(path); + } + } + } + } + + fn forget(&self, id: &str) { + self.lock().entries.remove(id); + } + + /// Creates this process's session directory on first use, after removing + /// the directories of processes that are gone. + fn session_directory(&self) -> Result { + let mut state = self.lock(); + if let Some(session) = &state.session { + return Ok(session.directory.clone()); + } + if state.retained == 0 { + return Err("the result cache is closed".into()); + } + let parent = self.directory.clone()?; + fs::create_dir_all(&parent) + .map_err(|error| format!("failed to create {}: {error}", parent.display()))?; + remove_stale_sessions(&parent); + let directory = parent.join(uuid::Uuid::new_v4().simple().to_string()); + create_private_directory(&directory) + .map_err(|error| format!("failed to create {}: {error}", directory.display()))?; + let lock = open_lock_file(&directory.join(SESSION_LOCK))?; + if !try_lock_file(&lock, LOCK_EX, "result session")? { + return Err("a new result session is locked by another process".into()); + } + state.session = Some(Session { + directory: directory.clone(), + _lock: lock, + }); + Ok(directory) + } + + pub(crate) fn drop_result(&self, id: &str) -> bool { + let removed = { + let mut state = self.lock(); + match state.entries.get(id) { + Some(entry) if entry.stored.is_some() => state.entries.remove(id), + _ => None, + } + }; + removed.map(|entry| entry.remove_file()).is_some() + } + + fn readable(&self, id: &str) -> Result<(SchemaRef, Arc), String> { + let state = self.lock(); + state + .entries + .get(id) + .and_then(|entry| Some((entry.schema.clone(), entry.stored.clone()?))) + .ok_or_else(|| missing(id)) + } + + /// The columns `scan` reads: the stored columns, then the optional row number. + pub(crate) fn scan_schema(&self, id: &str, row_number: Option<&str>) -> Result { + let (schema, _) = self.readable(id)?; + with_row_number(&schema, row_number) + } + + /// Reads rows `[first_row, first_row + row_count)` of a stored result, + /// projected to `columns` (indices into `scan_schema`). + pub(crate) fn scan( + &self, + id: &str, + first_row: u64, + row_count: u64, + row_number: Option<&str>, + columns: &[usize], + ) -> Result { + // Open the file before a concurrent drop can remove it; an open scan + // keeps reading the file it opened. + let (schema, stored, file) = { + let state = self.lock(); + let entry = state.entries.get(id).ok_or_else(|| missing(id))?; + let stored = entry.stored.clone().ok_or_else(|| missing(id))?; + let file = match &stored.data { + StoredData::File(path) => Some(File::open(path).map_err(|_| missing(id))?), + StoredData::Memory(_) => None, + }; + (entry.schema.clone(), stored, file) + }; + let full_schema = with_row_number(&schema, row_number)?; + let stored_count = schema.fields().len(); + let mut stored_columns: Vec = columns + .iter() + .copied() + .filter(|&column| column < stored_count) + .collect(); + stored_columns.sort_unstable(); + stored_columns.dedup(); + let mut fields = Vec::with_capacity(columns.len()); + let mut sources = Vec::with_capacity(columns.len()); + for &column in columns { + let field = full_schema + .fields() + .get(column) + .ok_or_else(|| format!("result column {column} does not exist"))?; + fields.push(field.clone()); + sources.push(match stored_columns.binary_search(&column) { + Ok(position) => ColumnSource::Stored(position), + Err(_) => ColumnSource::RowNumber, + }); + } + let source = match file { + Some(file) => BatchSource::File(Box::new( + FileReaderBuilder::new() + .with_projection(stored_columns) + .build(BufReader::new(file)) + .map_err(|error| format!("failed to read stored result {id}: {error}"))?, + )), + None => BatchSource::Memory(stored_columns), + }; + let first_row = first_row.min(stored.stored_rows); + let end_row = first_row.saturating_add(row_count).min(stored.stored_rows); + let mut scan = StoredScan { + schema: Arc::new(Schema::new(fields)), + sources, + next_batch: stored.batch_ends.partition_point(|&end| end <= first_row), + stored, + source, + position: first_row, + end_row, + }; + if let BatchSource::File(reader) = &mut scan.source { + if scan.position < scan.end_row { + reader + .set_index(scan.next_batch) + .map_err(|error| format!("failed to read stored result {id}: {error}"))?; + } + } + Ok(scan) + } + + /// One row per readable result, newest first. + pub(crate) fn list(&self) -> RecordBatch { + let state = self.lock(); + let mut results: Vec<_> = state + .entries + .iter() + .filter_map(|(id, entry)| Some((id, entry, entry.stored.as_ref()?))) + .collect(); + results.sort_by_key(|(_, entry, _)| std::cmp::Reverse(entry.sequence)); + let int64 = |value: fn(&Entry, &StoredResult) -> u64| -> ArrayRef { + Arc::new(Int64Array::from_iter_values(results.iter().map(|(_, entry, stored)| { + i64::try_from(value(entry, stored)).unwrap_or(i64::MAX) + }))) + }; + let columns: Vec = vec![ + Arc::new(StringArray::from_iter_values(results.iter().map(|(id, _, _)| id.as_str()))), + int64(|_, stored| stored.rows), + int64(|_, stored| stored.stored_rows), + int64(|entry, _| entry.stored_bytes), + Arc::new(BooleanArray::from_iter(results.iter().map(|(_, _, stored)| { + Some(matches!(stored.data, StoredData::Memory(_))) + }))), + Arc::new(StringArray::from_iter(results.iter().map(|(_, _, stored)| { + stored.limit_reason.map(LimitReason::as_str) + }))), + Arc::new(StringArray::from_iter_values(results.iter().map(|(_, entry, _)| entry.meta.as_str()))), + Arc::new(Int64Array::from_iter_values(results.iter().map(|(_, entry, _)| entry.created_ms))), + int64(|_, stored| stored.elapsed_ms), + Arc::new(BooleanArray::from_iter( + results.iter().map(|(_, _, stored)| Some(stored.rows_exact)), + )), + ]; + RecordBatch::try_new(list_schema(), columns).expect("result list matches its schema") + } +} + +fn list_schema() -> SchemaRef { + Arc::new(Schema::new(vec![ + Field::new("id", DataType::Utf8, false), + Field::new("rows", DataType::Int64, false), + Field::new("stored_rows", DataType::Int64, false), + Field::new("stored_bytes", DataType::Int64, false), + Field::new("in_memory", DataType::Boolean, false), + Field::new("limit_reason", DataType::Utf8, true), + Field::new("meta", DataType::Utf8, false), + Field::new("created_ms", DataType::Int64, false), + Field::new("elapsed_ms", DataType::Int64, false), + Field::new("rows_exact", DataType::Boolean, false), + ])) +} + +pub(crate) fn valid_id(id: &str) -> bool { + id.len() == 32 && id.bytes().all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f')) +} + +fn validate_new_result(id: &str, meta: &str, schema: &Schema) -> Result<(), String> { + if !valid_id(id) { + return Err(format!("result id '{id}' must be 32 lowercase hexadecimal characters")); + } + if meta.len() > MAX_META_BYTES { + return Err(format!("result meta exceeds {MAX_META_BYTES} bytes")); + } + // Encoding the schema rejects every type the IPC file format cannot hold. + FileWriter::try_new_with_options(std::io::sink(), schema, write_options()) + .map(|_| ()) + .map_err(|error| format!("SQLNB_RESULT_UNSUPPORTED: {error}")) +} + +fn exists(id: &str) -> String { + format!("SQLNB_RESULT_EXISTS: result '{id}' already exists") +} + +fn missing(id: &str) -> String { + format!("SQLNB_RESULT_MISSING: result '{id}' does not exist or was evicted") +} + +fn with_row_number(schema: &Schema, row_number: Option<&str>) -> Result { + let mut fields = schema.fields().to_vec(); + if let Some(name) = row_number { + let lowered = name.to_lowercase(); + if name.is_empty() || fields.iter().any(|field| field.name().to_lowercase() == lowered) { + return Err(format!("row_number column '{name}' must be a new, non-empty column name")); + } + fields.push(Arc::new(Field::new(name, DataType::Int64, false))); + } + Ok(Schema::new_with_metadata(fields, schema.metadata().clone())) +} + +/// Uncompressed: LZ4 frames made files 2.6 times smaller on measured data but +/// writing 35% and full scans 40% slower (docs/results.md). +fn write_options() -> IpcWriteOptions { + IpcWriteOptions::default() +} + +fn unix_ms() -> i64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |elapsed| elapsed.as_millis() as i64) +} + +fn create_private_directory(path: &Path) -> std::io::Result<()> { + let mut builder = fs::DirBuilder::new(); + #[cfg(unix)] + std::os::unix::fs::DirBuilderExt::mode(&mut builder, 0o700); + builder.create(path) +} + +fn remove_stale_sessions(parent: &Path) { + let Ok(sessions) = fs::read_dir(parent) else { + return; + }; + for session in sessions.flatten() { + if session.file_type().is_ok_and(|kind| kind.is_dir()) && session_is_stale(&session.path()) { + let _ = fs::remove_dir_all(session.path()); + } + } +} + +fn session_is_stale(directory: &Path) -> bool { + let claimed_before_grace = |path: &Path| { + fs::metadata(path) + .and_then(|metadata| metadata.modified()) + .is_ok_and(|modified| modified.elapsed().is_ok_and(|age| age >= SESSION_CLAIM_GRACE)) + }; + let lock_path = directory.join(SESSION_LOCK); + match open_lease_file(&lock_path) { + // The process stopped between creating the directory and its lock. + Err(_) => claimed_before_grace(directory), + // The lock is released, and the file closed, when this function returns. + Ok(lock) => { + claimed_before_grace(&lock_path) + && try_lock_file(&lock, LOCK_EX, "result session").unwrap_or(false) + } + } +} + +/// Sum of the Arrow buffer bytes of a batch. +fn batch_bytes(batch: &RecordBatch) -> u64 { + fn data_bytes(data: &ArrayData) -> u64 { + data.buffers().iter().map(|buffer| buffer.len() as u64).sum::() + + data.nulls().map_or(0, |nulls| nulls.buffer().len() as u64) + + data.child_data().iter().map(data_bytes).sum::() + } + batch.columns().iter().map(|column| data_bytes(&column.to_data())).sum() +} + +struct CountingWriter { + inner: W, + bytes: u64, +} + +impl Write for CountingWriter { + fn write(&mut self, buffer: &[u8]) -> std::io::Result { + let written = self.inner.write(buffer)?; + self.bytes += written as u64; + Ok(written) + } + + fn flush(&mut self) -> std::io::Result<()> { + self.inner.flush() + } +} + +struct SpillFile { + writer: FileWriter>>, + temporary: PathBuf, + path: PathBuf, +} + +impl SpillFile { + fn create(directory: &Path, id: &str, schema: &Schema) -> Result { + let temporary = directory.join(format!("{id}.arrow.tmp")); + let file = private_new_file(&temporary) + .map_err(|error| format!("failed to create {}: {error}", temporary.display()))?; + let output = CountingWriter { + inner: BufWriter::with_capacity(FILE_BUFFER_BYTES, file), + bytes: 0, + }; + match FileWriter::try_new_with_options(output, schema, write_options()) { + Ok(writer) => Ok(Self { + writer, + temporary, + path: directory.join(format!("{id}.arrow")), + }), + Err(error) => { + let _ = fs::remove_file(&temporary); + Err(error.to_string()) + } + } + } + + fn bytes(&self) -> u64 { + self.writer.get_ref().bytes + } + + /// Writes the footer and publishes the file under its final name. + fn finish(self) -> Result<(PathBuf, u64), String> { + let temporary = self.temporary.clone(); + let result = (|| { + let output = self.writer.into_inner().map_err(|error| error.to_string())?; + let bytes = output.bytes; + drop(output.inner.into_inner().map_err(|error| error.to_string())?); + fs::rename(&self.temporary, &self.path).map_err(|error| error.to_string())?; + Ok((self.path, bytes)) + })(); + if result.is_err() { + let _ = fs::remove_file(temporary); + } + result + } + + fn discard(self) { + let temporary = self.temporary.clone(); + drop(self); + let _ = fs::remove_file(temporary); + } +} + +/// Stores one statement's rows. Dropping an unfinished writer discards the result. +pub(crate) struct ResultWriter { + store: Arc, + id: String, + schema: SchemaRef, + batch_type: DataType, + limits: ResultLimits, + started: Instant, + stored_rows: u64, + stored_bytes: u64, + batch_ends: Vec, + memory: Vec, + file: Option, + limit_reason: Option, + finished: bool, +} + +impl ResultWriter { + /// Imports and stores a batch exported through the C Data Interface. + fn append_ffi(&mut self, array: FFI_ArrowArray) -> bool { + if self.limit_reason.is_some() { + return false; + } + let batch = unsafe { from_ffi_and_data_type(array, self.batch_type.clone()) }.and_then(|data| { + RecordBatch::try_new(self.schema.clone(), StructArray::from(data).into_parts().1) + }); + match batch { + Ok(batch) => self.append(batch), + Err(_) => { + self.stop(LimitReason::Io); + false + } + } + } + + /// Stores a batch, or the prefix of it that the limits allow. Returns whether + /// later batches can still be stored. + pub(crate) fn append(&mut self, batch: RecordBatch) -> bool { + if self.limit_reason.is_some() { + return false; + } + let rows = batch.num_rows() as u64; + if rows == 0 { + return true; + } + let bytes = batch_bytes(&batch); + let (granted, reason) = self.store.reserve(&self.id, self.stored_bytes, bytes, &self.limits); + let (batch, rows, bytes) = if granted < bytes { + // Byte sizes are proportional enough to keep the prefix that fits. + let fitting = (u128::from(rows) * u128::from(granted) / u128::from(bytes.max(1))) as u64; + (batch.slice(0, fitting as usize), fitting, granted) + } else { + (batch, rows, bytes) + }; + if rows > 0 { + if let Err(error) = self.store_batch(batch, rows, bytes) { + self.stop(error); + return false; + } + } + match reason { + Some(reason) => { + self.stop(reason); + false + } + None => true, + } + } + + fn store_batch(&mut self, batch: RecordBatch, rows: u64, bytes: u64) -> Result<(), LimitReason> { + if self.file.is_none() + && (self.stored_rows + rows > self.limits.head_rows + || self.stored_bytes + bytes > MEMORY_RESULT_BYTES) + { + self.spill()?; + } + match &mut self.file { + Some(file) => { + file.writer.write(&batch).map_err(|_| LimitReason::Io)?; + self.stored_bytes = file.bytes(); + } + None => { + self.memory.push(batch); + self.stored_bytes += bytes; + } + } + self.stored_rows += rows; + self.batch_ends.push(self.stored_rows); + self.store.record_stored_bytes(&self.id, self.stored_bytes); + Ok(()) + } + + /// Moves the batches kept in memory into a new file. On failure the + /// batches stay in memory as the stored prefix. + fn spill(&mut self) -> Result<(), LimitReason> { + let directory = self.store.session_directory().map_err(|_| LimitReason::Io)?; + let mut file = SpillFile::create(&directory, &self.id, &self.schema).map_err(|_| LimitReason::Io)?; + for batch in &self.memory { + if file.writer.write(batch).is_err() { + file.discard(); + return Err(LimitReason::Io); + } + } + self.memory.clear(); + self.stored_bytes = file.bytes(); + self.file = Some(file); + Ok(()) + } + + /// Stops storing; the rows stored so far remain the result's prefix. + pub(crate) fn stop(&mut self, reason: LimitReason) { + self.limit_reason.get_or_insert(reason); + } + + /// Makes the result readable. `rows` is the number of rows the statement + /// produced, or only those it read when it stopped early (`rows_exact` false). + pub(crate) fn finish(mut self, rows: u64, rows_exact: bool) { + self.finished = true; + let elapsed_ms = self.started.elapsed().as_millis() as u64; + let data = match self.file.take() { + None => StoredData::Memory(std::mem::take(&mut self.memory)), + Some(file) => match file.finish() { + Ok((path, bytes)) => { + self.stored_bytes = bytes; + StoredData::File(path) + } + Err(_) => { + self.stored_rows = 0; + self.stored_bytes = 0; + self.batch_ends.clear(); + self.limit_reason = Some(LimitReason::Io); + StoredData::Memory(Vec::new()) + } + }, + }; + let stored = StoredResult { + rows, + rows_exact, + stored_rows: self.stored_rows, + limit_reason: self.limit_reason, + elapsed_ms, + batch_ends: std::mem::take(&mut self.batch_ends), + data, + }; + self.store.complete(&self.id, stored, self.stored_bytes); + } +} + +impl Drop for ResultWriter { + fn drop(&mut self) { + if self.finished { + return; + } + if let Some(file) = self.file.take() { + file.discard(); + } + self.store.forget(&self.id); + } +} + +enum ColumnSource { + /// Position among the stored columns the scan reads. + Stored(usize), + RowNumber, +} + +enum BatchSource { + /// The stored columns to project from each batch. + Memory(Vec), + File(Box>>), +} + +/// A window of a stored result, read batch by batch. +pub(crate) struct StoredScan { + schema: SchemaRef, + sources: Vec, + stored: Arc, + source: BatchSource, + next_batch: usize, + position: u64, + end_row: u64, +} + +impl StoredScan { + fn read_batch(&mut self) -> Result { + let index = self.next_batch; + self.next_batch += 1; + match &mut self.source { + BatchSource::Memory(columns) => match &self.stored.data { + StoredData::Memory(batches) => batches[index].project(columns), + StoredData::File(_) => unreachable!("memory scans read memory results"), + }, + BatchSource::File(reader) => reader.next().unwrap_or_else(|| { + Err(ArrowError::IpcError("stored result has fewer batches than recorded".into())) + }), + } + } +} + +impl Iterator for StoredScan { + type Item = Result; + + fn next(&mut self) -> Option { + if self.position >= self.end_row { + return None; + } + let index = self.next_batch; + let batch_start = index.checked_sub(1).map_or(0, |previous| self.stored.batch_ends[previous]); + let batch_end = self.stored.batch_ends[index]; + let batch = match self.read_batch() { + Ok(batch) => batch, + Err(error) => return Some(Err(error)), + }; + let from = self.position - batch_start; + let length = batch_end.min(self.end_row) - self.position; + let batch = batch.slice(from as usize, length as usize); + let columns = self + .sources + .iter() + .map(|source| match source { + ColumnSource::Stored(position) => batch.column(*position).clone(), + ColumnSource::RowNumber => Arc::new(Int64Array::from_iter_values( + (self.position..self.position + length).map(|row| row as i64), + )) as ArrayRef, + }) + .collect(); + self.position += length; + Some(RecordBatch::try_new_with_options( + self.schema.clone(), + columns, + &RecordBatchOptions::new().with_row_count(Some(length as usize)), + )) + } +} + +impl RecordBatchReader for StoredScan { + fn schema(&self) -> SchemaRef { + self.schema.clone() + } +} + +static STORE: LazyLock> = + LazyLock::new(|| Arc::new(ResultStore::new(crate::cache_location::results_directory()))); + +/// Runs an exported function, turning errors and panics into `false` and `*error_out`. +fn exported(error_out: *mut *mut c_char, body: impl FnOnce() -> Result<(), String>) -> bool { + match std::panic::catch_unwind(std::panic::AssertUnwindSafe(body)) { + Ok(Ok(())) => true, + Ok(Err(error)) => { + crate::set_error(error_out, error); + false + } + Err(_) => { + crate::set_error(error_out, "unexpected panic in the result cache".into()); + false + } + } +} + +/// Reads a required UTF-8 argument; null pointers are rejected as absent. +unsafe fn text<'a>(value: *const c_char, name: &str) -> Result<&'a str, String> { + if value.is_null() { + return Err(format!("{name} must not be null")); + } + unsafe { CStr::from_ptr(value) } + .to_str() + .map_err(|_| format!("{name} must be UTF-8")) +} + +unsafe fn optional_text<'a>(value: *const c_char, name: &str) -> Result, String> { + if value.is_null() { + Ok(None) + } else { + unsafe { text(value, name) }.map(Some) + } +} + +unsafe fn import_schema(schema: *mut FFI_ArrowSchema) -> Result { + if schema.is_null() { + return Err("result schema must not be null".into()); + } + let schema = unsafe { FFI_ArrowSchema::from_raw(schema) }; + Schema::try_from(&schema).map_err(|error| format!("SQLNB_RESULT_UNSUPPORTED: {error}")) +} + +#[no_mangle] +pub extern "C" fn sidequery_results_retain() { + let _ = std::panic::catch_unwind(|| STORE.retain()); +} + +#[no_mangle] +pub extern "C" fn sidequery_results_release() { + let _ = std::panic::catch_unwind(|| STORE.release()); +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_check( + id: *const c_char, + meta: *const c_char, + schema: *mut FFI_ArrowSchema, + error_out: *mut *mut c_char, +) -> bool { + exported(error_out, || { + let schema = unsafe { import_schema(schema) }?; + STORE.check(unsafe { text(id, "id") }?, unsafe { text(meta, "meta") }?, &schema) + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_begin( + id: *const c_char, + meta: *const c_char, + schema: *mut FFI_ArrowSchema, + head_rows: u64, + max_result_bytes: u64, + max_cache_bytes: u64, + error_out: *mut *mut c_char, +) -> *mut ResultWriter { + let mut writer = None; + exported(error_out, || { + let schema = unsafe { import_schema(schema) }?; + let limits = ResultLimits { + head_rows, + max_result_bytes, + max_cache_bytes, + }; + writer = Some(STORE.begin(unsafe { text(id, "id") }?, unsafe { text(meta, "meta") }?, schema, limits)?); + Ok(()) + }); + writer.map_or(std::ptr::null_mut(), |writer| Box::into_raw(Box::new(writer))) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_append( + writer: *mut ResultWriter, + batch: *mut FFI_ArrowArray, +) -> bool { + std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + let writer = unsafe { &mut *writer }; + writer.append_ffi(unsafe { FFI_ArrowArray::from_raw(batch) }) + })) + .unwrap_or(false) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_stop(writer: *mut ResultWriter) { + let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + unsafe { &mut *writer }.stop(LimitReason::Io) + })); +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_finish( + writer: *mut ResultWriter, + rows: u64, + rows_exact: bool, +) { + let writer = unsafe { Box::from_raw(writer) }; + let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| writer.finish(rows, rows_exact))); +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_abort(writer: *mut ResultWriter) { + let writer = unsafe { Box::from_raw(writer) }; + let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| drop(writer))); +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_results_list( + out: *mut FFI_ArrowArrayStream, + error_out: *mut *mut c_char, +) -> bool { + exported(error_out, || { + let reader = RecordBatchIterator::new([Ok(STORE.list())], list_schema()); + unsafe { out.write(FFI_ArrowArrayStream::new(Box::new(reader))) }; + Ok(()) + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_schema( + id: *const c_char, + row_number: *const c_char, + out: *mut FFI_ArrowSchema, + error_out: *mut *mut c_char, +) -> bool { + exported(error_out, || { + let schema = STORE.scan_schema( + unsafe { text(id, "id") }?, + unsafe { optional_text(row_number, "row_number") }?, + )?; + let schema = FFI_ArrowSchema::try_from(&schema).map_err(|error| error.to_string())?; + unsafe { out.write(schema) }; + Ok(()) + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_scan( + id: *const c_char, + first_row: u64, + row_count: u64, + row_number: *const c_char, + columns: *const u64, + column_count: u64, + out: *mut FFI_ArrowArrayStream, + error_out: *mut *mut c_char, +) -> bool { + exported(error_out, || { + let columns: Vec = if column_count == 0 { + Vec::new() + } else { + unsafe { std::slice::from_raw_parts(columns, column_count as usize) } + .iter() + .map(|&column| column as usize) + .collect() + }; + let scan = STORE.scan( + unsafe { text(id, "id") }?, + first_row, + row_count, + unsafe { optional_text(row_number, "row_number") }?, + &columns, + )?; + unsafe { out.write(FFI_ArrowArrayStream::new(Box::new(scan))) }; + Ok(()) + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_drop(id: *const c_char) -> bool { + std::panic::catch_unwind(|| unsafe { text(id, "id") }.is_ok_and(|id| STORE.drop_result(id))) + .unwrap_or(false) +} + +#[cfg(test)] +mod tests; diff --git a/http/src/results/tests.rs b/http/src/results/tests.rs new file mode 100644 index 0000000..71a0cfb --- /dev/null +++ b/http/src/results/tests.rs @@ -0,0 +1,349 @@ +use super::*; +use arrow_array::cast::AsArray; +use arrow_array::types::Int64Type; + +const UNLIMITED: u64 = u64::MAX; + +fn open_store(directory: &Path) -> Arc { + let store = Arc::new(ResultStore::new(Ok(directory.to_path_buf()))); + store.retain(); + store +} + +fn schema() -> Schema { + Schema::new(vec![ + Field::new("value", DataType::Int64, true), + Field::new("label", DataType::Utf8, true), + ]) +} + +fn batch(start: i64, rows: i64) -> RecordBatch { + RecordBatch::try_new( + Arc::new(schema()), + vec![ + Arc::new(Int64Array::from_iter_values(start..start + rows)), + Arc::new(StringArray::from_iter_values( + (start..start + rows).map(|value| format!("row-{value}")), + )), + ], + ) + .unwrap() +} + +fn limits(head_rows: u64) -> ResultLimits { + ResultLimits { + head_rows, + max_result_bytes: UNLIMITED, + max_cache_bytes: UNLIMITED, + } +} + +fn id(number: u8) -> String { + format!("{number:032x}") +} + +/// Stores batches of the given sizes, numbering rows from 0. +fn store_result(store: &Arc, id: &str, sizes: &[i64], limits: ResultLimits) { + let mut writer = store.begin(id, "meta", schema(), limits).unwrap(); + let mut start = 0; + for &size in sizes { + writer.append(batch(start, size)); + start += size; + } + writer.finish(start as u64, true); +} + +/// The scanned values of the first scanned column, and the row numbers when requested. +fn scan_values( + store: &ResultStore, + id: &str, + first_row: u64, + row_count: u64, + row_number: Option<&str>, + columns: &[usize], +) -> Vec> { + let scan = store.scan(id, first_row, row_count, row_number, columns).unwrap(); + let mut values = vec![Vec::new(); columns.len()]; + for batch in scan { + let batch = batch.unwrap(); + for (column, values) in values.iter_mut().enumerate() { + let array = batch.column(column); + if let Some(int64) = array.as_primitive_opt::() { + values.extend(int64.values().iter().copied()); + } else { + values.extend(array.as_string::().iter().map(|label| { + label.unwrap().trim_start_matches("row-").parse::().unwrap() + })); + } + } + } + values +} + +fn listed(store: &ResultStore) -> Vec<(String, i64, i64, bool, Option, bool)> { + let list = store.list(); + let ids = list.column(0).as_string::(); + let rows = list.column(1).as_primitive::(); + let stored_rows = list.column(2).as_primitive::(); + let in_memory = list.column(4).as_boolean(); + let reasons = list.column(5).as_string::(); + let rows_exact = list.column(9).as_boolean(); + (0..list.num_rows()) + .map(|row| { + ( + ids.value(row).to_string(), + rows.value(row), + stored_rows.value(row), + in_memory.value(row), + reasons.is_valid(row).then(|| reasons.value(row).to_string()), + rows_exact.value(row), + ) + }) + .collect() +} + +fn session_files(directory: &Path) -> Vec { + let mut files = Vec::new(); + for session in fs::read_dir(directory).into_iter().flatten().flatten() { + for file in fs::read_dir(session.path()).unwrap().flatten() { + files.push(file.file_name().to_string_lossy().into_owned()); + } + } + files.sort(); + files +} + +#[test] +fn small_results_stay_in_memory_and_large_ones_spill_to_a_file() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + store_result(&store, &id(1), &[4, 4], limits(8)); + assert!(session_files(directory.path()).is_empty()); + store_result(&store, &id(2), &[4, 4, 1], limits(8)); + assert_eq!(session_files(directory.path()), [format!("{}.arrow", id(2)), SESSION_LOCK.to_string()]); + assert_eq!( + listed(&store), + [ + (id(2), 9, 9, false, None, true), + (id(1), 8, 8, true, None, true), + ] + ); + for result in [id(1), id(2)] { + let values = scan_values(&store, &result, 0, UNLIMITED, None, &[0, 1]); + let expected: Vec = (0..values[0].len() as i64).collect(); + assert_eq!(values, [expected.clone(), expected]); + } +} + +#[test] +fn windows_cross_batch_boundaries_with_projection_and_row_numbers() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + for (result, head_rows) in [(id(1), 100), (id(2), 0)] { + store_result(&store, &result, &[3, 5, 4], limits(head_rows)); + assert_eq!( + scan_values(&store, &result, 2, 7, Some("position"), &[2, 1]), + [(2..9).collect::>(), (2..9).collect()] + ); + assert_eq!(scan_values(&store, &result, 8, UNLIMITED, None, &[0])[0], (8..12).collect::>()); + assert_eq!(scan_values(&store, &result, 3, 5, None, &[0])[0], (3..8).collect::>()); + assert!(scan_values(&store, &result, 12, UNLIMITED, None, &[0])[0].is_empty()); + assert!(scan_values(&store, &result, 0, 0, None, &[0])[0].is_empty()); + } +} + +#[test] +fn row_number_must_not_collide_with_a_result_column() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + store_result(&store, &id(1), &[2], limits(10)); + assert!(store.scan_schema(&id(1), Some("VALUE")).is_err()); + assert!(store.scan_schema(&id(1), Some("")).is_err()); + let schema = store.scan_schema(&id(1), Some("row_index")).unwrap(); + assert_eq!(schema.field(2).name(), "row_index"); + assert_eq!(schema.field(2).data_type(), &DataType::Int64); +} + +#[test] +fn ids_are_validated_and_unique() { + assert!(valid_id("0123456789abcdef0123456789abcdef")); + for invalid in ["", "0123456789ABCDEF0123456789abcdef", "0123456789abcdef0123456789abcde", "../123456789abcdef0123456789abcd", "0123456789abcdef0123456789abcdeg"] { + assert!(!valid_id(invalid), "{invalid}"); + } + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + assert!(store.begin("not-an-id", "", schema(), limits(1)).is_err()); + assert!(store.check(&id(1), &"x".repeat(MAX_META_BYTES + 1), &schema()).is_err()); + let writer = store.begin(&id(1), "", schema(), limits(1)).unwrap(); + assert!(store.check(&id(1), "", &schema()).unwrap_err().starts_with("SQLNB_RESULT_EXISTS:")); + assert!(store.begin(&id(1), "", schema(), limits(1)).is_err()); + writer.finish(0, true); + assert!(store.check(&id(1), "", &schema()).is_err()); + assert!(store.scan_schema(&id(9), None).unwrap_err().starts_with("SQLNB_RESULT_MISSING:")); +} + +#[test] +fn unfinished_results_are_neither_listed_nor_readable_and_abort_leaves_nothing() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let mut writer = store.begin(&id(1), "", schema(), limits(2)).unwrap(); + assert!(writer.append(batch(0, 5))); + assert_eq!(session_files(directory.path()), [format!("{}.arrow.tmp", id(1)), SESSION_LOCK.to_string()]); + assert!(listed(&store).is_empty()); + assert!(store.scan(&id(1), 0, UNLIMITED, None, &[0]).is_err()); + assert!(!store.drop_result(&id(1))); + drop(writer); + assert_eq!(session_files(directory.path()), [SESSION_LOCK]); + store_result(&store, &id(1), &[1], limits(2)); + assert_eq!(listed(&store).len(), 1); +} + +#[test] +fn the_result_limit_keeps_a_prefix_and_counts_every_row() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let batch_size = batch_bytes(&batch(0, 100)); + let mut writer = store + .begin( + &id(1), + "", + schema(), + ResultLimits { + head_rows: 1000, + max_result_bytes: batch_size + batch_size / 2, + max_cache_bytes: UNLIMITED, + }, + ) + .unwrap(); + assert!(writer.append(batch(0, 100))); + assert!(!writer.append(batch(100, 100))); + assert!(!writer.append(batch(200, 100))); + writer.finish(300, true); + let [(_, rows, stored_rows, _, reason, _)] = listed(&store).try_into().unwrap(); + assert_eq!((rows, reason.as_deref()), (300, Some("result-bytes"))); + assert!((140..=160).contains(&stored_rows), "{stored_rows}"); + let values = scan_values(&store, &id(1), 0, UNLIMITED, None, &[0]); + assert_eq!(values[0], (0..stored_rows).collect::>()); +} + +#[test] +fn the_cache_limit_evicts_the_oldest_other_results() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let batch_size = batch_bytes(&batch(0, 100)); + let cache = ResultLimits { + head_rows: 1000, + max_result_bytes: UNLIMITED, + max_cache_bytes: batch_size * 2, + }; + store_result(&store, &id(1), &[100], cache); + store_result(&store, &id(2), &[100], cache); + store_result(&store, &id(3), &[100], cache); + let remaining: Vec<_> = listed(&store).into_iter().map(|result| result.0).collect(); + assert_eq!(remaining, [id(3), id(2)]); + assert!(store.scan_schema(&id(1), None).unwrap_err().starts_with("SQLNB_RESULT_MISSING:")); + + // An unfinished result cannot be evicted; the newer one stops storing instead. + let mut writer = store.begin(&id(4), "", schema(), cache).unwrap(); + assert!(writer.append(batch(0, 100))); + store_result(&store, &id(5), &[100, 100], cache); + writer.finish(100, true); + assert_eq!( + listed(&store), + [ + (id(5), 200, 100, true, Some("cache-bytes".into()), true), + (id(4), 100, 100, true, None, true), + ] + ); +} + +#[test] +fn stopping_early_reports_a_lower_bound() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let mut writer = store.begin(&id(1), "", schema(), limits(10)).unwrap(); + writer.append(batch(0, 5)); + writer.stop(LimitReason::Io); + assert!(!writer.append(batch(5, 5))); + writer.finish(10, false); + assert_eq!(listed(&store), [(id(1), 10, 5, true, Some("io".into()), false)]); +} + +#[test] +fn an_unavailable_cache_directory_keeps_the_memory_prefix() { + let store = Arc::new(ResultStore::new(Err("no cache root".into()))); + store.retain(); + let mut writer = store.begin(&id(1), "", schema(), limits(4)).unwrap(); + assert!(writer.append(batch(0, 4))); + assert!(!writer.append(batch(4, 4))); + writer.finish(8, true); + assert_eq!(listed(&store), [(id(1), 8, 4, true, Some("io".into()), true)]); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..4).collect::>()); +} + +#[test] +fn dropping_keeps_open_scans_readable() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + store_result(&store, &id(1), &[3, 3], limits(0)); + let scan = store.scan(&id(1), 0, UNLIMITED, None, &[0]).unwrap(); + assert!(store.drop_result(&id(1))); + assert!(!store.drop_result(&id(1))); + assert_eq!(session_files(directory.path()), [SESSION_LOCK]); + assert_eq!(scan.map(|batch| batch.unwrap().num_rows()).sum::(), 6); + assert!(store.scan(&id(1), 0, UNLIMITED, None, &[0]).is_err()); +} + +#[test] +fn closing_the_last_database_removes_the_session() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + store.retain(); + store_result(&store, &id(1), &[3], limits(0)); + store.release(); + assert_eq!(listed(&store).len(), 1); + store.release(); + assert!(listed(&store).is_empty()); + assert_eq!(fs::read_dir(directory.path()).unwrap().count(), 0); +} + +#[test] +fn stale_sessions_are_removed_when_a_session_starts() { + let directory = tempfile::tempdir().unwrap(); + let make_session = |name: &str, age: Duration| { + let session = directory.path().join(name); + fs::create_dir(&session).unwrap(); + fs::write(session.join("1.arrow"), b"data").unwrap(); + let lock = File::options().create(true).truncate(true).write(true).open(session.join(SESSION_LOCK)).unwrap(); + lock.set_modified(SystemTime::now() - age).unwrap(); + session + }; + let old = SESSION_CLAIM_GRACE * 2; + let abandoned = make_session("abandoned", old); + let live = make_session("live", old); + let live_lock = open_lock_file(&live.join(SESSION_LOCK)).unwrap(); + assert!(try_lock_file(&live_lock, LOCK_EX, "test session").unwrap()); + let starting = make_session("starting", Duration::ZERO); + + let store = open_store(directory.path()); + store_result(&store, &id(1), &[2], limits(0)); + assert!(!abandoned.exists()); + assert!(live.join("1.arrow").exists()); + assert!(starting.join("1.arrow").exists()); + assert_eq!(fs::read_dir(directory.path()).unwrap().count(), 3); +} + +#[test] +fn batches_arrive_through_the_c_data_interface() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let mut writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); + for start in [0, 4] { + let exported = StructArray::from(batch(start, 4)).into_data(); + let (array, _) = arrow_array::ffi::to_ffi(&exported).unwrap(); + assert!(writer.append_ffi(array)); + } + writer.finish(8, true); + let values = scan_values(&store, &id(1), 0, UNLIMITED, Some("n"), &[1, 2]); + assert_eq!(values, [(0..8).collect::>(), (0..8).collect()]); +} diff --git a/src/include/sidequery_http.h b/src/include/sidequery_http.h index 99d3dca..44f688c 100644 --- a/src/include/sidequery_http.h +++ b/src/include/sidequery_http.h @@ -22,6 +22,48 @@ uint16_t sidequery_http_unused_port(void); // A null previous validates a new notebook and starts its content version at 1. char *sidequery_duckdb_ui_next_version(const char *previous, const char *edited, char **error_out); +// Result cache (docs/results.md). Arrow structs follow the C Data Interface; +// a function that takes one releases it. Errors are written to *error_out, to +// be freed with sidequery_http_string_free. +struct ArrowSchema; +struct ArrowArray; +struct ArrowArrayStream; +typedef struct sidequery_result_writer sidequery_result_writer; +// Each database that loads the extension retains the cache; the last release +// removes every result and this process's session directory. +void sidequery_results_retain(void); +void sidequery_results_release(void); +// Validates a new result's id, meta and schema before its statement runs. +bool sidequery_result_check(const char *id, const char *meta, struct ArrowSchema *schema, + char **error_out); +// Registers an unreadable result; finish makes it readable, abort discards it. +sidequery_result_writer *sidequery_result_begin(const char *id, const char *meta, + struct ArrowSchema *schema, uint64_t head_rows, + uint64_t max_result_bytes, + uint64_t max_cache_bytes, char **error_out); +// Stores the rows of a struct array whose fields match the schema. Returns +// false once storing stopped; the rows stored before remain the result. +bool sidequery_result_append(sidequery_result_writer *writer, struct ArrowArray *batch); +// Stops storing because the caller could not convert its rows (limit reason "io"). +void sidequery_result_stop(sidequery_result_writer *writer); +// rows counts every row the statement produced; rows_exact is false when the +// statement stopped reading early and rows is only a lower bound. +void sidequery_result_finish(sidequery_result_writer *writer, uint64_t rows, bool rows_exact); +void sidequery_result_abort(sidequery_result_writer *writer); +// Exports one row per readable result, newest first. +bool sidequery_results_list(struct ArrowArrayStream *out, char **error_out); +// Exports the columns of a stored result, then a BIGINT column named row_number +// unless row_number is null. +bool sidequery_result_schema(const char *id, const char *row_number, struct ArrowSchema *out, + char **error_out); +// Reads rows [first_row, first_row + row_count) of a stored result, projected to +// columns (indices into its schema above). +bool sidequery_result_scan(const char *id, uint64_t first_row, uint64_t row_count, + const char *row_number, const uint64_t *columns, uint64_t column_count, + struct ArrowArrayStream *out, char **error_out); +// Removes a readable result; false when it does not exist. +bool sidequery_result_drop(const char *id); + #ifdef __cplusplus } #endif From c2f9c5d31f948933088dac1efe28383520395632 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 17:34:00 -0800 Subject: [PATCH 02/14] Add sqlnb_result_tee and functions to read back stored results sqlnb_result_tee passes a statement's first rows through in full chunks while storing every row, and can stop reading once storing stops. sqlnb_results, sqlnb_result and sqlnb_result_drop list, read back through DuckDB's Arrow scan, and remove results. The MCP agent connection cannot reach any of them. --- scripts/runtime-smoke.mjs | 123 ++++++++- src/include/sqlnb_results.hpp | 484 +++++++++++++++++++++++++++++++++ src/sidequery_ui_extension.cpp | 12 +- test/sql/results.test | 145 ++++++++++ 4 files changed, 761 insertions(+), 3 deletions(-) create mode 100644 src/include/sqlnb_results.hpp create mode 100644 test/sql/results.test diff --git a/scripts/runtime-smoke.mjs b/scripts/runtime-smoke.mjs index 1a2dc0a..3bd3b6e 100644 --- a/scripts/runtime-smoke.mjs +++ b/scripts/runtime-smoke.mjs @@ -5,6 +5,7 @@ import { existsSync, mkdirSync, mkdtempSync, + readdirSync, readFileSync, realpathSync, statSync, @@ -102,10 +103,22 @@ writeFileSync(join(notebookRoot, 'nested', 'query.sql'), 'select 2;\n'); writeFileSync(join(notebookRoot, 'ignored.txt'), 'not a notebook'); symlinkSync(outsideRoot, join(notebookRoot, 'outside-link')); +const childHome = mkdtempSync(join(tmpdir(), 'sidequery-ui-cli-home.')); const child = spawn(duckdb, [...cliOptions, ':memory:', '-json'], { stdio: ['pipe', 'pipe', 'pipe'], - env: cliEnvironment(), + env: cliEnvironment(childHome), }); +// The result cache follows the platform cache directory of the CLI's HOME. +const resultSessions = join( + process.platform === 'darwin' + ? join(childHome, 'Library', 'Caches') + : process.env.XDG_CACHE_HOME || join(childHome, '.cache'), + 'sidequery', 'sqlnb-extension', 'results', +); +function resultFiles() { + if (!existsSync(resultSessions)) return []; + return readdirSync(resultSessions).flatMap((session) => readdirSync(join(resultSessions, session))); +} let stdout = ''; let stderr = ''; const waiters = []; @@ -629,6 +642,110 @@ for (const ownerFunction of ['sqlnb_status', 'sqlnb_stop']) { assert.equal(firstValue(await runSQL('select 42 as recovered')), 42); } +// Result cache (docs/results.md), present with the final 2.0 Arrow scan API. +const hasResultCache = firstValue(await runSQL( + "select count(*) from duckdb_functions() where function_name = 'sqlnb_result_tee'", +)) > 0; +if (hasResultCache) { + const resultId = (number) => number.toString(16).padStart(32, '0'); + const large = resultId(1); + const small = resultId(2); + const source = "select i, i * 1.5 as amount, 'c-' || (i % 7) as label from range(50000) t(i)"; + // Only the head passes through; every row is stored. + assert.deepEqual( + await runSQL(`select count(*) as n, min(i) as low, max(i) as high from sqlnb_result_tee((${source}), id := '${large}', meta := '{"cell":1}')`), + [{ n: 10240, low: 0, high: 10239 }], + ); + assert.deepEqual( + await runSQL(`select count(*) as n from sqlnb_result_tee((select 1 as one), id := '${small}')`), + [{ n: 1 }], + ); + assert.equal( + firstValue(await runSQL("select string_agg(column_name || ' ' || column_type, ', ') from (describe select * from sqlnb_results())")), + 'id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN', + ); + assert.deepEqual( + firstValue(await runSQL(`select list(r order by r.id) from (select id, rows, stored_rows, in_memory, limit_reason, meta, rows_exact from sqlnb_results() where id in ('${large}', '${small}')) r`)), + [ + { id: large, rows: 50000, stored_rows: 50000, in_memory: false, limit_reason: null, meta: '{"cell":1}', rows_exact: true }, + { id: small, rows: 1, stored_rows: 1, in_memory: true, limit_reason: null, meta: '', rows_exact: true }, + ], + ); + assert.deepEqual(resultFiles().filter((file) => file.endsWith('.arrow')), [`${large}.arrow`]); + // Reading back returns the input, in order, with its original column types. + assert.equal( + firstValue(await runSQL(`select count(*) from ((${source}) except all (select * from sqlnb_result('${large}')))`)), + 0, + ); + assert.equal( + firstValue(await runSQL(`select bool_and(i = position) and count(*) = 50000 from sqlnb_result('${large}', row_number := 'position')`)), + true, + ); + assert.equal( + firstValue(await runSQL(`select list(column_type) = (select list(column_type) from (describe ${source})) from (describe select * from sqlnb_result('${large}'))`)), + true, + ); + assert.deepEqual( + await runSQL(`select count(*) as n, min(i) as low, max(position) as high from sqlnb_result('${large}', first_row := 45000, row_count := 200, row_number := 'position')`), + [{ n: 200, low: 45000, high: 45199 }], + ); + await expectSQLError(`select * from sqlnb_result('${resultId(99)}')`, /SQLNB_RESULT_MISSING:/); + await expectSQLError(`select * from sqlnb_result_tee((select 1), id := '${large}')`, /SQLNB_RESULT_EXISTS:/); + await expectSQLError( + `select * from sqlnb_result_tee((select 'a'::enum ('a', 'b') as mood), id := '${resultId(3)}')`, + /SQLNB_RESULT_UNSUPPORTED:/, + ); + // A failing statement leaves nothing readable and frees its id. + await expectSQLError( + `select count(*) from sqlnb_result_tee((select case when i = 40000 then error('tee failed') else i end as i from range(50000) t(i)), id := '${resultId(3)}')`, + /tee failed/, + ); + assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_results() where id = '${resultId(3)}'`)), 0); + assert.deepEqual(resultFiles().filter((file) => file.includes(resultId(3))), []); + assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_result_tee((select 1), id := '${resultId(3)}')`)), 1); + // A limit stops storing; stop_at_limit also stops reading. The notebook passes + // the Instant SQL verdict as a constant scalar call. + const endless = 'select i from range(100000000) t(i)'; + await runSQL(`select count(*) from sqlnb_result_tee((${endless}), id := '${resultId(4)}', max_result_bytes := 100000, stop_at_limit := system.main.sqlnb_is_read_only(${sqlLiteral(endless)}))`); + await runSQL(`select count(*) from sqlnb_result_tee((${endless}), id := '${resultId(5)}', max_result_bytes := 100000, stop_at_limit := false)`); + const [stopped, counted] = firstValue(await runSQL(`select list(r order by r.id) from (select id, rows, stored_rows, limit_reason, rows_exact from sqlnb_results() where id in ('${resultId(4)}', '${resultId(5)}')) r`)) + .map(({ id, ...result }) => result); + assert(stopped.rows < 1000000 && stopped.stored_rows > 0 && stopped.stored_rows <= stopped.rows, JSON.stringify(stopped)); + assert.equal(stopped.limit_reason, 'result-bytes'); + assert.equal(stopped.rows_exact, false); + assert.deepEqual(counted, { rows: 100000000, stored_rows: stopped.stored_rows, limit_reason: 'result-bytes', rows_exact: true }); + assert.equal( + firstValue(await runSQL(`select count(*) = ${stopped.stored_rows} and max(i) = ${stopped.stored_rows - 1} from sqlnb_result('${resultId(4)}')`)), + true, + ); + // The agent connection cannot reach the cache, on either SQL tool. + for (const sql of [ + 'select * from sqlnb_results()', + `select * from sqlnb_result('${small}')`, + `select sqlnb_result_drop('${small}')`, + `select * from sqlnb_result_tee((select 1), id := '${resultId(6)}')`, + ]) { + for (const execute of [false, true]) { + const rejected = await mcpSQL(sql, execute); + assert.equal(rejected.isError, true, `agent reached the result cache: ${sql}`); + assert.equal(rejected.structuredContent.error.code, 'POLICY_BLOCKED'); + } + } + // Quack sessions (the notebook's path) share the process-wide cache. + const quackTee = spawnSync(duckdb, [...cliOptions, ':memory:', '-csv', '-noheader', '-c', [ + loadExtensions(false), + `from quack_query(${sqlLiteral(`quack:${endpoint.hostname}:${endpoint.port}`)}, ${sqlLiteral(`select count(*) from sqlnb_result_tee((select * from range(30000) t(i)), id := '${resultId(7)}')`)}, token = ${sqlLiteral(token)})`, + ].join('; ')], { encoding: 'utf8', timeout: queryTimeoutMs, env: cliEnvironment() }); + assert.equal(quackTee.status, 0, quackTee.stderr || quackTee.stdout); + assert.equal(quackTee.stdout.trim(), '10240'); + assert.equal(firstValue(await runSQL(`select rows from sqlnb_results() where id = '${resultId(7)}'`)), 30000); + assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${large}')`)), true); + assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${large}')`)), false); + assert.deepEqual(resultFiles().filter((file) => file.includes(large)), []); + await expectSQLError(`select * from sqlnb_result('${large}')`, /SQLNB_RESULT_MISSING:/); + assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_results() where id = '${small}'`)), 1); +} + const serversBeforeStop = await runSQL('select count(*) as count from quack_server_list()'); assert.equal(firstValue(serversBeforeStop), 1); assert.equal(firstValue(await runSQL('select sqlnb_stop()')), true); @@ -772,6 +889,8 @@ await new Promise((resolve, reject) => { : reject(new Error(`DuckDB exited ${code}: ${stderr}`)), ); }); +// Closing the database removes the process's result session. +assert.deepEqual(existsSync(resultSessions) ? readdirSync(resultSessions) : [], []); console.log( - 'native SQLNB bootstrap, named/default options, compatibility aliases, official Quack query, notebook history/restore, scoped Git commits/push, isolation, shutdown, security, and asset proxy smoke passed', + 'native SQLNB bootstrap, named/default options, compatibility aliases, official Quack query, notebook history/restore, scoped Git commits/push, result cache, isolation, shutdown, security, and asset proxy smoke passed', ); diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp new file mode 100644 index 0000000..3039c65 --- /dev/null +++ b/src/include/sqlnb_results.hpp @@ -0,0 +1,484 @@ +#pragma once + +// Result cache (docs/results.md). sqlnb_result_tee passes a statement's first +// rows through while the Rust library stores every row as Arrow; the other +// functions list, read back and drop stored results through DuckDB's Arrow scan. +#if __has_include("duckdb/main/query_result_stream.hpp") +#include "duckdb/common/arrow/arrow_appender.hpp" +#include "duckdb/common/arrow/arrow_converter.hpp" +#include "duckdb/common/arrow/arrow_wrapper.hpp" +#include "duckdb/common/type_visitor.hpp" +#include "duckdb/common/vector_operations/unary_executor.hpp" +#include "duckdb/function/scalar_function.hpp" +#include "duckdb/function/table/arrow.hpp" +#include "duckdb/function/table/arrow/arrow_duck_schema.hpp" +#include "duckdb/function/table_function.hpp" +#include "duckdb/main/client_context.hpp" +#include "duckdb/main/client_context_state.hpp" +#include "duckdb/main/config.hpp" +#include "duckdb/main/extension/extension_loader.hpp" + +namespace duckdb { +namespace sqlnb_results { + +static constexpr int64_t DEFAULT_HEAD_ROWS = 10240; +static constexpr int64_t DEFAULT_HEAD_BYTES = 4LL * 1024 * 1024; +static constexpr int64_t DEFAULT_MAX_RESULT_BYTES = 4LL * 1024 * 1024 * 1024; +static constexpr int64_t DEFAULT_MAX_CACHE_BYTES = 16LL * 1024 * 1024 * 1024; +// A stored record batch holds this many rows, or fewer once its buffers reach +// BATCH_BYTES, which bounds the memory one batch takes for very wide rows. +static constexpr idx_t BATCH_ROWS = 8192; +static constexpr idx_t BATCH_BYTES = 64 * 1024 * 1024; +static constexpr const char *AGENT_CONNECTION = "sqlnb_agent_connection"; + +// Marks the MCP agent's connection, which must not reach the result cache. +class AgentConnection : public ClientContextState {}; + +static void MarkAgentConnection(ClientContext &context) { + context.registered_state->GetOrCreate(AGENT_CONNECTION); +} + +static void RejectAgentConnection(ClientContext &context, const char *function) { + if (context.registered_state->Get(AGENT_CONNECTION)) { + throw InvalidInputException("POLICY_BLOCKED: the agent connection cannot call %s", function); + } +} + +[[noreturn]] static void ThrowCacheError(char *error) { + string message = error ? error : "the result cache failed"; + sidequery_http_string_free(error); + throw InvalidInputException("%s", message); +} + +// Stored results use DuckDB's lossless Arrow types, whatever the caller's Arrow +// settings, so that UUID, HUGEINT, JSON and the like read back as themselves. +static ClientProperties StorageProperties(ClientContext &context) { + return ClientProperties("UTC", ArrowOffsetSize::REGULAR, false, false, true, ArrowFormatVersion::V1_0, + &context); +} + +// DuckDB's Arrow scan reads ENUMs back as VARCHAR, and aliased types (such as +// extension types) as their storage type unless an Arrow extension type keeps +// them, as it keeps JSON. +static bool ReadsBackAsAnotherType(ClientContext &context, const LogicalType &type) { + auto &config = DBConfig::GetConfig(context); + return TypeVisitor::Contains(type, [&](const LogicalType &child) { + return child.id() == LogicalTypeId::ENUM || (child.HasAlias() && !config.HasArrowExtension(child)); + }); +} + +static void ExportSchema(ClientContext &context, const vector &types, const vector &names, + ArrowSchema &schema) { + for (idx_t column = 0; column < types.size(); column++) { + if (ReadsBackAsAnotherType(context, types[column])) { + throw InvalidInputException("SQLNB_RESULT_UNSUPPORTED: column '%s' has type %s, which the result cache " + "cannot read back unchanged", + names[column], types[column].ToString()); + } + } + auto properties = StorageProperties(context); + try { + ArrowConverter::ToArrowSchema(&schema, types, names, properties); + } catch (std::exception &error) { + throw InvalidInputException("SQLNB_RESULT_UNSUPPORTED: %s", ErrorData(error).RawMessage()); + } +} + +static const Value &NamedParameter(TableFunctionBindInput &input, const char *name) { + auto &value = input.named_parameters.at(name); + if (value.IsNull()) { + throw InvalidInputException("%s must not be NULL", name); + } + return value; +} + +static idx_t CountParameter(TableFunctionBindInput &input, const char *name) { + auto count = NamedParameter(input, name).GetValue(); + if (count < 0) { + throw InvalidInputException("%s must not be negative", name); + } + return NumericCast(count); +} + +struct TeeBindData : public TableFunctionData { + string id; + string meta; + idx_t head_rows; + idx_t head_bytes; + idx_t max_result_bytes; + idx_t max_cache_bytes; + bool stop_at_limit; + vector types; + vector names; +}; + +static unique_ptr TeeBind(ClientContext &context, TableFunctionBindInput &input, + vector &return_types, vector &names) { + RejectAgentConnection(context, "sqlnb_result_tee"); + auto data = make_uniq(); + data->id = NamedParameter(input, "id").ToString(); + data->meta = NamedParameter(input, "meta").ToString(); + data->head_rows = CountParameter(input, "head_rows"); + data->head_bytes = CountParameter(input, "head_bytes"); + data->max_result_bytes = CountParameter(input, "max_result_bytes"); + data->max_cache_bytes = CountParameter(input, "max_cache_bytes"); + data->stop_at_limit = NamedParameter(input, "stop_at_limit").GetValue(); + data->types = input.input_table_types; + data->names = IdentifiersToStrings(input.input_table_names); + // Reject unsupported columns and taken ids before anything executes. + ArrowSchemaWrapper schema; + ExportSchema(context, data->types, data->names, schema.arrow_schema); + char *error = nullptr; + if (!sidequery_result_check(data->id.c_str(), data->meta.c_str(), &schema.arrow_schema, &error)) { + ThrowCacheError(error); + } + return_types = input.input_table_types; + names = input.input_table_names; + return std::move(data); +} + +// Passes the first rows of the input through and stores every row. Rows leave +// in full chunks so that Quack can send them before the statement ends. +class TeeState : public GlobalTableFunctionState { +public: + TeeState(ClientContext &context, const TeeBindData &bind) + : types(bind.types), properties(StorageProperties(context)), + extension_types(ArrowTypeExtensionData::GetExtensionTypes(context, bind.types)), + head_rows(bind.head_rows), head_bytes(bind.head_bytes), stop_at_limit(bind.stop_at_limit), + head_open(bind.head_rows > 0 && bind.head_bytes > 0) { + ArrowSchemaWrapper schema; + ExportSchema(context, types, bind.names, schema.arrow_schema); + char *error = nullptr; + writer = sidequery_result_begin(bind.id.c_str(), bind.meta.c_str(), &schema.arrow_schema, bind.head_rows, + bind.max_result_bytes, bind.max_cache_bytes, &error); + if (!writer) { + ThrowCacheError(error); + } + pending.Initialize(context, types); + } + + // An interrupted or failed statement never finishes its result. + ~TeeState() override { + if (writer) { + sidequery_result_abort(writer); + } + } + + // One thread runs the pipeline, so rows reach the cache in the statement's order. + idx_t MaxThreads() const override { + return 1; + } + + OperatorResultType Consume(DataChunk &input, DataChunk &output) { + while (input_offset < input.size() && !StoppedAtLimit()) { + if (!head_open) { + Store(input, input_offset, input.size()); + rows += input.size() - input_offset; + input_offset = input.size(); + break; + } + auto chunk_rows = MinValue(STANDARD_VECTOR_SIZE, head_rows - returned_rows); + auto take = MinValue(input.size() - input_offset, chunk_rows - pending.size()); + pending.Append(input, SelectionVector(input_offset, take), take); + input_offset += take; + rows += take; + if (pending.size() == chunk_rows) { + EmitHead(output); + if (input_offset < input.size() && !StoppedAtLimit()) { + return OperatorResultType::HAVE_MORE_OUTPUT; + } + } + } + if (StoppedAtLimit()) { + if (output.size() > 0) { + // DuckDB drops the rows of a call that returns FINISHED; finish on the next call. + return OperatorResultType::HAVE_MORE_OUTPUT; + } + // Stop reading, as a LIMIT would, and publish what was stored. DuckDB does + // not call the final function of an operator that finished early. + input_offset = 0; + Complete(false); + return OperatorResultType::FINISHED; + } + input_offset = 0; + return OperatorResultType::NEED_MORE_INPUT; + } + + void Finish(DataChunk &output) { + if (!writer) { + return; + } + if (head_open && pending.size() > 0) { + // The whole input was shorter than the head. + EmitHead(output); + } + Complete(true); + } + +private: + bool StoppedAtLimit() const { + return stop_at_limit && !storing; + } + + void EmitHead(DataChunk &output) { + auto bytes = Store(pending, 0, pending.size()); + output.Append(pending); + returned_rows += pending.size(); + returned_bytes += bytes; + pending.Reset(); + if (returned_rows >= head_rows || returned_bytes >= head_bytes) { + head_open = false; + } + } + + // Converts rows into the batch being built and returns their Arrow bytes. + // Rows are converted while storing, or while the head still needs their size. + idx_t Store(DataChunk &chunk, idx_t from, idx_t to) { + if (!storing && !head_open) { + return 0; + } + try { + if (!batch) { + batch = make_uniq(types, BATCH_ROWS, properties, extension_types); + } + auto before = batch->ByteSize(); + batch->Append(chunk, from, to, chunk.size()); + auto bytes = batch->ByteSize() - before; + if (batch->RowCount() >= BATCH_ROWS || batch->ByteSize() >= BATCH_BYTES) { + Flush(); + } + return bytes; + } catch (std::exception &) { + // A failure to store never fails the statement. + batch.reset(); + StopStoring(); + return 0; + } + } + + void Flush() { + if (!batch || batch->RowCount() == 0) { + return; + } + ArrowArrayWrapper array; + array.arrow_array = batch->Finalize(); + batch.reset(); + if (storing) { + storing = sidequery_result_append(writer, &array.arrow_array); + } + } + + void StopStoring() { + if (storing) { + storing = false; + sidequery_result_stop(writer); + } + } + + void Complete(bool rows_exact) { + try { + Flush(); + } catch (std::exception &) { + StopStoring(); + } + sidequery_result_finish(writer, rows, rows_exact); + writer = nullptr; + } + + sidequery_result_writer *writer = nullptr; + const vector types; + const ClientProperties properties; + const unordered_map> extension_types; + const idx_t head_rows; + const idx_t head_bytes; + const bool stop_at_limit; + // Rows of the head that do not fill a chunk yet. + DataChunk pending; + unique_ptr batch; + bool head_open; + bool storing = true; + idx_t input_offset = 0; + idx_t rows = 0; + idx_t returned_rows = 0; + idx_t returned_bytes = 0; +}; + +static unique_ptr TeeInit(ClientContext &context, TableFunctionInitInput &input) { + return make_uniq(context, input.bind_data->Cast()); +} + +static OperatorResultType TeeExecute(ExecutionContext &, TableFunctionInput &data, DataChunk &input, + DataChunk &output) { + return data.global_state->Cast().Consume(input, output); +} + +static OperatorFinalizeResultType TeeFinal(ExecutionContext &, TableFunctionInput &data, DataChunk &output) { + data.global_state->Cast().Finish(output); + return OperatorFinalizeResultType::FINISHED; +} + +static unique_ptr BindArrowScan(ClientContext &context, shared_ptr factory, + bool projection_pushdown, vector &return_types, + vector &names) { + auto data = make_uniq(std::move(factory)); + data->factory->GetSchema(data->schema_root.arrow_schema); + ArrowTableFunction::PopulateArrowTableSchema(context, data->arrow_table, data->schema_root.arrow_schema); + names = StringsToIdentifiers(data->arrow_table.GetNames()); + return_types = data->arrow_table.GetTypes(); + data->all_types = return_types; + data->projection_pushdown_enabled = projection_pushdown; + return std::move(data); +} + +class StoredResultFactory : public ArrowScanFactory { +public: + StoredResultFactory(string id_p, idx_t first_row_p, idx_t row_count_p, Value row_number_p) + : id(std::move(id_p)), first_row(first_row_p), row_count(row_count_p), has_row_number(!row_number_p.IsNull()), + row_number(has_row_number ? row_number_p.ToString() : string()) { + } + + void GetSchema(ArrowSchema &schema) override { + char *error = nullptr; + if (!sidequery_result_schema(id.c_str(), RowNumber(), &schema, &error)) { + ThrowCacheError(error); + } + } + + unique_ptr ProduceStream(ArrowStreamParameters ¶meters) override { + // The scan expects the projected columns in the order of its column ids. + auto &projection = parameters.projected_columns.filter_to_col; + vector columns; + for (idx_t position = 0; position < projection.size(); position++) { + columns.push_back(projection.at(position)); + } + auto stream = make_uniq(); + char *error = nullptr; + if (!sidequery_result_scan(id.c_str(), first_row, row_count, RowNumber(), columns.data(), columns.size(), + &stream->arrow_array_stream, &error)) { + ThrowCacheError(error); + } + return stream; + } + +private: + const char *RowNumber() const { + return has_row_number ? row_number.c_str() : nullptr; + } + + const string id; + const idx_t first_row; + const idx_t row_count; + const bool has_row_number; + const string row_number; +}; + +static unique_ptr StoredResultBind(ClientContext &context, TableFunctionBindInput &input, + vector &return_types, vector &names) { + RejectAgentConnection(context, "sqlnb_result"); + if (input.inputs[0].IsNull()) { + throw InvalidInputException("id must not be NULL"); + } + auto first_row = CountParameter(input, "first_row"); + auto &row_count = input.named_parameters.at("row_count"); + if (!row_count.IsNull() && row_count.GetValue() < 0) { + throw InvalidInputException("row_count must not be negative"); + } + auto factory = make_shared_ptr( + input.inputs[0].ToString(), first_row, + row_count.IsNull() ? NumericLimits::Maximum() : NumericCast(row_count.GetValue()), + input.named_parameters.at("row_number")); + return BindArrowScan(context, std::move(factory), true, return_types, names); +} + +// Mirrors DuckDB's Arrow scan, so that a parallel read keeps the stored order. +static OperatorPartitionData StoredResultPartition(ClientContext &, TableFunctionGetPartitionInput &input) { + if (input.partition_info.RequiresPartitionColumns()) { + throw InternalException("sqlnb_result does not provide partition columns"); + } + return OperatorPartitionData(input.local_state->Cast().batch_index); +} + +class ResultListFactory : public ArrowScanFactory { +public: + void GetSchema(ArrowSchema &schema) override { + auto stream = ProduceList(); + if (stream->arrow_array_stream.get_schema(&stream->arrow_array_stream, &schema) != 0) { + throw IOException("failed to read the result list schema"); + } + } + + unique_ptr ProduceStream(ArrowStreamParameters &) override { + return ProduceList(); + } + +private: + static unique_ptr ProduceList() { + auto stream = make_uniq(); + char *error = nullptr; + if (!sidequery_results_list(&stream->arrow_array_stream, &error)) { + ThrowCacheError(error); + } + return stream; + } +}; + +static unique_ptr ResultListBind(ClientContext &context, TableFunctionBindInput &, + vector &return_types, vector &names) { + RejectAgentConnection(context, "sqlnb_results"); + return BindArrowScan(context, make_shared_ptr(), false, return_types, names); +} + +static void DropResult(DataChunk &args, ExpressionState &state, Vector &result) { + RejectAgentConnection(state.GetContext(), "sqlnb_result_drop"); + UnaryExecutor::Execute(args.data[0], result, args.size(), [](string_t id) { + return sidequery_result_drop(id.GetString().c_str()); + }); +} + +} // namespace sqlnb_results + +static void RegisterSQLNBResults(ExtensionLoader &loader) { + using namespace sqlnb_results; + TableFunction tee("sqlnb_result_tee", + FunctionSignature() + .AddPositionalOnly("input", LogicalType::TABLE) + .AddKeywordOnly("id", LogicalType::VARCHAR) + .AddKeywordOnly("head_rows", LogicalType::BIGINT, Value::BIGINT(DEFAULT_HEAD_ROWS)) + .AddKeywordOnly("head_bytes", LogicalType::BIGINT, Value::BIGINT(DEFAULT_HEAD_BYTES)) + .AddKeywordOnly("meta", LogicalType::VARCHAR, Value("")) + .AddKeywordOnly("max_result_bytes", LogicalType::BIGINT, + Value::BIGINT(DEFAULT_MAX_RESULT_BYTES)) + .AddKeywordOnly("max_cache_bytes", LogicalType::BIGINT, + Value::BIGINT(DEFAULT_MAX_CACHE_BYTES)) + .AddKeywordOnly("stop_at_limit", LogicalType::BOOLEAN, Value::BOOLEAN(false)), + nullptr, TeeBind, TeeInit); + tee.in_out_function = TeeExecute; + tee.in_out_function_final = TeeFinal; + loader.RegisterFunction(tee); + + TableFunction results("sqlnb_results", {}, ArrowTableFunction::ArrowScanFunction, ResultListBind, + ArrowTableFunction::ArrowScanInitGlobal, ArrowTableFunction::ArrowScanInitLocal); + results.parallelism = TableFunctionParallelism::SEQUENTIAL; + loader.RegisterFunction(results); + + TableFunction result("sqlnb_result", + FunctionSignature() + .AddParameter("id", LogicalType::VARCHAR) + .AddKeywordOnly("first_row", LogicalType::BIGINT, Value::BIGINT(0)) + .AddKeywordOnly("row_count", LogicalType::BIGINT, Value(LogicalType::BIGINT)) + .AddKeywordOnly("row_number", LogicalType::VARCHAR, Value(LogicalType::VARCHAR)), + ArrowTableFunction::ArrowScanFunction, StoredResultBind, + ArrowTableFunction::ArrowScanInitGlobal, ArrowTableFunction::ArrowScanInitLocal); + result.projection_pushdown = true; + result.get_partition_data = StoredResultPartition; + result.parallelism = TableFunctionParallelism::SEQUENTIAL; + loader.RegisterFunction(result); + + ScalarFunction drop("sqlnb_result_drop", {LogicalType::VARCHAR}, LogicalType::BOOLEAN, DropResult); + drop.SetVolatile(); + drop.SetFallible(); + loader.RegisterFunction(drop); +} + +} // namespace duckdb +#endif diff --git a/src/sidequery_ui_extension.cpp b/src/sidequery_ui_extension.cpp index 2e4059e..b8c7518 100644 --- a/src/sidequery_ui_extension.cpp +++ b/src/sidequery_ui_extension.cpp @@ -37,6 +37,7 @@ #include "duckdb/main/query_result_stream.hpp" #define SQLNB_HAS_RESULT_STREAM 1 #include "sqlnb_read_policy.hpp" +#include "sqlnb_results.hpp" #endif #if __has_include("duckdb/main/extension_repository_manager.hpp") @@ -173,7 +174,11 @@ static void StopQuack(DatabaseInstance &database, const string &listen_uri) { // database -> extension state -> agent connection -> database reference cycle. class McpConnection { public: - explicit McpConnection(DatabaseInstance &database) : connection(database) {} + explicit McpConnection(DatabaseInstance &database) : connection(database) { +#ifdef SQLNB_HAS_RESULT_STREAM + sqlnb_results::MarkAgentConnection(*connection.context); +#endif + } static char *Query(void *context, uint64_t id, const char *sql, uint64_t max_rows, uint64_t max_bytes, bool read_only) noexcept { @@ -586,6 +591,10 @@ class SqlnbServer { class SqlnbState : public StorageExtensionInfo { public: + // Results outlive their statements but not the last database using them. + SqlnbState() { sidequery_results_retain(); } + ~SqlnbState() override { sidequery_results_release(); } + string Start(shared_ptr database, const string &remote_url, const string &local_dir, int port, bool open_browser, const string ¬ebook_root, bool mcp, connection_t caller) { std::lock_guard guard(lock); @@ -745,6 +754,7 @@ static void LoadInternal(ExtensionLoader &loader) { RegisterDuckDBUINotebooks(loader); #ifdef SQLNB_HAS_RESULT_STREAM RegisterSQLNBReadPolicy(loader); + RegisterSQLNBResults(loader); #endif auto state_extension = make_shared_ptr(); state_extension->storage_info = make_uniq(); diff --git a/test/sql/results.test b/test/sql/results.test new file mode 100644 index 0000000..4526eb4 --- /dev/null +++ b/test/sql/results.test @@ -0,0 +1,145 @@ +# Result cache (docs/results.md). Results are process-wide, so every id here is +# unique to this file. +require sqlnb + +# Only the head passes through the tee; every row is stored. +query III +select count(*), min(i), max(i) from sqlnb_result_tee((select i, i * 1.5 as amount, 'c-' || (i % 7) as label from range(50000) t(i)), id := 'a0000000000000000000000000000001', meta := '{"cell":1}'); +---- +10240 0 10239 + +query I +select count(*) from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000002'); +---- +1 + +# A result with more rows than its head is written to a file. +query I +select count(*) from sqlnb_result_tee((select * from range(5000) t(i)), id := 'a0000000000000000000000000000003', head_rows := 3000); +---- +3000 + +query TIIITTTI +select id, rows, stored_rows, in_memory, limit_reason, meta, rows_exact, elapsed_ms >= 0 and created_ms > 0 from sqlnb_results() where id like 'a000000000000000000000000000000%' order by id; +---- +a0000000000000000000000000000001 50000 50000 false NULL {"cell":1} true true +a0000000000000000000000000000002 1 1 true NULL (empty) true true +a0000000000000000000000000000003 5000 5000 false NULL (empty) true true + +query T +select string_agg(column_name || ' ' || column_type, ', ') from (describe select * from sqlnb_results()); +---- +id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN + +# Reading back returns the input, in order, with its original column types. +query I +select count(*) from ((select i, i * 1.5 as amount, 'c-' || (i % 7) as label from range(50000) t(i)) except all (select * from sqlnb_result('a0000000000000000000000000000001'))); +---- +0 + +query I +select bool_and(i = position) and count(*) = 50000 from sqlnb_result('a0000000000000000000000000000001', row_number := 'position'); +---- +true + +query TT +select column_name, column_type from (describe select * from sqlnb_result('a0000000000000000000000000000001')); +---- +i BIGINT +amount DECIMAL(21,1) +label VARCHAR + +query III +select count(*), min(i), max(position) from sqlnb_result('a0000000000000000000000000000001', first_row := 45000, row_count := 200, row_number := 'position'); +---- +200 45000 45199 + +query I +select count(*) from sqlnb_result('a0000000000000000000000000000001', first_row := 60000); +---- +0 + +statement error +select * from sqlnb_result('a0000000000000000000000000000001', row_number := 'label'); +---- +must be a new, non-empty column name + +statement error +select * from sqlnb_result('a0000000000000000000000000000099'); +---- +SQLNB_RESULT_MISSING: + +statement error +select * from sqlnb_result_tee((select 1), id := 'a0000000000000000000000000000001'); +---- +SQLNB_RESULT_EXISTS: + +statement error +select * from sqlnb_result_tee((select 1), id := 'not-an-id'); +---- +must be 32 lowercase hexadecimal characters + +statement error +select * from sqlnb_result_tee((select 'a'::enum ('a', 'b') as mood), id := 'a0000000000000000000000000000004'); +---- +SQLNB_RESULT_UNSUPPORTED: + +# A failing statement leaves nothing readable and frees its id. +statement error +select count(*) from sqlnb_result_tee((select case when i = 40000 then error('tee failed') else i end as i from range(50000) t(i)), id := 'a0000000000000000000000000000004'); +---- +tee failed + +query I +select count(*) from sqlnb_results() where id = 'a0000000000000000000000000000004'; +---- +0 + +query I +select count(*) from sqlnb_result_tee((select 1), id := 'a0000000000000000000000000000004'); +---- +1 + +# A limit stops storing but every row is still counted; stop_at_limit also +# stops reading, so rows becomes a lower bound. +statement ok +select count(*) from sqlnb_result_tee((select i from range(100000000) t(i)), id := 'a0000000000000000000000000000005', max_result_bytes := 100000, stop_at_limit := true); + +statement ok +select count(*) from sqlnb_result_tee((select i from range(10000000) t(i)), id := 'a0000000000000000000000000000006', max_result_bytes := 100000); + +query TIITI +select id, rows < 1000000, stored_rows > 0 and stored_rows <= rows, limit_reason, rows_exact from sqlnb_results() where id in ('a0000000000000000000000000000005', 'a0000000000000000000000000000006') order by id; +---- +a0000000000000000000000000000005 true true result-bytes false +a0000000000000000000000000000006 false true result-bytes true + +query I +select rows from sqlnb_results() where id = 'a0000000000000000000000000000006'; +---- +10000000 + +query I +select (select count(*) = max(i) + 1 from sqlnb_result('a0000000000000000000000000000005')) and (select count(*) from sqlnb_result('a0000000000000000000000000000005')) = (select stored_rows from sqlnb_results() where id = 'a0000000000000000000000000000005'); +---- +true + +query I +select sqlnb_result_drop('a0000000000000000000000000000001'); +---- +true + +query I +select sqlnb_result_drop('a0000000000000000000000000000001'); +---- +false + +statement error +select * from sqlnb_result('a0000000000000000000000000000001'); +---- +SQLNB_RESULT_MISSING: + +query I +select count(*) from sqlnb_results() where id = 'a0000000000000000000000000000002'; +---- +1 From 89b6a8b41afa86188a482ebda6498b554cf80827 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 17:34:00 -0800 Subject: [PATCH 03/14] Document the result cache --- README.md | 1 + docs/development.md | 2 +- docs/mcp.md | 3 +- docs/results.md | 160 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 164 insertions(+), 2 deletions(-) create mode 100644 docs/results.md diff --git a/README.md b/README.md index 1ef006e..0025db9 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ To connect an MCP client, start with `mcp := true` and follow the - [Build and test](docs/development.md) — native prerequisites and version-specific builds. - [Notebook storage](docs/notebooks.md) — files, DuckDB UI notebooks, history, and project Git. - [MCP reference](docs/mcp.md) — authentication, tools, and execution behavior. +- [Result cache](docs/results.md) — storing and reading back complete notebook results. - [UI assets](docs/ui-assets.md) — custom frontends, updates, and the deployment contract. - [Release procedures](docs/releases.md) — maintainer builds, signing, and publication. diff --git a/docs/development.md b/docs/development.md index a8045e0..536f623 100644 --- a/docs/development.md +++ b/docs/development.md @@ -22,7 +22,7 @@ make test The SQL tests start the server with a small local UI fixture, exercise MCP owner isolation and shutdown, and verify invalid startup options and disabled external -access. They install runtime dependencies from DuckDB's core repository; they +access. A separate file covers the [result cache](results.md). They install runtime dependencies from DuckDB's core repository; they do not need a Sidequery repository registration or the hosted UI. The [community workflow](../.github/workflows/community.yml) uses DuckDB's reusable diff --git a/docs/mcp.md b/docs/mcp.md index 9ef5ade..4d3eb7c 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -60,7 +60,8 @@ The read-only tool checks DuckDB's parsed statement, prepared-statement mutation properties, and bound plan. It rejects volatile functions and table functions it cannot establish are read-only. User-defined views and macros are rejected before binding because they can hide bind-time side effects; use the explicitly mutating -`sidequery.sql.execute` tool when these are needed. +`sidequery.sql.execute` tool when these are needed. Neither tool can use the +notebook's [result cache](results.md); its functions report `POLICY_BLOCKED`. Live tools accept `notebook_path` to select a unique open notebook. Omit it only when exactly one browser session exists, or provide `session_id` to select a window. diff --git a/docs/results.md b/docs/results.md new file mode 100644 index 0000000..515121e --- /dev/null +++ b/docs/results.md @@ -0,0 +1,160 @@ +# Result cache + +[Back to README](../README.md) + +The notebook keeps every statement's complete result so it can show the first rows +immediately and later page through, aggregate or export the rest without running +the statement again. These functions exist on DuckDB 2.0 builds only. + +## Storing a result + +```sql +select * from sqlnb_result_tee( + (select * from orders), + id := '5f0c2a3d9b8e4f61a7d2c0e9b4a1f387', + meta := '{"cell":"c1"}' +); +``` + +| Parameter | Default | Meaning | +|-----------|---------|---------| +| first argument | | The statement's rows, as a table. | +| `id` | required | 32 lowercase hexadecimal characters, unique among the process's results. | +| `head_rows` | 10240 | Rows passed through to the caller. | +| `head_bytes` | 4 MiB | Arrow buffer bytes passed through to the caller. | +| `meta` | `''` | Caller data returned by `sqlnb_results()`, at most 64 KiB. | +| `max_result_bytes` | 4 GiB | Bytes stored for this result. | +| `max_cache_bytes` | 16 GiB | Bytes stored for all results of the process. | +| `stop_at_limit` | `false` | Stop reading the input once storing stops. | + +The tee returns the first rows of its input in chunks of 2048 rows, as soon as +each chunk is complete, until `head_rows` rows or `head_bytes` bytes have been +returned; the chunk that crosses `head_bytes` is still returned whole. It keeps +reading and storing the rest of the input without returning it. One thread runs +the statement, so rows are stored in the statement's order. + +A result becomes readable when its statement finishes. A statement that fails or +is interrupted leaves nothing behind and frees its id. A `LIMIT` above the tee, +or anything else that stops reading the tee's output early, ends the statement +before its input does, so the result is discarded too. + +Results with at most `head_rows` rows and 1 MiB of Arrow buffers stay in memory. +Larger results are written to `.arrow.tmp` and renamed to `.arrow` once +complete, as an [Arrow IPC file](https://arrow.apache.org/docs/format/Columnar.html#ipc-file-format) +whose footer lets a read seek directly to the batches it needs. + +### Limits + +When a result would exceed `max_result_bytes`, or the process's results would +exceed `max_cache_bytes` even after evicting the oldest other results, the tee stops +storing. The rows stored before then remain readable as a prefix of the result, +and `limit_reason` says why. The statement still runs to completion, and `rows` +counts every row it produced. Failures to store, such as a full disk or an +unwritable cache directory, likewise stop storing with `limit_reason = 'io'`; they +never fail the statement. Limits count Arrow buffer bytes; a file can exceed its +limit by its footer and the framing of its last batch. + +With `stop_at_limit := true` the tee also stops reading its input once storing +stops, as a `LIMIT` would, and publishes the stored prefix. `rows` is then the +number of rows read, a lower bound, and `rows_exact` is false. The option accepts +any constant expression, such as Instant SQL's verdict that a statement is safe +to stop early: + +```sql +select * from sqlnb_result_tee( + (select * from big_table), + id := '5f0c2a3d9b8e4f61a7d2c0e9b4a1f387', + stop_at_limit := system.main.sqlnb_is_read_only('select * from big_table') +); +``` + +## Reading results + +`sqlnb_results()` lists the readable results, newest first: + +| Column | Type | Meaning | +|--------|------|---------| +| `id` | VARCHAR | The result's id. | +| `rows` | BIGINT | Rows the statement produced (or read, when `rows_exact` is false). | +| `stored_rows` | BIGINT | Rows that can be read back. Less than `rows` after a limit. | +| `stored_bytes` | BIGINT | File size, or Arrow buffer bytes for results in memory. | +| `in_memory` | BOOLEAN | Whether the result is held in memory rather than a file. | +| `limit_reason` | VARCHAR | `result-bytes`, `cache-bytes`, `io`, or NULL when every row was stored. | +| `meta` | VARCHAR | The tee's `meta`. | +| `created_ms` | BIGINT | Unix time in milliseconds when the statement started. | +| `elapsed_ms` | BIGINT | Milliseconds from the start of the statement to the end of its input. | +| `rows_exact` | BOOLEAN | False when `stop_at_limit` stopped the statement early. | + +`sqlnb_result(id, first_row := 0, row_count := NULL, row_number := NULL)` reads a +stored result back with its original column names, types and row order. +`first_row` and `row_count` select a window, NULL `row_count` meaning every row +from `first_row` on. `row_number` names an extra BIGINT column with each row's +zero-based position in the whole result; it must differ from the result's +columns. Only the batches and columns a query needs are read: + +```sql +select * from sqlnb_result('5f0c2a3d9b8e4f61a7d2c0e9b4a1f387', + first_row := 45000, row_count := 200, row_number := 'position'); +select sum(amount) from sqlnb_result('5f0c2a3d9b8e4f61a7d2c0e9b4a1f387'); +``` + +Columns with the same name come back with DuckDB's usual suffixes (`a`, `a_1`). +`TIMESTAMP WITH TIME ZONE` values are stored in UTC. + +`sqlnb_result_drop(id)` removes a readable result and returns whether it existed. +Scans that already started, including scans of evicted results, finish reading +their rows. + +## Errors + +DuckDB prefixes these messages with the error type, such as `Invalid Input Error:`. + +| Prefix | Raised by | +|--------|-----------| +| `SQLNB_RESULT_EXISTS:` | A tee whose id is already used by a running or readable result. | +| `SQLNB_RESULT_MISSING:` | Reading a result that never existed, was dropped or was evicted. | +| `SQLNB_RESULT_UNSUPPORTED:` | A tee over a column the cache cannot read back unchanged. | +| `POLICY_BLOCKED:` | Any of these functions on the MCP agent connection. | + +Every DuckDB type is stored and read back unchanged, including nested types, +`UNION`, `UUID`, `JSON`, `HUGEINT`, `BIGNUM`, `VARIANT` and `GEOMETRY`, except +`ENUM` (anywhere in a column's type) and aliased types without an Arrow extension +type. Cast those columns, for example to `VARCHAR`, before the tee. + +## Files and lifetime + +Results belong to the process: every connection and database in it shares them, +including the notebook's Quack sessions. The MCP agent connection cannot use them. +Results are removed when the last database that loaded SQLNB closes. + +Files live in a directory of their own per process, created when the first result +is written to disk, under: + +- macOS: `~/Library/Caches/sidequery/sqlnb-extension/results/` +- Linux: `${XDG_CACHE_HOME:-~/.cache}/sidequery/sqlnb-extension/results/` +- Windows: `%LOCALAPPDATA%\Cache\sidequery\sqlnb-extension\results\` + +The process holds a lock on its directory's `session.lock` file while it runs, +and on Unix the directory and its files are readable by their owner only. A +directory whose lock is free and more than a minute old belonged to a process +that exited without cleaning up; it is removed when another process creates its +own directory. + +## Storage format + +Files are uncompressed Arrow IPC with batches of 8192 rows, or fewer once a +batch reaches 64 MiB. The first rows reach the caller before anything is written +to disk, so compression would not change how quickly they appear. Measured on an +Apple Silicon Mac with a warm page cache, for 5,000,000 rows of `BIGINT`, +`DECIMAL`, `VARCHAR` and `TIMESTAMP WITH TIME ZONE` (medians of three runs): + +| | Uncompressed | LZ4 frames | +|---|---|---| +| File size | 239 MB | 92 MB | +| Tee statement (`create temp table`: 308 ms) | 283 ms | 387 ms | +| Window of 200 rows at row 4,500,000 | 1 ms | 1 ms | +| `sum` of one column | 16 ms | 23 ms | +| `count(*)` | 12 ms | 18 ms | + +The tee adds about 60 µs to a one-row statement, 80 µs at 1000 rows and 0.2 ms at +10,000 rows, which stay in memory. From 7f9fe15c10a0a97da36ee6bdaa2b8d94258b56ea Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:00:27 -0800 Subject: [PATCH 04/14] Link CoreFoundation so SQLNB loads on its own The Arrow crates read the local time zone's name (chrono's clock feature, through iana-time-zone), which calls CoreFoundation on Apple platforms. The extension only loaded after another extension that links the framework. --- CMakeLists.txt | 4 +++- docs/development.md | 11 +++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0855dba..8e3d4b7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -74,7 +74,9 @@ foreach(target ${EXTENSION_NAME} ${LOADABLE_EXTENSION_NAME}) add_dependencies(${target} sidequery_http_build) target_link_libraries(${target} sidequery_http OpenSSL::Crypto ZLIB::ZLIB Threads::Threads ${CMAKE_DL_LIBS}) if(APPLE) - target_link_libraries(${target} iconv) + # The Arrow crates read the local time zone name (chrono's clock feature, + # through iana-time-zone), which calls CoreFoundation on Apple platforms. + target_link_libraries(${target} iconv "-framework CoreFoundation") elseif(UNIX) target_link_libraries(${target} rt util m) elseif(WIN32) diff --git a/docs/development.md b/docs/development.md index 536f623..5c5a1ef 100644 --- a/docs/development.md +++ b/docs/development.md @@ -41,6 +41,17 @@ mbx test --manifest-path http/Cargo.toml --locked -- --test-threads=1 place. The release build also runs the ignored deployed-UI check, which requires network access. +## System libraries + +SQLNB has to load into a DuckDB process that has loaded nothing else, so every +system library its Rust code calls is named in `CMakeLists.txt`. The runtime +smoke test loads the extension alone in a fresh process to check this. The +Arrow crates read the local time zone's name through `iana-time-zone`: on Apple +platforms that calls CoreFoundation, which is linked as a framework; on Linux it +reads files and needs no library; on Windows it calls the Windows Runtime +through `windows-core`, which declares its imports itself (`raw-dylib`) instead +of relying on an import library. + ## DuckDB 2.0 on macOS Install Rust 1.99.0 through rustup, have Curl, Perl, and Make available, and supply From 19352625cbfc44a5193b14df71a3491ba75e848e Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:00:27 -0800 Subject: [PATCH 05/14] Store a result on every thread of its statement sqlnb_result_tee no longer limits the statement's last pipeline to one thread. It wraps the statement's result collector: every thread stores the rows it produces as Arrow batches keyed by their executor batch, the file's footer lists them in that order, and only the first rows are passed on to the client, exactly the first rows stored. The runtime smoke test now loads SQLNB alone in a fresh process and checks the stored order of a filtered scan, a sort, several Parquet files and a join, and the prefix kept when a verified read stops at the limit. --- docs/results.md | 65 ++- http/Cargo.lock | 1 + http/Cargo.toml | 1 + http/src/results.rs | 493 ++++++++++------ http/src/results/tests.rs | 110 +++- scripts/runtime-smoke.mjs | 127 +++- src/include/sidequery_http.h | 14 +- src/include/sqlnb_results.hpp | 1020 ++++++++++++++++++++++++++++----- test/sql/results.test | 71 ++- 9 files changed, 1500 insertions(+), 402 deletions(-) diff --git a/docs/results.md b/docs/results.md index 515121e..bbb9a80 100644 --- a/docs/results.md +++ b/docs/results.md @@ -18,25 +18,47 @@ select * from sqlnb_result_tee( | Parameter | Default | Meaning | |-----------|---------|---------| -| first argument | | The statement's rows, as a table. | +| first argument | | The statement whose result is kept, as a table. | | `id` | required | 32 lowercase hexadecimal characters, unique among the process's results. | -| `head_rows` | 10240 | Rows passed through to the caller. | -| `head_bytes` | 4 MiB | Arrow buffer bytes passed through to the caller. | +| `head_rows` | 10240 | Rows returned to the caller. | +| `head_bytes` | 4 MiB | Arrow buffer bytes returned to the caller. | | `meta` | `''` | Caller data returned by `sqlnb_results()`, at most 64 KiB. | | `max_result_bytes` | 4 GiB | Bytes stored for this result. | | `max_cache_bytes` | 16 GiB | Bytes stored for all results of the process. | | `stop_at_limit` | `false` | Stop reading the input once storing stops. | -The tee returns the first rows of its input in chunks of 2048 rows, as soon as -each chunk is complete, until `head_rows` rows or `head_bytes` bytes have been -returned; the chunk that crosses `head_bytes` is still returned whole. It keeps -reading and storing the rest of the input without returning it. One thread runs -the statement, so rows are stored in the statement's order. +The tee marks the statement whose result is kept. That statement has to return +the tee's columns unchanged, as `select * from sqlnb_result_tee(...)` does; +anything else, such as an aggregate over the tee, `CREATE TABLE AS`, `EXPLAIN` +or a second tee, is an error before the statement runs. + +The statement returns only its first rows: whole chunks, as DuckDB produces +them, until `head_rows` rows or `head_bytes` bytes have been returned (the chunk +that crosses either is still returned whole). Every row is stored. The rows +returned are exactly the first rows stored. + +The statement runs as it would without the tee, on all its threads, and each +thread stores the rows it produces. They are stored in the statement's order: +the order of an `ORDER BY`, of a table, or of the files and row groups of a +Parquet scan. Where DuckDB gives a statement's rows no order, such as the +output of a join or an aggregate, or everything when +`preserve_insertion_order` is false, they are stored in the order they arrive. A result becomes readable when its statement finishes. A statement that fails or -is interrupted leaves nothing behind and frees its id. A `LIMIT` above the tee, -or anything else that stops reading the tee's output early, ends the statement -before its input does, so the result is discarded too. +is interrupted leaves nothing behind and frees its id. + +### How the order is kept + +DuckDB numbers the batches a parallel scan hands to its threads, and delivers a +statement's rows in batch order. Each thread stores Arrow batches labelled with +the executor batch they come from and writes them to the file wherever there is +room, without waiting for earlier rows. When the statement ends, the file's +footer lists the batches in executor order, and readers follow the footer. + +Only the first rows need their order while the statement still runs. The thread +on the lowest executor batch returns its rows at once. Every other thread keeps +a copy of the first rows of its batch, at most `head_rows` rows or `head_bytes` +bytes, until the batches before it have ended or enough rows were returned. Results with at most `head_rows` rows and 1 MiB of Arrow buffers stay in memory. Larger results are written to `.arrow.tmp` and renamed to `.arrow` once @@ -47,12 +69,15 @@ whose footer lets a read seek directly to the batches it needs. When a result would exceed `max_result_bytes`, or the process's results would exceed `max_cache_bytes` even after evicting the oldest other results, the tee stops -storing. The rows stored before then remain readable as a prefix of the result, -and `limit_reason` says why. The statement still runs to completion, and `rows` +storing. The result keeps the rows before the first batch that was not stored, a +prefix of the statement's rows, and `limit_reason` says why. Batches are stored +whole, and threads store later parts of the result while earlier parts are +still being produced, so the prefix can be shorter than the limit by what the +threads had in progress. The statement still runs to completion, and `rows` counts every row it produced. Failures to store, such as a full disk or an unwritable cache directory, likewise stop storing with `limit_reason = 'io'`; they never fail the statement. Limits count Arrow buffer bytes; a file can exceed its -limit by its footer and the framing of its last batch. +limit by its footer and the framing of its batches. With `stop_at_limit := true` the tee also stops reading its input once storing stops, as a `LIMIT` would, and publishes the stored prefix. `rows` is then the @@ -142,10 +167,16 @@ own directory. ## Storage format -Files are uncompressed Arrow IPC with batches of 8192 rows, or fewer once a -batch reaches 64 MiB. The first rows reach the caller before anything is written +Files are uncompressed Arrow IPC with batches of at most 8192 rows; a batch +ends earlier when it reaches 64 MiB or its thread's executor batch ends. Batches +are in the file in the order they were written, which is not the result's +order: read the file through its footer, as `sqlnb_result` and any Arrow file +reader do, not as a stream. + +The first rows reach the caller before anything is written to disk, so compression would not change how quickly they appear. Measured on an -Apple Silicon Mac with a warm page cache, for 5,000,000 rows of `BIGINT`, +Apple Silicon Mac with a warm page cache, with one thread storing the result, +for 5,000,000 rows of `BIGINT`, `DECIMAL`, `VARCHAR` and `TIMESTAMP WITH TIME ZONE` (medians of three runs): | | Uncompressed | LZ4 frames | diff --git a/http/Cargo.lock b/http/Cargo.lock index 219809b..922e1dd 100644 --- a/http/Cargo.lock +++ b/http/Cargo.lock @@ -1466,6 +1466,7 @@ dependencies = [ "arrow-schema", "axum", "bytes", + "flatbuffers", "git2", "http-body-util", "libc", diff --git a/http/Cargo.toml b/http/Cargo.toml index 319ed6b..13bdbc0 100644 --- a/http/Cargo.toml +++ b/http/Cargo.toml @@ -16,6 +16,7 @@ arrow-ipc = { version = "=60.1.0", default-features = false } arrow-schema = { version = "=60.1.0", default-features = false } axum = { version = "0.7", features = ["json", "query"] } bytes = "1" +flatbuffers = "=25.12.19" git2 = { version = "0.20", default-features = false, features = ["vendored-libgit2"] } http-body-util = "0.1" libc = "0.2" diff --git a/http/src/results.rs b/http/src/results.rs index 546b9ec..6b33137 100644 --- a/http/src/results.rs +++ b/http/src/results.rs @@ -11,14 +11,18 @@ use arrow_array::{ RecordBatchOptions, RecordBatchReader, StringArray, StructArray, }; use arrow_data::ArrayData; +use arrow_ipc::convert::IpcSchemaEncoder; use arrow_ipc::reader::{FileReader, FileReaderBuilder}; -use arrow_ipc::writer::{FileWriter, IpcWriteOptions}; +use arrow_ipc::writer::{write_message, DictionaryTracker, FileWriter, IpcDataGenerator, IpcWriteOptions}; +use arrow_ipc::{Block, FooterBuilder, MetadataVersion}; use arrow_schema::{ArrowError, DataType, Field, Schema, SchemaRef}; +use flatbuffers::FlatBufferBuilder; use std::collections::HashMap; use std::ffi::{c_char, CStr}; use std::fs::{self, File}; -use std::io::{BufReader, BufWriter, Write}; +use std::io::BufReader; use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; use std::sync::{Arc, LazyLock, Mutex, MutexGuard}; use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; @@ -30,7 +34,8 @@ const SESSION_LOCK: &str = "session.lock"; /// A live process locks its session directory moments after creating it, so an /// unlocked directory older than this belongs to a process that is gone. const SESSION_CLAIM_GRACE: Duration = Duration::from_secs(60); -const FILE_BUFFER_BYTES: usize = 1024 * 1024; +/// Messages and their bodies start on this boundary in a result file. +const FILE_ALIGNMENT: u8 = 8; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum LimitReason { @@ -189,66 +194,50 @@ impl ResultStore { schema, limits, started: Instant::now(), - stored_rows: 0, - stored_bytes: 0, - batch_ends: Vec::new(), - memory: Vec::new(), - file: None, - limit_reason: None, + storing: AtomicBool::new(true), + state: Mutex::new(WriterState::default()), finished: false, }) } - /// Grants up to `requested` more stored bytes to the result `id`, evicting the + /// Counts `requested` more stored bytes for the result `id`, evicting the /// oldest other readable results when the whole cache would exceed its limit. - fn reserve( - &self, - id: &str, - stored_bytes: u64, - requested: u64, - limits: &ResultLimits, - ) -> (u64, Option) { - let result_room = limits.max_result_bytes.saturating_sub(stored_bytes); - let needed = requested.min(result_room); + fn reserve(&self, id: &str, requested: u64, limits: &ResultLimits) -> Result<(), LimitReason> { let mut evicted = Vec::new(); - let granted = { + let reserved = { let mut state = self.lock(); - if !state.entries.contains_key(id) { - // The cache closed while this statement ran. - return (0, Some(LimitReason::Io)); - } - let mut used: u64 = state.entries.values().map(|entry| entry.stored_bytes).sum(); - while used.saturating_add(needed) > limits.max_cache_bytes { - let oldest = state - .entries - .iter() - .filter(|(other, entry)| other.as_str() != id && entry.stored.is_some()) - .min_by_key(|(_, entry)| entry.sequence) - .map(|(other, _)| other.clone()); - let Some(oldest) = oldest else { break }; - let entry = state.entries.remove(&oldest).expect("oldest entry exists"); - used -= entry.stored_bytes; - evicted.push(entry); + // Without its entry, the cache closed while this statement ran. + let stored_bytes = state.entries.get(id).ok_or(LimitReason::Io)?.stored_bytes; + if stored_bytes.saturating_add(requested) > limits.max_result_bytes { + Err(LimitReason::ResultBytes) + } else { + let mut used: u64 = state.entries.values().map(|entry| entry.stored_bytes).sum(); + while used.saturating_add(requested) > limits.max_cache_bytes { + let oldest = state + .entries + .iter() + .filter(|(other, entry)| other.as_str() != id && entry.stored.is_some()) + .min_by_key(|(_, entry)| entry.sequence) + .map(|(other, _)| other.clone()); + let Some(oldest) = oldest else { break }; + let entry = state.entries.remove(&oldest).expect("oldest entry exists"); + used -= entry.stored_bytes; + evicted.push(entry); + } + if used.saturating_add(requested) > limits.max_cache_bytes { + Err(LimitReason::CacheBytes) + } else { + if let Some(entry) = state.entries.get_mut(id) { + entry.stored_bytes += requested; + } + Ok(()) + } } - needed.min(limits.max_cache_bytes.saturating_sub(used)) }; for entry in evicted { entry.remove_file(); } - let reason = if granted == requested { - None - } else if granted == result_room { - Some(LimitReason::ResultBytes) - } else { - Some(LimitReason::CacheBytes) - }; - (granted, reason) - } - - fn record_stored_bytes(&self, id: &str, stored_bytes: u64) { - if let Some(entry) = self.lock().entries.get_mut(id) { - entry.stored_bytes = stored_bytes; - } + reserved } fn complete(&self, id: &str, stored: StoredResult, stored_bytes: u64) { @@ -489,7 +478,8 @@ fn with_row_number(schema: &Schema, row_number: Option<&str>) -> Result IpcWriteOptions { - IpcWriteOptions::default() + IpcWriteOptions::try_new(FILE_ALIGNMENT as usize, false, MetadataVersion::V5) + .expect("the result file options are valid") } fn unix_ms() -> i64 { @@ -544,64 +534,137 @@ fn batch_bytes(batch: &RecordBatch) -> u64 { batch.columns().iter().map(|column| data_bytes(&column.to_data())).sum() } -struct CountingWriter { - inner: W, - bytes: u64, +/// Where a batch belongs in its result. Batches are stored as they arrive, +/// from any thread, and read back in the order of their keys. +pub(crate) type BatchKey = (u64, u64); + +const FILE_MAGIC: &[u8; 6] = b"ARROW1"; + +/// The start of an Arrow IPC file: the magic, padded, then the schema message. +fn file_header(schema: &Schema) -> Result, ArrowError> { + let options = write_options(); + let mut bytes = FILE_MAGIC.to_vec(); + bytes.resize(FILE_ALIGNMENT as usize, 0); + let schema = IpcDataGenerator::default().schema_to_bytes_with_dictionary_tracker( + schema, + &mut DictionaryTracker::new(true), + &options, + ); + write_message(&mut bytes, schema, &options)?; + Ok(bytes) } -impl Write for CountingWriter { - fn write(&mut self, buffer: &[u8]) -> std::io::Result { - let written = self.inner.write(buffer)?; - self.bytes += written as u64; - Ok(written) +/// One record batch message, with the lengths its footer block records. +fn encode_batch(batch: &RecordBatch) -> Result<(Vec, usize, usize), ArrowError> { + let options = write_options(); + let (dictionaries, encoded) = IpcDataGenerator::default().encode( + batch, + &mut DictionaryTracker::new(true), + &options, + &mut Default::default(), + )?; + if !dictionaries.is_empty() { + // A dictionary would have to precede every batch that uses it. + return Err(ArrowError::IpcError("dictionary-encoded columns are not stored".into())); } + let mut bytes = Vec::with_capacity(encoded.ipc_message.len() + encoded.arrow_data.len() + 64); + let (metadata, body) = write_message(&mut bytes, encoded, &options)?; + Ok((bytes, metadata, body)) +} + +/// The end of an Arrow IPC file. The footer lists the batches in the order +/// they are read, which is how batches written out of order become one result. +fn file_footer(schema: &Schema, blocks: &[Block]) -> Vec { + // The end-of-stream marker Arrow's own writer puts before the footer. + let mut bytes = vec![0xFF, 0xFF, 0xFF, 0xFF, 0, 0, 0, 0]; + let mut builder = FlatBufferBuilder::new(); + let dictionaries = builder.create_vector::(&[]); + let record_batches = builder.create_vector(blocks); + let mut tracker = DictionaryTracker::new(true); + let schema = IpcSchemaEncoder::new() + .with_dictionary_tracker(&mut tracker) + .schema_to_fb_offset(&mut builder, schema); + let root = { + let mut footer = FooterBuilder::new(&mut builder); + footer.add_version(MetadataVersion::V5); + footer.add_schema(schema); + footer.add_dictionaries(dictionaries); + footer.add_recordBatches(record_batches); + footer.finish() + }; + builder.finish(root, None); + let footer = builder.finished_data(); + bytes.extend_from_slice(footer); + bytes.extend_from_slice(&(footer.len() as i32).to_le_bytes()); + bytes.extend_from_slice(FILE_MAGIC); + bytes +} + +#[cfg(unix)] +fn write_all_at(file: &File, bytes: &[u8], offset: u64) -> std::io::Result<()> { + std::os::unix::fs::FileExt::write_all_at(file, bytes, offset) +} - fn flush(&mut self) -> std::io::Result<()> { - self.inner.flush() +#[cfg(windows)] +fn write_all_at(file: &File, mut bytes: &[u8], mut offset: u64) -> std::io::Result<()> { + use std::os::windows::fs::FileExt; + while !bytes.is_empty() { + let written = file.seek_write(bytes, offset)?; + if written == 0 { + return Err(std::io::ErrorKind::WriteZero.into()); + } + bytes = &bytes[written..]; + offset += written as u64; } + Ok(()) } struct SpillFile { - writer: FileWriter>>, + file: File, temporary: PathBuf, path: PathBuf, + /// The first free byte. A batch claims its place here and is written + /// there without a lock, so threads write at the same time. + end: AtomicU64, } impl SpillFile { fn create(directory: &Path, id: &str, schema: &Schema) -> Result { + let header = file_header(schema).map_err(|error| error.to_string())?; let temporary = directory.join(format!("{id}.arrow.tmp")); let file = private_new_file(&temporary) .map_err(|error| format!("failed to create {}: {error}", temporary.display()))?; - let output = CountingWriter { - inner: BufWriter::with_capacity(FILE_BUFFER_BYTES, file), - bytes: 0, - }; - match FileWriter::try_new_with_options(output, schema, write_options()) { - Ok(writer) => Ok(Self { - writer, - temporary, - path: directory.join(format!("{id}.arrow")), - }), - Err(error) => { - let _ = fs::remove_file(&temporary); - Err(error.to_string()) - } + if let Err(error) = write_all_at(&file, &header, 0) { + drop(file); + let _ = fs::remove_file(&temporary); + return Err(error.to_string()); } + Ok(Self { + file, + temporary, + path: directory.join(format!("{id}.arrow")), + end: AtomicU64::new(header.len() as u64), + }) } - fn bytes(&self) -> u64 { - self.writer.get_ref().bytes + fn write(&self, batch: &RecordBatch) -> Result { + let (bytes, metadata, body) = encode_batch(batch).map_err(|_| LimitReason::Io)?; + let offset = self.end.fetch_add(bytes.len() as u64, Ordering::Relaxed); + write_all_at(&self.file, &bytes, offset).map_err(|_| LimitReason::Io)?; + Ok(Block::new(offset as i64, metadata as i32, body as i64)) } /// Writes the footer and publishes the file under its final name. - fn finish(self) -> Result<(PathBuf, u64), String> { + fn finish(self, schema: &Schema, blocks: &[Block]) -> Result<(PathBuf, u64), String> { let temporary = self.temporary.clone(); let result = (|| { - let output = self.writer.into_inner().map_err(|error| error.to_string())?; - let bytes = output.bytes; - drop(output.inner.into_inner().map_err(|error| error.to_string())?); + let footer = file_footer(schema, blocks); + let end = self.end.load(Ordering::Relaxed); + write_all_at(&self.file, &footer, end).map_err(|error| error.to_string())?; + // Windows cannot rename a file that is still open. + drop(self.file); fs::rename(&self.temporary, &self.path).map_err(|error| error.to_string())?; - Ok((self.path, bytes)) + Ok((self.path, end + footer.len() as u64)) })(); if result.is_err() { let _ = fs::remove_file(temporary); @@ -610,13 +673,38 @@ impl SpillFile { } fn discard(self) { - let temporary = self.temporary.clone(); - drop(self); - let _ = fs::remove_file(temporary); + drop(self.file); + let _ = fs::remove_file(self.temporary); } } -/// Stores one statement's rows. Dropping an unfinished writer discards the result. +struct StoredBatch { + key: BatchKey, + rows: u64, + bytes: u64, + data: BatchData, +} + +enum BatchData { + Memory(RecordBatch), + File(Block), +} + +#[derive(Default)] +struct WriterState { + /// In the order they arrived. + batches: Vec, + file: Option>, + stored_rows: u64, + stored_bytes: u64, + limit_reason: Option, + /// The first batch of the result that was not stored. The result keeps the + /// batches before it. + first_missing: Option, +} + +/// Stores one statement's rows; any thread may append. Dropping an unfinished +/// writer discards the result. pub(crate) struct ResultWriter { store: Arc, id: String, @@ -624,110 +712,116 @@ pub(crate) struct ResultWriter { batch_type: DataType, limits: ResultLimits, started: Instant, - stored_rows: u64, - stored_bytes: u64, - batch_ends: Vec, - memory: Vec, - file: Option, - limit_reason: Option, + /// Cleared once a limit or a failure ends storing. + storing: AtomicBool, + state: Mutex, finished: bool, } impl ResultWriter { + fn lock(&self) -> MutexGuard<'_, WriterState> { + self.state.lock().unwrap_or_else(|poisoned| poisoned.into_inner()) + } + /// Imports and stores a batch exported through the C Data Interface. - fn append_ffi(&mut self, array: FFI_ArrowArray) -> bool { - if self.limit_reason.is_some() { + fn append_ffi(&self, array: FFI_ArrowArray, key: BatchKey) -> bool { + if !self.storing.load(Ordering::Relaxed) { + self.missing(key, LimitReason::Io); return false; } let batch = unsafe { from_ffi_and_data_type(array, self.batch_type.clone()) }.and_then(|data| { RecordBatch::try_new(self.schema.clone(), StructArray::from(data).into_parts().1) }); match batch { - Ok(batch) => self.append(batch), + Ok(batch) => self.append(batch, key), Err(_) => { - self.stop(LimitReason::Io); + self.missing(key, LimitReason::Io); false } } } - /// Stores a batch, or the prefix of it that the limits allow. Returns whether - /// later batches can still be stored. - pub(crate) fn append(&mut self, batch: RecordBatch) -> bool { - if self.limit_reason.is_some() { - return false; - } + /// Stores a batch whole, or not at all once a limit is reached. Returns + /// whether later batches can still be stored. + pub(crate) fn append(&self, batch: RecordBatch, key: BatchKey) -> bool { let rows = batch.num_rows() as u64; if rows == 0 { - return true; + return self.storing.load(Ordering::Relaxed); } - let bytes = batch_bytes(&batch); - let (granted, reason) = self.store.reserve(&self.id, self.stored_bytes, bytes, &self.limits); - let (batch, rows, bytes) = if granted < bytes { - // Byte sizes are proportional enough to keep the prefix that fits. - let fitting = (u128::from(rows) * u128::from(granted) / u128::from(bytes.max(1))) as u64; - (batch.slice(0, fitting as usize), fitting, granted) + let stored = if self.storing.load(Ordering::Relaxed) { + let bytes = batch_bytes(&batch); + self.store + .reserve(&self.id, bytes, &self.limits) + .and_then(|()| self.store_batch(batch, key, rows, bytes)) } else { - (batch, rows, bytes) + Err(LimitReason::Io) }; - if rows > 0 { - if let Err(error) = self.store_batch(batch, rows, bytes) { - self.stop(error); - return false; - } - } - match reason { - Some(reason) => { - self.stop(reason); + match stored { + Ok(()) => true, + Err(reason) => { + self.missing(key, reason); false } - None => true, } } - fn store_batch(&mut self, batch: RecordBatch, rows: u64, bytes: u64) -> Result<(), LimitReason> { - if self.file.is_none() - && (self.stored_rows + rows > self.limits.head_rows - || self.stored_bytes + bytes > MEMORY_RESULT_BYTES) - { - self.spill()?; - } - match &mut self.file { - Some(file) => { - file.writer.write(&batch).map_err(|_| LimitReason::Io)?; - self.stored_bytes = file.bytes(); - } - None => { - self.memory.push(batch); - self.stored_bytes += bytes; + fn store_batch(&self, batch: RecordBatch, key: BatchKey, rows: u64, bytes: u64) -> Result<(), LimitReason> { + let file = { + let mut state = self.lock(); + if state.file.is_none() { + if state.stored_rows + rows <= self.limits.head_rows + && state.stored_bytes + bytes <= MEMORY_RESULT_BYTES + { + state.stored_rows += rows; + state.stored_bytes += bytes; + state.batches.push(StoredBatch { key, rows, bytes, data: BatchData::Memory(batch) }); + return Ok(()); + } + self.spill(&mut state)?; } - } - self.stored_rows += rows; - self.batch_ends.push(self.stored_rows); - self.store.record_stored_bytes(&self.id, self.stored_bytes); + state.file.clone().expect("a spilled result has a file") + }; + // Encoded and written outside the lock: other threads do the same. + let block = file.write(&batch)?; + let mut state = self.lock(); + state.stored_rows += rows; + state.stored_bytes += bytes; + state.batches.push(StoredBatch { key, rows, bytes, data: BatchData::File(block) }); Ok(()) } - /// Moves the batches kept in memory into a new file. On failure the - /// batches stay in memory as the stored prefix. - fn spill(&mut self) -> Result<(), LimitReason> { + /// Moves the batches kept in memory into a new file. On failure they stay + /// in memory as what the result keeps. + fn spill(&self, state: &mut WriterState) -> Result<(), LimitReason> { let directory = self.store.session_directory().map_err(|_| LimitReason::Io)?; - let mut file = SpillFile::create(&directory, &self.id, &self.schema).map_err(|_| LimitReason::Io)?; - for batch in &self.memory { - if file.writer.write(batch).is_err() { - file.discard(); - return Err(LimitReason::Io); + let file = SpillFile::create(&directory, &self.id, &self.schema).map_err(|_| LimitReason::Io)?; + let mut blocks = Vec::with_capacity(state.batches.len()); + for stored in &state.batches { + let BatchData::Memory(batch) = &stored.data else { + unreachable!("a result without a file keeps its batches in memory") + }; + match file.write(batch) { + Ok(block) => blocks.push(block), + Err(reason) => { + file.discard(); + return Err(reason); + } } } - self.memory.clear(); - self.stored_bytes = file.bytes(); - self.file = Some(file); + for (stored, block) in state.batches.iter_mut().zip(blocks) { + stored.data = BatchData::File(block); + } + state.file = Some(Arc::new(file)); Ok(()) } - /// Stops storing; the rows stored so far remain the result's prefix. - pub(crate) fn stop(&mut self, reason: LimitReason) { - self.limit_reason.get_or_insert(reason); + /// Records that the batch `key` is not stored, which ends storing: the + /// result keeps the batches before the first missing one. + pub(crate) fn missing(&self, key: BatchKey, reason: LimitReason) { + let mut state = self.lock(); + state.limit_reason.get_or_insert(reason); + state.first_missing = Some(state.first_missing.map_or(key, |first| first.min(key))); + self.storing.store(false, Ordering::Relaxed); } /// Makes the result readable. `rows` is the number of rows the statement @@ -735,32 +829,70 @@ impl ResultWriter { pub(crate) fn finish(mut self, rows: u64, rows_exact: bool) { self.finished = true; let elapsed_ms = self.started.elapsed().as_millis() as u64; - let data = match self.file.take() { - None => StoredData::Memory(std::mem::take(&mut self.memory)), - Some(file) => match file.finish() { - Ok((path, bytes)) => { - self.stored_bytes = bytes; - StoredData::File(path) - } - Err(_) => { - self.stored_rows = 0; - self.stored_bytes = 0; - self.batch_ends.clear(); - self.limit_reason = Some(LimitReason::Io); - StoredData::Memory(Vec::new()) + let mut state = std::mem::take(&mut *self.lock()); + state.batches.sort_by_key(|stored| stored.key); + if let Some(first_missing) = state.first_missing { + let kept = state.batches.partition_point(|stored| stored.key < first_missing); + state.batches.truncate(kept); + } + let mut stored_rows = 0; + let mut stored_bytes = 0; + let mut batch_ends = Vec::with_capacity(state.batches.len()); + for stored in &state.batches { + stored_rows += stored.rows; + stored_bytes += stored.bytes; + batch_ends.push(stored_rows); + } + let mut limit_reason = state.limit_reason; + let data = match state.file.take() { + None => StoredData::Memory( + state + .batches + .into_iter() + .filter_map(|stored| match stored.data { + BatchData::Memory(batch) => Some(batch), + BatchData::File(_) => None, + }) + .collect(), + ), + Some(file) => { + let blocks: Vec = state + .batches + .iter() + .filter_map(|stored| match &stored.data { + BatchData::File(block) => Some(*block), + BatchData::Memory(_) => None, + }) + .collect(); + // Every append has returned, so this is the only reference left. + let published = Arc::try_unwrap(file) + .map_err(|_| "the result file is still being written".to_string()) + .and_then(|file| file.finish(&self.schema, &blocks)); + match published { + Ok((path, bytes)) => { + stored_bytes = bytes; + StoredData::File(path) + } + Err(_) => { + stored_rows = 0; + stored_bytes = 0; + batch_ends.clear(); + limit_reason = Some(LimitReason::Io); + StoredData::Memory(Vec::new()) + } } - }, + } }; let stored = StoredResult { rows, rows_exact, - stored_rows: self.stored_rows, - limit_reason: self.limit_reason, + stored_rows, + limit_reason, elapsed_ms, - batch_ends: std::mem::take(&mut self.batch_ends), + batch_ends, data, }; - self.store.complete(&self.id, stored, self.stored_bytes); + self.store.complete(&self.id, stored, stored_bytes); } } @@ -769,7 +901,8 @@ impl Drop for ResultWriter { if self.finished { return; } - if let Some(file) = self.file.take() { + let file = self.lock().file.take(); + if let Some(file) = file.and_then(Arc::into_inner) { file.discard(); } self.store.forget(&self.id); @@ -950,20 +1083,22 @@ pub unsafe extern "C" fn sidequery_result_begin( #[no_mangle] pub unsafe extern "C" fn sidequery_result_append( - writer: *mut ResultWriter, + writer: *const ResultWriter, batch: *mut FFI_ArrowArray, + major: u64, + minor: u64, ) -> bool { std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - let writer = unsafe { &mut *writer }; - writer.append_ffi(unsafe { FFI_ArrowArray::from_raw(batch) }) + let writer = unsafe { &*writer }; + writer.append_ffi(unsafe { FFI_ArrowArray::from_raw(batch) }, (major, minor)) })) .unwrap_or(false) } #[no_mangle] -pub unsafe extern "C" fn sidequery_result_stop(writer: *mut ResultWriter) { +pub unsafe extern "C" fn sidequery_result_missing(writer: *const ResultWriter, major: u64, minor: u64) { let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - unsafe { &mut *writer }.stop(LimitReason::Io) + unsafe { &*writer }.missing((major, minor), LimitReason::Io) })); } diff --git a/http/src/results/tests.rs b/http/src/results/tests.rs index 71a0cfb..1e8f177 100644 --- a/http/src/results/tests.rs +++ b/http/src/results/tests.rs @@ -44,10 +44,10 @@ fn id(number: u8) -> String { /// Stores batches of the given sizes, numbering rows from 0. fn store_result(store: &Arc, id: &str, sizes: &[i64], limits: ResultLimits) { - let mut writer = store.begin(id, "meta", schema(), limits).unwrap(); + let writer = store.begin(id, "meta", schema(), limits).unwrap(); let mut start = 0; - for &size in sizes { - writer.append(batch(start, size)); + for (position, &size) in sizes.iter().enumerate() { + writer.append(batch(start, size), (0, position as u64)); start += size; } writer.finish(start as u64, true); @@ -186,8 +186,8 @@ fn ids_are_validated_and_unique() { fn unfinished_results_are_neither_listed_nor_readable_and_abort_leaves_nothing() { let directory = tempfile::tempdir().unwrap(); let store = open_store(directory.path()); - let mut writer = store.begin(&id(1), "", schema(), limits(2)).unwrap(); - assert!(writer.append(batch(0, 5))); + let writer = store.begin(&id(1), "", schema(), limits(2)).unwrap(); + assert!(writer.append(batch(0, 5), (0, 0))); assert_eq!(session_files(directory.path()), [format!("{}.arrow.tmp", id(1)), SESSION_LOCK.to_string()]); assert!(listed(&store).is_empty()); assert!(store.scan(&id(1), 0, UNLIMITED, None, &[0]).is_err()); @@ -203,7 +203,7 @@ fn the_result_limit_keeps_a_prefix_and_counts_every_row() { let directory = tempfile::tempdir().unwrap(); let store = open_store(directory.path()); let batch_size = batch_bytes(&batch(0, 100)); - let mut writer = store + let writer = store .begin( &id(1), "", @@ -215,15 +215,12 @@ fn the_result_limit_keeps_a_prefix_and_counts_every_row() { }, ) .unwrap(); - assert!(writer.append(batch(0, 100))); - assert!(!writer.append(batch(100, 100))); - assert!(!writer.append(batch(200, 100))); + assert!(writer.append(batch(0, 100), (0, 0))); + assert!(!writer.append(batch(100, 100), (0, 1))); + assert!(!writer.append(batch(200, 100), (0, 2))); writer.finish(300, true); - let [(_, rows, stored_rows, _, reason, _)] = listed(&store).try_into().unwrap(); - assert_eq!((rows, reason.as_deref()), (300, Some("result-bytes"))); - assert!((140..=160).contains(&stored_rows), "{stored_rows}"); - let values = scan_values(&store, &id(1), 0, UNLIMITED, None, &[0]); - assert_eq!(values[0], (0..stored_rows).collect::>()); + assert_eq!(listed(&store), [(id(1), 300, 100, true, Some("result-bytes".into()), true)]); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..100).collect::>()); } #[test] @@ -244,8 +241,8 @@ fn the_cache_limit_evicts_the_oldest_other_results() { assert!(store.scan_schema(&id(1), None).unwrap_err().starts_with("SQLNB_RESULT_MISSING:")); // An unfinished result cannot be evicted; the newer one stops storing instead. - let mut writer = store.begin(&id(4), "", schema(), cache).unwrap(); - assert!(writer.append(batch(0, 100))); + let writer = store.begin(&id(4), "", schema(), cache).unwrap(); + assert!(writer.append(batch(0, 100), (0, 0))); store_result(&store, &id(5), &[100, 100], cache); writer.finish(100, true); assert_eq!( @@ -261,10 +258,10 @@ fn the_cache_limit_evicts_the_oldest_other_results() { fn stopping_early_reports_a_lower_bound() { let directory = tempfile::tempdir().unwrap(); let store = open_store(directory.path()); - let mut writer = store.begin(&id(1), "", schema(), limits(10)).unwrap(); - writer.append(batch(0, 5)); - writer.stop(LimitReason::Io); - assert!(!writer.append(batch(5, 5))); + let writer = store.begin(&id(1), "", schema(), limits(10)).unwrap(); + writer.append(batch(0, 5), (0, 0)); + writer.missing((0, 1), LimitReason::Io); + assert!(!writer.append(batch(5, 5), (0, 1))); writer.finish(10, false); assert_eq!(listed(&store), [(id(1), 10, 5, true, Some("io".into()), false)]); } @@ -273,9 +270,9 @@ fn stopping_early_reports_a_lower_bound() { fn an_unavailable_cache_directory_keeps_the_memory_prefix() { let store = Arc::new(ResultStore::new(Err("no cache root".into()))); store.retain(); - let mut writer = store.begin(&id(1), "", schema(), limits(4)).unwrap(); - assert!(writer.append(batch(0, 4))); - assert!(!writer.append(batch(4, 4))); + let writer = store.begin(&id(1), "", schema(), limits(4)).unwrap(); + assert!(writer.append(batch(0, 4), (0, 0))); + assert!(!writer.append(batch(4, 4), (0, 1))); writer.finish(8, true); assert_eq!(listed(&store), [(id(1), 8, 4, true, Some("io".into()), true)]); assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..4).collect::>()); @@ -337,13 +334,76 @@ fn stale_sessions_are_removed_when_a_session_starts() { fn batches_arrive_through_the_c_data_interface() { let directory = tempfile::tempdir().unwrap(); let store = open_store(directory.path()); - let mut writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); + let writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); for start in [0, 4] { let exported = StructArray::from(batch(start, 4)).into_data(); let (array, _) = arrow_array::ffi::to_ffi(&exported).unwrap(); - assert!(writer.append_ffi(array)); + assert!(writer.append_ffi(array, (0, start as u64))); } writer.finish(8, true); let values = scan_values(&store, &id(1), 0, UNLIMITED, Some("n"), &[1, 2]); assert_eq!(values, [(0..8).collect::>(), (0..8).collect()]); } + +#[test] +fn batches_stored_out_of_order_are_read_in_key_order() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + // In memory, then in a file that the third batch starts. + for (result, head_rows) in [(id(1), 100), (id(2), 8)] { + let writer = store.begin(&result, "", schema(), limits(head_rows)).unwrap(); + for (key, start, rows) in [((2, 0), 9, 3), ((1, 1), 6, 3), ((0, 0), 0, 4), ((1, 0), 4, 2)] { + assert!(writer.append(batch(start, rows), key)); + } + writer.finish(12, true); + let values = scan_values(&store, &result, 0, UNLIMITED, Some("n"), &[0, 2]); + assert_eq!(values, [(0..12).collect::>(), (0..12).collect()]); + assert_eq!(scan_values(&store, &result, 5, 5, None, &[1])[0], (5..10).collect::>()); + } + assert_eq!(listed(&store).iter().map(|result| result.3).collect::>(), [false, true]); + // Another reader of the file sees the same order: the footer carries it. + let path = fs::read_dir(directory.path()).unwrap().flatten().next().unwrap().path().join(format!("{}.arrow", id(2))); + let reader = FileReader::try_new(File::open(path).unwrap(), None).unwrap(); + let values: Vec = reader + .flat_map(|batch| batch.unwrap().column(0).as_primitive::().values().to_vec()) + .collect(); + assert_eq!(values, (0..12).collect::>()); +} + +#[test] +fn a_missing_batch_keeps_only_the_batches_before_it() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); + assert!(writer.append(batch(0, 4), (0, 0))); + assert!(writer.append(batch(8, 4), (2, 0))); + writer.missing((1, 0), LimitReason::Io); + assert!(!writer.append(batch(12, 4), (3, 0))); + writer.finish(16, true); + assert_eq!(listed(&store), [(id(1), 16, 4, false, Some("io".into()), true)]); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..4).collect::>()); +} + +#[test] +fn threads_store_batches_at_the_same_time() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); + const THREADS: i64 = 8; + const BATCHES: i64 = 50; + const ROWS: i64 = 100; + std::thread::scope(|scope| { + for thread in 0..THREADS { + let writer = &writer; + scope.spawn(move || { + // Each thread owns every eighth batch, as a thread owns its part of a scan. + for batch_number in (thread..THREADS * BATCHES).step_by(THREADS as usize) { + assert!(writer.append(batch(batch_number * ROWS, ROWS), (batch_number as u64, 0))); + } + }); + } + }); + let total = THREADS * BATCHES * ROWS; + writer.finish(total as u64, true); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..total).collect::>()); +} diff --git a/scripts/runtime-smoke.mjs b/scripts/runtime-smoke.mjs index 3bd3b6e..e0f3e33 100644 --- a/scripts/runtime-smoke.mjs +++ b/scripts/runtime-smoke.mjs @@ -93,6 +93,31 @@ function sqlLiteral(value) { return `'${value.replaceAll("'", "''")}'`; } +// SQLNB has to load into a process that has loaded nothing before it: what its +// own code needs from the system must be linked into it, not found by chance +// in an extension loaded earlier. +{ + const statements = []; + if (repository) { + const state = mkdtempSync(join(tmpdir(), 'sidequery-ui-extensions.')); + statements.push( + `set extension_directories = [${sqlLiteral(join(state, 'installed'))}]`, + 'install sqlnb from sidequery', + 'load sqlnb from sidequery', + ); + } else { + statements.push(`load ${sqlLiteral(extension)}`); + } + statements.push("select count(*) from duckdb_extensions() where extension_name = 'sqlnb' and loaded"); + const alone = spawnSync(duckdb, [...cliOptions, ':memory:', '-csv', '-noheader', '-c', statements.join('; ')], { + encoding: 'utf8', + timeout: queryTimeoutMs, + env: cliEnvironment(), + }); + assert.equal(alone.status, 0, `SQLNB did not load on its own: ${alone.stderr || alone.stdout}`); + assert.equal(alone.stdout.trim().split('\n').at(-1), '1', alone.stdout); +} + const fixture = mkdtempSync(join(tmpdir(), 'sidequery-ui-assets.')); writeFileSync(join(fixture, 'index.html'), 'Sidequery local fixture'); const notebookRoot = mkdtempSync(join(tmpdir(), 'sidequery-ui-notebooks.')); @@ -156,6 +181,21 @@ function runSQL(sql) { }); } +// For a result of more than one row: the CLI prints one row per line, and +// runSQL reads a line. +async function runRows(sql) { + const file = join(mkdtempSync(join(tmpdir(), 'sidequery-ui-rows.')), 'rows.json'); + child.stdin.write(`.once ${file}\n${sql};\n`); + await runSQL('select 1 as done'); + return JSON.parse(readFileSync(file, 'utf8')); +} + +// For a statement whose own output is not a row to assert on. +async function runStatement(sql) { + child.stdin.write(`.output /dev/null\n${sql};\n.output stdout\n`); + await runSQL('select 1 as done'); +} + function expectSQLError(sql, expectedMessage) { return new Promise((resolve, reject) => { let received = ''; @@ -651,15 +691,23 @@ if (hasResultCache) { const large = resultId(1); const small = resultId(2); const source = "select i, i * 1.5 as amount, 'c-' || (i % 7) as label from range(50000) t(i)"; - // Only the head passes through; every row is stored. - assert.deepEqual( - await runSQL(`select count(*) as n, min(i) as low, max(i) as high from sqlnb_result_tee((${source}), id := '${large}', meta := '{"cell":1}')`), - [{ n: 10240, low: 0, high: 10239 }], - ); - assert.deepEqual( - await runSQL(`select count(*) as n from sqlnb_result_tee((select 1 as one), id := '${small}')`), - [{ n: 1 }], - ); + // The statement returns only its first rows, in order; every row is stored. + const head = await runRows(`select * from sqlnb_result_tee((${source}), id := '${large}', meta := '{"cell":1}')`); + assert(head.length >= 10240 && head.length < 10240 + 2048, `${head.length} head rows`); + assert(head.every((row, position) => row.i === position), 'the head is not the first rows'); + assert.deepEqual(await runSQL(`select * from sqlnb_result_tee((select 1 as one), id := '${small}')`), [{ one: 1 }]); + // The tee marks the statement whose result is kept, so it has to be that + // statement's whole output. + for (const [number, misplaced] of [ + `select count(*) from sqlnb_result_tee((select 1 as one), id := '${resultId(90)}')`, + `create table misplaced as select * from sqlnb_result_tee((select 1 as one), id := '${resultId(91)}')`, + `explain select * from sqlnb_result_tee((select 1 as one), id := '${resultId(92)}')`, + `select * from sqlnb_result_tee((select 1 as one), id := '${resultId(93)}'), sqlnb_result_tee((select 2 as two), id := '${resultId(94)}')`, + ].entries()) { + await expectSQLError(misplaced, number === 3 ? /keeps one result/ : /returns its columns unchanged/); + } + assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_results() where id >= '${resultId(90)}'`)), 0); + assert.equal(firstValue(await runSQL("select count(*) from duckdb_tables() where table_name = 'misplaced'")), 0); assert.equal( firstValue(await runSQL("select string_agg(column_name || ' ' || column_type, ', ') from (describe select * from sqlnb_results())")), 'id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN', @@ -697,17 +745,17 @@ if (hasResultCache) { ); // A failing statement leaves nothing readable and frees its id. await expectSQLError( - `select count(*) from sqlnb_result_tee((select case when i = 40000 then error('tee failed') else i end as i from range(50000) t(i)), id := '${resultId(3)}')`, + `select * from sqlnb_result_tee((select case when i = 40000 then error('tee failed') else i end as i from range(50000) t(i)), id := '${resultId(3)}')`, /tee failed/, ); assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_results() where id = '${resultId(3)}'`)), 0); assert.deepEqual(resultFiles().filter((file) => file.includes(resultId(3))), []); - assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_result_tee((select 1), id := '${resultId(3)}')`)), 1); + assert.equal((await runSQL(`select * from sqlnb_result_tee((select 1), id := '${resultId(3)}')`)).length, 1); // A limit stops storing; stop_at_limit also stops reading. The notebook passes // the Instant SQL verdict as a constant scalar call. const endless = 'select i from range(100000000) t(i)'; - await runSQL(`select count(*) from sqlnb_result_tee((${endless}), id := '${resultId(4)}', max_result_bytes := 100000, stop_at_limit := system.main.sqlnb_is_read_only(${sqlLiteral(endless)}))`); - await runSQL(`select count(*) from sqlnb_result_tee((${endless}), id := '${resultId(5)}', max_result_bytes := 100000, stop_at_limit := false)`); + await runRows(`select * from sqlnb_result_tee((${endless}), id := '${resultId(4)}', max_result_bytes := 100000, stop_at_limit := system.main.sqlnb_is_read_only(${sqlLiteral(endless)}))`); + await runRows(`select * from sqlnb_result_tee((${endless}), id := '${resultId(5)}', max_result_bytes := 100000, stop_at_limit := false)`); const [stopped, counted] = firstValue(await runSQL(`select list(r order by r.id) from (select id, rows, stored_rows, limit_reason, rows_exact from sqlnb_results() where id in ('${resultId(4)}', '${resultId(5)}')) r`)) .map(({ id, ...result }) => result); assert(stopped.rows < 1000000 && stopped.stored_rows > 0 && stopped.stored_rows <= stopped.rows, JSON.stringify(stopped)); @@ -718,6 +766,55 @@ if (hasResultCache) { firstValue(await runSQL(`select count(*) = ${stopped.stored_rows} and max(i) = ${stopped.stored_rows - 1} from sqlnb_result('${resultId(4)}')`)), true, ); + // The statement runs on all its threads, and its rows are stored in its own + // order: a scan with a filter, a sort, several Parquet files, and a verified + // read stopped at the limit while many threads store. + await runStatement('create table tee_scan as select i, hash(i) as h from range(3000000) t(i)'); + const parquet = join(mkdtempSync(join(tmpdir(), 'sidequery-ui-results.')), 'part'); + for (const part of [0, 1, 2]) { + await runStatement(`copy (select i from range(${part * 400000}, ${(part + 1) * 400000}) t(i)) to ${sqlLiteral(`${parquet}${part}.parquet`)} (row_group_size 50000)`); + } + const ordered = [ + [10, 'select i, h from tee_scan where i % 3 = 0', 'i = position * 3', 1000000], + [11, 'select i, h from tee_scan order by i desc', 'i = 2999999 - position', 3000000], + [12, `select i from read_parquet(${sqlLiteral(`${parquet}*.parquet`)})`, 'i = position', 1200000], + ]; + for (const [number, statement, inPlace, rows] of ordered) { + const first = await runRows(`select * from sqlnb_result_tee((${statement}), id := '${resultId(number)}')`); + assert.deepEqual( + await runSQL(`select count(*) as n, bool_and(${inPlace}) as ordered from sqlnb_result('${resultId(number)}', row_number := 'position')`), + [{ n: rows, ordered: true }], + statement, + ); + assert.deepEqual( + first.map((row) => row.i), + (await runRows(`select i from sqlnb_result('${resultId(number)}', row_count := ${first.length})`)).map((row) => row.i), + `the head is not the first stored rows: ${statement}`, + ); + assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${resultId(number)}')`)), true); + } + // Rows without an order of their own: the head is still the first rows stored. + const joined = 'select a.i, b.h from tee_scan a join tee_scan b using (i) where a.i % 5 = 0'; + const firstJoined = await runRows(`select * from sqlnb_result_tee((${joined}), id := '${resultId(13)}')`); + assert(firstJoined.length >= 10240, `${firstJoined.length} head rows of a join`); + assert.deepEqual( + firstJoined.map((row) => row.i), + (await runRows(`select i from sqlnb_result('${resultId(13)}', row_count := ${firstJoined.length})`)).map((row) => row.i), + 'the head of a join is not the first stored rows', + ); + assert.deepEqual( + await runSQL(`select count(*) as n, count(distinct i) as different, sum(i) as total from sqlnb_result('${resultId(13)}')`), + await runSQL(`select count(*) as n, count(distinct i) as different, sum(i) as total from (${joined})`), + ); + await runRows(`select * from sqlnb_result_tee((select i, h from tee_scan), id := '${resultId(14)}', max_result_bytes := 4000000, stop_at_limit := true)`); + assert.deepEqual( + await runSQL(`select count(*) > 0 as kept, bool_and(i = position) as ordered, count(*) = (select stored_rows from sqlnb_results() where id = '${resultId(14)}') as counted from sqlnb_result('${resultId(14)}', row_number := 'position')`), + [{ kept: true, ordered: true, counted: true }], + ); + for (const number of [13, 14]) { + assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${resultId(number)}')`)), true); + } + await runStatement('drop table tee_scan'); // The agent connection cannot reach the cache, on either SQL tool. for (const sql of [ 'select * from sqlnb_results()', @@ -734,10 +831,10 @@ if (hasResultCache) { // Quack sessions (the notebook's path) share the process-wide cache. const quackTee = spawnSync(duckdb, [...cliOptions, ':memory:', '-csv', '-noheader', '-c', [ loadExtensions(false), - `from quack_query(${sqlLiteral(`quack:${endpoint.hostname}:${endpoint.port}`)}, ${sqlLiteral(`select count(*) from sqlnb_result_tee((select * from range(30000) t(i)), id := '${resultId(7)}')`)}, token = ${sqlLiteral(token)})`, + `select count(*), min(i), max(i) from quack_query(${sqlLiteral(`quack:${endpoint.hostname}:${endpoint.port}`)}, ${sqlLiteral(`select * from sqlnb_result_tee((select * from range(30000) t(i)), id := '${resultId(7)}')`)}, token = ${sqlLiteral(token)})`, ].join('; ')], { encoding: 'utf8', timeout: queryTimeoutMs, env: cliEnvironment() }); assert.equal(quackTee.status, 0, quackTee.stderr || quackTee.stdout); - assert.equal(quackTee.stdout.trim(), '10240'); + assert.equal(quackTee.stdout.trim(), '10240,0,10239'); assert.equal(firstValue(await runSQL(`select rows from sqlnb_results() where id = '${resultId(7)}'`)), 30000); assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${large}')`)), true); assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${large}')`)), false); diff --git a/src/include/sidequery_http.h b/src/include/sidequery_http.h index 44f688c..2b66d3e 100644 --- a/src/include/sidequery_http.h +++ b/src/include/sidequery_http.h @@ -41,11 +41,15 @@ sidequery_result_writer *sidequery_result_begin(const char *id, const char *meta struct ArrowSchema *schema, uint64_t head_rows, uint64_t max_result_bytes, uint64_t max_cache_bytes, char **error_out); -// Stores the rows of a struct array whose fields match the schema. Returns -// false once storing stopped; the rows stored before remain the result. -bool sidequery_result_append(sidequery_result_writer *writer, struct ArrowArray *batch); -// Stops storing because the caller could not convert its rows (limit reason "io"). -void sidequery_result_stop(sidequery_result_writer *writer); +// Stores the rows of a struct array whose fields match the schema, from any +// thread. The result reads back in the order of the keys (major, then minor), +// whatever order the batches were stored in. Returns false when the batch was +// not stored; the result is then the batches before the first one missing. +bool sidequery_result_append(sidequery_result_writer *writer, struct ArrowArray *batch, + uint64_t major, uint64_t minor); +// Marks the batch with this key as one the caller could not store (limit +// reason "io" unless a limit already stopped storing). +void sidequery_result_missing(sidequery_result_writer *writer, uint64_t major, uint64_t minor); // rows counts every row the statement produced; rows_exact is false when the // statement stopped reading early and rows is only a lower bound. void sidequery_result_finish(sidequery_result_writer *writer, uint64_t rows, bool rows_exact); diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index 3039c65..b06fc8b 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -1,22 +1,30 @@ #pragma once -// Result cache (docs/results.md). sqlnb_result_tee passes a statement's first -// rows through while the Rust library stores every row as Arrow; the other -// functions list, read back and drop stored results through DuckDB's Arrow scan. +// Result cache (docs/results.md). sqlnb_result_tee makes its statement's result +// collector pass the first rows on while the Rust library stores every row as +// Arrow; the other functions list, read back and drop stored results through +// DuckDB's Arrow scan. #if __has_include("duckdb/main/query_result_stream.hpp") #include "duckdb/common/arrow/arrow_appender.hpp" #include "duckdb/common/arrow/arrow_converter.hpp" #include "duckdb/common/arrow/arrow_wrapper.hpp" #include "duckdb/common/type_visitor.hpp" #include "duckdb/common/vector_operations/unary_executor.hpp" +#include "duckdb/execution/operator/helper/physical_result_collector.hpp" +#include "duckdb/execution/operator/helper/physical_result_sink.hpp" #include "duckdb/function/scalar_function.hpp" #include "duckdb/function/table/arrow.hpp" #include "duckdb/function/table/arrow/arrow_duck_schema.hpp" #include "duckdb/function/table_function.hpp" +#include "duckdb/main/client_config.hpp" #include "duckdb/main/client_context.hpp" #include "duckdb/main/client_context_state.hpp" #include "duckdb/main/config.hpp" #include "duckdb/main/extension/extension_loader.hpp" +#include "duckdb/main/prepared_statement_data.hpp" + +#include +#include namespace duckdb { namespace sqlnb_results { @@ -100,7 +108,7 @@ static idx_t CountParameter(TableFunctionBindInput &input, const char *name) { return NumericCast(count); } -struct TeeBindData : public TableFunctionData { +struct TeeParameters { string id; string meta; idx_t head_rows; @@ -112,209 +120,924 @@ struct TeeBindData : public TableFunctionData { vector names; }; -static unique_ptr TeeBind(ClientContext &context, TableFunctionBindInput &input, - vector &return_types, vector &names) { - RejectAgentConnection(context, "sqlnb_result_tee"); - auto data = make_uniq(); - data->id = NamedParameter(input, "id").ToString(); - data->meta = NamedParameter(input, "meta").ToString(); - data->head_rows = CountParameter(input, "head_rows"); - data->head_bytes = CountParameter(input, "head_bytes"); - data->max_result_bytes = CountParameter(input, "max_result_bytes"); - data->max_cache_bytes = CountParameter(input, "max_cache_bytes"); - data->stop_at_limit = NamedParameter(input, "stop_at_limit").GetValue(); - data->types = input.input_table_types; - data->names = IdentifiersToStrings(input.input_table_names); - // Reject unsupported columns and taken ids before anything executes. - ArrowSchemaWrapper schema; - ExportSchema(context, data->types, data->names, schema.arrow_schema); - char *error = nullptr; - if (!sidequery_result_check(data->id.c_str(), data->meta.c_str(), &schema.arrow_schema, &error)) { - ThrowCacheError(error); +struct TeeBindData : public TableFunctionData { + shared_ptr parameters; +}; + +typedef unique_ptr (*tee_collector_t)(ClientContext &, PreparedStatementData &); +static unique_ptr TeeCollector(ClientContext &context, PreparedStatementData &data); + +// Carries a tee from the bind of its statement to the statement's result +// collector, and takes the collector hook down when the statement ends. +class TeeStatement : public ClientContextState { +public: + shared_ptr parameters; + // The collector hook in place when the statement was bound, such as Quack's. + get_result_collector_t previous; + bool hooked = false; + // Set once the statement's collector stores its result. + bool collecting = false; + + void Unhook(ClientContext &context) { + if (!hooked) { + return; + } + hooked = false; + auto &hook = ClientConfig::GetConfig(context).get_result_collector; + auto installed = hook.target(); + if (installed && *installed == TeeCollector) { + // Nobody replaced the hook since the bind: the one it replaced comes back. + hook = std::move(previous); + } + previous = nullptr; } - return_types = input.input_table_types; - names = input.input_table_names; - return std::move(data); -} -// Passes the first rows of the input through and stores every row. Rows leave -// in full chunks so that Quack can send them before the statement ends. -class TeeState : public GlobalTableFunctionState { + void QueryEnd(ClientContext &context) override { + Unhook(context); + parameters.reset(); + collecting = false; + } +}; + +// A result collector that hands every call to the collector it wraps: the one +// another extension installed for the statement. +class DelegatingCollector : public PhysicalResultCollector { public: - TeeState(ClientContext &context, const TeeBindData &bind) - : types(bind.types), properties(StorageProperties(context)), - extension_types(ArrowTypeExtensionData::GetExtensionTypes(context, bind.types)), - head_rows(bind.head_rows), head_bytes(bind.head_bytes), stop_at_limit(bind.stop_at_limit), - head_open(bind.head_rows > 0 && bind.head_bytes > 0) { + DelegatingCollector(PhysicalPlan &plan, PreparedStatementData &data, unique_ptr inner_p) + : PhysicalResultCollector(plan, data), inner(std::move(inner_p)) { + } + + unique_ptr GetGlobalSinkState(ClientContext &context) const override { + return inner->GetGlobalSinkState(context); + } + unique_ptr GetLocalSinkState(ExecutionContext &context) const override { + return inner->GetLocalSinkState(context); + } + SinkResultType Sink(ExecutionContext &context, DataChunk &chunk, OperatorSinkInput &input) const override { + return inner->Sink(context, chunk, input); + } + SinkNextBatchType NextBatch(ExecutionContext &context, OperatorSinkNextBatchInput &input) const override { + return inner->NextBatch(context, input); + } + SinkNextBatchType UpdateMinBatchIndex(ExecutionContext &context, OperatorSinkNextBatchInput &input) const override { + return inner->UpdateMinBatchIndex(context, input); + } + SinkCombineResultType Combine(ExecutionContext &context, OperatorSinkCombineInput &input) const override { + return inner->Combine(context, input); + } + void PrepareFinalize(ClientContext &context, GlobalSinkState &state) const override { + inner->PrepareFinalize(context, state); + } + SinkFinalizeType Finalize(Pipeline &pipeline, Event &event, ClientContext &context, + OperatorSinkFinalizeInput &input) const override { + return inner->Finalize(pipeline, event, context, input); + } + unique_ptr GetResult(GlobalSinkState &state) const override { + return Collector().GetResult(state); + } + ProgressData GetSinkProgress(ClientContext &context, GlobalSinkState &state, + const ProgressData source_progress) const override { + return inner->GetSinkProgress(context, state, source_progress); + } + bool ParallelSink() const override { + return inner->ParallelSink(); + } + OperatorPartitionInfo RequiredPartitionInfo() const override { + return inner->RequiredPartitionInfo(); + } + bool SinkOrderDependent() const override { + return inner->SinkOrderDependent(); + } + PipelineExternalInputSupport GetExternalInputSupport() const override { + return inner->GetExternalInputSupport(); + } + bool IsStreaming() const override { + return Collector().IsStreaming(); + } + bool BuildsOwnResult() const override { + return Collector().BuildsOwnResult(); + } + +private: + const PhysicalResultCollector &Collector() const { + return inner->Cast(); + } + + unique_ptr inner; +}; + +// Rows held back for the head, with their size as Arrow. +struct TeeHeldChunk { + unique_ptr chunk; + idx_t bytes; +}; + +class TeeLocalState; + +class TeeGlobalState : public GlobalSinkState { +public: + // An interrupted or failed statement never finishes its result. + ~TeeGlobalState() override { + if (writer) { + sidequery_result_abort(writer); + } + } + + idx_t MaxThreads(idx_t source_max_threads) override { + return inner->MaxThreads(source_max_threads); + } + + unique_ptr inner; + sidequery_result_writer *writer = nullptr; + atomic storing {true}; + atomic rows {0}; + // Numbers the stored batches of a result that has no executor batches. + atomic arrivals {0}; + // Set once the first rows of the result have been passed on. + atomic head_done {false}; + atomic passed_rows {0}; + atomic passed_bytes {0}; + // The lowest executor batch still being read, as far as any thread knows. + atomic min_batch {0}; + mutex head_lock; + // Head rows of ended executor batches, waiting for the batches before them. + map> waiting; + // Threads that have not combined. + idx_t threads = 0; + // Without executor batches the head is the chunks claimed first, in the + // order they were claimed. One thread at a time passes them on; the chunks + // other threads claim meanwhile queue up for it. + idx_t claims = 0; + idx_t claimed_rows = 0; + idx_t claimed_bytes = 0; + TeeLocalState *passer = nullptr; + std::deque queue; + // The passer's state in the wrapped collector when its sink is parallel: + // that collector keeps the order of one state's rows, not of several. + unique_ptr head_inner; +}; + +class TeeLocalState : public LocalSinkState { +public: + unique_ptr inner; + // Rows converted to Arrow that are not stored yet. + unique_ptr batch; + // Stored batches of this thread: the minor part of their key. + idx_t pieces = 0; + // The executor batch being read; unset for a result without executor batches. + optional_idx current_batch; + // Rows and bytes of the current batch that may belong to the head. + idx_t head_rows = 0; + idx_t head_bytes = 0; + // Head rows to pass on, in the result's order: those of the current batch + // and, once it is the lowest, those of the ended batches before it. + vector held; + idx_t held_passed = 0; + // Every batch before the current one has ended and its head rows were taken. + bool lowest = false; + // The chunk in hand was stored; a blocked call returns here with it. + bool chunk_taken = false; + // The chunk in hand is passed on once the held chunks are. + bool pass_chunk = false; + idx_t chunk_bytes = 0; + // Without executor batches: this thread passes the head on, and the + // queued chunk it is passing. + bool passer = false; + TeeHeldChunk passing; + bool reported_missing = false; + // Combine: this thread is no longer counted, and the batch the last + // waiting rows are passed on as, when that is not its own. + bool left = false; + optional_idx last_batch; +}; + +// Stores every row of a statement's result and passes only its first rows on +// to the collector BASE, which serves them to the client. It runs where that +// collector runs: on every thread of the statement's last pipeline. +// +// Threads store their rows as they produce them. A stored batch is keyed by +// its executor batch, and the result reads back in key order, so storing +// never waits for an earlier batch. +// +// Only the head needs the order while the statement runs, and the rows passed +// on are exactly the first rows of the result. The thread reading the lowest +// executor batch passes its rows on at once. Every other thread holds the +// first rows of its batch back; when the batch ends they wait in the global +// state for the thread whose batch becomes the lowest, or for the last thread +// to combine. A result without executor batches has no order to wait for: +// its head is the chunks that arrive first, stored first. +template +class TeeSink : public BASE { +public: + template + TeeSink(ClientContext &context, shared_ptr parameters_p, ARGS &&... args) + : BASE(std::forward(args)...), parameters(std::move(parameters_p)), + properties(StorageProperties(context)), + extension_types(ArrowTypeExtensionData::GetExtensionTypes(context, parameters->types)) { + } + + string GetName() const override { + return "SQLNB_RESULT_TEE"; + } + + unique_ptr GetGlobalSinkState(ClientContext &context) const override { + auto state = make_uniq(); + state->inner = BASE::GetGlobalSinkState(context); + state->head_done = parameters->head_rows == 0 || parameters->head_bytes == 0; ArrowSchemaWrapper schema; - ExportSchema(context, types, bind.names, schema.arrow_schema); + ExportSchema(context, parameters->types, parameters->names, schema.arrow_schema); char *error = nullptr; - writer = sidequery_result_begin(bind.id.c_str(), bind.meta.c_str(), &schema.arrow_schema, bind.head_rows, - bind.max_result_bytes, bind.max_cache_bytes, &error); - if (!writer) { + state->writer = sidequery_result_begin(parameters->id.c_str(), parameters->meta.c_str(), &schema.arrow_schema, + parameters->head_rows, parameters->max_result_bytes, + parameters->max_cache_bytes, &error); + if (!state->writer) { ThrowCacheError(error); } - pending.Initialize(context, types); + return std::move(state); } - // An interrupted or failed statement never finishes its result. - ~TeeState() override { - if (writer) { - sidequery_result_abort(writer); + unique_ptr GetLocalSinkState(ExecutionContext &context) const override { + auto state = make_uniq(); + state->inner = BASE::GetLocalSinkState(context); + auto &global = this->sink_state->template Cast(); + lock_guard guard(global.head_lock); + global.threads++; + return std::move(state); + } + + SinkResultType Sink(ExecutionContext &context, DataChunk &chunk, OperatorSinkInput &input) const override { + auto &global = input.global_state.template Cast(); + auto &local = input.local_state.template Cast(); + if (!local.chunk_taken) { + Take(global, local, chunk); + local.chunk_taken = true; + } + if (!PassHead(context, global, local, chunk, input.interrupt_state)) { + // The executor calls again with the same chunk. + return SinkResultType::BLOCKED; + } + local.chunk_taken = false; + if (StoppedAtLimit(global)) { + // This thread reads no further, so the rest of its batch is not stored. + ReportMissing(global, local); + return SinkResultType::FINISHED; } + return SinkResultType::NEED_MORE_INPUT; } - // One thread runs the pipeline, so rows reach the cache in the statement's order. - idx_t MaxThreads() const override { - return 1; + // The executor has already moved partition_info to the next batch. + SinkNextBatchType NextBatch(ExecutionContext &context, OperatorSinkNextBatchInput &input) const override { + auto &global = input.global_state.template Cast(); + auto &local = input.local_state.template Cast(); + if (local.current_batch.IsValid() && !EndBatch(context, global, local, input.interrupt_state)) { + return SinkNextBatchType::BLOCKED; + } + SyncPartition(global, local, local.partition_info.batch_index); + OperatorSinkNextBatchInput inner {*global.inner, *local.inner, input.interrupt_state}; + if (BASE::NextBatch(context, inner) == SinkNextBatchType::BLOCKED) { + return SinkNextBatchType::BLOCKED; + } + StartBatch(local); + return SinkNextBatchType::READY; + } + + SinkNextBatchType UpdateMinBatchIndex(ExecutionContext &context, + OperatorSinkNextBatchInput &input) const override { + auto &global = input.global_state.template Cast(); + auto &local = input.local_state.template Cast(); + SyncPartition(global, local, local.partition_info.batch_index); + OperatorSinkNextBatchInput inner {*global.inner, *local.inner, input.interrupt_state}; + return BASE::UpdateMinBatchIndex(context, inner); + } + + SinkCombineResultType Combine(ExecutionContext &context, OperatorSinkCombineInput &input) const override { + auto &global = input.global_state.template Cast(); + auto &local = input.local_state.template Cast(); + if (!LeaveHead(context, global, local, input.interrupt_state)) { + return SinkCombineResultType::BLOCKED; + } + SyncPartition(global, local, InnerBatch(local)); + OperatorSinkCombineInput inner {*global.inner, *local.inner, input.interrupt_state}; + if (BASE::Combine(context, inner) == SinkCombineResultType::BLOCKED) { + return SinkCombineResultType::BLOCKED; + } + return SinkCombineResultType::FINISHED; + } + + void PrepareFinalize(ClientContext &context, GlobalSinkState &state) const override { + BASE::PrepareFinalize(context, *state.template Cast().inner); } - OperatorResultType Consume(DataChunk &input, DataChunk &output) { - while (input_offset < input.size() && !StoppedAtLimit()) { - if (!head_open) { - Store(input, input_offset, input.size()); - rows += input.size() - input_offset; - input_offset = input.size(); - break; + SinkFinalizeType Finalize(Pipeline &pipeline, Event &event, ClientContext &context, + OperatorSinkFinalizeInput &input) const override { + auto &global = input.global_state.template Cast(); + OperatorSinkFinalizeInput inner {*global.inner, input.interrupt_state}; + auto result = BASE::Finalize(pipeline, event, context, inner); + if (result != SinkFinalizeType::BLOCKED && global.writer) { + // Every thread has combined: the result becomes readable. + sidequery_result_finish(global.writer, global.rows, !StoppedAtLimit(global)); + global.writer = nullptr; + } + return result; + } + + unique_ptr GetResult(GlobalSinkState &state) const override { + return BASE::GetResult(*state.template Cast().inner); + } + + ProgressData GetSinkProgress(ClientContext &context, GlobalSinkState &state, + const ProgressData source_progress) const override { + return BASE::GetSinkProgress(context, *state.template Cast().inner, source_progress); + } + +private: + bool BatchOrdered() const { + return this->RequiredPartitionInfo().RequiresBatchIndex(); + } + + // A statement the read policy verifies stops reading once nothing more is stored. + bool StoppedAtLimit(TeeGlobalState &global) const { + return parameters->stop_at_limit && !global.storing; + } + + void StartBatch(TeeLocalState &local) const { + local.current_batch = local.partition_info.batch_index; + local.head_rows = 0; + local.head_bytes = 0; + local.lowest = false; + } + + // Stores a chunk and decides whether it may belong to the head. + void Take(TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk) const { + auto batches = BatchOrdered(); + if (batches && !local.current_batch.IsValid()) { + StartBatch(local); + } + global.rows += chunk.size(); + local.pass_chunk = false; + if (!batches) { + if (global.head_done) { + Store(global, local, chunk); + } else { + ClaimChunk(global, local, chunk); } - auto chunk_rows = MinValue(STANDARD_VECTOR_SIZE, head_rows - returned_rows); - auto take = MinValue(input.size() - input_offset, chunk_rows - pending.size()); - pending.Append(input, SelectionVector(input_offset, take), take); - input_offset += take; - rows += take; - if (pending.size() == chunk_rows) { - EmitHead(output); - if (input_offset < input.size() && !StoppedAtLimit()) { - return OperatorResultType::HAVE_MORE_OUTPUT; + return; + } + auto bytes = Store(global, local, chunk); + local.chunk_bytes = bytes; + if (global.head_done) { + return; + } + if (local.head_rows >= parameters->head_rows || local.head_bytes >= parameters->head_bytes) { + // The batch has given the head all it can take. + return; + } + local.head_rows += chunk.size(); + local.head_bytes += bytes; + if (BecomeLowest(global, local)) { + local.pass_chunk = true; + return; + } + local.held.push_back(Copy(chunk, bytes)); + } + + // Without executor batches: makes the chunk the next of the head and + // stores it there, unless the head got all its rows meanwhile. + void ClaimChunk(TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk) const { + // The rows this thread has not stored yet come after the head. + FlushStore(global, local); + auto bytes = Convert(global, local, chunk); + idx_t claim; + { + unique_lock guard(global.head_lock); + if (global.head_done) { + guard.unlock(); + // The chunk is stored with the rows that follow it. + if (!local.batch) { + ReportMissing(global, local); } + return; + } + claim = global.claims++; + global.claimed_rows += chunk.size(); + global.claimed_bytes += bytes; + if (global.claimed_rows >= parameters->head_rows || global.claimed_bytes >= parameters->head_bytes) { + global.head_done = true; + } + if (!global.passer) { + global.passer = &local; + local.passer = true; + local.pass_chunk = true; + } else { + global.queue.push_back(Copy(chunk, bytes)); } } - if (StoppedAtLimit()) { - if (output.size() > 0) { - // DuckDB drops the rows of a call that returns FINISHED; finish on the next call. - return OperatorResultType::HAVE_MORE_OUTPUT; + FlushStoreAs(global, local, 0, claim); + } + + static TeeHeldChunk Copy(DataChunk &chunk, idx_t bytes) { + TeeHeldChunk held; + held.chunk = make_uniq(); + held.chunk->Initialize(Allocator::DefaultAllocator(), chunk.GetTypes(), MaxValue(chunk.size(), 1)); + chunk.Copy(*held.chunk); + held.bytes = bytes; + return held; + } + + // Without executor batches: passes one chunk of the head on. False when + // the wrapped collector blocked without taking the chunk. + bool PassClaimed(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk, + InterruptState &interrupt) const { + auto state = local.inner.get(); + if (this->ParallelSink()) { + if (!global.head_inner) { + global.head_inner = BASE::GetLocalSinkState(context); } - // Stop reading, as a LIMIT would, and publish what was stored. DuckDB does - // not call the final function of an operator that finished early. - input_offset = 0; - Complete(false); - return OperatorResultType::FINISHED; + state = global.head_inner.get(); + state->partition_info = local.partition_info; + } else { + SyncPartition(global, local, InnerBatch(local)); } - input_offset = 0; - return OperatorResultType::NEED_MORE_INPUT; + OperatorSinkInput inner {*global.inner, *state, interrupt}; + return BASE::Sink(context, chunk, inner) != SinkResultType::BLOCKED; + } + + // The passer passes on the chunks other threads claimed meanwhile, then + // gives the role up. Once no more chunks can follow, it first combines the + // state it passed them through. False when the wrapped collector blocked; + // this thread stays the passer and the next call continues. + bool FinishPassing(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, + InterruptState &interrupt) const { + while (true) { + if (local.passing.chunk) { + if (!PassClaimed(context, global, local, *local.passing.chunk, interrupt)) { + return false; + } + local.passing.chunk.reset(); + } + unique_lock guard(global.head_lock); + if (!global.queue.empty()) { + local.passing = std::move(global.queue.front()); + global.queue.pop_front(); + continue; + } + if (global.head_inner && (global.head_done || global.threads == 0)) { + guard.unlock(); + global.head_inner->partition_info = local.partition_info; + OperatorSinkCombineInput inner {*global.inner, *global.head_inner, interrupt}; + if (BASE::Combine(context, inner) == SinkCombineResultType::BLOCKED) { + return false; + } + // A thread that starts later passes its chunks through a new state. + global.head_inner.reset(); + continue; + } + global.passer = nullptr; + local.passer = false; + return true; + } + } + + // The lowest batch only rises. A thread learns it when its own batch + // changes, so the threads share the highest value any of them has seen. + idx_t PublishMinBatch(TeeGlobalState &global, TeeLocalState &local) const { + auto seen = local.partition_info.min_batch_index.IsValid() ? local.partition_info.min_batch_index.GetIndex() : 0; + auto known = global.min_batch.load(); + while (seen > known && !global.min_batch.compare_exchange_weak(known, seen)) { + } + return MaxValue(seen, known); + } + + // Whether every executor batch before this thread's has ended. The first + // time it has, the head rows those batches left waiting become this + // thread's to pass on, before its own. + bool BecomeLowest(TeeGlobalState &global, TeeLocalState &local) const { + if (local.lowest) { + return true; + } + if (local.current_batch.GetIndex() > PublishMinBatch(global, local)) { + return false; + } + lock_guard guard(global.head_lock); + TakeWaitingBefore(global, local); + return true; + } + + // Requires head_lock. A batch leaves its rows waiting before the lowest + // batch moves past it, so none arrive here later. + void TakeWaitingBefore(TeeGlobalState &global, TeeLocalState &local) const { + auto end = global.waiting.lower_bound(local.current_batch.GetIndex()); + vector before; + for (auto entry = global.waiting.begin(); entry != end; entry++) { + for (auto &held : entry->second) { + before.push_back(std::move(held)); + } + } + global.waiting.erase(global.waiting.begin(), end); + if (!before.empty()) { + // Nothing of this batch was passed on while a batch before it was read. + D_ASSERT(local.held_passed == 0); + for (auto &held : local.held) { + before.push_back(std::move(held)); + } + local.held = std::move(before); + } + local.lowest = true; + } + + // The batch the wrapped collector is told this thread reads. + static optional_idx InnerBatch(TeeLocalState &local) { + return local.current_batch.IsValid() ? local.current_batch : local.partition_info.batch_index; } - void Finish(DataChunk &output) { - if (!writer) { + // Gives the wrapped collector the partition of the batch its next call is for. + void SyncPartition(TeeGlobalState &global, TeeLocalState &local, optional_idx batch) const { + local.inner->partition_info = local.partition_info; + if (!BatchOrdered()) { return; } - if (head_open && pending.size() > 0) { - // The whole input was shorter than the head. - EmitHead(output); + local.inner->partition_info.batch_index = batch; + local.inner->partition_info.min_batch_index = PublishMinBatch(global, local); + } + + // Passes one chunk to the wrapped collector. False when it blocked without + // taking the chunk. + bool PassChunk(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk, + idx_t bytes, InterruptState &interrupt) const { + SyncPartition(global, local, InnerBatch(local)); + OperatorSinkInput inner {*global.inner, *local.inner, interrupt}; + if (BASE::Sink(context, chunk, inner) == SinkResultType::BLOCKED) { + return false; } - Complete(true); + auto rows = global.passed_rows.fetch_add(chunk.size()) + chunk.size(); + auto passed = global.passed_bytes.fetch_add(bytes) + bytes; + if (rows >= parameters->head_rows || passed >= parameters->head_bytes) { + CloseHead(global, local); + } + return true; } -private: - bool StoppedAtLimit() const { - return stop_at_limit && !storing; + void CloseHead(TeeGlobalState &global, TeeLocalState &local) const { + global.head_done = true; + lock_guard guard(global.head_lock); + global.waiting.clear(); + } + + // Passes on the chunks this thread holds for the head. False when the + // wrapped collector blocked; the next call continues where this one stopped. + bool PassHeld(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, + InterruptState &interrupt) const { + while (local.held_passed < local.held.size() && !global.head_done) { + auto &held = local.held[local.held_passed]; + if (!PassChunk(context, global, local, *held.chunk, held.bytes, interrupt)) { + return false; + } + local.held_passed++; + } + DropHeld(local); + return true; + } + + static void DropHeld(TeeLocalState &local) { + local.held.clear(); + local.held_passed = 0; + } + + // Passes on what the head needs from this thread now. `chunk` is the chunk + // in hand. False when the wrapped collector blocked. + bool PassHead(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk, + InterruptState &interrupt) const { + if (!BatchOrdered()) { + if (!local.passer) { + return true; + } + if (local.pass_chunk && !PassClaimed(context, global, local, chunk, interrupt)) { + return false; + } + local.pass_chunk = false; + return FinishPassing(context, global, local, interrupt); + } + if (!global.head_done && !BecomeLowest(global, local)) { + return true; + } + if (!PassHeld(context, global, local, interrupt)) { + return false; + } + if (local.pass_chunk && !global.head_done && + !PassChunk(context, global, local, chunk, local.chunk_bytes, interrupt)) { + return false; + } + local.pass_chunk = false; + return true; + } + + // Stores what is left of this thread's batch. Its head rows are passed on + // if every batch before it has ended, and wait for those batches if not. + // False when the wrapped collector blocked. + bool EndBatch(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, + InterruptState &interrupt) const { + FlushStore(global, local); + if (!global.head_done && !BecomeLowest(global, local)) { + LeaveWaiting(global, local); + return true; + } + return PassHeld(context, global, local, interrupt); + } + + void LeaveWaiting(TeeGlobalState &global, TeeLocalState &local) const { + if (local.held.empty()) { + return; + } + lock_guard guard(global.head_lock); + WaitLocked(global, local); + } + + // Requires head_lock. + static void WaitLocked(TeeGlobalState &global, TeeLocalState &local) { + if (!local.held.empty()) { + global.waiting[local.current_batch.GetIndex()] = std::move(local.held); + } + DropHeld(local); + } + + // The end of this thread's rows. Its head rows are passed on or left + // waiting as at the end of a batch, except for the last thread: no thread + // is left to take the rows that wait, so it passes all of them on. False + // when the wrapped collector blocked. + bool LeaveHead(ExecutionContext &context, TeeGlobalState &global, TeeLocalState &local, + InterruptState &interrupt) const { + FlushStore(global, local); + auto batches = BatchOrdered(); + if (!local.left) { + local.left = true; + lock_guard guard(global.head_lock); + auto last = --global.threads == 0; + if (!batches) { + if (last && global.head_inner && !global.passer) { + // Nothing follows the chunks passed on so far: their state is combined. + global.passer = &local; + local.passer = true; + } + } else if (global.head_done) { + DropHeld(local); + } else if (last) { + TakeAllWaiting(global, local); + } else if (local.current_batch.IsValid()) { + if (local.lowest || local.current_batch.GetIndex() <= PublishMinBatch(global, local)) { + TakeWaitingBefore(global, local); + } else { + WaitLocked(global, local); + } + } + } + if (!batches) { + return !local.passer || FinishPassing(context, global, local, interrupt); + } + if (local.last_batch.IsValid() && !global.head_done) { + // The rows of later batches cannot be passed on as part of this + // thread's batch: the wrapped collector is told of a batch after them. + SyncPartition(global, local, local.last_batch); + OperatorSinkNextBatchInput inner {*global.inner, *local.inner, interrupt}; + if (BASE::NextBatch(context, inner) == SinkNextBatchType::BLOCKED) { + return false; + } + local.current_batch = local.last_batch; + } + local.last_batch = optional_idx(); + return PassHeld(context, global, local, interrupt); } - void EmitHead(DataChunk &output) { - auto bytes = Store(pending, 0, pending.size()); - output.Append(pending); - returned_rows += pending.size(); - returned_bytes += bytes; - pending.Reset(); - if (returned_rows >= head_rows || returned_bytes >= head_bytes) { - head_open = false; + // Requires head_lock. Every other thread has combined, so the batches that + // wait and this thread's own are all that is left of the head. + void TakeAllWaiting(TeeGlobalState &global, TeeLocalState &local) const { + auto batch = local.partition_info.batch_index.GetIndex(); + auto last = batch; + vector all; + auto own_placed = !local.current_batch.IsValid(); + auto place_own = [&]() { + for (idx_t i = local.held_passed; i < local.held.size(); i++) { + all.push_back(std::move(local.held[i])); + } + own_placed = true; + }; + for (auto &entry : global.waiting) { + if (!own_placed && entry.first > local.current_batch.GetIndex()) { + place_own(); + } + for (auto &held : entry.second) { + all.push_back(std::move(held)); + } + last = MaxValue(last, entry.first); + } + if (!own_placed) { + place_own(); + } + global.waiting.clear(); + local.held = std::move(all); + local.held_passed = 0; + local.lowest = true; + if (last != batch && !local.held.empty()) { + local.last_batch = last; } } - // Converts rows into the batch being built and returns their Arrow bytes. - // Rows are converted while storing, or while the head still needs their size. - idx_t Store(DataChunk &chunk, idx_t from, idx_t to) { - if (!storing && !head_open) { + // Adds a chunk to the Arrow batch this thread is building and returns its + // Arrow bytes. Rows are converted while they are stored, or while the head + // still needs their size. A failure to store never fails the statement. + idx_t Convert(TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk) const { + if (!global.storing && global.head_done) { return 0; } try { - if (!batch) { - batch = make_uniq(types, BATCH_ROWS, properties, extension_types); - } - auto before = batch->ByteSize(); - batch->Append(chunk, from, to, chunk.size()); - auto bytes = batch->ByteSize() - before; - if (batch->RowCount() >= BATCH_ROWS || batch->ByteSize() >= BATCH_BYTES) { - Flush(); + if (!local.batch) { + local.batch = make_uniq(parameters->types, BATCH_ROWS, properties, extension_types); } - return bytes; + auto before = local.batch->ByteSize(); + local.batch->Append(chunk, 0, chunk.size(), chunk.size()); + return local.batch->ByteSize() - before; } catch (std::exception &) { - // A failure to store never fails the statement. - batch.reset(); - StopStoring(); + local.batch.reset(); + global.storing = false; return 0; } } - void Flush() { - if (!batch || batch->RowCount() == 0) { - return; + // Stores a chunk in this thread's place in the result. + idx_t Store(TeeGlobalState &global, TeeLocalState &local, DataChunk &chunk) const { + auto bytes = Convert(global, local, chunk); + if (!local.batch) { + ReportMissing(global, local); + } else if (local.batch->RowCount() >= BATCH_ROWS || local.batch->ByteSize() >= BATCH_BYTES) { + FlushStore(global, local); } - ArrowArrayWrapper array; - array.arrow_array = batch->Finalize(); - batch.reset(); - if (storing) { - storing = sidequery_result_append(writer, &array.arrow_array); + return bytes; + } + + // The key of the next batch this thread stores: executor batch, then the + // thread's own count. Without executor batches: after the head, in the + // order of arrival. + void NextKey(TeeGlobalState &global, TeeLocalState &local, idx_t &major, idx_t &minor) const { + if (BatchOrdered()) { + major = InnerBatch(local).GetIndex(); + minor = local.pieces++; + } else { + major = 1; + minor = global.arrivals++; } } - void StopStoring() { - if (storing) { - storing = false; - sidequery_result_stop(writer); + void FlushStore(TeeGlobalState &global, TeeLocalState &local) const { + if (!local.batch || local.batch->RowCount() == 0) { + local.batch.reset(); + return; } + idx_t major; + idx_t minor; + NextKey(global, local, major, minor); + FlushStoreAs(global, local, major, minor); } - void Complete(bool rows_exact) { - try { - Flush(); - } catch (std::exception &) { - StopStoring(); + // Stores the rows this thread converted as the batch with this key, or + // tells the cache that the batch is the first without its rows. + void FlushStoreAs(TeeGlobalState &global, TeeLocalState &local, idx_t major, idx_t minor) const { + auto batch = std::move(local.batch); + if (batch && batch->RowCount() > 0 && global.storing) { + try { + ArrowArrayWrapper array; + array.arrow_array = batch->Finalize(); + if (sidequery_result_append(global.writer, &array.arrow_array, major, minor)) { + return; + } + // The cache has recorded the batch as missing. + global.storing = false; + local.reported_missing = true; + return; + } catch (std::exception &) { + } + } + global.storing = false; + if (!local.reported_missing) { + local.reported_missing = true; + sidequery_result_missing(global.writer, major, minor); } - sidequery_result_finish(writer, rows, rows_exact); - writer = nullptr; } - sidequery_result_writer *writer = nullptr; - const vector types; + // Tells the cache that the next batch of this thread is the first of the + // result without its rows. + void ReportMissing(TeeGlobalState &global, TeeLocalState &local) const { + global.storing = false; + if (local.reported_missing) { + return; + } + local.reported_missing = true; + idx_t major; + idx_t minor; + NextKey(global, local, major, minor); + sidequery_result_missing(global.writer, major, minor); + } + + const shared_ptr parameters; const ClientProperties properties; const unordered_map> extension_types; - const idx_t head_rows; - const idx_t head_bytes; - const bool stop_at_limit; - // Rows of the head that do not fill a chunk yet. - DataChunk pending; - unique_ptr batch; - bool head_open; - bool storing = true; - idx_t input_offset = 0; - idx_t rows = 0; - idx_t returned_rows = 0; - idx_t returned_bytes = 0; }; -static unique_ptr TeeInit(ClientContext &context, TableFunctionInitInput &input) { - return make_uniq(context, input.bind_data->Cast()); +static constexpr const char *TEE_STATEMENT = "sqlnb_result_tee"; +static constexpr const char *TEE_PLACEMENT = + "sqlnb_result_tee keeps the result of a SELECT statement that returns its columns unchanged: " + "select * from sqlnb_result_tee(...)"; + +// Wraps the collector the statement would have had. +static unique_ptr TeeCollector(ClientContext &context, PreparedStatementData &data) { + auto statement = context.registered_state->Get(TEE_STATEMENT); + shared_ptr parameters; + if (statement) { + parameters = statement->parameters; + statement->Unhook(context); + } + auto &previous = ClientConfig::GetConfig(context).get_result_collector; + auto inner = previous ? previous(context, data) : PhysicalResultCollector::GetResultCollector(context, data); + if (!parameters) { + return inner; + } + // What is kept is the statement's result, in the schema checked at bind. + if (data.statement_type != StatementType::SELECT_STATEMENT || + data.properties.return_type != StatementReturnType::QUERY_RESULT || data.types != parameters->types || + IdentifiersToStrings(data.names) != parameters->names) { + throw InvalidInputException(TEE_PLACEMENT); + } + statement->collecting = true; + auto &plan = *data.physical_plan; + if (inner->Cast().BuildsOwnResult()) { + return make_uniq>(context, std::move(parameters), plan, data, std::move(inner)); + } + // DuckDB's own collector is handed its result buffer after this returns, so + // the tee has to be that collector. + auto ordering = inner->Cast().ordering; + return make_uniq>(context, std::move(parameters), plan, data, ordering); } -static OperatorResultType TeeExecute(ExecutionContext &, TableFunctionInput &data, DataChunk &input, - DataChunk &output) { - return data.global_state->Cast().Consume(input, output); +static unique_ptr TeeBind(ClientContext &context, TableFunctionBindInput &input, + vector &return_types, vector &names) { + RejectAgentConnection(context, "sqlnb_result_tee"); + auto parameters = make_shared_ptr(); + parameters->id = NamedParameter(input, "id").ToString(); + parameters->meta = NamedParameter(input, "meta").ToString(); + parameters->head_rows = CountParameter(input, "head_rows"); + parameters->head_bytes = CountParameter(input, "head_bytes"); + parameters->max_result_bytes = CountParameter(input, "max_result_bytes"); + parameters->max_cache_bytes = CountParameter(input, "max_cache_bytes"); + parameters->stop_at_limit = NamedParameter(input, "stop_at_limit").GetValue(); + parameters->types = input.input_table_types; + parameters->names = IdentifiersToStrings(input.input_table_names); + // Reject unsupported columns and taken ids before anything executes. + ArrowSchemaWrapper schema; + ExportSchema(context, parameters->types, parameters->names, schema.arrow_schema); + char *error = nullptr; + if (!sidequery_result_check(parameters->id.c_str(), parameters->meta.c_str(), &schema.arrow_schema, &error)) { + ThrowCacheError(error); + } + auto statement = context.registered_state->GetOrCreate(TEE_STATEMENT); + if (statement->parameters && statement->parameters->id != parameters->id) { + throw InvalidInputException("a statement keeps one result: sqlnb_result_tee appears twice"); + } + statement->parameters = parameters; + if (!statement->hooked && !statement->collecting) { + // The statement's collector is created after its plan. Until then the + // hook is this function's; the collector it replaces is asked first. + auto &config = ClientConfig::GetConfig(context); + statement->previous = config.get_result_collector; + config.get_result_collector = tee_collector_t(TeeCollector); + statement->hooked = true; + } + auto data = make_uniq(); + data->parameters = std::move(parameters); + return_types = input.input_table_types; + names = input.input_table_names; + return std::move(data); +} + +// The function itself passes its input through on every thread; the +// statement's collector does the storing. +class TeeFunctionState : public GlobalTableFunctionState { +public: + idx_t MaxThreads() const override { + return MAX_THREADS; + } +}; + +static unique_ptr TeeInit(ClientContext &context, TableFunctionInitInput &input) { + auto statement = context.registered_state->Get(TEE_STATEMENT); + auto ¶meters = input.bind_data->Cast().parameters; + if (!statement || !statement->collecting || !statement->parameters || statement->parameters->id != parameters->id) { + // Without the collector the rows would pass through and never be kept. + throw InvalidInputException(TEE_PLACEMENT); + } + return make_uniq(); } -static OperatorFinalizeResultType TeeFinal(ExecutionContext &, TableFunctionInput &data, DataChunk &output) { - data.global_state->Cast().Finish(output); - return OperatorFinalizeResultType::FINISHED; +static OperatorResultType TeeExecute(ExecutionContext &, TableFunctionInput &, DataChunk &input, DataChunk &output) { + output.Reference(input); + return OperatorResultType::NEED_MORE_INPUT; } static unique_ptr BindArrowScan(ClientContext &context, shared_ptr factory, @@ -453,7 +1176,6 @@ static void RegisterSQLNBResults(ExtensionLoader &loader) { .AddKeywordOnly("stop_at_limit", LogicalType::BOOLEAN, Value::BOOLEAN(false)), nullptr, TeeBind, TeeInit); tee.in_out_function = TeeExecute; - tee.in_out_function_final = TeeFinal; loader.RegisterFunction(tee); TableFunction results("sqlnb_results", {}, ArrowTableFunction::ArrowScanFunction, ResultListBind, diff --git a/test/sql/results.test b/test/sql/results.test index 4526eb4..957a81e 100644 --- a/test/sql/results.test +++ b/test/sql/results.test @@ -2,22 +2,39 @@ # unique to this file. require sqlnb -# Only the head passes through the tee; every row is stored. -query III -select count(*), min(i), max(i) from sqlnb_result_tee((select i, i * 1.5 as amount, 'c-' || (i % 7) as label from range(50000) t(i)), id := 'a0000000000000000000000000000001', meta := '{"cell":1}'); ----- -10240 0 10239 +# The statement returns its first rows; every row is stored. +statement ok +select * from sqlnb_result_tee((select i, i * 1.5 as amount, 'c-' || (i % 7) as label from range(50000) t(i)), id := 'a0000000000000000000000000000001', meta := '{"cell":1}'); query I -select count(*) from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000002'); +select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000002'); ---- 1 # A result with more rows than its head is written to a file. +statement ok +select * from sqlnb_result_tee((select * from range(5000) t(i)), id := 'a0000000000000000000000000000003', head_rows := 3000); + +# The tee has to be the statement's whole output. +statement error +select count(*) from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000090'); +---- +returns its columns unchanged + +statement error +create table misplaced as select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000091'); +---- +returns its columns unchanged + +statement error +select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000092'), sqlnb_result_tee((select 2 as two), id := 'a0000000000000000000000000000093'); +---- +keeps one result + query I -select count(*) from sqlnb_result_tee((select * from range(5000) t(i)), id := 'a0000000000000000000000000000003', head_rows := 3000); +select count(*) from sqlnb_results() where id >= 'a0000000000000000000000000000090'; ---- -3000 +0 query TIIITTTI select id, rows, stored_rows, in_memory, limit_reason, meta, rows_exact, elapsed_ms >= 0 and created_ms > 0 from sqlnb_results() where id like 'a000000000000000000000000000000%' order by id; @@ -86,7 +103,7 @@ SQLNB_RESULT_UNSUPPORTED: # A failing statement leaves nothing readable and frees its id. statement error -select count(*) from sqlnb_result_tee((select case when i = 40000 then error('tee failed') else i end as i from range(50000) t(i)), id := 'a0000000000000000000000000000004'); +select * from sqlnb_result_tee((select case when i = 40000 then error('tee failed') else i end as i from range(50000) t(i)), id := 'a0000000000000000000000000000004'); ---- tee failed @@ -96,17 +113,17 @@ select count(*) from sqlnb_results() where id = 'a000000000000000000000000000000 0 query I -select count(*) from sqlnb_result_tee((select 1), id := 'a0000000000000000000000000000004'); +select * from sqlnb_result_tee((select 1), id := 'a0000000000000000000000000000004'); ---- 1 # A limit stops storing but every row is still counted; stop_at_limit also # stops reading, so rows becomes a lower bound. statement ok -select count(*) from sqlnb_result_tee((select i from range(100000000) t(i)), id := 'a0000000000000000000000000000005', max_result_bytes := 100000, stop_at_limit := true); +select * from sqlnb_result_tee((select i from range(100000000) t(i)), id := 'a0000000000000000000000000000005', max_result_bytes := 100000, stop_at_limit := true); statement ok -select count(*) from sqlnb_result_tee((select i from range(10000000) t(i)), id := 'a0000000000000000000000000000006', max_result_bytes := 100000); +select * from sqlnb_result_tee((select i from range(10000000) t(i)), id := 'a0000000000000000000000000000006', max_result_bytes := 100000); query TIITI select id, rows < 1000000, stored_rows > 0 and stored_rows <= rows, limit_reason, rows_exact from sqlnb_results() where id in ('a0000000000000000000000000000005', 'a0000000000000000000000000000006') order by id; @@ -124,6 +141,36 @@ select (select count(*) = max(i) + 1 from sqlnb_result('a00000000000000000000000 ---- true +# The statement runs on all its threads and its rows are stored in its order. +statement ok +create table tee_scan as select i, hash(i) as h from range(3000000) t(i); + +statement ok +select * from sqlnb_result_tee((select i, h from tee_scan where i % 3 = 0), id := 'a0000000000000000000000000000007'); + +statement ok +select * from sqlnb_result_tee((select i, h from tee_scan order by i desc), id := 'a0000000000000000000000000000008'); + +query IIII +select (select count(*) from sqlnb_result('a0000000000000000000000000000007')), (select bool_and(i = position * 3) from sqlnb_result('a0000000000000000000000000000007', row_number := 'position')), (select count(*) from sqlnb_result('a0000000000000000000000000000008')), (select bool_and(i = 2999999 - position) from sqlnb_result('a0000000000000000000000000000008', row_number := 'position')); +---- +1000000 true 3000000 true + +# A verified read stopped at the limit keeps a prefix, whatever its threads stored. +statement ok +select * from sqlnb_result_tee((select i, h from tee_scan), id := 'a0000000000000000000000000000009', max_result_bytes := 4000000, stop_at_limit := true); + +query II +select count(*) > 0, bool_and(i = position) from sqlnb_result('a0000000000000000000000000000009', row_number := 'position'); +---- +true true + +statement ok +select sqlnb_result_drop('a0000000000000000000000000000007'), sqlnb_result_drop('a0000000000000000000000000000008'), sqlnb_result_drop('a0000000000000000000000000000009'); + +statement ok +drop table tee_scan; + query I select sqlnb_result_drop('a0000000000000000000000000000001'); ---- From d634f22348666ed61c2fed415521293d12544af5 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:07:23 -0800 Subject: [PATCH 06/14] Remove the files the result cache smoke checks write --- scripts/runtime-smoke.mjs | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/scripts/runtime-smoke.mjs b/scripts/runtime-smoke.mjs index e0f3e33..4efcbb1 100644 --- a/scripts/runtime-smoke.mjs +++ b/scripts/runtime-smoke.mjs @@ -8,6 +8,7 @@ import { readdirSync, readFileSync, realpathSync, + rmSync, statSync, symlinkSync, writeFileSync, @@ -184,10 +185,15 @@ function runSQL(sql) { // For a result of more than one row: the CLI prints one row per line, and // runSQL reads a line. async function runRows(sql) { - const file = join(mkdtempSync(join(tmpdir(), 'sidequery-ui-rows.')), 'rows.json'); - child.stdin.write(`.once ${file}\n${sql};\n`); - await runSQL('select 1 as done'); - return JSON.parse(readFileSync(file, 'utf8')); + const directory = mkdtempSync(join(tmpdir(), 'sidequery-ui-rows.')); + const file = join(directory, 'rows.json'); + try { + child.stdin.write(`.once ${file}\n${sql};\n`); + await runSQL('select 1 as done'); + return JSON.parse(readFileSync(file, 'utf8')); + } finally { + rmSync(directory, { recursive: true, force: true }); + } } // For a statement whose own output is not a row to assert on. @@ -770,7 +776,8 @@ if (hasResultCache) { // order: a scan with a filter, a sort, several Parquet files, and a verified // read stopped at the limit while many threads store. await runStatement('create table tee_scan as select i, hash(i) as h from range(3000000) t(i)'); - const parquet = join(mkdtempSync(join(tmpdir(), 'sidequery-ui-results.')), 'part'); + const parquetDirectory = mkdtempSync(join(tmpdir(), 'sidequery-ui-results.')); + const parquet = join(parquetDirectory, 'part'); for (const part of [0, 1, 2]) { await runStatement(`copy (select i from range(${part * 400000}, ${(part + 1) * 400000}) t(i)) to ${sqlLiteral(`${parquet}${part}.parquet`)} (row_group_size 50000)`); } @@ -815,6 +822,7 @@ if (hasResultCache) { assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${resultId(number)}')`)), true); } await runStatement('drop table tee_scan'); + rmSync(parquetDirectory, { recursive: true, force: true }); // The agent connection cannot reach the cache, on either SQL tool. for (const sql of [ 'select * from sqlnb_results()', From 2f82063c456d14df00f1df2b38663f94c1f9e9c1 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:34:49 -0800 Subject: [PATCH 07/14] Expire unused results, keep 8 GiB by default and leave room on the disk sqlnb_result_tee takes ttl_seconds (24 hours unless named, NULL for as long as DuckDB runs). A result expires that long after its statement finished or sqlnb_result last read it, and is then gone like an evicted one. There is no timer: binding or beginning a tee, listing, reading and dropping remove what expired. sqlnb_results() reports last_used_ms and expires_ms. The cache keeps 8 GiB unless a tee names another limit, and a tee whose limit is below what is kept evicts the oldest results when it begins instead of when it first stores a batch. Nothing more is written to a result file once its volume would have less than 5 GiB free, or a tenth of a volume smaller than 50 GiB. Storing stops with limit_reason 'disk-space'; the statement runs on. The defaults now live with the cache in Rust and reach the function through sidequery_result_defaults. --- docs/results.md | 62 +++++-- http/src/platform.rs | 8 + http/src/platform/unix.rs | 14 ++ http/src/platform/windows.rs | 11 ++ http/src/results.rs | 239 +++++++++++++++++++++----- http/src/results/tests.rs | 311 +++++++++++++++++++++++++++++++++- scripts/runtime-smoke.mjs | 42 ++++- src/include/sidequery_http.h | 13 +- src/include/sqlnb_results.hpp | 23 ++- test/sql/results.test | 35 +++- 10 files changed, 695 insertions(+), 63 deletions(-) diff --git a/docs/results.md b/docs/results.md index bbb9a80..f772ac0 100644 --- a/docs/results.md +++ b/docs/results.md @@ -24,7 +24,8 @@ select * from sqlnb_result_tee( | `head_bytes` | 4 MiB | Arrow buffer bytes returned to the caller. | | `meta` | `''` | Caller data returned by `sqlnb_results()`, at most 64 KiB. | | `max_result_bytes` | 4 GiB | Bytes stored for this result. | -| `max_cache_bytes` | 16 GiB | Bytes stored for all results of the process. | +| `max_cache_bytes` | 8 GiB | Bytes stored for all results of the process. | +| `ttl_seconds` | 86400 | Seconds the result is kept after its last use. NULL keeps it until DuckDB exits. | | `stop_at_limit` | `false` | Stop reading the input once storing stops. | The tee marks the statement whose result is kept. That statement has to return @@ -67,6 +68,12 @@ whose footer lets a read seek directly to the batches it needs. ### Limits +`max_cache_bytes` is the caller's limit for the whole cache, not a property of +one result: each tee applies the value it was given. When a tee begins, before +it stores anything, the oldest results are evicted until the cache holds no +more than that, so a caller that lowers its limit frees the space with its next +statement, not before. + When a result would exceed `max_result_bytes`, or the process's results would exceed `max_cache_bytes` even after evicting the oldest other results, the tee stops storing. The result keeps the rows before the first batch that was not stored, a @@ -74,10 +81,21 @@ prefix of the statement's rows, and `limit_reason` says why. Batches are stored whole, and threads store later parts of the result while earlier parts are still being produced, so the prefix can be shorter than the limit by what the threads had in progress. The statement still runs to completion, and `rows` -counts every row it produced. Failures to store, such as a full disk or an -unwritable cache directory, likewise stop storing with `limit_reason = 'io'`; they -never fail the statement. Limits count Arrow buffer bytes; a file can exceed its -limit by its footer and the framing of its batches. +counts every row it produced. Failures to store, such as an unwritable cache +directory, likewise stop storing with `limit_reason = 'io'`; they never fail the +statement. Limits count Arrow buffer bytes; a file can exceed its limit by its +footer and the framing of its batches. + +The cache also leaves room on its disk. Nothing more is written to a result +file once the volume that holds the cache would have less than 5 GiB free, or +less than a tenth of its size on a volume smaller than 50 GiB. The result keeps +what it has, with `limit_reason = 'disk-space'`, and results that fit in memory +are still kept. The free space is read when a result's file is created and +again after every 64 MiB written to the cache, so several threads can take the +volume a little below the floor before storing stops; once it is below, the +space is read before every write until there is room again. Other results are +not evicted to make room, and a volume that does not report its free space has +no floor. With `stop_at_limit := true` the tee also stops reading its input once storing stops, as a `LIMIT` would, and publishes the stored prefix. `rows` is then the @@ -104,11 +122,13 @@ select * from sqlnb_result_tee( | `stored_rows` | BIGINT | Rows that can be read back. Less than `rows` after a limit. | | `stored_bytes` | BIGINT | File size, or Arrow buffer bytes for results in memory. | | `in_memory` | BOOLEAN | Whether the result is held in memory rather than a file. | -| `limit_reason` | VARCHAR | `result-bytes`, `cache-bytes`, `io`, or NULL when every row was stored. | +| `limit_reason` | VARCHAR | `result-bytes`, `cache-bytes`, `disk-space`, `io`, or NULL when every row was stored. | | `meta` | VARCHAR | The tee's `meta`. | | `created_ms` | BIGINT | Unix time in milliseconds when the statement started. | | `elapsed_ms` | BIGINT | Milliseconds from the start of the statement to the end of its input. | | `rows_exact` | BOOLEAN | False when `stop_at_limit` stopped the statement early. | +| `last_used_ms` | BIGINT | Unix time in milliseconds when the statement finished or the result was last read. | +| `expires_ms` | BIGINT | Unix time in milliseconds from which the result is no longer kept, unless it is read before. NULL when it is kept until DuckDB exits. | `sqlnb_result(id, first_row := 0, row_count := NULL, row_number := NULL)` reads a stored result back with its original column names, types and row order. @@ -127,8 +147,29 @@ Columns with the same name come back with DuckDB's usual suffixes (`a`, `a_1`). `TIMESTAMP WITH TIME ZONE` values are stored in UTC. `sqlnb_result_drop(id)` removes a readable result and returns whether it existed. -Scans that already started, including scans of evicted results, finish reading -their rows. +Scans that already started, including scans of evicted and expired results, +finish reading their rows. + +## Expiry + +A result is kept for `ttl_seconds` after its last use and then expires. Its +last use is the end of its statement or, later, the last time `sqlnb_result` +read it: binding a read and starting its scan both count, so a result that is +being paged through does not expire. Listing results with `sqlnb_results()` is +not a use. The period belongs to the result: it is the `ttl_seconds` its tee +was given, and later tees with another period do not change it. + +An expired result is gone exactly as an evicted one is: it is no longer listed, +reading it raises `SQLNB_RESULT_MISSING:`, its file is removed and its id is +free. A statement that runs longer than its period is not affected; the period +starts when it finishes. + +There is no timer. Expired results are removed whenever the cache is used: when +a tee is bound or begins, and by `sqlnb_results()`, `sqlnb_result` and +`sqlnb_result_drop`. Until then an expired result's file stays on disk, so a +DuckDB process that nobody queries keeps its last results until it exits. +Times are the system clock's: setting the clock forward expires results early, +setting it back keeps them longer. ## Errors @@ -137,7 +178,7 @@ DuckDB prefixes these messages with the error type, such as `Invalid Input Error | Prefix | Raised by | |--------|-----------| | `SQLNB_RESULT_EXISTS:` | A tee whose id is already used by a running or readable result. | -| `SQLNB_RESULT_MISSING:` | Reading a result that never existed, was dropped or was evicted. | +| `SQLNB_RESULT_MISSING:` | Reading a result that never existed, was dropped, expired or was evicted. | | `SQLNB_RESULT_UNSUPPORTED:` | A tee over a column the cache cannot read back unchanged. | | `POLICY_BLOCKED:` | Any of these functions on the MCP agent connection. | @@ -150,7 +191,8 @@ type. Cast those columns, for example to `VARCHAR`, before the tee. Results belong to the process: every connection and database in it shares them, including the notebook's Quack sessions. The MCP agent connection cannot use them. -Results are removed when the last database that loaded SQLNB closes. +Results are removed when the last database that loaded SQLNB closes, and +earlier when they expire or are evicted. Files live in a directory of their own per process, created when the first result is written to disk, under: diff --git a/http/src/platform.rs b/http/src/platform.rs index 138c4ad..324368c 100644 --- a/http/src/platform.rs +++ b/http/src/platform.rs @@ -15,6 +15,14 @@ pub(crate) struct FileIdentity { pub regular: bool, } +/// Bytes on the volume that holds a path. +#[derive(Clone, Copy, Debug)] +pub(crate) struct DiskSpace { + /// Free for this process to write. + pub available: u64, + pub total: u64, +} + pub(crate) fn home_directory() -> Option { #[cfg(windows)] let home = std::env::var_os("USERPROFILE"); diff --git a/http/src/platform/unix.rs b/http/src/platform/unix.rs index dc7cfc6..83bd705 100644 --- a/http/src/platform/unix.rs +++ b/http/src/platform/unix.rs @@ -391,6 +391,20 @@ pub(crate) fn private_new_file(path: &Path) -> std::io::Result { .mode(0o600) .open(path) } +/// The space on the volume of `path`; `None` when the volume does not say. +pub(crate) fn disk_space(path: &Path) -> Option { + let path = CString::new(path.as_os_str().as_encoded_bytes()).ok()?; + let mut stats = std::mem::MaybeUninit::::uninit(); + if unsafe { libc::statvfs(path.as_ptr(), stats.as_mut_ptr()) } != 0 { + return None; + } + let stats = unsafe { stats.assume_init() }; + let block = stats.f_frsize as u64; + Some(DiskSpace { + available: (stats.f_bavail as u64).saturating_mul(block), + total: (stats.f_blocks as u64).saturating_mul(block), + }) +} pub(crate) fn open_lease_file(path: &Path) -> std::io::Result { OpenOptions::new() .read(true) diff --git a/http/src/platform/windows.rs b/http/src/platform/windows.rs index 3f08ebb..65466ce 100644 --- a/http/src/platform/windows.rs +++ b/http/src/platform/windows.rs @@ -465,6 +465,17 @@ pub(crate) fn private_new_file(path: &Path) -> Result { .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT) .open(path) } +/// The space on the volume of `path`; `None` when the volume does not say. +pub(crate) fn disk_space(path: &Path) -> Option { + use std::os::windows::ffi::OsStrExt; + let path: Vec = path.as_os_str().encode_wide().chain(std::iter::once(0)).collect(); + let mut available = 0u64; + let mut total = 0u64; + let read = unsafe { + GetDiskFreeSpaceExW(path.as_ptr(), &mut available, &mut total, std::ptr::null_mut()) + }; + (read != 0).then_some(DiskSpace { available, total }) +} pub(crate) fn open_lease_file(path: &Path) -> Result { checked( OpenOptions::new() diff --git a/http/src/results.rs b/http/src/results.rs index 6b33137..ea12952 100644 --- a/http/src/results.rs +++ b/http/src/results.rs @@ -3,7 +3,9 @@ //! The registry is process-global. Results small enough stay in memory; the //! others are Arrow IPC files in one session directory per process, which a //! lock file claims for the life of the process. -use crate::platform::{open_lease_file, open_lock_file, private_new_file, try_lock_file, LOCK_EX}; +use crate::platform::{ + disk_space, open_lease_file, open_lock_file, private_new_file, try_lock_file, DiskSpace, LOCK_EX, +}; use arrow_array::ffi::{from_ffi_and_data_type, FFI_ArrowArray, FFI_ArrowSchema}; use arrow_array::ffi_stream::FFI_ArrowArrayStream; use arrow_array::{ @@ -36,11 +38,22 @@ const SESSION_LOCK: &str = "session.lock"; const SESSION_CLAIM_GRACE: Duration = Duration::from_secs(60); /// Messages and their bodies start on this boundary in a result file. const FILE_ALIGNMENT: u8 = 8; +/// What `sqlnb_result_tee` uses for a caller that names no limit. +const DEFAULT_MAX_RESULT_BYTES: u64 = 4 * 1024 * 1024 * 1024; +const DEFAULT_MAX_CACHE_BYTES: u64 = 8 * 1024 * 1024 * 1024; +const DEFAULT_TTL_SECONDS: u64 = 24 * 60 * 60; +/// Nothing more is written to a result file while its volume has less free +/// space than this, or than a tenth of a volume too small for that. +const MIN_FREE_DISK_BYTES: u64 = 5 * 1024 * 1024 * 1024; +const MIN_FREE_DISK_DIVISOR: u64 = 10; +/// The free space is read again after this many bytes were written. +const DISK_PROBE_BYTES: u64 = 64 * 1024 * 1024; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum LimitReason { ResultBytes, CacheBytes, + DiskSpace, Io, } @@ -49,6 +62,7 @@ impl LimitReason { match self { LimitReason::ResultBytes => "result-bytes", LimitReason::CacheBytes => "cache-bytes", + LimitReason::DiskSpace => "disk-space", LimitReason::Io => "io", } } @@ -59,12 +73,35 @@ pub(crate) struct ResultLimits { pub head_rows: u64, pub max_result_bytes: u64, pub max_cache_bytes: u64, + /// How long the result is kept after its last use; `None` keeps it until + /// the process ends. + pub ttl_ms: Option, +} + +impl ResultLimits { + /// The limits of a caller that names none. + pub(crate) fn defaults(head_rows: u64) -> Self { + Self { + head_rows, + max_result_bytes: DEFAULT_MAX_RESULT_BYTES, + max_cache_bytes: DEFAULT_MAX_CACHE_BYTES, + ttl_ms: Some(DEFAULT_TTL_SECONDS * 1000), + } + } } pub(crate) struct ResultStore { /// Parent of the session directories; unavailable without a cache root. directory: Result, state: Mutex, + /// Milliseconds since the Unix epoch. + clock: Box i64 + Send + Sync>, + /// The space on the volume of a directory; `None` when it cannot be read. + disk_space: Box Option + Send + Sync>, + /// Bytes written to result files since the free space was last read. + unprobed_bytes: AtomicU64, + /// The last reading was below the floor: read again before every write. + disk_low: AtomicBool, } #[derive(Default)] @@ -85,6 +122,9 @@ struct Session { struct Entry { sequence: u64, created_ms: i64, + /// When the statement finished, or when the result was last read. + last_used_ms: i64, + ttl_ms: Option, meta: String, schema: SchemaRef, stored_bytes: u64, @@ -115,13 +155,68 @@ impl Entry { let _ = fs::remove_file(path); } } + + /// When a readable result stops being kept unless it is read before. + fn expires_ms(&self) -> Option { + let ttl_ms = i64::try_from(self.ttl_ms?).unwrap_or(i64::MAX); + Some(self.last_used_ms.saturating_add(ttl_ms)) + } +} + +impl StoreState { + /// Takes out the readable results nobody used for their whole period. A + /// result still being stored has not begun its period. + fn take_expired(&mut self, now_ms: i64) -> Vec { + let expired: Vec = self + .entries + .iter() + .filter(|(_, entry)| { + entry.stored.is_some() && entry.expires_ms().is_some_and(|expires| expires <= now_ms) + }) + .map(|(id, _)| id.clone()) + .collect(); + expired.iter().filter_map(|id| self.entries.remove(id)).collect() + } + + /// Takes out the oldest readable results other than `keep` until the cache + /// holds at most `limit` bytes or has no other to give up. Returns the + /// bytes it still holds with what it took out. + fn evict_oldest(&mut self, keep: &str, limit: u64) -> (u64, Vec) { + let mut used: u64 = self.entries.values().map(|entry| entry.stored_bytes).sum(); + let mut evicted = Vec::new(); + while used > limit { + let oldest = self + .entries + .iter() + .filter(|(other, entry)| other.as_str() != keep && entry.stored.is_some()) + .min_by_key(|(_, entry)| entry.sequence) + .map(|(other, _)| other.clone()); + let Some(oldest) = oldest else { break }; + let entry = self.entries.remove(&oldest).expect("oldest entry exists"); + used -= entry.stored_bytes; + evicted.push(entry); + } + (used, evicted) + } } impl ResultStore { pub(crate) fn new(directory: Result) -> Self { + Self::with_environment(directory, Box::new(unix_ms), Box::new(disk_space)) + } + + fn with_environment( + directory: Result, + clock: Box i64 + Send + Sync>, + disk_space: Box Option + Send + Sync>, + ) -> Self { Self { directory, state: Mutex::new(StoreState::default()), + clock, + disk_space, + unprobed_bytes: AtomicU64::new(0), + disk_low: AtomicBool::new(false), } } @@ -129,6 +224,43 @@ impl ResultStore { self.state.lock().unwrap_or_else(|poisoned| poisoned.into_inner()) } + /// Locks the registry once the results that expired are gone from it. + /// Every call that lists, reads, drops or begins a result comes through + /// here, which is what removes expired results: there is no timer. + fn lock_swept(&self) -> MutexGuard<'_, StoreState> { + let mut state = self.lock(); + let expired = state.take_expired((self.clock)()); + if expired.is_empty() { + return state; + } + drop(state); + for entry in &expired { + entry.remove_file(); + } + self.lock() + } + + /// Whether `bytes` more may be written to a result file in `directory`. + /// `first` is set for the write that creates the file. + fn disk_room(&self, directory: &Path, bytes: u64, first: bool) -> Result<(), LimitReason> { + let unprobed = self.unprobed_bytes.fetch_add(bytes, Ordering::Relaxed).saturating_add(bytes); + if !first && unprobed < DISK_PROBE_BYTES && !self.disk_low.load(Ordering::Relaxed) { + return Ok(()); + } + self.unprobed_bytes.store(0, Ordering::Relaxed); + // A volume that does not report its space is not held against the result. + let low = (self.disk_space)(directory).is_some_and(|space| { + let floor = MIN_FREE_DISK_BYTES.min(space.total / MIN_FREE_DISK_DIVISOR); + space.available < floor.saturating_add(bytes) + }); + self.disk_low.store(low, Ordering::Relaxed); + if low { + Err(LimitReason::DiskSpace) + } else { + Ok(()) + } + } + pub(crate) fn retain(&self) { self.lock().retained += 1; } @@ -156,7 +288,7 @@ impl ResultStore { /// Validates a result before its statement runs. pub(crate) fn check(&self, id: &str, meta: &str, schema: &Schema) -> Result<(), String> { validate_new_result(id, meta, schema)?; - if self.lock().entries.contains_key(id) { + if self.lock_swept().entries.contains_key(id) { return Err(exists(id)); } Ok(()) @@ -171,21 +303,29 @@ impl ResultStore { ) -> Result { validate_new_result(id, meta, &schema)?; let schema = Arc::new(schema); - { - let mut state = self.lock(); + let evicted = { + let mut state = self.lock_swept(); if state.entries.contains_key(id) { return Err(exists(id)); } state.next_sequence += 1; + let now_ms = (self.clock)(); let entry = Entry { sequence: state.next_sequence, - created_ms: unix_ms(), + created_ms: now_ms, + last_used_ms: now_ms, + ttl_ms: limits.ttl_ms, meta: meta.to_string(), schema: schema.clone(), stored_bytes: 0, stored: None, }; state.entries.insert(id.to_string(), entry); + // A cache limit lower than what is kept applies from here on. + state.evict_oldest(id, limits.max_cache_bytes).1 + }; + for entry in evicted { + entry.remove_file(); } Ok(ResultWriter { store: self.clone(), @@ -203,34 +343,22 @@ impl ResultStore { /// Counts `requested` more stored bytes for the result `id`, evicting the /// oldest other readable results when the whole cache would exceed its limit. fn reserve(&self, id: &str, requested: u64, limits: &ResultLimits) -> Result<(), LimitReason> { - let mut evicted = Vec::new(); - let reserved = { + let (reserved, evicted) = { let mut state = self.lock(); // Without its entry, the cache closed while this statement ran. let stored_bytes = state.entries.get(id).ok_or(LimitReason::Io)?.stored_bytes; if stored_bytes.saturating_add(requested) > limits.max_result_bytes { - Err(LimitReason::ResultBytes) + (Err(LimitReason::ResultBytes), Vec::new()) } else { - let mut used: u64 = state.entries.values().map(|entry| entry.stored_bytes).sum(); - while used.saturating_add(requested) > limits.max_cache_bytes { - let oldest = state - .entries - .iter() - .filter(|(other, entry)| other.as_str() != id && entry.stored.is_some()) - .min_by_key(|(_, entry)| entry.sequence) - .map(|(other, _)| other.clone()); - let Some(oldest) = oldest else { break }; - let entry = state.entries.remove(&oldest).expect("oldest entry exists"); - used -= entry.stored_bytes; - evicted.push(entry); - } + let (used, evicted) = + state.evict_oldest(id, limits.max_cache_bytes.saturating_sub(requested)); if used.saturating_add(requested) > limits.max_cache_bytes { - Err(LimitReason::CacheBytes) + (Err(LimitReason::CacheBytes), evicted) } else { if let Some(entry) = state.entries.get_mut(id) { entry.stored_bytes += requested; } - Ok(()) + (Ok(()), evicted) } } }; @@ -241,11 +369,14 @@ impl ResultStore { } fn complete(&self, id: &str, stored: StoredResult, stored_bytes: u64) { + let now_ms = (self.clock)(); let mut state = self.lock(); match state.entries.get_mut(id) { Some(entry) => { entry.stored_bytes = stored_bytes; entry.stored = Some(Arc::new(stored)); + // The period without use starts when the result can be read. + entry.last_used_ms = now_ms; } None => { if let StoredData::File(path) = stored.data { @@ -289,7 +420,7 @@ impl ResultStore { pub(crate) fn drop_result(&self, id: &str) -> bool { let removed = { - let mut state = self.lock(); + let mut state = self.lock_swept(); match state.entries.get(id) { Some(entry) if entry.stored.is_some() => state.entries.remove(id), _ => None, @@ -298,13 +429,14 @@ impl ResultStore { removed.map(|entry| entry.remove_file()).is_some() } + /// A result about to be read, which counts as a use of it. fn readable(&self, id: &str) -> Result<(SchemaRef, Arc), String> { - let state = self.lock(); - state - .entries - .get(id) - .and_then(|entry| Some((entry.schema.clone(), entry.stored.clone()?))) - .ok_or_else(|| missing(id)) + let now_ms = (self.clock)(); + let mut state = self.lock_swept(); + let entry = state.entries.get_mut(id).ok_or_else(|| missing(id))?; + let stored = entry.stored.clone().ok_or_else(|| missing(id))?; + entry.last_used_ms = now_ms; + Ok((entry.schema.clone(), stored)) } /// The columns `scan` reads: the stored columns, then the optional row number. @@ -326,13 +458,15 @@ impl ResultStore { // Open the file before a concurrent drop can remove it; an open scan // keeps reading the file it opened. let (schema, stored, file) = { - let state = self.lock(); - let entry = state.entries.get(id).ok_or_else(|| missing(id))?; + let now_ms = (self.clock)(); + let mut state = self.lock_swept(); + let entry = state.entries.get_mut(id).ok_or_else(|| missing(id))?; let stored = entry.stored.clone().ok_or_else(|| missing(id))?; let file = match &stored.data { StoredData::File(path) => Some(File::open(path).map_err(|_| missing(id))?), StoredData::Memory(_) => None, }; + entry.last_used_ms = now_ms; (entry.schema.clone(), stored, file) }; let full_schema = with_row_number(&schema, row_number)?; @@ -387,9 +521,9 @@ impl ResultStore { Ok(scan) } - /// One row per readable result, newest first. + /// One row per readable result, newest first. Listing is not a use. pub(crate) fn list(&self) -> RecordBatch { - let state = self.lock(); + let state = self.lock_swept(); let mut results: Vec<_> = state .entries .iter() @@ -418,6 +552,8 @@ impl ResultStore { Arc::new(BooleanArray::from_iter( results.iter().map(|(_, _, stored)| Some(stored.rows_exact)), )), + Arc::new(Int64Array::from_iter_values(results.iter().map(|(_, entry, _)| entry.last_used_ms))), + Arc::new(Int64Array::from_iter(results.iter().map(|(_, entry, _)| entry.expires_ms()))), ]; RecordBatch::try_new(list_schema(), columns).expect("result list matches its schema") } @@ -435,6 +571,8 @@ fn list_schema() -> SchemaRef { Field::new("created_ms", DataType::Int64, false), Field::new("elapsed_ms", DataType::Int64, false), Field::new("rows_exact", DataType::Boolean, false), + Field::new("last_used_ms", DataType::Int64, false), + Field::new("expires_ms", DataType::Int64, true), ])) } @@ -460,7 +598,7 @@ fn exists(id: &str) -> String { } fn missing(id: &str) -> String { - format!("SQLNB_RESULT_MISSING: result '{id}' does not exist or was evicted") + format!("SQLNB_RESULT_MISSING: result '{id}' does not exist, expired or was evicted") } fn with_row_number(schema: &Schema, row_number: Option<&str>) -> Result { @@ -621,6 +759,7 @@ fn write_all_at(file: &File, mut bytes: &[u8], mut offset: u64) -> std::io::Resu struct SpillFile { file: File, + directory: PathBuf, temporary: PathBuf, path: PathBuf, /// The first free byte. A batch claims its place here and is written @@ -641,6 +780,7 @@ impl SpillFile { } Ok(Self { file, + directory: directory.to_path_buf(), temporary, path: directory.join(format!("{id}.arrow")), end: AtomicU64::new(header.len() as u64), @@ -777,7 +917,10 @@ impl ResultWriter { state.batches.push(StoredBatch { key, rows, bytes, data: BatchData::Memory(batch) }); return Ok(()); } - self.spill(&mut state)?; + self.spill(&mut state, bytes)?; + } else { + let directory = &state.file.as_ref().expect("checked above").directory; + self.store.disk_room(directory, bytes, false)?; } state.file.clone().expect("a spilled result has a file") }; @@ -790,10 +933,12 @@ impl ResultWriter { Ok(()) } - /// Moves the batches kept in memory into a new file. On failure they stay - /// in memory as what the result keeps. - fn spill(&self, state: &mut WriterState) -> Result<(), LimitReason> { + /// Moves the batches kept in memory into a new file that `incoming` more + /// bytes are about to follow into. On failure they stay in memory as what + /// the result keeps. + fn spill(&self, state: &mut WriterState, incoming: u64) -> Result<(), LimitReason> { let directory = self.store.session_directory().map_err(|_| LimitReason::Io)?; + self.store.disk_room(&directory, state.stored_bytes.saturating_add(incoming), true)?; let file = SpillFile::create(&directory, &self.id, &self.schema).map_err(|_| LimitReason::Io)?; let mut blocks = Vec::with_capacity(state.batches.len()); for stored in &state.batches { @@ -1044,6 +1189,20 @@ pub extern "C" fn sidequery_results_release() { let _ = std::panic::catch_unwind(|| STORE.release()); } +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_defaults( + max_result_bytes: *mut u64, + max_cache_bytes: *mut u64, + ttl_seconds: *mut u64, +) { + let defaults = ResultLimits::defaults(0); + unsafe { + max_result_bytes.write(defaults.max_result_bytes); + max_cache_bytes.write(defaults.max_cache_bytes); + ttl_seconds.write(defaults.ttl_ms.map_or(0, |ttl_ms| ttl_ms / 1000)); + } +} + #[no_mangle] pub unsafe extern "C" fn sidequery_result_check( id: *const c_char, @@ -1065,6 +1224,7 @@ pub unsafe extern "C" fn sidequery_result_begin( head_rows: u64, max_result_bytes: u64, max_cache_bytes: u64, + ttl_seconds: u64, error_out: *mut *mut c_char, ) -> *mut ResultWriter { let mut writer = None; @@ -1074,6 +1234,7 @@ pub unsafe extern "C" fn sidequery_result_begin( head_rows, max_result_bytes, max_cache_bytes, + ttl_ms: (ttl_seconds > 0).then(|| ttl_seconds.saturating_mul(1000)), }; writer = Some(STORE.begin(unsafe { text(id, "id") }?, unsafe { text(meta, "meta") }?, schema, limits)?); Ok(()) diff --git a/http/src/results/tests.rs b/http/src/results/tests.rs index 1e8f177..b6ca3ce 100644 --- a/http/src/results/tests.rs +++ b/http/src/results/tests.rs @@ -2,12 +2,51 @@ use super::*; use arrow_array::cast::AsArray; use arrow_array::types::Int64Type; +use std::sync::atomic::AtomicI64; + const UNLIMITED: u64 = u64::MAX; +const GIB: u64 = 1024 * 1024 * 1024; +const HOUR_MS: i64 = 60 * 60 * 1000; -fn open_store(directory: &Path) -> Arc { - let store = Arc::new(ResultStore::new(Ok(directory.to_path_buf()))); +/// The time and the disk a store sees, set by the test. +#[derive(Clone)] +struct Environment { + now_ms: Arc, + /// Free bytes on the cache volume; `u64::MAX` for a volume that does not say. + free_bytes: Arc, + volume_bytes: Arc, +} + +impl Environment { + fn advance(&self, milliseconds: i64) { + self.now_ms.fetch_add(milliseconds, Ordering::Relaxed); + } +} + +/// A store with a clock that stands still and a volume with room, so that +/// neither the machine's clock nor its disk decides a test. +fn open_store_in(directory: Result) -> (Arc, Environment) { + let environment = Environment { + now_ms: Arc::new(AtomicI64::new(1_700_000_000_000)), + free_bytes: Arc::new(AtomicU64::new(512 * GIB)), + volume_bytes: Arc::new(AtomicU64::new(1024 * GIB)), + }; + let (clock, disk) = (environment.clone(), environment.clone()); + let store = Arc::new(ResultStore::with_environment( + directory, + Box::new(move || clock.now_ms.load(Ordering::Relaxed)), + Box::new(move |_| { + let available = disk.free_bytes.load(Ordering::Relaxed); + (available != u64::MAX) + .then(|| DiskSpace { available, total: disk.volume_bytes.load(Ordering::Relaxed) }) + }), + )); store.retain(); - store + (store, environment) +} + +fn open_store(directory: &Path) -> Arc { + open_store_in(Ok(directory.to_path_buf())).0 } fn schema() -> Schema { @@ -35,9 +74,14 @@ fn limits(head_rows: u64) -> ResultLimits { head_rows, max_result_bytes: UNLIMITED, max_cache_bytes: UNLIMITED, + ttl_ms: None, } } +fn kept_for(head_rows: u64, ttl_ms: i64) -> ResultLimits { + ResultLimits { ttl_ms: Some(ttl_ms as u64), ..limits(head_rows) } +} + fn id(number: u8) -> String { format!("{number:032x}") } @@ -102,6 +146,25 @@ fn listed(store: &ResultStore) -> Vec<(String, i64, i64, bool, Option, b .collect() } +fn listed_ids(store: &ResultStore) -> Vec { + listed(store).into_iter().map(|result| result.0).collect() +} + +/// When a listed result was last used and when it expires. +fn usage(store: &ResultStore, id: &str) -> (i64, Option) { + let list = store.list(); + let row = list.column(0).as_string::().iter().position(|listed| listed == Some(id)).unwrap(); + let expires = list.column(11).as_primitive::(); + ( + list.column(10).as_primitive::().value(row), + expires.is_valid(row).then(|| expires.value(row)), + ) +} + +fn is_missing(result: Result) -> bool { + result.err().is_some_and(|error| error.starts_with("SQLNB_RESULT_MISSING:")) +} + fn session_files(directory: &Path) -> Vec { let mut files = Vec::new(); for session in fs::read_dir(directory).into_iter().flatten().flatten() { @@ -212,6 +275,7 @@ fn the_result_limit_keeps_a_prefix_and_counts_every_row() { head_rows: 1000, max_result_bytes: batch_size + batch_size / 2, max_cache_bytes: UNLIMITED, + ttl_ms: None, }, ) .unwrap(); @@ -232,6 +296,7 @@ fn the_cache_limit_evicts_the_oldest_other_results() { head_rows: 1000, max_result_bytes: UNLIMITED, max_cache_bytes: batch_size * 2, + ttl_ms: None, }; store_result(&store, &id(1), &[100], cache); store_result(&store, &id(2), &[100], cache); @@ -268,8 +333,7 @@ fn stopping_early_reports_a_lower_bound() { #[test] fn an_unavailable_cache_directory_keeps_the_memory_prefix() { - let store = Arc::new(ResultStore::new(Err("no cache root".into()))); - store.retain(); + let store = open_store_in(Err("no cache root".into())).0; let writer = store.begin(&id(1), "", schema(), limits(4)).unwrap(); assert!(writer.append(batch(0, 4), (0, 0))); assert!(!writer.append(batch(4, 4), (0, 1))); @@ -407,3 +471,240 @@ fn threads_store_batches_at_the_same_time() { writer.finish(total as u64, true); assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..total).collect::>()); } + +#[test] +fn a_lower_cache_limit_evicts_the_oldest_results_when_the_next_result_begins() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + for result in 1..=3 { + store_result(&store, &id(result), &[100], limits(0)); + } + let result_bytes = store.lock().entries[&id(3)].stored_bytes; + let lowered = ResultLimits { max_cache_bytes: result_bytes * 2, ..limits(0) }; + let writer = store.begin(&id(4), "", schema(), lowered).unwrap(); + // Before the new result stored anything. + assert_eq!(listed_ids(&store), [id(3), id(2)]); + assert_eq!( + session_files(directory.path()), + [format!("{}.arrow", id(2)), format!("{}.arrow", id(3)), SESSION_LOCK.to_string()] + ); + drop(writer); +} + +#[test] +fn a_caller_that_names_no_limits_keeps_4_gib_of_a_result_8_gib_in_all_for_24_hours() { + let directory = tempfile::tempdir().unwrap(); + let store = open_store(directory.path()); + let defaults = ResultLimits::defaults(1000); + let batch_size = batch_bytes(&batch(0, 100)); + let set_stored_bytes = |result: &str, bytes: u64| { + store.lock().entries.get_mut(result).unwrap().stored_bytes = bytes; + }; + + store_result(&store, &id(1), &[100], defaults); + let (last_used, expires) = usage(&store, &id(1)); + assert_eq!(expires, Some(last_used + 24 * HOUR_MS)); + + // The cache holds one batch less than 8 GiB: one more batch fits, a second does not. + set_stored_bytes(&id(1), 8 * GIB - batch_size); + store_result(&store, &id(2), &[100], defaults); + assert_eq!(listed_ids(&store), [id(2), id(1)]); + store_result(&store, &id(3), &[100], defaults); + assert_eq!(listed_ids(&store), [id(3), id(2)]); + + // A result that holds one batch less than 4 GiB takes one more batch. + let writer = store.begin(&id(4), "", schema(), defaults).unwrap(); + set_stored_bytes(&id(4), 4 * GIB - batch_size); + assert!(writer.append(batch(0, 100), (0, 0))); + assert!(!writer.append(batch(100, 100), (0, 1))); + writer.finish(200, true); + assert_eq!(listed(&store)[0], (id(4), 200, 100, true, Some("result-bytes".into()), true)); +} + +#[test] +fn a_result_expires_after_its_period_without_use() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + store_result(&store, &id(1), &[3, 3], kept_for(0, HOUR_MS)); + store_result(&store, &id(2), &[3], kept_for(10, HOUR_MS)); + store_result(&store, &id(3), &[3], limits(10)); + let (last_used, expires) = usage(&store, &id(1)); + assert_eq!(expires, Some(last_used + HOUR_MS)); + assert_eq!(usage(&store, &id(3)).1, None); + + environment.advance(HOUR_MS - 1); + assert_eq!(listed_ids(&store), [id(3), id(2), id(1)]); + + environment.advance(1); + assert_eq!(listed_ids(&store), [id(3)]); + assert_eq!(session_files(directory.path()), [SESSION_LOCK]); + assert!(is_missing(store.scan_schema(&id(1), None))); + assert!(is_missing(store.scan(&id(2), 0, UNLIMITED, None, &[0]).map(|_| ()))); + assert!(!store.drop_result(&id(1))); + // The id is free again, as after an eviction. + store_result(&store, &id(1), &[1], limits(10)); + + // A result without a period stays until the cache closes. + environment.advance(10 * 365 * 24 * HOUR_MS); + assert_eq!(listed_ids(&store), [id(1), id(3)]); +} + +#[test] +fn reading_a_result_starts_its_period_again_and_listing_does_not() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + store_result(&store, &id(1), &[3, 3], kept_for(0, HOUR_MS)); + store_result(&store, &id(2), &[3, 3], kept_for(0, HOUR_MS)); + store_result(&store, &id(3), &[3, 3], kept_for(0, HOUR_MS)); + let stored_at = usage(&store, &id(1)).0; + + environment.advance(HOUR_MS - 1); + assert_eq!(scan_values(&store, &id(1), 2, 2, None, &[0])[0], [2, 3]); + store.scan_schema(&id(2), None).unwrap(); + assert_eq!(usage(&store, &id(1)), (stored_at + HOUR_MS - 1, Some(stored_at + 2 * HOUR_MS - 1))); + assert_eq!(usage(&store, &id(3)), (stored_at, Some(stored_at + HOUR_MS))); + + // Only the two that were read are still there. + environment.advance(1); + assert_eq!(listed_ids(&store), [id(2), id(1)]); + environment.advance(HOUR_MS - 2); + assert_eq!(listed_ids(&store), [id(2), id(1)]); + environment.advance(1); + assert!(listed_ids(&store).is_empty()); + assert_eq!(session_files(directory.path()), [SESSION_LOCK]); +} + +#[test] +fn the_period_starts_when_the_statement_ends() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + let writer = store.begin(&id(1), "", schema(), kept_for(0, HOUR_MS)).unwrap(); + assert!(writer.append(batch(0, 5), (0, 0))); + environment.advance(3 * HOUR_MS); + // A statement that runs longer than the period is not swept while it runs. + assert!(listed(&store).is_empty()); + assert!(writer.append(batch(5, 5), (0, 1))); + writer.finish(10, true); + let finished_at = environment.now_ms.load(Ordering::Relaxed); + assert_eq!(usage(&store, &id(1)), (finished_at, Some(finished_at + HOUR_MS))); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..10).collect::>()); +} + +#[test] +fn every_use_of_the_cache_removes_the_results_that_expired() { + type Touch = fn(&Arc); + let touches: [(&str, Touch); 6] = [ + ("check", |store| store.check(&id(9), "", &schema()).unwrap()), + ("begin", |store| drop(store.begin(&id(9), "", schema(), limits(0)).unwrap())), + ("list", |store| drop(store.list())), + ("schema", |store| drop(store.scan_schema(&id(2), None).unwrap())), + ("scan", |store| drop(store.scan(&id(2), 0, UNLIMITED, None, &[0]).unwrap())), + ("drop", |store| assert!(store.drop_result(&id(2)))), + ]; + for (name, touch) in touches { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + store_result(&store, &id(1), &[3], kept_for(0, HOUR_MS)); + store_result(&store, &id(2), &[3], limits(0)); + environment.advance(HOUR_MS); + assert!(session_files(directory.path()).contains(&format!("{}.arrow", id(1))), "{name}"); + touch(&store); + assert!(!session_files(directory.path()).contains(&format!("{}.arrow", id(1))), "{name}"); + assert!(!store.lock().entries.contains_key(&id(1)), "{name}"); + } +} + +#[test] +fn a_scan_that_is_open_when_its_result_expires_reads_to_the_end() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + store_result(&store, &id(1), &[3, 3], kept_for(0, HOUR_MS)); + let scan = store.scan(&id(1), 0, UNLIMITED, None, &[0]).unwrap(); + environment.advance(HOUR_MS); + assert!(listed(&store).is_empty()); + assert_eq!(scan.map(|batch| batch.unwrap().num_rows()).sum::(), 6); + assert!(is_missing(store.scan(&id(1), 0, UNLIMITED, None, &[0]).map(|_| ()))); +} + +#[test] +fn nothing_is_written_to_a_volume_below_its_free_space_floor() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + let two_batches = batch_bytes(&batch(0, 100)) + batch_bytes(&batch(100, 100)); + + // One byte short of 5 GiB left once the file held its first two batches. + environment.free_bytes.store(5 * GIB + two_batches - 1, Ordering::Relaxed); + let writer = store.begin(&id(1), "", schema(), limits(100)).unwrap(); + assert!(writer.append(batch(0, 100), (0, 0))); + assert!(!writer.append(batch(100, 100), (0, 1))); + writer.finish(200, true); + // The statement goes on; the rows before the floor stay, in memory. + assert_eq!(listed(&store), [(id(1), 200, 100, true, Some("disk-space".into()), true)]); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..100).collect::>()); + assert_eq!(session_files(directory.path()), [SESSION_LOCK]); + + // A result that fits in memory needs no disk. + environment.free_bytes.store(0, Ordering::Relaxed); + store_result(&store, &id(2), &[100], limits(100)); + assert_eq!(listed(&store)[0], (id(2), 100, 100, true, None, true)); + + // With room again, results are written again. + environment.free_bytes.store(5 * GIB + two_batches, Ordering::Relaxed); + store_result(&store, &id(3), &[100, 100], limits(100)); + assert_eq!(listed(&store)[0], (id(3), 200, 200, false, None, true)); +} + +#[test] +fn a_result_being_written_stops_when_the_volume_runs_low() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + let writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); + assert!(writer.append(batch(0, 100), (0, 0))); + environment.free_bytes.store(GIB, Ordering::Relaxed); + // The free space is not read for every batch, only every 64 MiB written. + assert!(writer.append(batch(100, 100), (0, 1))); + store.unprobed_bytes.store(DISK_PROBE_BYTES, Ordering::Relaxed); + assert!(!writer.append(batch(200, 100), (0, 2))); + + // Once low, the space is read before every write, also for other results. + let other = store.begin(&id(2), "", schema(), limits(0)).unwrap(); + assert!(!other.append(batch(0, 100), (0, 0))); + other.finish(100, true); + writer.finish(300, true); + assert_eq!( + listed(&store), + [ + (id(2), 100, 0, true, Some("disk-space".into()), true), + (id(1), 300, 200, false, Some("disk-space".into()), true), + ] + ); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..200).collect::>()); +} + +#[test] +fn the_floor_of_a_small_volume_is_a_tenth_of_it_and_an_unknown_volume_has_none() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + environment.volume_bytes.store(20 * GIB, Ordering::Relaxed); + environment.free_bytes.store(3 * GIB, Ordering::Relaxed); + store_result(&store, &id(1), &[100], limits(0)); + environment.free_bytes.store(2 * GIB, Ordering::Relaxed); + store_result(&store, &id(2), &[100], limits(0)); + environment.free_bytes.store(u64::MAX, Ordering::Relaxed); + store_result(&store, &id(3), &[100], limits(0)); + assert_eq!( + listed(&store), + [ + (id(3), 100, 100, false, None, true), + (id(2), 100, 0, true, Some("disk-space".into()), true), + (id(1), 100, 100, false, None, true), + ] + ); +} + +#[test] +fn the_volume_of_a_directory_reports_its_space() { + let directory = tempfile::tempdir().unwrap(); + let space = disk_space(directory.path()).expect("the temporary directory is on a volume"); + assert!(space.available > 0 && space.available <= space.total, "{space:?}"); +} diff --git a/scripts/runtime-smoke.mjs b/scripts/runtime-smoke.mjs index 4efcbb1..f01577c 100644 --- a/scripts/runtime-smoke.mjs +++ b/scripts/runtime-smoke.mjs @@ -716,7 +716,7 @@ if (hasResultCache) { assert.equal(firstValue(await runSQL("select count(*) from duckdb_tables() where table_name = 'misplaced'")), 0); assert.equal( firstValue(await runSQL("select string_agg(column_name || ' ' || column_type, ', ') from (describe select * from sqlnb_results())")), - 'id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN', + 'id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN, last_used_ms BIGINT, expires_ms BIGINT', ); assert.deepEqual( firstValue(await runSQL(`select list(r order by r.id) from (select id, rows, stored_rows, in_memory, limit_reason, meta, rows_exact from sqlnb_results() where id in ('${large}', '${small}')) r`)), @@ -849,6 +849,46 @@ if (hasResultCache) { assert.deepEqual(resultFiles().filter((file) => file.includes(large)), []); await expectSQLError(`select * from sqlnb_result('${large}')`, /SQLNB_RESULT_MISSING:/); assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_results() where id = '${small}'`)), 1); + // A result is kept for a period after its last use: 24 hours unless the tee + // names another, NULL for as long as DuckDB runs. Reading it starts the + // period again; listing it does not. + const usage = async (number) => (await runSQL( + `select last_used_ms, expires_ms from sqlnb_results() where id = '${resultId(number)}'`, + ))[0]; + const dayMs = 24 * 60 * 60 * 1000; + const hourMs = 60 * 60 * 1000; + const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)); + assert.equal(firstValue(await runSQL(`select expires_ms - last_used_ms from sqlnb_results() where id = '${small}'`)), dayMs); + await runRows(`select * from sqlnb_result_tee((select i from range(30000) t(i)), id := '${resultId(20)}', ttl_seconds := 3600)`); + await runSQL(`select * from sqlnb_result_tee((select 1 as one), id := '${resultId(21)}', ttl_seconds := NULL)`); + const stored = await usage(20); + assert.equal(stored.expires_ms - stored.last_used_ms, hourMs); + assert.equal((await usage(21)).expires_ms, null); + await pause(20); + assert.deepEqual(await usage(20), stored); + assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_result('${resultId(20)}', first_row := 100, row_count := 5)`)), 5); + const read = await usage(20); + assert(read.last_used_ms > stored.last_used_ms, 'reading a result did not count as a use'); + assert.equal(read.expires_ms - read.last_used_ms, hourMs); + // An expired result is gone like an evicted one, with its file. + await runRows(`select * from sqlnb_result_tee((select i from range(30000) t(i)), id := '${resultId(22)}', ttl_seconds := 1)`); + assert.deepEqual(resultFiles().filter((file) => file.includes(resultId(22))), [`${resultId(22)}.arrow`]); + await pause(1200); + assert.equal(firstValue(await runSQL(`select count(*) from sqlnb_results() where id = '${resultId(22)}'`)), 0); + assert.deepEqual(resultFiles().filter((file) => file.includes(resultId(22))), []); + await expectSQLError(`select * from sqlnb_result('${resultId(22)}')`, /SQLNB_RESULT_MISSING:/); + await expectSQLError( + `select * from sqlnb_result_tee((select 1), id := '${resultId(23)}', ttl_seconds := 0)`, + /ttl_seconds must be positive/, + ); + // A cache limit below what is kept evicts the oldest results as soon as the + // next result begins, before it stores anything. + await runSQL(`select * from sqlnb_result_tee((select 1 as one), id := '${resultId(24)}', max_cache_bytes := 0)`); + assert.deepEqual( + await runSQL('select id, rows, stored_rows, limit_reason from sqlnb_results()'), + [{ id: resultId(24), rows: 1, stored_rows: 0, limit_reason: 'cache-bytes' }], + ); + assert.deepEqual(resultFiles().filter((file) => file.endsWith('.arrow')), []); } const serversBeforeStop = await runSQL('select count(*) as count from quack_server_list()'); diff --git a/src/include/sidequery_http.h b/src/include/sidequery_http.h index 2b66d3e..9df5341 100644 --- a/src/include/sidequery_http.h +++ b/src/include/sidequery_http.h @@ -36,11 +36,19 @@ void sidequery_results_release(void); // Validates a new result's id, meta and schema before its statement runs. bool sidequery_result_check(const char *id, const char *meta, struct ArrowSchema *schema, char **error_out); +// The limits of a caller that names none: bytes kept for one result, bytes +// kept for all results, and seconds a result is kept after its last use. +void sidequery_result_defaults(uint64_t *max_result_bytes, uint64_t *max_cache_bytes, + uint64_t *ttl_seconds); // Registers an unreadable result; finish makes it readable, abort discards it. +// Results older than max_cache_bytes allows are evicted here. The result +// expires ttl_seconds after it was finished or last read; 0 keeps it until +// the cache is released. sidequery_result_writer *sidequery_result_begin(const char *id, const char *meta, struct ArrowSchema *schema, uint64_t head_rows, uint64_t max_result_bytes, - uint64_t max_cache_bytes, char **error_out); + uint64_t max_cache_bytes, uint64_t ttl_seconds, + char **error_out); // Stores the rows of a struct array whose fields match the schema, from any // thread. The result reads back in the order of the keys (major, then minor), // whatever order the batches were stored in. Returns false when the batch was @@ -54,7 +62,8 @@ void sidequery_result_missing(sidequery_result_writer *writer, uint64_t major, u // statement stopped reading early and rows is only a lower bound. void sidequery_result_finish(sidequery_result_writer *writer, uint64_t rows, bool rows_exact); void sidequery_result_abort(sidequery_result_writer *writer); -// Exports one row per readable result, newest first. +// Exports one row per readable result, newest first. Listing, reading, +// dropping and beginning a result first remove the results that expired. bool sidequery_results_list(struct ArrowArrayStream *out, char **error_out); // Exports the columns of a stored result, then a BIGINT column named row_number // unless row_number is null. diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index b06fc8b..518f409 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -31,8 +31,6 @@ namespace sqlnb_results { static constexpr int64_t DEFAULT_HEAD_ROWS = 10240; static constexpr int64_t DEFAULT_HEAD_BYTES = 4LL * 1024 * 1024; -static constexpr int64_t DEFAULT_MAX_RESULT_BYTES = 4LL * 1024 * 1024 * 1024; -static constexpr int64_t DEFAULT_MAX_CACHE_BYTES = 16LL * 1024 * 1024 * 1024; // A stored record batch holds this many rows, or fewer once its buffers reach // BATCH_BYTES, which bounds the memory one batch takes for very wide rows. static constexpr idx_t BATCH_ROWS = 8192; @@ -115,6 +113,8 @@ struct TeeParameters { idx_t head_bytes; idx_t max_result_bytes; idx_t max_cache_bytes; + // Seconds the result is kept after its last use; 0 keeps it until DuckDB exits. + idx_t ttl_seconds; bool stop_at_limit; vector types; vector names; @@ -349,7 +349,7 @@ class TeeSink : public BASE { char *error = nullptr; state->writer = sidequery_result_begin(parameters->id.c_str(), parameters->meta.c_str(), &schema.arrow_schema, parameters->head_rows, parameters->max_result_bytes, - parameters->max_cache_bytes, &error); + parameters->max_cache_bytes, parameters->ttl_seconds, &error); if (!state->writer) { ThrowCacheError(error); } @@ -986,6 +986,14 @@ static unique_ptr TeeBind(ClientContext &context, TableFunctionBin parameters->head_bytes = CountParameter(input, "head_bytes"); parameters->max_result_bytes = CountParameter(input, "max_result_bytes"); parameters->max_cache_bytes = CountParameter(input, "max_cache_bytes"); + auto &ttl_seconds = input.named_parameters.at("ttl_seconds"); + if (ttl_seconds.IsNull()) { + parameters->ttl_seconds = 0; + } else if (ttl_seconds.GetValue() <= 0) { + throw InvalidInputException("ttl_seconds must be positive, or NULL to keep the result until DuckDB exits"); + } else { + parameters->ttl_seconds = NumericCast(ttl_seconds.GetValue()); + } parameters->stop_at_limit = NamedParameter(input, "stop_at_limit").GetValue(); parameters->types = input.input_table_types; parameters->names = IdentifiersToStrings(input.input_table_names); @@ -1162,6 +1170,9 @@ static void DropResult(DataChunk &args, ExpressionState &state, Vector &result) static void RegisterSQLNBResults(ExtensionLoader &loader) { using namespace sqlnb_results; + // The storage limits a caller does not name are the cache's own. + uint64_t max_result_bytes, max_cache_bytes, ttl_seconds; + sidequery_result_defaults(&max_result_bytes, &max_cache_bytes, &ttl_seconds); TableFunction tee("sqlnb_result_tee", FunctionSignature() .AddPositionalOnly("input", LogicalType::TABLE) @@ -1170,9 +1181,11 @@ static void RegisterSQLNBResults(ExtensionLoader &loader) { .AddKeywordOnly("head_bytes", LogicalType::BIGINT, Value::BIGINT(DEFAULT_HEAD_BYTES)) .AddKeywordOnly("meta", LogicalType::VARCHAR, Value("")) .AddKeywordOnly("max_result_bytes", LogicalType::BIGINT, - Value::BIGINT(DEFAULT_MAX_RESULT_BYTES)) + Value::BIGINT(NumericCast(max_result_bytes))) .AddKeywordOnly("max_cache_bytes", LogicalType::BIGINT, - Value::BIGINT(DEFAULT_MAX_CACHE_BYTES)) + Value::BIGINT(NumericCast(max_cache_bytes))) + .AddKeywordOnly("ttl_seconds", LogicalType::BIGINT, + Value::BIGINT(NumericCast(ttl_seconds))) .AddKeywordOnly("stop_at_limit", LogicalType::BOOLEAN, Value::BOOLEAN(false)), nullptr, TeeBind, TeeInit); tee.in_out_function = TeeExecute; diff --git a/test/sql/results.test b/test/sql/results.test index 957a81e..0507e24 100644 --- a/test/sql/results.test +++ b/test/sql/results.test @@ -46,7 +46,7 @@ a0000000000000000000000000000003 5000 5000 false NULL (empty) true true query T select string_agg(column_name || ' ' || column_type, ', ') from (describe select * from sqlnb_results()); ---- -id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN +id VARCHAR, rows BIGINT, stored_rows BIGINT, stored_bytes BIGINT, in_memory BOOLEAN, limit_reason VARCHAR, meta VARCHAR, created_ms BIGINT, elapsed_ms BIGINT, rows_exact BOOLEAN, last_used_ms BIGINT, expires_ms BIGINT # Reading back returns the input, in order, with its original column types. query I @@ -190,3 +190,36 @@ query I select count(*) from sqlnb_results() where id = 'a0000000000000000000000000000002'; ---- 1 + +# A result is kept for 24 hours after its last use unless the tee names another +# period; NULL keeps it until DuckDB exits. +query I +select expires_ms - last_used_ms from sqlnb_results() where id = 'a0000000000000000000000000000002'; +---- +86400000 + +statement ok +select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000020', ttl_seconds := 3600); + +statement ok +select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000021', ttl_seconds := NULL); + +query II +select id, expires_ms - last_used_ms from sqlnb_results() where id in ('a0000000000000000000000000000020', 'a0000000000000000000000000000021') order by id; +---- +a0000000000000000000000000000020 3600000 +a0000000000000000000000000000021 NULL + +statement error +select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000022', ttl_seconds := 0); +---- +ttl_seconds must be positive + +# A cache limit below what is kept evicts the oldest results when the next result begins. +statement ok +select * from sqlnb_result_tee((select 1 as one), id := 'a0000000000000000000000000000023', max_cache_bytes := 0); + +query IIIT +select id, rows, stored_rows, limit_reason from sqlnb_results(); +---- +a0000000000000000000000000000023 1 0 cache-bytes From e6faf7634e9bdd984702d835073f93cd01866363 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:58:07 -0800 Subject: [PATCH 08/14] Set the head's shared collector state under the head lock The thread that passes the head on created and released the wrapped collector's shared state without the lock under which a thread leaving the head tests it. --- src/include/sqlnb_results.hpp | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index 518f409..ce0d7f5 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -273,7 +273,9 @@ class TeeGlobalState : public GlobalSinkState { TeeLocalState *passer = nullptr; std::deque queue; // The passer's state in the wrapped collector when its sink is parallel: - // that collector keeps the order of one state's rows, not of several. + // that collector keeps the order of one state's rows, not of several. Only + // the passer makes, uses and combines it. It sets and clears the pointer + // under head_lock, where a thread that leaves the head tests it. unique_ptr head_inner; }; @@ -551,7 +553,9 @@ class TeeSink : public BASE { auto state = local.inner.get(); if (this->ParallelSink()) { if (!global.head_inner) { - global.head_inner = BASE::GetLocalSinkState(context); + auto created = BASE::GetLocalSinkState(context); + lock_guard guard(global.head_lock); + global.head_inner = std::move(created); } state = global.head_inner.get(); state->partition_info = local.partition_info; @@ -589,7 +593,9 @@ class TeeSink : public BASE { return false; } // A thread that starts later passes its chunks through a new state. - global.head_inner.reset(); + guard.lock(); + auto combined = std::move(global.head_inner); + guard.unlock(); continue; } global.passer = nullptr; From b4a4f3286113b9a9ef5b2a7f713f3396e7591d59 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:59:22 -0800 Subject: [PATCH 09/14] Return the first rows whole when storing stops within them A statement that stops reading once storing has stopped now completes its head first; threads that stopped earlier left the head with rows from wherever each of them was. The documentation no longer promises that every returned row is stored: both are the first rows of the result, and a cache that stops storing keeps fewer. --- docs/results.md | 14 +++++++++++--- scripts/runtime-smoke.mjs | 14 +++++++++++++- src/include/sqlnb_results.hpp | 10 +++++++--- 3 files changed, 31 insertions(+), 7 deletions(-) diff --git a/docs/results.md b/docs/results.md index f772ac0..f9984b0 100644 --- a/docs/results.md +++ b/docs/results.md @@ -35,8 +35,15 @@ or a second tee, is an error before the statement runs. The statement returns only its first rows: whole chunks, as DuckDB produces them, until `head_rows` rows or `head_bytes` bytes have been returned (the chunk -that crosses either is still returned whole). Every row is stored. The rows -returned are exactly the first rows stored. +that crosses either is still returned whole). Every row is stored, unless a +limit or a failure stops storing (see [Limits](#limits)). + +The rows returned and the rows stored are both the first rows of the +statement's result. When everything is stored, the rows returned are exactly +the first rows stored. When storing stopped early, the result can keep fewer +rows than the statement returned, down to none: `stored_rows` is then at most +the number of rows returned, and the cache adds nothing to them. A cache that +cannot store never shortens or reorders what the statement returns. The statement runs as it would without the tee, on all its threads, and each thread stores the rows it produces. They are stored in the statement's order: @@ -98,7 +105,8 @@ not evicted to make room, and a volume that does not report its free space has no floor. With `stop_at_limit := true` the tee also stops reading its input once storing -stops, as a `LIMIT` would, and publishes the stored prefix. `rows` is then the +stops, as a `LIMIT` would, and publishes the stored prefix. It returns its first +rows in full before it stops, also when storing stopped within them. `rows` is then the number of rows read, a lower bound, and `rows_exact` is false. The option accepts any constant expression, such as Instant SQL's verdict that a statement is safe to stop early: diff --git a/scripts/runtime-smoke.mjs b/scripts/runtime-smoke.mjs index f01577c..9f52d95 100644 --- a/scripts/runtime-smoke.mjs +++ b/scripts/runtime-smoke.mjs @@ -818,7 +818,19 @@ if (hasResultCache) { await runSQL(`select count(*) > 0 as kept, bool_and(i = position) as ordered, count(*) = (select stored_rows from sqlnb_results() where id = '${resultId(14)}') as counted from sqlnb_result('${resultId(14)}', row_number := 'position')`), [{ kept: true, ordered: true, counted: true }], ); - for (const number of [13, 14]) { + // A cache that stores nothing does not shorten or reorder the rows returned, + // also when the statement stops reading once storing has stopped. + for (const [number, stop] of [[15, false], [16, true]]) { + const unstored = await runRows(`select * from sqlnb_result_tee((select i, h from tee_scan), id := '${resultId(number)}', max_result_bytes := 0, stop_at_limit := ${stop})`); + assert(unstored.length >= 10240, `${unstored.length} head rows with nothing stored`); + assert(unstored.every((row, position) => Number(row.i) === position), `the head is not the first rows of the statement (stop_at_limit ${stop})`); + const [kept] = await runSQL(`select rows, rows_exact, stored_rows, limit_reason from sqlnb_results() where id = '${resultId(number)}'`); + assert.equal(kept.stored_rows, 0); + assert.equal(kept.limit_reason, 'result-bytes'); + assert.equal(kept.rows_exact, !stop); + assert(stop ? kept.rows >= unstored.length && kept.rows < 3000000 : kept.rows === 3000000, JSON.stringify(kept)); + } + for (const number of [13, 14, 15, 16]) { assert.equal(firstValue(await runSQL(`select sqlnb_result_drop('${resultId(number)}')`)), true); } await runStatement('drop table tee_scan'); diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index ce0d7f5..bbe86c6 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -322,7 +322,9 @@ class TeeLocalState : public LocalSinkState { // never waits for an earlier batch. // // Only the head needs the order while the statement runs, and the rows passed -// on are exactly the first rows of the result. The thread reading the lowest +// on are exactly the first rows of the result, whether or not the cache could +// store them: a cache that stops storing never shortens what the statement +// returns. The thread reading the lowest // executor batch passes its rows on at once. Every other thread holds the // first rows of its batch back; when the batch ends they wait in the global // state for the thread whose batch becomes the lowest, or for the last thread @@ -457,9 +459,11 @@ class TeeSink : public BASE { return this->RequiredPartitionInfo().RequiresBatchIndex(); } - // A statement the read policy verifies stops reading once nothing more is stored. + // A statement the read policy verifies stops reading once nothing more is + // stored. Not before its head is complete: threads that stopped earlier + // would leave the head with rows from wherever each of them had got to. bool StoppedAtLimit(TeeGlobalState &global) const { - return parameters->stop_at_limit && !global.storing; + return parameters->stop_at_limit && !global.storing && global.head_done; } void StartBatch(TeeLocalState &local) const { From 0d09ccbb41648a93e6130cfe291c9b27195e1fca Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 19:59:50 -0800 Subject: [PATCH 10/14] Record a batch as missing when storing it panics --- http/src/results.rs | 18 +++++++++++++----- http/src/results/tests.rs | 34 +++++++++++++++++++++++++++++++++- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/http/src/results.rs b/http/src/results.rs index ea12952..9ca6103 100644 --- a/http/src/results.rs +++ b/http/src/results.rs @@ -881,6 +881,17 @@ impl ResultWriter { } } + /// `append_ffi` for the exported function, which never unwinds. A panic + /// while storing the batch records it as missing: the caller takes `false` + /// to mean the cache already did. + fn append_ffi_guarded(&self, array: FFI_ArrowArray, key: BatchKey) -> bool { + let appended = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.append_ffi(array, key))); + appended.unwrap_or_else(|_| { + let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.missing(key, LimitReason::Io))); + false + }) + } + /// Stores a batch whole, or not at all once a limit is reached. Returns /// whether later batches can still be stored. pub(crate) fn append(&self, batch: RecordBatch, key: BatchKey) -> bool { @@ -1249,11 +1260,8 @@ pub unsafe extern "C" fn sidequery_result_append( major: u64, minor: u64, ) -> bool { - std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - let writer = unsafe { &*writer }; - writer.append_ffi(unsafe { FFI_ArrowArray::from_raw(batch) }, (major, minor)) - })) - .unwrap_or(false) + let writer = unsafe { &*writer }; + writer.append_ffi_guarded(unsafe { FFI_ArrowArray::from_raw(batch) }, (major, minor)) } #[no_mangle] diff --git a/http/src/results/tests.rs b/http/src/results/tests.rs index b6ca3ce..6ac9e35 100644 --- a/http/src/results/tests.rs +++ b/http/src/results/tests.rs @@ -15,12 +15,20 @@ struct Environment { /// Free bytes on the cache volume; `u64::MAX` for a volume that does not say. free_bytes: Arc, volume_bytes: Arc, + /// The next reading of the clock or of the free space panics. + panic_next: Arc, } impl Environment { fn advance(&self, milliseconds: i64) { self.now_ms.fetch_add(milliseconds, Ordering::Relaxed); } + + fn panic_if_asked(&self) { + if self.panic_next.swap(false, Ordering::Relaxed) { + panic!("the test asked the environment to panic"); + } + } } /// A store with a clock that stands still and a volume with room, so that @@ -30,12 +38,17 @@ fn open_store_in(directory: Result) -> (Arc, Envir now_ms: Arc::new(AtomicI64::new(1_700_000_000_000)), free_bytes: Arc::new(AtomicU64::new(512 * GIB)), volume_bytes: Arc::new(AtomicU64::new(1024 * GIB)), + panic_next: Arc::new(AtomicBool::new(false)), }; let (clock, disk) = (environment.clone(), environment.clone()); let store = Arc::new(ResultStore::with_environment( directory, - Box::new(move || clock.now_ms.load(Ordering::Relaxed)), + Box::new(move || { + clock.panic_if_asked(); + clock.now_ms.load(Ordering::Relaxed) + }), Box::new(move |_| { + disk.panic_if_asked(); let available = disk.free_bytes.load(Ordering::Relaxed); (available != u64::MAX) .then(|| DiskSpace { available, total: disk.volume_bytes.load(Ordering::Relaxed) }) @@ -448,6 +461,25 @@ fn a_missing_batch_keeps_only_the_batches_before_it() { assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..4).collect::>()); } +#[test] +fn a_batch_that_panics_while_being_stored_is_missing() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + let writer = store.begin(&id(1), "", schema(), limits(8)).unwrap(); + let append = |start: i64, key: BatchKey| { + let (array, _) = arrow_array::ffi::to_ffi(&StructArray::from(batch(start, 4)).into_data()).unwrap(); + writer.append_ffi_guarded(array, key) + }; + assert!(append(0, (0, 0))); + assert!(append(8, (0, 2))); + // The third batch moves the result to a file, which reads the free space. + environment.panic_next.store(true, Ordering::Relaxed); + assert!(!append(4, (0, 1))); + writer.finish(12, true); + assert_eq!(listed(&store), [(id(1), 12, 4, true, Some("io".into()), true)]); + assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..4).collect::>()); +} + #[test] fn threads_store_batches_at_the_same_time() { let directory = tempfile::tempdir().unwrap(); From a7ab16d1f071a053f56768d16c0ac0f624a00d9a Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 20:00:05 -0800 Subject: [PATCH 11/14] Publish a result only after the wrapped collector's last events Quack sends a result's last batches from an event it inserts while it finalizes. The tee made the result readable as soon as that finalize returned, so a statement that failed in the event, with the client gone or the statement interrupted, left its result behind. The result is now published from an event that runs after those. Also say that the wrapped collector's own sink_state stays unset. --- src/include/sqlnb_results.hpp | 51 +++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index bbe86c6..0f5c970 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -22,6 +22,7 @@ #include "duckdb/main/config.hpp" #include "duckdb/main/extension/extension_loader.hpp" #include "duckdb/main/prepared_statement_data.hpp" +#include "duckdb/parallel/base_pipeline_event.hpp" #include #include @@ -160,7 +161,11 @@ class TeeStatement : public ClientContextState { }; // A result collector that hands every call to the collector it wraps: the one -// another extension installed for the statement. +// another extension installed for the statement. The wrapped collector gets +// its states with each call. Its own `sink_state` member stays unset, because +// DuckDB sets that on the pipeline's sink, which is this operator; a collector +// that read its own member instead of the state it is passed could not be +// wrapped. Quack's and DuckDB's collectors do not. class DelegatingCollector : public PhysicalResultCollector { public: DelegatingCollector(PhysicalPlan &plan, PreparedStatementData &data, unique_ptr inner_p) @@ -249,6 +254,8 @@ class TeeGlobalState : public GlobalSinkState { unique_ptr inner; sidequery_result_writer *writer = nullptr; + // The event that makes the result readable is in place. + bool publish_scheduled = false; atomic storing {true}; atomic rows {0}; // Numbers the stored batches of a result that has no executor batches. @@ -279,6 +286,34 @@ class TeeGlobalState : public GlobalSinkState { unique_ptr head_inner; }; +// Makes a statement's result readable, as the last thing its last pipeline +// does. The wrapped collector may finish its own work in events it inserts +// while it finalizes: Quack sends a result's last batches from one, which +// waits for the client and fails when the client is gone. A statement that +// fails there has failed, and leaves no result. This event is inserted before +// the wrapped collector finalizes, which puts it after every event inserted +// later (Event::InsertEvent), so it only runs once those have finished. +class TeePublishEvent : public BasePipelineEvent { +public: + TeePublishEvent(Pipeline &pipeline, TeeGlobalState &global_p, bool rows_exact_p) + : BasePipelineEvent(pipeline), global(global_p), rows_exact(rows_exact_p) { + } + + void Schedule() override { + } + + void FinishEvent() override { + if (global.writer) { + sidequery_result_finish(global.writer, global.rows, rows_exact); + global.writer = nullptr; + } + } + +private: + TeeGlobalState &global; + const bool rows_exact; +}; + class TeeLocalState : public LocalSinkState { public: unique_ptr inner; @@ -435,14 +470,14 @@ class TeeSink : public BASE { SinkFinalizeType Finalize(Pipeline &pipeline, Event &event, ClientContext &context, OperatorSinkFinalizeInput &input) const override { auto &global = input.global_state.template Cast(); - OperatorSinkFinalizeInput inner {*global.inner, input.interrupt_state}; - auto result = BASE::Finalize(pipeline, event, context, inner); - if (result != SinkFinalizeType::BLOCKED && global.writer) { - // Every thread has combined: the result becomes readable. - sidequery_result_finish(global.writer, global.rows, !StoppedAtLimit(global)); - global.writer = nullptr; + if (!global.publish_scheduled) { + // Every thread has combined, so the counts are final. A wrapped + // collector that blocks is finalized again with the same event. + global.publish_scheduled = true; + event.InsertEvent(make_shared_ptr(pipeline, global, !StoppedAtLimit(global))); } - return result; + OperatorSinkFinalizeInput inner {*global.inner, input.interrupt_state}; + return BASE::Finalize(pipeline, event, context, inner); } unique_ptr GetResult(GlobalSinkState &state) const override { From f4d4f6b74b2b62c4899e6b9822f3f727ff8738e0 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 20:01:43 -0800 Subject: [PATCH 12/14] Bound the first rows that wait for earlier batches Every batch that ended before the lowest one left up to a head's worth of rows waiting, so a slow or unstarted lowest batch let them grow with the number of batches. Only the lowest ended batches now wait, up to the one with which they fill the head; later batches keep no copy. --- docs/results.md | 6 +++ src/include/sqlnb_results.hpp | 84 +++++++++++++++++++++++++++++++---- 2 files changed, 82 insertions(+), 8 deletions(-) diff --git a/docs/results.md b/docs/results.md index f9984b0..a7eef34 100644 --- a/docs/results.md +++ b/docs/results.md @@ -67,6 +67,12 @@ Only the first rows need their order while the statement still runs. The thread on the lowest executor batch returns its rows at once. Every other thread keeps a copy of the first rows of its batch, at most `head_rows` rows or `head_bytes` bytes, until the batches before it have ended or enough rows were returned. +A batch that ends before the batches below it leaves its copy waiting for them. +Only the lowest such batches wait, up to the one with which they hold enough +rows to be the first rows by themselves; batches after that one keep no copy. +The memory this takes therefore does not grow with the number of batches: at +most about twice `head_rows` rows or `head_bytes` bytes wait, besides one copy +per thread. Results with at most `head_rows` rows and 1 MiB of Arrow buffers stay in memory. Larger results are written to `.arrow.tmp` and renamed to `.arrow` once diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index 0f5c970..ca3d7a2 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -237,6 +237,13 @@ struct TeeHeldChunk { idx_t bytes; }; +// The head rows an ended executor batch left waiting. +struct TeeWaitingBatch { + vector chunks; + idx_t rows = 0; + idx_t bytes = 0; +}; + class TeeLocalState; class TeeGlobalState : public GlobalSinkState { @@ -268,7 +275,15 @@ class TeeGlobalState : public GlobalSinkState { atomic min_batch {0}; mutex head_lock; // Head rows of ended executor batches, waiting for the batches before them. - map> waiting; + // Only as many batches wait as can still be part of the head: the lowest of + // them, up to the one with which they fill it. Without that, a slow lowest + // batch would leave a head's worth of rows here for every batch that ends. + map waiting; + idx_t waiting_rows = 0; + idx_t waiting_bytes = 0; + // The highest executor batch whose rows can still be part of the head: the + // ended batches up to it fill the head. It only falls; set under head_lock. + atomic head_cutoff {DConstants::INVALID_INDEX}; // Threads that have not combined. idx_t threads = 0; // Without executor batches the head is the chunks claimed first, in the @@ -539,6 +554,12 @@ class TeeSink : public BASE { local.pass_chunk = true; return; } + if (local.current_batch.GetIndex() > global.head_cutoff) { + // Ended batches before this one fill the head. Nothing of this batch + // was passed on, so all it holds is its own rows. + DropHeld(local); + return; + } local.held.push_back(Copy(chunk, bytes)); } @@ -674,7 +695,9 @@ class TeeSink : public BASE { auto end = global.waiting.lower_bound(local.current_batch.GetIndex()); vector before; for (auto entry = global.waiting.begin(); entry != end; entry++) { - for (auto &held : entry->second) { + global.waiting_rows -= entry->second.rows; + global.waiting_bytes -= entry->second.bytes; + for (auto &held : entry->second.chunks) { before.push_back(std::move(held)); } } @@ -725,7 +748,14 @@ class TeeSink : public BASE { void CloseHead(TeeGlobalState &global, TeeLocalState &local) const { global.head_done = true; lock_guard guard(global.head_lock); + ClearWaiting(global); + } + + // Requires head_lock. + static void ClearWaiting(TeeGlobalState &global) { global.waiting.clear(); + global.waiting_rows = 0; + global.waiting_bytes = 0; } // Passes on the chunks this thread holds for the head. False when the @@ -797,14 +827,52 @@ class TeeSink : public BASE { WaitLocked(global, local); } - // Requires head_lock. - static void WaitLocked(TeeGlobalState &global, TeeLocalState &local) { - if (!local.held.empty()) { - global.waiting[local.current_batch.GetIndex()] = std::move(local.held); + // Requires head_lock. Leaves this thread's head rows waiting for the + // batches before its own, unless they can no longer be part of the head. + void WaitLocked(TeeGlobalState &global, TeeLocalState &local) const { + auto batch = local.current_batch.GetIndex(); + if (!local.held.empty() && !global.head_done && batch <= global.head_cutoff) { + auto &waiting = global.waiting[batch]; + for (auto &held : local.held) { + waiting.rows += held.chunk->size(); + waiting.bytes += held.bytes; + global.waiting_rows += held.chunk->size(); + global.waiting_bytes += held.bytes; + waiting.chunks.push_back(std::move(held)); + } + TrimWaiting(global); } DropHeld(local); } + // Requires head_lock. The head takes the rows that wait in batch order, and + // the batches still being read only add rows before them. So once the + // batches that wait fill the head without the highest of them, that one can + // never be part of it: it is dropped, and the batches after the highest one + // left stop holding rows back. + void TrimWaiting(TeeGlobalState &global) const { + auto fills = [&](idx_t rows, idx_t bytes) { + return rows >= parameters->head_rows || bytes >= parameters->head_bytes; + }; + while (global.waiting.size() > 1) { + auto highest = std::prev(global.waiting.end()); + auto rows = global.waiting_rows - highest->second.rows; + auto bytes = global.waiting_bytes - highest->second.bytes; + if (!fills(rows, bytes)) { + break; + } + global.waiting_rows = rows; + global.waiting_bytes = bytes; + global.waiting.erase(highest); + } + if (fills(global.waiting_rows, global.waiting_bytes)) { + auto highest = global.waiting.rbegin()->first; + if (highest < global.head_cutoff) { + global.head_cutoff = highest; + } + } + } + // The end of this thread's rows. Its head rows are passed on or left // waiting as at the end of a batch, except for the last thread: no thread // is left to take the rows that wait, so it passes all of them on. False @@ -869,7 +937,7 @@ class TeeSink : public BASE { if (!own_placed && entry.first > local.current_batch.GetIndex()) { place_own(); } - for (auto &held : entry.second) { + for (auto &held : entry.second.chunks) { all.push_back(std::move(held)); } last = MaxValue(last, entry.first); @@ -877,7 +945,7 @@ class TeeSink : public BASE { if (!own_placed) { place_own(); } - global.waiting.clear(); + ClearWaiting(global); local.held = std::move(all); local.held_passed = 0; local.lowest = true; From 200d986a788b32e0b836d39e909910cc4b5f30f7 Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 20:02:35 -0800 Subject: [PATCH 13/14] Free the id and remove the file when finishing a result panics --- http/src/results.rs | 73 ++++++++++++++++++++------------------- http/src/results/tests.rs | 17 +++++++++ 2 files changed, 54 insertions(+), 36 deletions(-) diff --git a/http/src/results.rs b/http/src/results.rs index 9ca6103..5a7080e 100644 --- a/http/src/results.rs +++ b/http/src/results.rs @@ -368,8 +368,7 @@ impl ResultStore { reserved } - fn complete(&self, id: &str, stored: StoredResult, stored_bytes: u64) { - let now_ms = (self.clock)(); + fn complete(&self, id: &str, stored: StoredResult, stored_bytes: u64, now_ms: i64) { let mut state = self.lock(); match state.entries.get_mut(id) { Some(entry) => { @@ -757,14 +756,17 @@ fn write_all_at(file: &File, mut bytes: &[u8], mut offset: u64) -> std::io::Resu Ok(()) } +/// Removed when dropped unless it was published. struct SpillFile { - file: File, + /// Closed once the footer is written. + file: Option, directory: PathBuf, temporary: PathBuf, path: PathBuf, /// The first free byte. A batch claims its place here and is written /// there without a lock, so threads write at the same time. end: AtomicU64, + published: bool, } impl SpillFile { @@ -779,42 +781,45 @@ impl SpillFile { return Err(error.to_string()); } Ok(Self { - file, + file: Some(file), directory: directory.to_path_buf(), temporary, path: directory.join(format!("{id}.arrow")), end: AtomicU64::new(header.len() as u64), + published: false, }) } fn write(&self, batch: &RecordBatch) -> Result { + let file = self.file.as_ref().expect("a result file is open until it is finished"); let (bytes, metadata, body) = encode_batch(batch).map_err(|_| LimitReason::Io)?; let offset = self.end.fetch_add(bytes.len() as u64, Ordering::Relaxed); - write_all_at(&self.file, &bytes, offset).map_err(|_| LimitReason::Io)?; + write_all_at(file, &bytes, offset).map_err(|_| LimitReason::Io)?; Ok(Block::new(offset as i64, metadata as i32, body as i64)) } /// Writes the footer and publishes the file under its final name. - fn finish(self, schema: &Schema, blocks: &[Block]) -> Result<(PathBuf, u64), String> { - let temporary = self.temporary.clone(); - let result = (|| { - let footer = file_footer(schema, blocks); - let end = self.end.load(Ordering::Relaxed); - write_all_at(&self.file, &footer, end).map_err(|error| error.to_string())?; - // Windows cannot rename a file that is still open. - drop(self.file); - fs::rename(&self.temporary, &self.path).map_err(|error| error.to_string())?; - Ok((self.path, end + footer.len() as u64)) - })(); - if result.is_err() { - let _ = fs::remove_file(temporary); - } - result + fn finish(mut self, schema: &Schema, blocks: &[Block]) -> Result<(PathBuf, u64), String> { + let footer = file_footer(schema, blocks); + let end = self.end.load(Ordering::Relaxed); + let file = self.file.take().expect("a result file is open until it is finished"); + let written = write_all_at(&file, &footer, end); + // Windows cannot rename a file that is still open. + drop(file); + written.map_err(|error| error.to_string())?; + fs::rename(&self.temporary, &self.path).map_err(|error| error.to_string())?; + self.published = true; + Ok((self.path.clone(), end + footer.len() as u64)) } +} - fn discard(self) { - drop(self.file); - let _ = fs::remove_file(self.temporary); +impl Drop for SpillFile { + fn drop(&mut self) { + // Windows cannot remove a file that is still open. + drop(self.file.take()); + if !self.published { + let _ = fs::remove_file(&self.temporary); + } } } @@ -956,13 +961,7 @@ impl ResultWriter { let BatchData::Memory(batch) = &stored.data else { unreachable!("a result without a file keeps its batches in memory") }; - match file.write(batch) { - Ok(block) => blocks.push(block), - Err(reason) => { - file.discard(); - return Err(reason); - } - } + blocks.push(file.write(batch)?); } for (stored, block) in state.batches.iter_mut().zip(blocks) { stored.data = BatchData::File(block); @@ -983,7 +982,6 @@ impl ResultWriter { /// Makes the result readable. `rows` is the number of rows the statement /// produced, or only those it read when it stopped early (`rows_exact` false). pub(crate) fn finish(mut self, rows: u64, rows_exact: bool) { - self.finished = true; let elapsed_ms = self.started.elapsed().as_millis() as u64; let mut state = std::mem::take(&mut *self.lock()); state.batches.sort_by_key(|stored| stored.key); @@ -1000,6 +998,9 @@ impl ResultWriter { batch_ends.push(stored_rows); } let mut limit_reason = state.limit_reason; + // Read before the file is published, after which nothing may unwind: + // an unwinding writer forgets its result, which would leave the file. + let now_ms = (self.store.clock)(); let data = match state.file.take() { None => StoredData::Memory( state @@ -1048,7 +1049,9 @@ impl ResultWriter { batch_ends, data, }; - self.store.complete(&self.id, stored, stored_bytes); + self.store.complete(&self.id, stored, stored_bytes, now_ms); + // Until here, dropping the writer forgets the result. + self.finished = true; } } @@ -1057,10 +1060,8 @@ impl Drop for ResultWriter { if self.finished { return; } - let file = self.lock().file.take(); - if let Some(file) = file.and_then(Arc::into_inner) { - file.discard(); - } + // The file is removed before the id is free again. + drop(self.lock().file.take()); self.store.forget(&self.id); } } diff --git a/http/src/results/tests.rs b/http/src/results/tests.rs index 6ac9e35..f690715 100644 --- a/http/src/results/tests.rs +++ b/http/src/results/tests.rs @@ -480,6 +480,23 @@ fn a_batch_that_panics_while_being_stored_is_missing() { assert_eq!(scan_values(&store, &id(1), 0, UNLIMITED, None, &[0])[0], (0..4).collect::>()); } +#[test] +fn a_finish_that_panics_forgets_the_result_and_its_file() { + let directory = tempfile::tempdir().unwrap(); + let (store, environment) = open_store_in(Ok(directory.path().to_path_buf())); + let writer = store.begin(&id(1), "", schema(), limits(0)).unwrap(); + assert!(writer.append(batch(0, 4), (0, 0))); + assert_eq!(session_files(directory.path()), [format!("{}.arrow.tmp", id(1)), SESSION_LOCK.to_string()]); + // Finishing reads the clock once, before it publishes the file. + environment.panic_next.store(true, Ordering::Relaxed); + assert!(std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| writer.finish(4, true))).is_err()); + assert!(listed(&store).is_empty()); + assert_eq!(session_files(directory.path()), [SESSION_LOCK]); + // The id is free again. + store_result(&store, &id(1), &[2], limits(0)); + assert_eq!(listed_ids(&store), [id(1)]); +} + #[test] fn threads_store_batches_at_the_same_time() { let directory = tempfile::tempdir().unwrap(); From c7e2dfa1ac181cb26342820098ac07f878d878fb Mon Sep 17 00:00:00 2001 From: Nico Ritschel Date: Sat, 14 Nov 2026 20:33:22 -0800 Subject: [PATCH 14/14] Drop a result whose statement fails after its last pipeline DuckDB does not interrupt a pipeline's combine and finalize: a cancel that arrives then is raised afterwards, when the result has already been made readable. Over Quack a client that stopped reading and cancelled left the result of its failed statement listed and on disk. The statement now drops the result it published when it ends in error. --- src/include/sqlnb_results.hpp | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp index ca3d7a2..2fd7521 100644 --- a/src/include/sqlnb_results.hpp +++ b/src/include/sqlnb_results.hpp @@ -119,6 +119,8 @@ struct TeeParameters { bool stop_at_limit; vector types; vector names; + // The statement made its result readable. + atomic published {false}; }; struct TeeBindData : public TableFunctionData { @@ -153,7 +155,13 @@ class TeeStatement : public ClientContextState { previous = nullptr; } - void QueryEnd(ClientContext &context) override { + void QueryEnd(ClientContext &context, optional_ptr error) override { + if (error && error->HasError() && parameters && parameters->published) { + // The statement failed after its last pipeline had finished: DuckDB + // raises an interrupt that arrives while that pipeline finalizes only + // afterwards. A failed statement leaves no result. + sidequery_result_drop(parameters->id.c_str()); + } Unhook(context); parameters.reset(); collecting = false; @@ -303,15 +311,19 @@ class TeeGlobalState : public GlobalSinkState { // Makes a statement's result readable, as the last thing its last pipeline // does. The wrapped collector may finish its own work in events it inserts -// while it finalizes: Quack sends a result's last batches from one, which +// while it finalizes: Quack can send a result's last batches from one, which // waits for the client and fails when the client is gone. A statement that // fails there has failed, and leaves no result. This event is inserted before // the wrapped collector finalizes, which puts it after every event inserted -// later (Event::InsertEvent), so it only runs once those have finished. +// later (Event::InsertEvent), so it only runs once those have finished. A +// statement that still fails after this event is handled when it ends +// (TeeStatement::QueryEnd). class TeePublishEvent : public BasePipelineEvent { public: - TeePublishEvent(Pipeline &pipeline, TeeGlobalState &global_p, bool rows_exact_p) - : BasePipelineEvent(pipeline), global(global_p), rows_exact(rows_exact_p) { + TeePublishEvent(Pipeline &pipeline, TeeGlobalState &global_p, shared_ptr parameters_p, + bool rows_exact_p) + : BasePipelineEvent(pipeline), global(global_p), parameters(std::move(parameters_p)), + rows_exact(rows_exact_p) { } void Schedule() override { @@ -321,11 +333,13 @@ class TeePublishEvent : public BasePipelineEvent { if (global.writer) { sidequery_result_finish(global.writer, global.rows, rows_exact); global.writer = nullptr; + parameters->published = true; } } private: TeeGlobalState &global; + const shared_ptr parameters; const bool rows_exact; }; @@ -489,7 +503,8 @@ class TeeSink : public BASE { // Every thread has combined, so the counts are final. A wrapped // collector that blocks is finalized again with the same event. global.publish_scheduled = true; - event.InsertEvent(make_shared_ptr(pipeline, global, !StoppedAtLimit(global))); + event.InsertEvent( + make_shared_ptr(pipeline, global, parameters, !StoppedAtLimit(global))); } OperatorSinkFinalizeInput inner {*global.inner, input.interrupt_state}; return BASE::Finalize(pipeline, event, context, inner);