quiverdb 0.12.3 → 0.12.4

package/package.json

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

package/src/composites.ts

@@ -39,9 +39,9 @@ Database.prototype.readVectorsById = function (
   this: Database,
   collection: string,
   id: number,
-): Record<string, number[] | string[]> {
+): Record<string, (number | null)[] | (string | null)[]> {
   const groups = this.listVectorGroups(collection);
-  const result: Record<string, number[] | string[]> = {};
+  const result: Record<string, (number | null)[] | (string | null)[]> = {};
 
   for (const group of groups) {
     for (const col of group.valueColumns) {
@@ -69,9 +69,9 @@ Database.prototype.readSetsById = function (
   this: Database,
   collection: string,
   id: number,
-): Record<string, number[] | string[]> {
+): Record<string, (number | null)[] | (string | null)[]> {
   const groups = this.listSetGroups(collection);
-  const result: Record<string, number[] | string[]> = {};
+  const result: Record<string, (number | null)[] | (string | null)[]> = {};
 
   for (const group of groups) {
     for (const col of group.valueColumns) {

package/src/create.ts

@@ -29,6 +29,15 @@ function setElementArray(
 
   const first = values[0];
 
+  // A vector/set read returns a NULL cell as null. The element surface is non-null (NULL cells go
+  // through updateVectorGroup / updateSetGroup), and the numeric setters below would store a null
+  // as 0 / false. A string array keeps its NULL-pointer path, which the C setter reads as NULL.
+  if (typeof first !== "string" && values.some((v) => v === null || v === undefined)) {
+    throw new QuiverError(
+      `Unsupported null cell in array '${name}': write NULL cells with updateVectorGroup or updateSetGroup`,
+    );
+  }
+
   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));

package/src/database.ts

@@ -138,22 +138,54 @@ export class Database {
   ) => string | null;
   declare readElementIds: (collection: string) => number[];
   declare numberOfElements: (collection: string) => number;
-  declare readVectorIntegers: (collection: string, attribute: string) => number[][];
-  declare readVectorBooleans: (collection: string, attribute: string) => boolean[][];
-  declare readVectorFloats: (collection: string, attribute: string) => number[][];
-  declare readVectorStrings: (collection: string, attribute: string) => string[][];
-  declare readVectorIntegersById: (collection: string, attribute: string, id: number) => number[];
-  declare readVectorBooleansById: (collection: string, attribute: string, id: number) => boolean[];
-  declare readVectorFloatsById: (collection: string, attribute: string, id: number) => number[];
-  declare readVectorStringsById: (collection: string, attribute: string, id: number) => string[];
-  declare readSetIntegers: (collection: string, attribute: string) => number[][];
-  declare readSetBooleans: (collection: string, attribute: string) => boolean[][];
-  declare readSetFloats: (collection: string, attribute: string) => number[][];
-  declare readSetStrings: (collection: string, attribute: string) => string[][];
-  declare readSetIntegersById: (collection: string, attribute: string, id: number) => number[];
-  declare readSetBooleansById: (collection: string, attribute: string, id: number) => boolean[];
-  declare readSetFloatsById: (collection: string, attribute: string, id: number) => number[];
-  declare readSetStringsById: (collection: string, attribute: string, id: number) => string[];
+  declare readVectorIntegers: (collection: string, attribute: string) => (number | null)[][];
+  declare readVectorBooleans: (collection: string, attribute: string) => (boolean | null)[][];
+  declare readVectorFloats: (collection: string, attribute: string) => (number | null)[][];
+  declare readVectorStrings: (collection: string, attribute: string) => (string | null)[][];
+  declare readVectorIntegersById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (number | null)[];
+  declare readVectorBooleansById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (boolean | null)[];
+  declare readVectorFloatsById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (number | null)[];
+  declare readVectorStringsById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (string | null)[];
+  declare readSetIntegers: (collection: string, attribute: string) => (number | null)[][];
+  declare readSetBooleans: (collection: string, attribute: string) => (boolean | null)[][];
+  declare readSetFloats: (collection: string, attribute: string) => (number | null)[][];
+  declare readSetStrings: (collection: string, attribute: string) => (string | null)[][];
+  declare readSetIntegersById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (number | null)[];
+  declare readSetBooleansById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (boolean | null)[];
+  declare readSetFloatsById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (number | null)[];
+  declare readSetStringsById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => (string | null)[];
 
   // --- Queries (implemented in query.ts) ---
   declare queryString: (sql: string, parameters?: QueryParam[]) => string | null;
@@ -268,6 +300,12 @@ export class Database {
     collection: string,
     id: number,
   ) => Record<string, number | string | null>;
-  declare readVectorsById: (collection: string, id: number) => Record<string, number[] | string[]>;
-  declare readSetsById: (collection: string, id: number) => Record<string, number[] | string[]>;
+  declare readVectorsById: (
+    collection: string,
+    id: number,
+  ) => Record<string, (number | null)[] | (string | null)[]>;
+  declare readSetsById: (
+    collection: string,
+    id: number,
+  ) => Record<string, (number | null)[] | (string | null)[]>;
 }

package/src/loader.ts

@@ -73,17 +73,17 @@ const readSymbols = {
   quiver_database_read_scalar_integer_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
   quiver_database_read_scalar_float_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
   quiver_database_read_scalar_string_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
-  quiver_database_read_vector_integers: { args: [P, BUF, BUF, P, P, P], returns: I32 },
-  quiver_database_read_vector_floats: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_vector_integers: { args: [P, BUF, BUF, P, P, P, P], returns: I32 },
+  quiver_database_read_vector_floats: { args: [P, BUF, BUF, P, P, P, P], returns: I32 },
   quiver_database_read_vector_strings: { args: [P, BUF, BUF, P, P, P], returns: I32 },
-  quiver_database_read_set_integers: { args: [P, BUF, BUF, P, P, P], returns: I32 },
-  quiver_database_read_set_floats: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_set_integers: { args: [P, BUF, BUF, P, P, P, P], returns: I32 },
+  quiver_database_read_set_floats: { args: [P, BUF, BUF, P, P, P, P], returns: I32 },
   quiver_database_read_set_strings: { args: [P, BUF, BUF, P, P, P], returns: I32 },
-  quiver_database_read_vector_integers_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
-  quiver_database_read_vector_floats_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_vector_integers_by_id: { args: [P, BUF, BUF, I64, P, P, P], returns: I32 },
+  quiver_database_read_vector_floats_by_id: { args: [P, BUF, BUF, I64, P, P, P], returns: I32 },
   quiver_database_read_vector_strings_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
-  quiver_database_read_set_integers_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
-  quiver_database_read_set_floats_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_set_integers_by_id: { args: [P, BUF, BUF, I64, P, P, P], returns: I32 },
+  quiver_database_read_set_floats_by_id: { args: [P, BUF, BUF, I64, P, P, P], returns: I32 },
   quiver_database_read_set_strings_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
   quiver_database_read_element_ids: { args: [P, BUF, P, P], returns: I32 },
   quiver_database_number_of_elements: { args: [P, BUF, P], returns: I32 },
@@ -181,6 +181,7 @@ const freeSymbols = {
   quiver_database_free_integer_array: { args: [P], returns: I32 },
   quiver_database_free_float_array: { args: [P], returns: I32 },
   quiver_database_free_mask: { args: [P], returns: I32 },
+  quiver_database_free_masks: { args: [P, USIZE], returns: I32 },
   quiver_database_free_string_array: { args: [P, USIZE], returns: I32 },
   quiver_database_free_string: { args: [P], returns: I32 },
   quiver_database_free_integer_vectors: { args: [P, P, USIZE], returns: I32 },

package/src/lua-api.ts

@@ -127,9 +127,14 @@ midnight.
 
   **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
-  \`{"1":10,"3":30}\` — not \`[10,null,30]\` — and the keys sort as text (\`"1","11","2"\`). When the host
-  needs positional data, return the ids alongside and fill the holes yourself:
+  \`{"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\`.
+  **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
+  restore inner positions — take the row count from a \`NOT NULL\` column of the group (see
+  *Vector reads*), or do that read in the host binding.
 
   Returning a function, a coroutine, or a userdata (including \`db\` itself) raises
   \`Cannot run: script returned an unsupported Lua type\`; nesting deeper than 32 levels raises
@@ -280,6 +285,10 @@ Notes:
   \`Cannot update_element: ...\`.
 - **Empty arrays are skipped.** An attribute whose value is \`{}\` writes no vector/set (the element
   type can't be inferred from an empty array), so it is silently dropped.
+- **Arrays must be dense.** A vector/set read returns a NULL cell as a \`nil\` hole, but an element
+  array cannot carry one: \`create_element\` / \`update_element\` throw \`array '<name>' has a nil
+  hole ...\` rather than cut the array short at the hole. Write NULL cells with
+  \`update_vector_group\` / \`update_set_group\`, which write a hole as NULL.
 - **No \`nil\` scalar attributes.** In Lua a key set to \`nil\` is dropped from the table, so
   \`{ 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
@@ -314,10 +323,13 @@ db:read_scalar_strings(collection, attribute)     -- { "Item 1", "Item 2", ... }
 
 ## Vector reads (bulk)
 
-Each returns an array of arrays — one inner array per element.
+Each returns an array of arrays — one inner array per element, aligned with
+\`db:read_element_ids\`; an element with no rows is \`{}\`. A NULL cell is a \`nil\` hole, so on a
+nullable column \`#\` and \`ipairs\` are unreliable on an inner list, and a trailing NULL is
+invisible (\`[10, NULL]\` reads as \`{10}\`; a NULL-only row reads as \`{}\`).
 
 \`\`\`lua
-db:read_vector_integers(collection, attribute)   -- { {1,2,3}, {2,3,4}, ... }
+db:read_vector_integers(collection, attribute)   -- { {1,2,3}, {10,nil,30}, {}, ... }
 db:read_vector_floats(collection, attribute)
 db:read_vector_strings(collection, attribute)
 \`\`\`
@@ -326,7 +338,7 @@ db:read_vector_strings(collection, attribute)
 
 ## Set reads (bulk)
 
-Same shape as vector reads — an array of arrays.
+Same shape and NULL handling as vector reads — an array of arrays with \`nil\` holes.
 
 \`\`\`lua
 db:read_set_integers(collection, attribute)
@@ -358,7 +370,8 @@ rewriting groups you never named. \`(collection, group)\` names exactly one tabl
 
 Rules:
 - **Row count is the largest index any column reaches.** Shorter or sparse columns write NULL in
-  the gaps, so \`nil\` holes from a read round-trip.
+  the gaps, so interior \`nil\` holes from a read round-trip. A trailing row that is NULL in every
+  column is invisible to a read (see *Vector reads*), so writing a read back drops it.
 - **\`{}\` (no columns) clears the group.** Naming a column whose array is empty is an error, not a
   clear — a typo'd column name must not destroy data.
 - **\`id\` and \`vector_index\` are managed by the group** (the element and the row's position) and
@@ -376,20 +389,17 @@ Rules:
 db:read_element_ids(collection)                  -- { 1, 2, 3, ... }
 
 db:read_scalars_by_id(collection, id)            -- { attr = value, ... } (missing -> nil)
-db:read_vectors_by_id(collection, id)            -- { column = { v1, v2, ... }, ... }
-db:read_sets_by_id(collection, id)               -- { column = { v1, v2, ... }, ... }
+db:read_vectors_by_id(collection, id)            -- { column = { v1, nil, v3, ... }, ... }
+db:read_sets_by_id(collection, id)               -- { column = { v1, nil, v3, ... }, ... }
 db:read_element_by_id(collection, id)            -- scalars + vectors + sets merged into one table
 \`\`\`
 
 \`read_element_by_id\` merges every scalar, vector, and set for the element into a single table.
 Scalar attributes with no value come back as \`nil\`.
 
-**Group columns are returned densely, with NULL cells dropped.** \`read_vectors_by_id\` and
-\`read_sets_by_id\` read each column independently, and a column read skips its NULL cells — so two
-columns of the same group are **not** positionally aligned with each other whenever one is
-nullable (e.g. an \`ON DELETE SET NULL\` relation). Do not zip them into rows. There is no
-row-aligned group read in Lua; if you need per-row alignment across a nullable group, do that read
-in the host binding instead.
+**Group columns keep NULL cells as \`nil\` holes**, so cell *i* of every column of one group is
+the same row. Zipping them needs the row count: \`#\` of a \`NOT NULL\` column of the group.
+There is no row-shaped group read in Lua.
 
 ---
 
@@ -856,6 +866,6 @@ and \`unit\` default to \`""\`; \`labels\`, \`dimensions\`, \`dimension_sizes\`,
 DateTime wrapper helpers (Lua uses ISO 8601 strings), boolean *reader* helpers (a stored flag reads
 back as \`0\`/\`1\` — writing a boolean is supported), \`_by_id\` single-scalar variants (use the
 composite by-id readers or the bulk readers instead), and the row-aligned whole-group readers the
-other bindings have (hence the null-dropping caveat under composite by-id reads). Everything else
+other bindings have (hence the row-count caveat under composite by-id reads). Everything else
 the native binding exposes — CRUD, reads, time series, metadata, query, CSV, and the
 binary/expression subsystems — is documented above and callable.`;

package/src/read.ts

@@ -8,7 +8,6 @@ import {
   decodeFloat64Array,
   decodeInt64Array,
   decodePtrArray,
-  decodeStringArray,
   decodeStringFromBuf,
   decodeUint64Array,
   readPtrOut,
@@ -251,10 +250,11 @@ function readBulkIntegers(
   fn: string,
   collection: string,
   attribute: string,
-): number[][] {
+): (number | null)[][] {
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outVectors = allocPtrOut();
+  const outMasks = allocPtrOut();
   const outSizes = allocPtrOut();
   const outCount = allocUint64Out();
   check(
@@ -263,6 +263,7 @@ function readBulkIntegers(
       collBuf.buf,
       attrBuf.buf,
       outVectors.buf,
+      outMasks.buf,
       outSizes.buf,
       outCount.buf,
     ),
@@ -270,14 +271,23 @@ function readBulkIntegers(
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const vectorsPtr = readPtrOut(outVectors);
+  const masksPtr = readPtrOut(outMasks);
   const sizesPtr = readPtrOut(outSizes);
   const vectorPtrs = decodePtrArray(vectorsPtr, count);
+  const maskPtrs = decodePtrArray(masksPtr, count);
   const sizes = decodeUint64Array(sizesPtr, count);
-  const result: number[][] = new Array(count);
+  const result: (number | null)[][] = new Array(count);
   for (let i = 0; i < count; i++) {
-    result[i] = sizes[i] === 0 ? [] : decodeInt64Array(vectorPtrs[i], sizes[i]);
+    if (sizes[i] === 0) {
+      result[i] = [];
+      continue;
+    }
+    const values = decodeInt64Array(vectorPtrs[i], sizes[i]);
+    const mask = new Uint8Array(toArrayBuffer(maskPtrs[i] as Pointer, 0, sizes[i]));
+    result[i] = values.map((v, j) => (mask[j] ? v : null));
   }
   lib.quiver_database_free_integer_vectors(vectorsPtr, sizesPtr, BigInt(count));
+  lib.quiver_database_free_masks(masksPtr, BigInt(count));
   return result;
 }
 
@@ -287,10 +297,11 @@ function readBulkFloats(
   fn: string,
   collection: string,
   attribute: string,
-): number[][] {
+): (number | null)[][] {
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outVectors = allocPtrOut();
+  const outMasks = allocPtrOut();
   const outSizes = allocPtrOut();
   const outCount = allocUint64Out();
   check(
@@ -299,6 +310,7 @@ function readBulkFloats(
       collBuf.buf,
       attrBuf.buf,
       outVectors.buf,
+      outMasks.buf,
       outSizes.buf,
       outCount.buf,
     ),
@@ -306,14 +318,23 @@ function readBulkFloats(
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const vectorsPtr = readPtrOut(outVectors);
+  const masksPtr = readPtrOut(outMasks);
   const sizesPtr = readPtrOut(outSizes);
   const vectorPtrs = decodePtrArray(vectorsPtr, count);
+  const maskPtrs = decodePtrArray(masksPtr, count);
   const sizes = decodeUint64Array(sizesPtr, count);
-  const result: number[][] = new Array(count);
+  const result: (number | null)[][] = new Array(count);
   for (let i = 0; i < count; i++) {
-    result[i] = sizes[i] === 0 ? [] : decodeFloat64Array(vectorPtrs[i], sizes[i]);
+    if (sizes[i] === 0) {
+      result[i] = [];
+      continue;
+    }
+    const values = decodeFloat64Array(vectorPtrs[i], sizes[i]);
+    const mask = new Uint8Array(toArrayBuffer(maskPtrs[i] as Pointer, 0, sizes[i]));
+    result[i] = values.map((v, j) => (mask[j] ? v : null));
   }
   lib.quiver_database_free_float_vectors(vectorsPtr, sizesPtr, BigInt(count));
+  lib.quiver_database_free_masks(masksPtr, BigInt(count));
   return result;
 }
 
@@ -323,7 +344,7 @@ function readBulkStrings(
   fn: string,
   collection: string,
   attribute: string,
-): string[][] {
+): (string | null)[][] {
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outVectors = allocPtrOut();
@@ -345,9 +366,16 @@ function readBulkStrings(
   const sizesPtr = readPtrOut(outSizes);
   const vectorPtrs = decodePtrArray(vectorsPtr, count);
   const sizes = decodeUint64Array(sizesPtr, count);
-  const result: string[][] = new Array(count);
+  const result: (string | null)[][] = new Array(count);
   for (let i = 0; i < count; i++) {
-    result[i] = sizes[i] === 0 ? [] : decodeStringArray(vectorPtrs[i], sizes[i]);
+    // A NULL cell is a NULL char* entry, so decode the pointer array and map NULL -> null
+    // (decodeStringArray would construct "" from a NULL pointer instead).
+    result[i] =
+      sizes[i] === 0
+        ? []
+        : decodePtrArray(vectorPtrs[i], sizes[i]).map((cell) =>
+            cell === null ? null : new CString(cell).toString(),
+          );
   }
   lib.quiver_database_free_string_vectors(vectorsPtr, sizesPtr, BigInt(count));
   return result;
@@ -357,7 +385,7 @@ Database.prototype.readVectorIntegers = function (
   this: Database,
   collection: string,
   attribute: string,
-): number[][] {
+): (number | null)[][] {
   return readBulkIntegers(
     getSymbols(),
     this._handle,
@@ -366,15 +394,12 @@ Database.prototype.readVectorIntegers = function (
     attribute,
   );
 };
-/**
- * NULL cells are dropped and only elements that own rows are returned, so the result is not
- * positionally aligned with `readElementIds` (unlike `readScalarBooleans`).
- */
+/** One entry per element; within an entry a SQL NULL cell is `null`. */
 Database.prototype.readVectorBooleans = function (
   this: Database,
   collection: string,
   attribute: string,
-): boolean[][] {
+): (boolean | null)[][] {
   return this.readVectorIntegers(collection, attribute).map((values) =>
     values.map((value) => integerToBoolean(value, collection, attribute)),
   );
@@ -383,7 +408,7 @@ Database.prototype.readVectorFloats = function (
   this: Database,
   collection: string,
   attribute: string,
-): number[][] {
+): (number | null)[][] {
   return readBulkFloats(
     getSymbols(),
     this._handle,
@@ -396,7 +421,7 @@ Database.prototype.readVectorStrings = function (
   this: Database,
   collection: string,
   attribute: string,
-): string[][] {
+): (string | null)[][] {
   return readBulkStrings(
     getSymbols(),
     this._handle,
@@ -409,7 +434,7 @@ Database.prototype.readSetIntegers = function (
   this: Database,
   collection: string,
   attribute: string,
-): number[][] {
+): (number | null)[][] {
   return readBulkIntegers(
     getSymbols(),
     this._handle,
@@ -418,12 +443,12 @@ Database.prototype.readSetIntegers = function (
     attribute,
   );
 };
-/** Same alignment caveat as `readVectorBooleans`: NULL cells dropped, only ids that own rows. */
+/** Same contract as `readVectorBooleans`: one entry per element, and a NULL cell is `null`. */
 Database.prototype.readSetBooleans = function (
   this: Database,
   collection: string,
   attribute: string,
-): boolean[][] {
+): (boolean | null)[][] {
   return this.readSetIntegers(collection, attribute).map((values) =>
     values.map((value) => integerToBoolean(value, collection, attribute)),
   );
@@ -432,7 +457,7 @@ Database.prototype.readSetFloats = function (
   this: Database,
   collection: string,
   attribute: string,
-): number[][] {
+): (number | null)[][] {
   return readBulkFloats(
     getSymbols(),
     this._handle,
@@ -445,7 +470,7 @@ Database.prototype.readSetStrings = function (
   this: Database,
   collection: string,
   attribute: string,
-): string[][] {
+): (string | null)[][] {
   return readBulkStrings(
     getSymbols(),
     this._handle,
@@ -464,10 +489,11 @@ function readByIdIntegers(
   collection: string,
   attribute: string,
   id: number,
-): number[] {
+): (number | null)[] {
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValues = allocPtrOut();
+  const outMask = allocPtrOut();
   const outCount = allocUint64Out();
   check(
     (lib as Record<string, Function>)[fn](
@@ -476,14 +502,19 @@ function readByIdIntegers(
       attrBuf.buf,
       BigInt(id),
       outValues.buf,
+      outMask.buf,
       outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outValues);
-  const result = decodeInt64Array(arrPtr, count);
+  const maskPtr = readPtrOut(outMask);
+  const values = decodeInt64Array(arrPtr, count);
+  const mask = new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, count));
+  const result = values.map((v, i) => (mask[i] ? v : null));
   lib.quiver_database_free_integer_array(arrPtr);
+  lib.quiver_database_free_mask(maskPtr);
   return result;
 }
 
@@ -494,10 +525,11 @@ function readByIdFloats(
   collection: string,
   attribute: string,
   id: number,
-): number[] {
+): (number | null)[] {
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValues = allocPtrOut();
+  const outMask = allocPtrOut();
   const outCount = allocUint64Out();
   check(
     (lib as Record<string, Function>)[fn](
@@ -506,14 +538,19 @@ function readByIdFloats(
       attrBuf.buf,
       BigInt(id),
       outValues.buf,
+      outMask.buf,
       outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outValues);
-  const result = decodeFloat64Array(arrPtr, count);
+  const maskPtr = readPtrOut(outMask);
+  const values = decodeFloat64Array(arrPtr, count);
+  const mask = new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, count));
+  const result = values.map((v, i) => (mask[i] ? v : null));
   lib.quiver_database_free_float_array(arrPtr);
+  lib.quiver_database_free_mask(maskPtr);
   return result;
 }
 
@@ -524,7 +561,7 @@ function readByIdStrings(
   collection: string,
   attribute: string,
   id: number,
-): string[] {
+): (string | null)[] {
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValues = allocPtrOut();
@@ -542,7 +579,11 @@ function readByIdStrings(
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outValues);
-  const result = decodeStringArray(arrPtr, count);
+  // A NULL cell is a NULL char* entry, so decode the pointer array and map NULL -> null
+  // (decodeStringArray would construct "" from a NULL pointer instead).
+  const result = decodePtrArray(arrPtr, count).map((cell) =>
+    cell === null ? null : new CString(cell).toString(),
+  );
   lib.quiver_database_free_string_array(arrPtr, BigInt(count));
   return result;
 }
@@ -552,7 +593,7 @@ Database.prototype.readVectorIntegersById = function (
   collection: string,
   attribute: string,
   id: number,
-): number[] {
+): (number | null)[] {
   return readByIdIntegers(
     getSymbols(),
     this._handle,
@@ -567,7 +608,7 @@ Database.prototype.readVectorBooleansById = function (
   collection: string,
   attribute: string,
   id: number,
-): boolean[] {
+): (boolean | null)[] {
   return this.readVectorIntegersById(collection, attribute, id).map((value) =>
     integerToBoolean(value, collection, attribute),
   );
@@ -577,7 +618,7 @@ Database.prototype.readVectorFloatsById = function (
   collection: string,
   attribute: string,
   id: number,
-): number[] {
+): (number | null)[] {
   return readByIdFloats(
     getSymbols(),
     this._handle,
@@ -592,7 +633,7 @@ Database.prototype.readVectorStringsById = function (
   collection: string,
   attribute: string,
   id: number,
-): string[] {
+): (string | null)[] {
   return readByIdStrings(
     getSymbols(),
     this._handle,
@@ -607,7 +648,7 @@ Database.prototype.readSetIntegersById = function (
   collection: string,
   attribute: string,
   id: number,
-): number[] {
+): (number | null)[] {
   return readByIdIntegers(
     getSymbols(),
     this._handle,
@@ -622,7 +663,7 @@ Database.prototype.readSetBooleansById = function (
   collection: string,
   attribute: string,
   id: number,
-): boolean[] {
+): (boolean | null)[] {
   return this.readSetIntegersById(collection, attribute, id).map((value) =>
     integerToBoolean(value, collection, attribute),
   );
@@ -632,7 +673,7 @@ Database.prototype.readSetFloatsById = function (
   collection: string,
   attribute: string,
   id: number,
-): number[] {
+): (number | null)[] {
   return readByIdFloats(
     getSymbols(),
     this._handle,
@@ -647,7 +688,7 @@ Database.prototype.readSetStringsById = function (
   collection: string,
   attribute: string,
   id: number,
-): string[] {
+): (string | null)[] {
   return readByIdStrings(
     getSymbols(),
     this._handle,