@minnowdb/core 0.1.0 → 0.2.0

package/dist/engine/vector.js

@@ -4,7 +4,7 @@ import { ByteGroupIndex } from "./group-index.js";
 import { ByteJoinIndex } from "./join-index.js";
 import { QueryMemoryBudgetError, QueryMemoryContext, } from "./memory.js";
 import { compareSqlStrings, defineSqlResultProperty } from "./sql-semantics.js";
-import { buildSortKeyColumn } from "./sort-keys.js";
+import { buildSortKeyColumn, sortKeyIndexes } from "./sort-keys.js";
 const DEFAULT_BATCH_ROWS = 2_048;
 /** Above this, locating each IN member separately costs more than scanning between them. */
 const MAX_SPLIT_LIST_MEMBERS = 64;
@@ -24,6 +24,21 @@ const PACKED_GROUP_ENTRY_BYTES = 24;
 const SPILL_PAGE_MAGIC = 0x5350494c;
 const SPILL_PAGE_HEADER_BYTES = 8;
 const vectorTextEncoder = new TextEncoder();
+/** Pages per batched spill write: bounds the transient encoded copies a batch holds. */
+const SPILL_WRITE_BATCH_PAGES = 8;
+/** Writes already-materialized pages through the batch method when the store offers one. */
+async function writeSpillPages(store, pages) {
+    const batched = store.putPages?.bind(store);
+    if (batched === undefined) {
+        for (const page of pages) {
+            await store.putPage(page.ownerId, page.runId, page.pageIndex, page.bytes);
+        }
+        return;
+    }
+    for (let start = 0; start < pages.length; start += SPILL_WRITE_BATCH_PAGES) {
+        await batched(pages.slice(start, start + SPILL_WRITE_BATCH_PAGES));
+    }
+}
 export function createColumnarTable(name, columns, uniqueKey) {
     const first = columns.values().next().value;
     const rowCount = first?.values.length ?? 0;
@@ -1156,11 +1171,18 @@ async function executeBoundPlanWithHashSpill(plan, memory, options) {
                         partitionBuffers.set(partition, rows);
                     }
                 });
+                const flush = [];
                 for (const [partition, rows] of partitionBuffers) {
                     const pageIndex = partitionPages[partition] ?? 0;
-                    await store.putPage(ownerId, `partition-${String(partition)}`, pageIndex, encodeSpillRows(spillColumns, rows));
+                    flush.push({
+                        ownerId,
+                        runId: `partition-${String(partition)}`,
+                        pageIndex,
+                        bytes: encodeSpillRows(spillColumns, rows),
+                    });
                     partitionPages[partition] = pageIndex + 1;
                 }
+                await writeSpillPages(store, flush);
             }
             finally {
                 batchMemory.close();
@@ -1206,10 +1228,21 @@ async function executeBoundPlanWithHashSpill(plan, memory, options) {
                 }
                 const runId = `group-${String(runSequence++)}`;
                 let outputPage = 0;
+                let pending = [];
                 for (let start = 0; start < rows.length; start += pageRows) {
-                    await store.putPage(ownerId, runId, outputPage, encodeSpillRows(columns, rows.slice(start, start + pageRows)));
+                    pending.push({
+                        ownerId,
+                        runId,
+                        pageIndex: outputPage,
+                        bytes: encodeSpillRows(columns, rows.slice(start, start + pageRows)),
+                    });
                     outputPage += 1;
+                    if (pending.length >= SPILL_WRITE_BATCH_PAGES) {
+                        await writeSpillPages(store, pending);
+                        pending = [];
+                    }
                 }
+                await writeSpillPages(store, pending);
                 runs.push({ id: runId, pageCount: outputPage });
             }
             finally {
@@ -2329,7 +2362,17 @@ function appendJoinedRow(output, outputRow, input, row, buildSource, buildRow) {
         }
     }
 }
