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/README.md b/README.md index 0dfcb86..4a5b227 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,7 @@ To connect an MCP client, start with `mcp := true` and follow the - [Notebook storage](docs/notebooks.md) — files, DuckDB UI notebooks, history, and project Git. - [MCP reference](docs/mcp.md) — authentication, tools, and execution behavior. - [Instant SQL read policy](docs/instant-sql.md) — what previews automatically and why the rest needs Run. +- [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..5c5a1ef 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 @@ -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 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..a7eef34 --- /dev/null +++ b/docs/results.md @@ -0,0 +1,247 @@ +# 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 whose result is kept, as a table. | +| `id` | required | 32 lowercase hexadecimal characters, unique among the process's results. | +| `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` | 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 +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, 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: +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. + +### 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. +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 +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 + +`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 +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 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. 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: + +```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`, `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. +`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 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 + +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, 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. | + +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, 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: + +- 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 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, 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 | +|---|---|---| +| 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. diff --git a/http/Cargo.lock b/http/Cargo.lock index ef1c262..922e1dd 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,8 +1460,13 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" name = "sidequery-ui-http" version = "0.1.0" dependencies = [ + "arrow-array", + "arrow-data", + "arrow-ipc", + "arrow-schema", "axum", "bytes", + "flatbuffers", "git2", "http-body-util", "libc", @@ -1380,6 +1608,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 +1867,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 +2101,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 +2136,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..13bdbc0 100644 --- a/http/Cargo.toml +++ b/http/Cargo.toml @@ -10,8 +10,13 @@ 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" +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/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 de50cef..17279ab 100644 --- a/http/src/lib.rs +++ b/http/src/lib.rs @@ -21,6 +21,7 @@ mod history; mod imports; mod mcp; mod project_git; +mod results; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; use std::{ 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 969524e..2828720 100644 --- a/http/src/platform/unix.rs +++ b/http/src/platform/unix.rs @@ -408,6 +408,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 edcb9bf..496d60f 100644 --- a/http/src/platform/windows.rs +++ b/http/src/platform/windows.rs @@ -475,6 +475,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 new file mode 100644 index 0000000..5a7080e --- /dev/null +++ b/http/src/results.rs @@ -0,0 +1,1360 @@ +//! 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::{ + 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::{ + Array, ArrayRef, BooleanArray, Int64Array, RecordBatch, RecordBatchIterator, + RecordBatchOptions, RecordBatchReader, StringArray, StructArray, +}; +use arrow_data::ArrayData; +use arrow_ipc::convert::IpcSchemaEncoder; +use arrow_ipc::reader::{FileReader, FileReaderBuilder}; +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; +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}; + +/// 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); +/// 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, +} + +impl LimitReason { + fn as_str(self) -> &'static str { + match self { + LimitReason::ResultBytes => "result-bytes", + LimitReason::CacheBytes => "cache-bytes", + LimitReason::DiskSpace => "disk-space", + 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, + /// 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)] +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, + /// 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, + /// 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); + } + } + + /// 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), + } + } + + fn lock(&self) -> MutexGuard<'_, StoreState> { + 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; + } + + 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_swept().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 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: 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(), + id: id.to_string(), + batch_type: DataType::Struct(schema.fields().clone()), + schema, + limits, + started: Instant::now(), + storing: AtomicBool::new(true), + state: Mutex::new(WriterState::default()), + finished: false, + }) + } + + /// 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 (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), Vec::new()) + } else { + 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), evicted) + } else { + if let Some(entry) = state.entries.get_mut(id) { + entry.stored_bytes += requested; + } + (Ok(()), evicted) + } + } + }; + for entry in evicted { + entry.remove_file(); + } + reserved + } + + 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) => { + 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 { + 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_swept(); + 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() + } + + /// A result about to be read, which counts as a use of it. + fn readable(&self, id: &str) -> Result<(SchemaRef, Arc), String> { + 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. + 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 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)?; + 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. Listing is not a use. + pub(crate) fn list(&self) -> RecordBatch { + let state = self.lock_swept(); + 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)), + )), + 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") + } +} + +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), + Field::new("last_used_ms", DataType::Int64, false), + Field::new("expires_ms", DataType::Int64, true), + ])) +} + +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, expired 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::try_new(FILE_ALIGNMENT as usize, false, MetadataVersion::V5) + .expect("the result file options are valid") +} + +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() +} + +/// 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) +} + +/// 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) +} + +#[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(()) +} + +/// Removed when dropped unless it was published. +struct SpillFile { + /// 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 { + 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()))?; + 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: 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(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(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)) + } +} + +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); + } + } +} + +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, + schema: SchemaRef, + batch_type: DataType, + limits: ResultLimits, + started: Instant, + /// 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(&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, key), + Err(_) => { + self.missing(key, LimitReason::Io); + false + } + } + } + + /// `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 { + let rows = batch.num_rows() as u64; + if rows == 0 { + return self.storing.load(Ordering::Relaxed); + } + 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 { + Err(LimitReason::Io) + }; + match stored { + Ok(()) => true, + Err(reason) => { + self.missing(key, reason); + false + } + } + } + + 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, 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") + }; + // 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 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 { + let BatchData::Memory(batch) = &stored.data else { + unreachable!("a result without a file keeps its batches in memory") + }; + blocks.push(file.write(batch)?); + } + for (stored, block) in state.batches.iter_mut().zip(blocks) { + stored.data = BatchData::File(block); + } + state.file = Some(Arc::new(file)); + Ok(()) + } + + /// 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 + /// produced, or only those it read when it stopped early (`rows_exact` false). + pub(crate) fn finish(mut self, rows: u64, rows_exact: bool) { + 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); + 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; + // 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 + .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, + limit_reason, + elapsed_ms, + batch_ends, + data, + }; + self.store.complete(&self.id, stored, stored_bytes, now_ms); + // Until here, dropping the writer forgets the result. + self.finished = true; + } +} + +impl Drop for ResultWriter { + fn drop(&mut self) { + if self.finished { + return; + } + // The file is removed before the id is free again. + drop(self.lock().file.take()); + 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_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, + 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, + ttl_seconds: 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, + 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(()) + }); + 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: *const ResultWriter, + batch: *mut FFI_ArrowArray, + major: u64, + minor: u64, +) -> bool { + let writer = unsafe { &*writer }; + writer.append_ffi_guarded(unsafe { FFI_ArrowArray::from_raw(batch) }, (major, minor)) +} + +#[no_mangle] +pub unsafe extern "C" fn sidequery_result_missing(writer: *const ResultWriter, major: u64, minor: u64) { + let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + unsafe { &*writer }.missing((major, minor), 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..f690715 --- /dev/null +++ b/http/src/results/tests.rs @@ -0,0 +1,759 @@ +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; + +/// 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, + /// 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 +/// 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)), + 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.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) }) + }), + )); + store.retain(); + (store, environment) +} + +fn open_store(directory: &Path) -> Arc { + open_store_in(Ok(directory.to_path_buf())).0 +} + +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, + 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}") +} + +/// Stores batches of the given sizes, numbering rows from 0. +fn store_result(store: &Arc, id: &str, sizes: &[i64], limits: ResultLimits) { + let writer = store.begin(id, "meta", schema(), limits).unwrap(); + let mut start = 0; + for (position, &size) in sizes.iter().enumerate() { + writer.append(batch(start, size), (0, position as u64)); + 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 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() { + 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 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()); + 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 writer = store + .begin( + &id(1), + "", + schema(), + ResultLimits { + head_rows: 1000, + max_result_bytes: batch_size + batch_size / 2, + max_cache_bytes: UNLIMITED, + ttl_ms: None, + }, + ) + .unwrap(); + 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); + 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] +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, + ttl_ms: None, + }; + 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 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!( + 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 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)]); +} + +#[test] +fn an_unavailable_cache_directory_keeps_the_memory_prefix() { + 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))); + 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 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, (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 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 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(); + 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::>()); +} + +#[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 f5d6fe1..8ac9bf8 100644 --- a/scripts/runtime-smoke.mjs +++ b/scripts/runtime-smoke.mjs @@ -5,8 +5,10 @@ import { existsSync, mkdirSync, mkdtempSync, + readdirSync, readFileSync, realpathSync, + rmSync, statSync, symlinkSync, writeFileSync, @@ -93,6 +95,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.')); @@ -103,10 +130,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 = []; @@ -144,6 +183,26 @@ 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 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. +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 = ''; @@ -631,6 +690,221 @@ 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)"; + // 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, 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`)), + [ + { 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 * 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((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 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)); + 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 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 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)`); + } + 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 }], + ); + // 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'); + 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()', + `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), + `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,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); + 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()'); assert.equal(firstValue(serversBeforeStop), 1); assert.equal(firstValue(await runSQL('select sqlnb_stop()')), true); @@ -774,6 +1048,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/sidequery_http.h b/src/include/sidequery_http.h index 99d3dca..9df5341 100644 --- a/src/include/sidequery_http.h +++ b/src/include/sidequery_http.h @@ -22,6 +22,61 @@ 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); +// 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, 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 +// 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); +void sidequery_result_abort(sidequery_result_writer *writer); +// 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. +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 diff --git a/src/include/sqlnb_results.hpp b/src/include/sqlnb_results.hpp new file mode 100644 index 0000000..2fd7521 --- /dev/null +++ b/src/include/sqlnb_results.hpp @@ -0,0 +1,1347 @@ +#pragma once + +// 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 "duckdb/parallel/base_pipeline_event.hpp" + +#include +#include + +namespace duckdb { +namespace sqlnb_results { + +static constexpr int64_t DEFAULT_HEAD_ROWS = 10240; +static constexpr int64_t DEFAULT_HEAD_BYTES = 4LL * 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 TeeParameters { + string id; + string meta; + idx_t head_rows; + 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; + // The statement made its result readable. + atomic published {false}; +}; + +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; + } + + 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; + } +}; + +// A result collector that hands every call to the collector it wraps: the one +// 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) + : 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; +}; + +// 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 { +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; + // 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. + 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. + // 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 + // 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. 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; +}; + +// 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 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. 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, 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 { + } + + void FinishEvent() override { + 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; +}; + +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, 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 +// 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, parameters->types, parameters->names, schema.arrow_schema); + 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, parameters->ttl_seconds, &error); + if (!state->writer) { + ThrowCacheError(error); + } + return std::move(state); + } + + 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; + } + + // 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); + } + + SinkFinalizeType Finalize(Pipeline &pipeline, Event &event, ClientContext &context, + OperatorSinkFinalizeInput &input) const override { + auto &global = input.global_state.template Cast(); + 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, parameters, !StoppedAtLimit(global))); + } + OperatorSinkFinalizeInput inner {*global.inner, input.interrupt_state}; + return BASE::Finalize(pipeline, event, context, inner); + } + + 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. 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 && global.head_done; + } + + 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); + } + 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; + } + 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)); + } + + // 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)); + } + } + 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) { + 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; + } else { + SyncPartition(global, local, InnerBatch(local)); + } + 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. + guard.lock(); + auto combined = std::move(global.head_inner); + guard.unlock(); + 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++) { + global.waiting_rows -= entry->second.rows; + global.waiting_bytes -= entry->second.bytes; + for (auto &held : entry->second.chunks) { + 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; + } + + // 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; + } + 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; + } + 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; + } + + 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 + // 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. 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 + // 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); + } + + // 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.chunks) { + all.push_back(std::move(held)); + } + last = MaxValue(last, entry.first); + } + if (!own_placed) { + place_own(); + } + ClearWaiting(global); + local.held = std::move(all); + local.held_passed = 0; + local.lowest = true; + if (last != batch && !local.held.empty()) { + local.last_batch = last; + } + } + + // 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 (!local.batch) { + local.batch = make_uniq(parameters->types, BATCH_ROWS, properties, extension_types); + } + auto before = local.batch->ByteSize(); + local.batch->Append(chunk, 0, chunk.size(), chunk.size()); + return local.batch->ByteSize() - before; + } catch (std::exception &) { + local.batch.reset(); + global.storing = false; + return 0; + } + } + + // 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); + } + 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 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); + } + + // 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); + } + } + + // 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; +}; + +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 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"); + 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); + // 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 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, + 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; + // 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) + .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(NumericCast(max_result_bytes))) + .AddKeywordOnly("max_cache_bytes", LogicalType::BIGINT, + 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; + 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..0507e24 --- /dev/null +++ b/test/sql/results.test @@ -0,0 +1,225 @@ +# Result cache (docs/results.md). Results are process-wide, so every id here is +# unique to this file. +require sqlnb + +# 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 * 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_results() where id >= 'a0000000000000000000000000000090'; +---- +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; +---- +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, last_used_ms BIGINT, expires_ms BIGINT + +# 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 * 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 * 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 * from sqlnb_result_tee((select i from range(100000000) t(i)), id := 'a0000000000000000000000000000005', max_result_bytes := 100000, stop_at_limit := true); + +statement ok +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; +---- +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 + +# 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'); +---- +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 + +# 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