quiverdb 0.12.5 → 0.12.7

package/README.md

@@ -135,8 +135,8 @@ bun run example.ts
 - `queryBoolean(sql, parameters?)` -- Query returning an INTEGER-backed boolean or null
 - `queryFloat(sql, parameters?)` -- Query returning float or null
 
-Parameters are passed as an array of `number | boolean | string | null` (a `boolean` binds as the
-INTEGER 1 or 0).
+Parameters are passed as an array of `number | bigint | boolean | string | null` (a `bigint` binds
+as an exact INTEGER, a `boolean` as the INTEGER 1 or 0).
 
 ### Transaction
 
@@ -182,12 +182,15 @@ Exported types available for TypeScript consumers:
 - `ArrayValue` -- `number[] | bigint[] | string[]`
 - `Value` -- `ScalarValue | ArrayValue`
 - `ElementData` -- `Record<string, Value | undefined>`
-- `QueryParam` -- `number | string | null`
+- `QueryParam` -- `number | bigint | boolean | string | null`
 - `QuiverError` -- Error class for all Quiver operations
 - `ScalarMetadata` -- Scalar attribute metadata
 - `GroupMetadata` -- Vector/set/time series group metadata
 - `TimeSeriesData` -- Time series column data
 - `CsvOptions` -- CSV import/export options
+- `DatabaseOptions` -- `{ readOnly?: boolean; consoleLevel?: number }` (a `LOG_LEVEL_*` constant)
+- `LOG_LEVEL_DEBUG | INFO | WARN | ERROR | OFF`, `DATA_TYPE_INTEGER | FLOAT | STRING | DATE_TIME | NULL`
+  -- constants for `DatabaseOptions.consoleLevel` and metadata `dataType`
 
 ## Development
 

package/mod.ts