-const DEFERRED_SELECTION_BYTES = 2 * QUERY_REFERENCE_BYTES;
+const RETAINED_ROW_BYTES = 3 * QUERY_REFERENCE_BYTES;
+/**
+ * A LIMIT that keeps at least this share of the scanned rows is not a bound worth enforcing:
+ * what the bounded sink saves in memory it spends in time, and past the share it is cheaper to
+ * keep every row and sort once. Measured at 200k rows, `ORDER BY region, id` and `ORDER BY
+ * amount`, against an unbounded scan-and-sort that costs the same (30 ms and 21 ms) whatever the
+ * LIMIT: at 5% the bound wins (22 ms and 17 ms), at 10% it loses (39 ms and 31 ms), and at 50%
+ * it loses by three times (97 ms and 72 ms). The crossover sits between those two shares, so
+ * the bound stops at the upper one.
+ */
+const BOUNDED_SINK_MAX_SHARE = 0.1;
 /**
  * Accumulates ungrouped result rows. With ORDER BY and LIMIT the sink keeps only the best
  * `limit + offset` rows instead of materializing every scanned row for one full sort, so memory
@@ -2337,15 +2380,18 @@ const DEFERRED_SELECTION_BYTES = 2 * QUERY_REFERENCE_BYTES;
  * ties resolve by arrival order, so the retained set is precisely the slice a full stable sort
  * would have produced.
  *
- * Two bounded strategies:
- * - Deferred selection (single-source plans whose order keys resolve to select expressions and
- *   whose scan vectors outlive the scan): rows are tracked as (keys, arrival, source row) and
- *   compacted by sort once the selection buffer reaches twice the capacity; only the final
- *   survivors are projected. A losing row never allocates a result object, so even the
- *   adversarial ascending-input/descending-order case stays allocation-free per row.
- * - Eager heap (joins, wildcard selects, or windowed scans): each retained row is projected into
- *   a worst-at-root heap; a candidate that cannot beat the current worst is rejected before
- *   projection whenever the order keys are resolvable.
+ * Candidates are tracked as (keys, arrival) entries in a selection buffer that is compacted by
+ * quickselect once it reaches twice the capacity, so a retained row costs a few comparisons
+ * amortized, and a row that cannot beat the current cut line costs nothing past its keys.
+ * Whether the entry also carries the projected row depends on the scan: when the scan
+ * vectors outlive the scan and the order keys resolve to select expressions, projection waits
+ * for the survivors; a streamed scan, a join, or a wildcard select projects the candidate as it
+ * arrives, since there is nothing to read it back from later.
+ *
+ * The bound is dropped for a page that would keep most of the scan anyway: a single-source
+ * plan whose `limit + offset` reaches BOUNDED_SINK_MAX_SHARE of the scan rows keeps every row
+ * and leaves the ordering to one final sort. A join's output size is not known from its scan, so
+ * a joined plan stays bounded.
  */
 class ResultSink {
     #plan;
@@ -2354,7 +2400,6 @@ class ResultSink {
     #keyExpressions;
     #deferred;
     #rows = [];
-    #heap = [];
     #selection = [];
     #keyScratch = [];
     #threshold;
@@ -2367,8 +2412,13 @@ class ResultSink {
     constructor(plan, memory, stableScan) {
         this.#plan = plan;
         this.#memory = memory;
-        const bounded = !plan.grouped && plan.orderBy.length > 0 && plan.limit !== undefined;
-        this.#capacity = bounded ? (plan.limit ?? 0) + (plan.offset ?? 0) : undefined;
+        const capacity = (plan.limit ?? 0) + (plan.offset ?? 0);
+        const scanRows = plan.sourceTables[plan.scanSource]?.rowCount ?? 0;
+        const bounded = !plan.grouped &&
+            plan.orderBy.length > 0 &&
+            plan.limit !== undefined &&
+            (plan.joins.length > 0 || capacity < scanRows * BOUNDED_SINK_MAX_SHARE);
+        this.#capacity = bounded ? capacity : undefined;
         let keyExpressions;
         if (bounded && !plan.wildcard) {
             keyExpressions = [];
@@ -2428,7 +2478,7 @@ class ResultSink {
         for (let row = 0; row < batch.length; row += 1) {
             const threshold = this.#thresholdFirst;
             if (threshold === undefined || threshold === null) {
-                this.#addSlow(batch, row);
+                this.#addCandidate(batch, row);
                 continue;
             }
             const sourceRow = rows?.[row] ?? -1;
@@ -2442,16 +2492,10 @@ class ResultSink {
                     }
                 }
             }
-            this.#addSlow(batch, row);
+            this.#addCandidate(batch, row);
         }
         return true;
     }
-    #addSlow(batch, row) {
-        if (this.#deferred)
-            this.#addDeferred(batch, row);
-        else
-            this.#addEager(batch, row);
-    }
     add(batch, row) {
         if (this.#capacity === undefined) {
             const resultRow = projectBatchRow(this.#plan, batch, row);
@@ -2461,21 +2505,17 @@ class ResultSink {
         }
         if (this.#capacity === 0)
             return;
-        if (this.#deferred) {
-            this.#addDeferred(batch, row);
-            return;
-        }
-        this.#addEager(batch, row);
+        this.#addCandidate(batch, row);
     }
     /** Returns accepted rows in arrival order, ready for the shared stable sort and trim. */
     finish() {
         if (this.#capacity === undefined)
             return this.#rows;
-        if (!this.#deferred) {
-            return this.#heap.sort((left, right) => left.seq - right.seq).map((entry) => entry.row);
-        }
         this.#compactSelection();
         this.#selection.sort((left, right) => left.seq - right.seq);
+        if (!this.#deferred) {
+            return this.#selection.map((entry) => required(entry.row, "Retained row is missing"));
+        }
         const scanIndex = new Int32Array(1);
         const rowsBySource = [scanIndex];
         const batch = { length: 1, rowsBySource };
@@ -2488,7 +2528,7 @@ class ResultSink {
         }
         return rows;
     }
-    #addDeferred(batch, row) {
+    #addCandidate(batch, row) {
         const fast = this.#fastFirstKey;
         if (fast !== undefined && this.#thresholdFirst !== undefined && this.#thresholdFirst !== null) {
             const value = rawFloat64Value(fast.vector, batch.rowsBySource[fast.source]?.[row] ?? -1);
@@ -2501,7 +2541,18 @@ class ResultSink {
                 }
             }
         }
-        this.#evaluateKeys(batch, row);
+        let projected;
+        if (this.#keyExpressions === undefined) {
+            // The order keys are not select expressions, so the projected row is where they live.
+            projected = projectBatchRow(this.#plan, batch, row);
+            for (let index = 0; index < this.#plan.orderBy.length; index += 1) {
+                const order = required(this.#plan.orderBy[index], "Order term is missing");
+                this.#keyScratch[index] = projected[order.outputName] ?? null;
+            }
+        }
+        else {
+            this.#evaluateKeys(batch, row);
+        }
         const seq = this.#seq;
         this.#seq += 1;
         // The candidate arrived after every retained row, so an order-key tie keeps the retained
@@ -2510,14 +2561,21 @@ class ResultSink {
             this.#compareKeys(this.#keyScratch, this.#threshold.keys) >= 0) {
             return;
         }
-        let bytes = DEFERRED_SELECTION_BYTES;
+        if (!this.#deferred && projected === undefined) {
+            projected = projectBatchRow(this.#plan, batch, row);
+        }
+        let bytes = RETAINED_ROW_BYTES;
         for (let index = 0; index < this.#plan.orderBy.length; index += 1) {
             bytes = safeMemorySum(bytes, queryValuePayloadBytes(this.#keyScratch[index] ?? null), "Top-N selection entry");
         }
+        if (projected !== undefined) {
+            bytes = safeMemorySum(bytes, queryRowPayloadBytes(projected), "Top-N selection entry");
+        }
         this.#selection.push({
             keys: this.#keyScratch.slice(0, this.#plan.orderBy.length),
             seq,
-            sourceRow: batch.rowsBySource[this.#plan.scanSource]?.[row] ?? -1,
+            sourceRow: this.#deferred ? (batch.rowsBySource[this.#plan.scanSource]?.[row] ?? -1) : -1,
+            row: projected,
             bytes,
         });
         this.#reserveSelectionBytes(bytes);
@@ -2623,64 +2681,6 @@ class ResultSink {
                 low = right + 1;
         }
     }
-    #addEager(batch, row) {
-        let projected;
-        if (this.#keyExpressions === undefined) {
-            projected = projectBatchRow(this.#plan, batch, row);
-            for (let index = 0; index < this.#plan.orderBy.length; index += 1) {
-                const order = required(this.#plan.orderBy[index], "Order term is missing");
-                this.#keyScratch[index] = projected[order.outputName] ?? null;
-            }
-        }
-        else {
-            this.#evaluateKeys(batch, row);
-        }
-        const seq = this.#seq;
-        this.#seq += 1;
-        const capacity = this.#capacity ?? 0;
-        if (this.#heap.length >= capacity) {
-            const worst = required(this.#heap[0], "Top-N heap root is missing");
-            // An order-key tie keeps the earlier-arriving retained row.
-            if (this.#compareKeys(this.#keyScratch, worst.keys) >= 0)
-                return;
-            const resultRow = projected ?? projectBatchRow(this.#plan, batch, row);
-            const reservation = this.#memory.reserve(this.#entryPayloadBytes(resultRow), "Top-N result row");
-            worst.reservation.release();
-            this.#heap[0] = {
-                row: resultRow,
-                keys: this.#keyScratch.slice(0, this.#plan.orderBy.length),
-                seq,
-                reservation,
-            };
-            this.#siftDown(0);
-            this.#updateEagerThreshold();
-            return;
-        }
-        const resultRow = projected ?? projectBatchRow(this.#plan, batch, row);
-        const reservation = this.#memory.reserve(this.#entryPayloadBytes(resultRow), "Top-N result row");
-        this.#heap.push({
-            row: resultRow,
-            keys: this.#keyScratch.slice(0, this.#plan.orderBy.length),
-            seq,
-            reservation,
-        });
-        this.#siftUp(this.#heap.length - 1);
-        this.#updateEagerThreshold();
-    }
-    /**
-     * The eager cut line for the unboxed batch loop: once the heap is full, its root's first
-     * order key as a float. Non-numeric keys leave the threshold null, which sends every row
-     * through the full comparison.
-     */
-    #updateEagerThreshold() {
-        if (this.#fastFirstKey === undefined)
-            return;
-        if (this.#heap.length < (this.#capacity ?? 0))
-            return;
-        const first = this.#heap[0]?.keys[0];
-        this.#thresholdFirst =
-            typeof first === "number" ? first : first instanceof Date ? first.getTime() : null;
-    }
     #evaluateKeys(batch, row) {
         const expressions = required(this.#keyExpressions, "Order keys are missing");
         for (let index = 0; index < expressions.length; index += 1) {
@@ -2688,13 +2688,6 @@ class ResultSink {
             this.#keyScratch[index] = asQueryValue(evaluateBatchExpression(this.#plan, expression, batch, row));
         }
     }
-    #entryPayloadBytes(row) {
-        let bytes = queryRowPayloadBytes(row);
-        for (let index = 0; index < this.#plan.orderBy.length; index += 1) {
-            bytes = safeMemorySum(bytes, queryValuePayloadBytes(this.#keyScratch[index] ?? null), "Top-N order keys");
-        }
-        return bytes;
-    }
     #compareKeys(left, right) {
         const orderBy = this.#plan.orderBy;
         for (let index = 0; index < orderBy.length; index += 1) {
@@ -2708,51 +2701,6 @@ class ResultSink {
         }
         return 0;
     }
-    /** Entry `left` loses to `right` when it sorts later under (keys, arrival). */
-    #isWorse(left, right) {
-        const comparison = this.#compareKeys(left.keys, right.keys);
-        if (comparison !== 0)
-            return comparison > 0;
-        return left.seq > right.seq;
-    }
-    #siftUp(index) {
-        let child = index;
-        while (child > 0) {
-            const parent = (child - 1) >> 1;
-            const childEntry = required(this.#heap[child], "Heap entry is missing");
-            const parentEntry = required(this.#heap[parent], "Heap entry is missing");
-            if (!this.#isWorse(childEntry, parentEntry))
-                break;
-            this.#heap[child] = parentEntry;
-            this.#heap[parent] = childEntry;
-            child = parent;
-        }
-    }
-    #siftDown(index) {
-        let parent = index;
-        for (;;) {
-            let worst = parent;
-            let worstEntry = required(this.#heap[worst], "Heap entry is missing");
-            const left = parent * 2 + 1;
-            const right = left + 1;
-            const leftEntry = this.#heap[left];
-            if (leftEntry !== undefined && this.#isWorse(leftEntry, worstEntry)) {
-                worst = left;
-                worstEntry = leftEntry;
-            }
-            const rightEntry = this.#heap[right];
-            if (rightEntry !== undefined && this.#isWorse(rightEntry, worstEntry)) {
-                worst = right;
-                worstEntry = rightEntry;
-            }
-            if (worst === parent)
-                return;
-            const parentEntry = required(this.#heap[parent], "Heap entry is missing");
-            this.#heap[parent] = worstEntry;
-            this.#heap[worst] = parentEntry;
-            parent = worst;
-        }
-    }
 }
 /**
  * Insertion-ordered group-state store. A single bare string-column GROUP BY resolves each row
@@ -4065,66 +4013,14 @@ function groupKey(value) {
     throw new TypeError("Group keys must be SQL scalar values");
 }
 function stableSortRows(rows, orderBy) {
-    if (rows.length > 0xffffffff)
-        throw new RangeError("Too many rows to order");
-    const indexes = new Uint32Array(rows.length);
-    const scratch = new Uint32Array(rows.length);
-    for (let index = 0; index < indexes.length; index += 1)
-        indexes[index] = index;
-    let source = indexes;
-    let target = scratch;
-    // One prepared column per term, extracted once; see sort-keys.ts for why the comparison
-    // rather than the merge is what a sort costs. Direction and explicit NULL placement are
-    // resolved here, outside the comparison, because they never vary row to row.
-    const termCount = orderBy.length;
+    // One prepared column per term, extracted once; see sort-keys.ts for the kernel and for why
+    // the comparison rather than the merge is what a sort costs.
     const terms = orderBy.map((order) => ({
-        /** Signed placement for an explicit NULLS FIRST/LAST, or 0 when the default applies. */
-        nullPlacement: order.nulls === undefined ? 0 : order.nulls === "first" ? 1 : -1,
+        column: buildSortKeyColumn(rows.length, (index) => required(rows[index], "Ordering row is missing")[order.outputName]),
         descending: order.direction === "desc",
+        nulls: order.nulls,
     }));
-    const columns = orderBy.map((order) => buildSortKeyColumn(rows.length, (index) => required(rows[index], "Ordering row is missing")[order.outputName]));
-    const compareIndexes = (leftIndex, rightIndex) => {
-        for (let term = 0; term < termCount; term += 1) {
-            const column = required(columns[term], "Order keys are missing");
-            const { nullPlacement, descending } = required(terms[term], "Order term is missing");
-            if (nullPlacement !== 0) {
-                // An explicit placement is absolute: direction must not negate it.
-                const leftNull = column.isNull(leftIndex);
-                const rightNull = column.isNull(rightIndex);
-                if (leftNull || rightNull) {
-                    if (leftNull && rightNull)
-                        continue;
-                    return (leftNull ? -1 : 1) * nullPlacement;
-                }
-            }
-            const comparison = column.compare(leftIndex, rightIndex);
-            if (comparison !== 0)
-                return descending ? -comparison : comparison;
-        }
-        return 0;
-    };
-    for (let width = 1; width < rows.length; width *= 2) {
-        for (let start = 0; start < rows.length; start += width * 2) {
-            const middle = Math.min(start + width, rows.length);
-            const end = Math.min(start + width * 2, rows.length);
-            let left = start;
-            let right = middle;
-            for (let output = start; output < end; output += 1) {
-                if (right >= end ||
-                    (left < middle && compareIndexes(source[left] ?? 0, source[right] ?? 0) <= 0)) {
-                    target[output] = source[left] ?? 0;
-                    left += 1;
-                }
-                else {
-                    target[output] = source[right] ?? 0;
-                    right += 1;
-                }
-            }
-        }
-        [source, target] = [target, source];
-    }
-    if (source !== indexes)
-        indexes.set(source);
+    const indexes = sortKeyIndexes(rows.length, terms);
     const visited = new Uint8Array(rows.length);
     for (let start = 0; start < rows.length; start += 1) {
         if (visited[start] === 1)