@@ -11,16 +11,4 @@
  * ```
  */
 
-export type {
-  ArrayValue,
-  CsvOptions,
-  ElementData,
-  GroupColumns,
-  GroupMetadata,
-  QueryParam,
-  ScalarMetadata,
-  ScalarValue,
-  TimeSeriesData,
-  Value,
-} from "./src/index.ts";
-export { Database, LUA_DB_API_REFERENCE, LuaRunner, QuiverError } from "./src/index.ts";
+export * from "./src/index.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/create.ts

@@ -8,7 +8,7 @@ import {
   readPtrOut,
   toCString,
 } from "./ffi-helpers.ts";
-import { type GroupColumns, updateGroupColumns } from "./group-columns.ts";
+import { type GroupColumns, numericCells, updateGroupColumns } from "./group-columns.ts";
 import { getSymbols, type NativePointer } from "./loader.ts";
 import type { ElementData, Value } from "./types.ts";
 
@@ -17,6 +17,7 @@ type Symbols = ReturnType<typeof getSymbols>;
 function setElementArray(
   lib: Symbols,
   elemPtr: NativePointer,
+  caller: string,
   name: string,
   values: unknown[],
 ): void {
@@ -39,27 +40,18 @@ function setElementArray(
     );
   }
 
-  if (typeof first === "bigint") {
-    const arr = allocNativeInt64(values as bigint[]);
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
-    return;
-  }
-
-  if (typeof first === "boolean") {
-    const arr = allocNativeInt64((values as boolean[]).map((v) => (v ? 1 : 0)));
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
-    return;
-  }
-
-  if (typeof first === "number") {
-    const allIntegers = (values as number[]).every((v) => Number.isInteger(v));
-    if (allIntegers) {
-      const arr = allocNativeInt64(values as number[]);
+  if (typeof first === "number" || typeof first === "boolean" || typeof first === "bigint") {
+    // The null check above leaves no null cell, so the cast only narrows.
+    const cells = numericCells(caller, name, values) as (number | bigint)[];
+    if (cells.every((v) => typeof v === "bigint" || Number.isInteger(v))) {
+      const arr = allocNativeInt64(cells);
       check(
         lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null),
       );
     } else {
-      const arr = allocNativeFloat64(values as number[]);
+      // A fractional cell makes the array FLOAT; a bigint cell then follows the int-for-REAL rule
+      // through Number(), exact up to 2^53 like any JS number.
+      const arr = allocNativeFloat64(cells.map(Number));
       check(lib.quiver_element_set_array_float(elemPtr, nameBuf.buf, arr.buf, values.length, null));
     }
     return;
@@ -76,7 +68,13 @@ function setElementArray(
   throw new QuiverError(`Unsupported array element type for '${name}': ${typeof first}`);
 }
 
-function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, value: Value): void {
+function setElementField(
+  lib: Symbols,
+  elemPtr: NativePointer,
+  caller: string,
+  name: string,
+  value: Value,
+): void {
   const nameBuf = toCString(name);
 
   if (value === null) {
@@ -110,7 +108,7 @@ function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, val
   }
 
   if (Array.isArray(value)) {
-    setElementArray(lib, elemPtr, name, value);
+    setElementArray(lib, elemPtr, caller, name, value);
     return;
   }
 
@@ -132,7 +130,7 @@ Database.prototype.createElement = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "createElement", key, value);
     }
 
     const outIdBuf = new Uint8Array(8);
@@ -160,7 +158,7 @@ Database.prototype.updateElement = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "updateElement", key, value);
     }
     const collBuf = toCString(collection);
     check(lib.quiver_database_update_element(handle, collBuf.buf, BigInt(id), elemPtr));
@@ -186,7 +184,7 @@ Database.prototype.updateElementByLabel = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "updateElementByLabel", key, value);
     }
     const collBuf = toCString(collection);
     const labelBuf = toCString(label);

package/src/group-columns.ts

@@ -24,12 +24,16 @@ import {
   DATA_TYPE_STRING,
 } from "./types.ts";
 
-/** Column-oriented group payload: one array of cells per column name, `null` for SQL NULL. */
-export type GroupColumns = Record<string, (number | string | boolean | null)[]>;
+/**
+ * Column-oriented group payload: one array of cells per column name, `null` for SQL NULL. A
+ * `bigint` cell is written as an exact int64 (like createElement); a `boolean` as INTEGER 1/0.
+ */
+export type GroupColumns = Record<string, (number | bigint | string | boolean | null)[]>;
 
 /**
  * Column-oriented group read result: one array of cells per column name, `null` for SQL NULL.
- * The read-side twin of GroupColumns; no reader produces a boolean, so it admits none.
+ * The read-side twin of GroupColumns; no reader produces a boolean or a bigint, so it admits
+ * neither.
  */
 export type TimeSeriesData = Record<string, (number | string | null)[]>;
 
@@ -51,6 +55,34 @@ type ColumnUpdateFn = (
   rowCount: bigint,
 ) => number;
 
+/**
+ * Check and normalize the cells of a numeric column: one whose first non-null cell is a number, a
+ * bigint or a boolean. Shared by updateGroupColumns and setElementArray (create.ts) so the group
+ * writers and the element arrays agree on every cell. String columns are never passed here.
+ *
+ * - A boolean becomes INTEGER 1/0, since SQLite has no boolean type. Per cell, because mapping the
+ *   whole column from a leading boolean truthiness-mapped the rest and rewrote [true, 5] as
+ *   [1, 1]. Before the INTEGER/FLOAT choice, because Number.isInteger(true) is false.
+ * - A bigint stays a bigint, so an INTEGER column keeps it exact; the caller maps it through
+ *   Number() only if the column turns out FLOAT.
+ * - Any other non-null cell throws, naming the column and the cell. It would fail
+ *   Number.isInteger, tag the column FLOAT and reach DataView.setFloat64, which converts it with no
+ *   error: "abc" to NaN, which SQLite stores as NULL, and "2" to 2.
+ */
+export function numericCells(
+  caller: string,
+  name: string,
+  values: readonly unknown[],
+): (number | bigint | null)[] {
+  return values.map((v, r) => {
+    if (v === null || typeof v === "number" || typeof v === "bigint") return v;
+    if (typeof v === "boolean") return v ? 1 : 0;
+    throw new QuiverError(
+      `Cannot ${caller}: numeric column '${name}' has unsupported value type ${typeof v} in cell ${r}`,
+    );
+  });
+}
+
 /**
  * Marshal a column-oriented payload and forward it to one of the columnar group update C
  * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup and their
@@ -114,16 +146,7 @@ export function updateGroupColumns(
   const maskPtrs: (Pointer | null)[] = [];
 
   for (let c = 0; c < columnCount; c++) {
-    const [colName, rawValues] = entries[c];
-    // SQLite has no boolean type: a boolean is INTEGER 1/0, as in setElementField and
-    // marshalParams. Normalizing per cell before the dispatch (rather than adding a boolean
-    // branch after it) is what makes a mixed [true, 5] column write 1 and 5 instead of
-    // truthiness-mapping every cell, and matches Python's per-cell `int(v)`. A string column is
-    // left alone so normalizing cannot change what a mixed ['a', true] column already wrote.
-    const isStringColumn = typeof rawValues.find((v) => v !== null) === "string";
-    const values = isStringColumn
-      ? rawValues
-      : rawValues.map((v) => (typeof v === "boolean" ? (v ? 1 : 0) : v));
+    const [colName, values] = entries[c];
     const first = values.find((v) => v !== null);
 
     // Mask via direct indexing — never a DataView, to avoid the documented
@@ -141,23 +164,29 @@ export function updateGroupColumns(
       keepalive.push(p);
       dataPtrs.push(p.ptr);
     } else if (typeof first === "string") {
+      // Not checked by numericCells: a mixed ['a', true] column still writes what it always wrote.
       typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
       const { table, keepalive: strPtrs } = allocNativeStringArray(
         values.map((v) => (v === null ? null : (v as string))),
       );
       keepalive.push(table, ...strPtrs);
       dataPtrs.push(table.ptr);
-    } else if (typeof first === "number") {
-      const nonNull = values.filter((v) => v !== null) as number[];
-      const sanitized = values.map((v) => (v === null ? 0 : (v as number)));
-      if (nonNull.every((v) => Number.isInteger(v))) {
+    } else if (
+      typeof first === "number" ||
+      typeof first === "boolean" ||
+      typeof first === "bigint"
+    ) {
+      const cells = numericCells(caller, colName, values);
+      if (cells.every((v) => v === null || typeof v === "bigint" || Number.isInteger(v))) {
         typesDv.setInt32(c * 4, DATA_TYPE_INTEGER, true);
-        const p = allocNativeInt64(sanitized);
+        const p = allocNativeInt64(cells.map((v) => v ?? 0));
         keepalive.push(p);
         dataPtrs.push(p.ptr);
       } else {
+        // A fractional cell makes the column FLOAT; a bigint cell then follows the int-for-REAL
+        // rule through Number(), exact up to 2^53 like any JS number.
         typesDv.setInt32(c * 4, DATA_TYPE_FLOAT, true);
-        const p = allocNativeFloat64(sanitized);
+        const p = allocNativeFloat64(cells.map((v) => (v === null ? 0 : Number(v))));
         keepalive.push(p);
         dataPtrs.push(p.ptr);
       }

package/src/index.ts

@@ -24,6 +24,11 @@ export type {
   Value,
 } from "./types.ts";
 export {
+  DATA_TYPE_DATE_TIME,
+  DATA_TYPE_FLOAT,
+  DATA_TYPE_INTEGER,
+  DATA_TYPE_NULL,
+  DATA_TYPE_STRING,
   LOG_LEVEL_DEBUG,
   LOG_LEVEL_ERROR,
   LOG_LEVEL_INFO,

package/src/lua-api.ts

@@ -52,7 +52,7 @@ Lua values map to Quiver column values as follows:
 | number (float)     | REAL         | A float is rejected for an INTEGER column.     |
 | string             | TEXT         | Also used for \`date_time\` columns (ISO 8601).  |
 | boolean            | INTEGER 1/0  | SQLite has no boolean type; \`true\` writes 1, \`false\` 0. |
-| \`nil\`              | NULL         | In query params, file paths, ts rows, relations.|
+| \`nil\`              | NULL         | In query params (not trailing), ts rows, group cells, relations. |
 | table (1-indexed)  | array        | Used for vectors/sets and column-oriented data.|
 
 A boolean is accepted **wherever an integer is** — element scalars and arrays, query parameters,
@@ -86,10 +86,18 @@ midnight.
 - **Type coercion.** An integer is accepted for a REAL column (coerced to real on insert); a float
   is rejected for an INTEGER column. A string bound to a \`date_*\` column must parse as ISO 8601
   (\`YYYY-MM-DD\`, optionally \`THH:MM:SS\` or \` HH:MM:SS\`). Other type mismatches raise a
-  validation error and roll the whole script back.
-- **Errors abort the script.** Any error thrown by a \`db:\` call stops the script and surfaces as
-  \`Failed to run Lua script: <message>\`. Validation failures roll back whatever the current
-  transaction covered.
+  validation error.
+- **An uncaught error aborts the script, and the script is not rolled back.** Any error thrown by
+  a \`db:\` call that you do not catch with \`pcall\` stops the script and surfaces as
+  \`Failed to run Lua script: <message>\`. Outside a transaction each \`db:\` write commits on its
+  own, so the failing call changes nothing in the database, but every write that finished before
+  it **stays**. Only \`db:transaction(fn)\` and \`db:dry_run(fn)\` undo their block's database
+  writes when \`fn\` errors; nothing undoes a file a \`db:\` call wrote. A
+  \`db:begin_transaction()\` (or \`db:begin_dry_run()\`) you opened and never closed stays open
+  after the error, and closing it is up to the host. A host that runs your script inside its own
+  transaction or dry run may undo the whole run; check \`db:in_transaction()\` if it matters. To
+  make several writes all-or-nothing, put them in one \`db:transaction(function(db) ... end)\`
+  and do not \`pcall\` inside it: a caught error lets the block commit whatever ran.
 - **Standard library.** Loaded standard libraries: base, string, table, math, coroutine, utf8.
   That is the pure-computation set — there is no \`os\`, \`io\`, \`debug\`, or \`package\`/\`require\`,
   and \`dofile\`/\`loadfile\` are removed (string-form \`load\` stays available). Integer division is
@@ -106,9 +114,12 @@ midnight.
   \`Cannot <op>: database is in-memory, file operations are unavailable\`.
 - **Output.** A script can \`return\` one value and the host receives it as JSON — prefer this over
   \`print()\` when you need structured data back (\`print()\` still works and is captured). Only the
-  **first** returned value is encoded. Arrays are 1-indexed (iterate with \`ipairs\`); reading a NULL
-  yields \`nil\`, writing \`nil\` stores NULL where NULL is accepted (query params, ts rows, file
-  columns, relation targets — but NOT element scalar attributes; see CRUD).
+  **first** returned value is encoded. Arrays are 1-indexed. Iterate with \`ipairs\` only where no
+  NULL can appear: a read of a nullable column (a bulk scalar read, a vector/set inner list, a
+  time-series value column, \`db:read_time_series_row\`) has \`nil\` holes, and \`ipairs\` stops at
+  the first one (see Scalar reads). Reading a NULL yields \`nil\`; writing \`nil\` stores NULL where
+  NULL is accepted (query params except a trailing one, ts rows, group cells, relation targets —
+  but NOT element scalar attributes; see CRUD).
 
   \`\`\`lua
   return { ids = db:read_element_ids("Collection"), total = 3 }
@@ -126,10 +137,10 @@ midnight.
   | any other table            | object, keys sorted; integer keys stringify              |
 
   **A table with holes is an object, not an array.** A bulk read of a nullable column returns
-  \`nil\` holes (see Reading), so \`return db:read_scalar_integers(c, a)\` encodes as
+  \`nil\` holes (see Scalar reads), so \`return db:read_scalar_integers(c, a)\` encodes as
   \`{"1":10,"3":30}\` — not \`[10,null,30]\` — and the keys sort as text (\`"1","11","2"\`). When the
   host needs positional scalar data, return the ids alongside and fill the holes yourself:
-  \`local v = db:read_scalar_integers(c, a); local out = {}; for i in ipairs(ids) do out[i] = v[i] or false end\`.
+  \`local ids = db:read_element_ids(c); local v = db:read_scalar_integers(c, a); local out = {}; for i = 1, #ids do out[i] = v[i] or false end\`.
   **Inside** a vector/set read an inner list with an interior NULL cell encodes as an object nested
   in the outer array (\`[{"1":10,"3":30},[]]\`), but a trailing NULL cell leaves no trace at all:
   \`[10, NULL]\` encodes as the plain \`[10]\`. The ids count elements, not rows, so they cannot
@@ -142,8 +153,10 @@ midnight.
   self-referencing table); a result over 64 MB raises
   \`Cannot run: script return value exceeds ... bytes of JSON\`; a string holding bytes that are not
   valid UTF-8 raises \`Cannot run: script return value contains a string that is not valid UTF-8\`;
-  and a table where an integer key and a string key spell the same thing (\`{[1] = 'a', ['1'] = 'b'}\`)
-  raises \`Cannot run: script returned a table with duplicate key '1'\`.
+  a table where an integer key and a string key spell the same thing (\`{[1] = 'a', ['1'] = 'b'}\`)
+  raises \`Cannot run: script returned a table with duplicate key '1'\`; and a table with a key that
+  is neither an integer nor a string (a boolean, a float such as \`1.5\`, a table) raises
+  \`Cannot run: script returned a table with an unsupported key type\`.
 - **Embedding harness may restrict further.** The library itself allows transactions and the
   (sandboxed) CSV/file operations below. A host that runs your script (e.g. a hosted \`run_lua\`
   tool) may disable some of them and report \`disabled in the run_lua sandbox\` — that limit comes
@@ -193,10 +206,12 @@ end)   -- both writes commit together; if either throws, both roll back
 \`\`\`
 
 **Caveat:** if the host already runs your script inside a plain transaction (not a dry run), an
-explicit \`db:begin_transaction()\` will error (\`cannot start a transaction within a transaction\`)
-and a mid-script \`db:commit()\` would prematurely end the host's transaction. When unsure whether
-a transaction is already open, check \`db:in_transaction()\` first, or just issue writes directly —
-each \`db:\` write is durable on its own.
+explicit \`db:begin_transaction()\` will error
+(\`Cannot begin_transaction: transaction already active\`) and a mid-script \`db:commit()\` would
+prematurely end the host's transaction. \`db:transaction(fn)\` begins one too, so it fails the same
+way. When unsure whether a transaction is already open, check \`db:in_transaction()\` first, or just issue writes directly:
+outside a transaction each \`db:\` write commits on its own, while inside the host's transaction it
+commits or rolls back with the host's.
 
 ---
 
@@ -235,6 +250,11 @@ Rules worth knowing:
   \`Cannot begin_dry_run: dry run already active\` — check \`db:in_dry_run()\` first and skip the
   wrapper when one is already active. Do **not** call \`db:end_dry_run()\` to get around it: that
   ends the host's dry run, and everything you write afterwards is committed for real.
+- **Nor inside a plain transaction.** If the host (or a \`db:transaction\` block) already holds a
+  plain transaction, \`db:begin_dry_run()\` and \`db:dry_run(fn)\` throw
+  \`Cannot begin_dry_run: transaction already active\`. \`db:in_transaction()\` is true under a host
+  dry run *and* under a host transaction, so it is the one check that covers both;
+  \`db:in_dry_run()\` covers only the first.
 - For a rough sense of how much a run touched, \`db:query_integer("SELECT total_changes()")\` gives
   the number of rows inserted, updated or deleted on this connection.
 
@@ -293,8 +313,10 @@ Notes:
   \`{ x = nil }\` is identical to \`{}\`; an update/create table that ends up with no attributes
   **throws** (\`...must have at least one scalar attribute\` on create, \`...at least one attribute
   to update\` on update). To leave a column unchanged, omit the key — you cannot set a scalar to
-  NULL via the element table. (\`nil\` → NULL is only accepted by
-  \`upsert_time_series_row\`, \`update_time_series_files\` and \`update_relation\`.)
+  NULL via the element table. (\`nil\` → NULL is accepted by \`update_relation\` and in query params
+  (not a trailing one), and as a cell in the group writers; \`upsert_time_series_row\` and
+  \`update_time_series_files\` replace the whole row, so a column you leave out (or set to \`nil\`,
+  the same thing) is cleared — see Time series and Time series files.)
 - **\`update_relation\` points one scalar foreign-key relation at another element**, named by the
   target's label. The column is derived from the naming convention —
   \`lowercase(collection_to) .. "_" .. relation_type\`, so
@@ -311,7 +333,10 @@ Notes:
 
 ## Scalar reads (bulk, across all elements)
 
-Each returns a flat array (1-indexed table), one value per element, in id order.
+Each returns a flat array (1-indexed table), one value per element, in id order. A NULL is a
+\`nil\` hole at that position, so \`ipairs\` stops at the first one and \`#\` is unreliable. Loop
+\`for i = 1, #ids\` over \`local ids = db:read_element_ids(collection)\` and index the result with
+\`i\`.
 
 \`\`\`lua
 db:read_scalar_integers(collection, attribute)   -- { 42, 37, ... }
@@ -432,9 +457,10 @@ local values = db:read_time_series_row(collection, group, attribute, date_time)
 \`\`\`
 
 One value per element using **last non-null value at or before \`date_time\`** semantics. Elements
-with no matching data yield \`nil\` in the array. \`date_time\` is an ISO 8601 string. A group with
-more than one dimension column (e.g. \`date_time\` + \`block\`) throws — read it with
-\`read_time_series_group\`.
+with no matching data yield \`nil\` in the array, so the result can hold \`nil\` holes: loop over
+\`db:read_element_ids(collection)\` rather than using \`ipairs\`. \`date_time\` is an ISO 8601
+string. A group with more than one dimension column (e.g. \`date_time\` + \`block\`) throws — read
+it with \`read_time_series_group\`.
 
 ### Replace a whole group (column-oriented — SAME shape as the read)
 
@@ -463,10 +489,10 @@ db:update_time_series_group("Items", "data", id, ts)   -- write the whole group
 
 **DO NOT pass an array of row tables** (\`{ { date_time = ..., value = ... }, ... }\`) — that is the
 \`upsert_time_series_row\` shape, not this one. Doing so raises
-\`stack index -1, expected string, received number\` (the integer array indices 1, 2, 3 are not
-column names). Each value of the top-level table must be an **array**, not a scalar.
+\`Cannot update_time_series_group: column names must be strings; pass { column = { values... } }, not an array of row tables\`.
+Each value of the top-level table must be an **array**, not a scalar.
 
-**Rules** (validation throws, rolling the script back):
+**Rules** (a violation throws; see "Errors abort the script" for what is kept):
 - Every column value must be an array — a bare scalar throws \`column '...' must be an array of values\`.
 - The **dimension column(s) set the row count** and must be present and fully populated: the
   \`date_*\` ordering column, plus any extra primary-key columns in a multi-dimensional group (e.g.
@@ -478,8 +504,9 @@ column names). Each value of the top-level table must be an **array**, not a sca
   column **longer** than the dimension column throws \`column '...' has length N but expected M\`.
 - Named columns whose dimension transposes to zero rows throw (\`contain no rows; pass an empty
   table {} to clear the group\`) — only a bare \`{}\` clears.
-- Integer values are accepted for REAL columns (converted on insert). Booleans, functions, and
-  other unsupported Lua types throw \`column '...' has unsupported Lua type\`.
+- Integer values are accepted for REAL columns (converted on insert), and a boolean is written as
+  1/0. A function, a table or another unsupported Lua type throws
+  \`column '...' has unsupported Lua type\`.
 - The element id must exist; the \`_by_label\` form takes a label in its place, with
   \`update_element_by_label\`'s resolution and miss semantics. Every rule above applies to both.
 
@@ -503,6 +530,10 @@ db:upsert_time_series_row_by_label("Items", "data", "Item 1", {
 The element id must exist; the \`_by_label\` form takes a label in its place, with
 \`update_element_by_label\`'s resolution and miss semantics.
 
+An existing row with the same dimension key is **replaced whole**: every value column you leave
+out (or set to \`nil\`) is reset to NULL (or its DEFAULT). To change one value, pass every value
+column of the row.
+
 ---
 
 ## Time series files
@@ -514,10 +545,15 @@ singleton table):
 db:has_time_series_files(collection)              -- boolean
 db:list_time_series_files_columns(collection)     -- { "data_file", "metadata_file", ... }
 db:read_time_series_files(collection)             -- { data_file = "path", metadata_file = nil, ... }
-db:update_time_series_files(collection, { data_file = "path/to/data.bin", metadata_file = nil })
+db:update_time_series_files(collection, { data_file = "path/to/data.bin" })  -- metadata_file is cleared
 \`\`\`
 
-In \`update_time_series_files\`, a \`nil\` value clears that column.
+\`update_time_series_files\` **replaces the whole row**: every column you do not give a string is
+set to NULL (or to its DEFAULT, if the schema declares one), and in Lua a \`nil\` value and a
+missing key are the same thing. A table with no string values (\`{}\`, or only \`nil\` values)
+changes nothing and clears nothing. A value that is not a string throws. To change one path, read
+the row with \`db:read_time_series_files(collection)\`, change that one entry, and pass the whole
+table back.
 
 ---
 
@@ -575,9 +611,15 @@ entirely.
 ## Query (parameterized SQL)
 
 Positional \`?\` placeholders; \`params\` is an optional 1-indexed array. Each returns the first
-column of the first row as the requested type, or \`nil\` if there is no result. The number of
+column of the first row, or \`nil\` when there is no row, the value is NULL, or it is not already
+the requested type. Only \`query_float\` converts (it widens an INTEGER), so
+\`db:query_string("SELECT COUNT(*) ...")\` and \`db:query_integer("SELECT AVG(x) ...")\` return
+\`nil\`; \`CAST\` in the SQL when unsure (\`SELECT CAST(AVG(x) AS INTEGER)\`). The number of
 \`params\` must match the number of \`?\` placeholders exactly — a mismatch (too few or too many)
-throws rather than binding NULL or ignoring extras.
+throws rather than binding NULL or ignoring extras. A \`nil\` param binds NULL only in a table
+constructor whose last entry is not \`nil\` (\`{ nil, 5 }\`): Lua stores no key for a \`nil\`, so
+\`{ 5, nil }\` or \`{ nil }\` comes up short and throws that mismatch. To test for NULL, write
+\`IS NULL\` in the SQL.
 
 \`\`\`lua
 db:query_string(sql, params)    -- string or nil
@@ -599,9 +641,22 @@ local count = db:query_integer("SELECT COUNT(*) FROM Collection")
 
 ## CSV import / export
 
-Export a time-series group to a CSV file, or import one from a CSV file. \`path\` is sandboxed:
-relative paths resolve against the database file's directory and must stay inside it (see
-Critical rules); \`options\` is optional.
+Export one table of \`collection\` to a CSV file, or import one from a CSV file. \`group\` names a
+vector, set or time-series group of \`collection\`; pass \`""\` for the collection's own scalar table
+(the CSV then holds exactly the table's columns except \`id\`, \`label\` included). \`path\` is
+sandboxed: relative paths resolve against the database file's directory and must stay inside it
+(see Critical rules); \`options\` is optional.
+
+**\`db:import_csv\` replaces, it does not merge.** A group import deletes every existing row of
+that group, for every element, not only the elements named in the file, and then inserts the
+file's rows. A scalar import (\`group = ""\`) matches elements by exact label. An element whose
+label is in the file keeps its id and has every column overwritten from the file (a blank cell
+writes NULL). **Every element whose label is not in the file is deleted** as
+\`db:delete_element\` would delete it: its group rows go with it, and every relation pointing at
+it from another table follows its \`ON DELETE\` action (\`SET NULL\` clears it, \`CASCADE\`
+deletes the row that holds it, a group row or an element of another collection). So editing a
+label in the file deletes that element and creates a new one. A header-only CSV empties the
+table. To add or change a few elements, use \`db:create_element\` / \`db:update_element\` instead.
 
 \`\`\`lua
 db:export_csv(collection, group, path, options)
@@ -612,7 +667,7 @@ The optional \`options\` table has two keys:
 
 \`\`\`lua
 {
-    date_time_format = "%Y-%m-%d",   -- strftime-style format for the dimension column
+    date_time_format = "%Y-%m-%d",   -- strftime-style format for every date-time column
 
     -- enum_labels: write/read integer codes as human labels. Three nested levels:
     --   attribute name -> locale -> { label = integer_id }
@@ -625,6 +680,9 @@ The optional \`options\` table has two keys:
 }
 \`\`\`
 
+An options value that is not a table, an unknown key or a wrong-typed value throws
+(\`Cannot export_csv: unknown option '...'\`).
+
 **Precondition:** \`db:import_csv\` cannot run inside an open transaction (it opens and commits its
 own) — it throws \`Cannot import_csv: transaction already active\`. Call it outside any
 \`db:transaction\` / \`db:begin_transaction\` block.
@@ -812,7 +870,9 @@ File I/O is db-scoped (\`db:open_file\` / \`db:bin_to_csv\` / \`db:csv_to_bin\`)
 base paths, sandboxed to the database directory (see Critical rules), and \`get_file_path()\` returns
 the resolved absolute path. The pure-metadata builders and expression constructors live under the
 global \`quiver\` table. Mirrors the Julia surface; aggregation ops are strings (Lua has no enums);
-operators are \`+ - * /\` and unary \`-\`, with scalars allowed on either side.
+operators are \`+ - * /\` and unary \`-\`, with scalars allowed on either side. A file handle does not
+outlive the \`run()\` that opened it: any handle still open when the script returns is closed (and a
+writer flushed), so reopen the file in each script.
 
 \`\`\`lua
 local md = quiver.metadata{
@@ -847,7 +907,8 @@ e:save(out_path); e:metadata()                       -- save path is sandboxed l
 
 **\`quiver.metadata{...}\` kwargs and defaults:** \`version\` defaults to \`"1"\`; \`initial_datetime\`
 and \`unit\` default to \`""\`; \`labels\`, \`dimensions\`, \`dimension_sizes\`, \`time_dimensions\`, and
-\`frequencies\` default to empty arrays.
+\`frequencies\` default to empty arrays. Only these eight keys are accepted; an unknown key or a
+value of the wrong type throws.
 
 **\`get_dimensions()\` / \`get_metadata()\` dimension shape** — returns an array of dimension tables:
 

package/src/query.ts

@@ -50,6 +50,11 @@ function marshalParams(parameters?: QueryParam[]): {
       const native = allocNativeInt64([p ? 1 : 0]);
       keepalive.push(native);
       valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
+    } else if (typeof p === "bigint") {
+      typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
+      const native = allocNativeInt64([p]);
+      keepalive.push(native);
+      valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
     } else if (typeof p === "number") {
       if (Number.isInteger(p)) {
         typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);

package/src/types.ts

@@ -26,7 +26,8 @@ export type ScalarValue = number | bigint | boolean | string | null;
 export type ArrayValue = number[] | bigint[] | boolean[] | string[];
 export type Value = ScalarValue | ArrayValue;
 export type ElementData = Record<string, Value | undefined>;
-export type QueryParam = number | boolean | string | null;
+/** A `bigint` binds as an exact INTEGER; a `boolean` as INTEGER 1/0. */
+export type QueryParam = number | bigint | boolean | string | null;
 
 /** Native memory allocation result. Callers MUST hold `buf` in scope to prevent GC. */
 export type Allocation = {