@nshiab/simple-data-analysis-core 2.1.2 → 2.1.4

package/esm/methods/similarityMahalanobis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarityMahalanobis.d.ts","sourceRoot":"","sources":["../../src/methods/similarityMahalanobis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AASvD,KAAK,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhF,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,cAAc,EAAE,MAAM,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EACrD,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,OAAY,GACpB,IAAI,CAsDN"}

package/esm/methods/{mahalanobis.js → similarityMahalanobis.js}

@@ -5,17 +5,34 @@ import prepareNumericFeatures from "../helpers/prepareNumericFeatures.js";
 import publishPreparedColumns from "../helpers/publishPreparedColumns.js";
 import queueOp from "../helpers/queueOp.js";
 import quoteIdentifier from "../helpers/quoteIdentifier.js";
-export default function mahalanobis(table, columns, referencePoint, newColumn, options = {}) {
+export default function similarityMahalanobis(table, columns, referencePoint, newColumn, options = {}) {
+    const selected = typeof columns === "string" ? columns : [...columns];
+    if (!Array.isArray(referencePoint) && referencePoint !== null &&
+        typeof referencePoint === "object") {
+        if (typeof selected === "string") {
+            throw new Error("similarityMahalanobis() an object referencePoint requires an array of scalar feature column names; use a numeric array for a vector column.");
+        }
+        const referenceObject = referencePoint;
+        referencePoint = selected.map((column) => {
+            if (!Object.hasOwn(referenceObject, column)) {
+                throw new Error(`similarityMahalanobis() referencePoint is missing its own value for feature ${quoteIdentifier(column)}.`);
+            }
+            const value = referenceObject[column];
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                throw new Error(`similarityMahalanobis() referencePoint feature ${quoteIdentifier(column)} must be a finite number.`);
+            }
+            return value;
+        });
+    }
     if (!Array.isArray(referencePoint) || referencePoint.length === 0 ||
         Array.from(referencePoint).some((value) => typeof value !== "number" || !Number.isFinite(value))) {
-        throw new Error("mahalanobis() referencePoint must be a nonempty array of finite numbers in feature-dimension order.");
+        throw new Error("similarityMahalanobis() referencePoint must be a nonempty array of finite numbers in feature-dimension order.");
     }
-    const selected = typeof columns === "string" ? columns : [...columns];
     const reference = [...referencePoint];
     const settings = { ...options };
     queueOp(table, {
         kind: "barrier",
-        method: "mahalanobis()",
+        method: "similarityMahalanobis()",
         parameters: {
             columns: selected,
             referencePoint: reference,
@@ -27,29 +44,34 @@ export default function mahalanobis(table, columns, referencePoint, newColumn, o
 }
 async function execute(table, columns, referencePoint, newColumn, options) {
     const sourceColumns = Object.keys(await table.getTypes());
-    const outputNames = options.similarityScoreColumn === undefined
+    const scoreColumn = options.similarityScoreColumn === true
+        ? "similarity"
+        : options.similarityScoreColumn === false
+            ? undefined
+            : options.similarityScoreColumn;
+    const outputNames = scoreColumn === undefined
         ? [newColumn]
-        : [newColumn, options.similarityScoreColumn];
+        : [newColumn, scoreColumn];
     const seen = new Set();
     for (const name of outputNames) {
         if (typeof name !== "string" || name.length === 0 || name.includes("\0")) {
-            throw new Error("mahalanobis() output column names must be nonempty strings without null characters.");
+            throw new Error("similarityMahalanobis() output column names must be nonempty strings without null characters.");
         }
         const folded = foldIdentifier(name);
         if (seen.has(folded)) {
-            throw new Error("mahalanobis() distance and similarity score columns must have different names (case-insensitive).");
+            throw new Error("similarityMahalanobis() distance and similarity score columns must have different names (case-insensitive).");
         }
         seen.add(folded);
         if (sourceColumns.some((column) => foldIdentifier(column) === folded)) {
-            throw new Error(`mahalanobis() cannot create ${quoteIdentifier(name)} because that column already exists. Remove it first or choose a different name.`);
+            throw new Error(`similarityMahalanobis() cannot create ${quoteIdentifier(name)} because that column already exists. Remove it first or choose a different name.`);
         }
     }
     const prepared = await prepareNumericFeatures(table, typeof columns === "string"
         ? { kind: "vector", column: columns }
-        : { kind: "scalars", columns }, { method: "mahalanobis()" });
+        : { kind: "scalars", columns }, { method: "similarityMahalanobis()" });
     try {
         if (referencePoint.length !== prepared.dimensions) {
-            throw new Error(`mahalanobis() referencePoint must contain ${prepared.dimensions} values in feature-dimension order; received ${referencePoint.length}.`);
+            throw new Error(`similarityMahalanobis() referencePoint must contain ${prepared.dimensions} values in feature-dimension order; received ${referencePoint.length}.`);
         }
         const model = await computeCovariance(table.connection, {
             relation: prepared.relation,
@@ -66,14 +88,14 @@ async function execute(table, columns, referencePoint, newColumn, options) {
         try {
             const distance = `r.${quoteIdentifier(distances.distanceColumn)}`;
             const outputs = [{ name: newColumn, expression: distance }];
-            if (options.similarityScoreColumn !== undefined) {
+            if (scoreColumn !== undefined) {
                 outputs.push({
-                    name: options.similarityScoreColumn,
+                    name: scoreColumn,
                     expression: `CASE WHEN max(${distance}) OVER () = 0 THEN 1::DOUBLE ELSE 1 - ${distance} / max(${distance}) OVER () END`,
                 });
             }
             await publishPreparedColumns(table, prepared, {
-                method: "mahalanobis()",
+                method: "similarityMahalanobis()",
                 parameters: { columns, referencePoint, newColumn, options },
                 result: {
                     relation: distances.relation,

package/esm/methods/updateWithJS.js

@@ -60,6 +60,7 @@ async function executeUpdateWithJS(simpleTable, dataModifier, options) {
     const accumulator = `updateWithJS_accumulator_${suffix}`;
     try {
         let first = true;
+        let accumulatorSchema;
         let lastRowid = null;
         let sawRows = false;
         let outputOffset = 0;
@@ -131,9 +132,17 @@ async function executeUpdateWithJS(simpleTable, dataModifier, options) {
                 ? parseDuckDBType("VARCHAR")
                 : source.types.get(key) ??
                     parseDuckDBType(added.types[newKeys.indexOf(key)]));
-            await simpleTable.sdb.customQuery(`CREATE OR REPLACE TABLE ${quoteIdentifier(scratch.name)} (${keys.map((key, i) => `${quoteIdentifier(key)} ${columnTypes[i]}`)
-                .join(", ")})`);
-            await appendColumnBatches(simpleTable.connection, scratch.name, columnTypes, modified.length, (column, start, end) => {
+            const schema = JSON.stringify(keys.map((key, i) => [key, columnTypes[i].toString()]));
+            // Append matching native batches directly. SQL still handles conversion
+            // and BY NAME alignment when a callback changes the batch schema.
+            const direct = outputGeometry.length === 0 && outputJSON.length === 0 &&
+                (first || schema === accumulatorSchema);
+            const destination = direct ? accumulator : scratch.name;
+            if (!direct || first) {
+                await simpleTable.sdb.customQuery(`CREATE OR REPLACE TABLE ${quoteIdentifier(destination)} (${keys.map((key, i) => `${quoteIdentifier(key)} ${columnTypes[i]}`)
+                    .join(", ")})`);
+            }
+            await appendColumnBatches(simpleTable.connection, destination, columnTypes, modified.length, (column, start, end) => {
                 const key = keys[column];
                 return outputGeometry.includes(key)
                     ? geometryData.get(key).slice(start, end)
@@ -146,7 +155,11 @@ async function executeUpdateWithJS(simpleTable, dataModifier, options) {
                 : outputJSON.includes(key)
                     ? `${quoteIdentifier(key)}::JSON AS ${quoteIdentifier(key)}`
                     : quoteIdentifier(key)).join(", ");
-            if (first) {
+            if (direct) {
+                accumulatorSchema = schema;
+                first = false;
+            }
+            else if (first) {
                 await simpleTable.sdb.customQuery(`CREATE OR REPLACE TABLE ${quoteIdentifier(accumulator)} AS SELECT ${projection} FROM ${quoteIdentifier(scratch.name)}`);
                 first = false;
             }
@@ -159,7 +172,13 @@ async function executeUpdateWithJS(simpleTable, dataModifier, options) {
         if (first) {
             throw new Error("The dataModifier returned no rows. updateWithJS can't infer the table schema from zero rows.");
         }
-        await simpleTable.sdb.customQuery(`CREATE OR REPLACE TABLE ${quoteIdentifier(simpleTable.name)} AS SELECT * FROM ${quoteIdentifier(accumulator)}`);
+        // Publish the completed ordinary table without copying its rows again.
+        // Qualify the creation namespace: a temporary table or a later search-path
+        // schema can shadow the name without being the destination of replacement.
+        const namespace = await simpleTable.connection.runAndReadAll("SELECT current_database(), current_schema()");
+        const prefix = namespace.getRows()[0].map((name) => quoteIdentifier(String(name))).join(".");
+        await simpleTable.sdb.customQuery(`DROP TABLE IF EXISTS ${prefix}.${quoteIdentifier(simpleTable.name)};
+ALTER TABLE ${prefix}.${quoteIdentifier(accumulator)} RENAME TO ${quoteIdentifier(simpleTable.name)};`);
     }
     finally {
         await simpleTable.sdb.customQuery(`DROP TABLE IF EXISTS ${quoteIdentifier(accumulator)};

package/llm.md

@@ -1,7 +1,7 @@
 # The Simple Data Analysis (Core) Library
 
 - Package: `@nshiab/simple-data-analysis-core`
-- Version: `2.1.2`
+- Version: `2.1.4`
 
 To install the library with Deno, use:
 
@@ -781,7 +781,9 @@ await table.setTypes({
 Loads an array of JavaScript objects into the table. Types are inferred for
 numbers, bigints, strings, booleans, and Date values. Array and object cells
 require an explicit supported type in columnTypes. Types can also be specified
-for scalar columns instead of inferred from their values.
+for scalar columns instead of inferred from their values. Inferred bigints use
+signed 64-bit `BIGINT`; values outside that range throw when written instead of
+wrapping.
 
 JavaScript `Date` values are inferred as DuckDB `TIMESTAMP` values. Their
 instant is preserved, but JavaScript `Date` does not retain the timezone or
@@ -5714,16 +5716,23 @@ await table
   .log();
 ```
 
-#### `mahalanobis`
+#### `similarityMahalanobis`
 
-Calculates each row's Mahalanobis distance from a supplied reference point and
-stores it in a new DOUBLE column. Sample covariance (`n - 1`) is estimated from
-the dataset, independently of the reference point.
+Measures numeric profile similarity using each row's Mahalanobis distance from a
+supplied reference point and stores it in a new DOUBLE column. Smaller distances
+indicate more similar profiles. Optionally adds a dataset-relative similarity
+score, where larger values mean more similar. Sample covariance (`n - 1`) is
+estimated from the dataset, independently of the reference point.
+
+Accounts for differences in feature scales and correlations between features,
+making it useful for comparing profiles with measurements in different units.
 
 Pass one numeric LIST or ARRAY column, or an array of numeric scalar columns.
-Reference values follow the same dimension order. Inputs are converted privately
-to DOUBLE, which can lose precision for large integers and exact decimals;
-source columns and types remain unchanged.
+Reference arrays follow the same dimension order. For scalar columns, a
+reference object supplies its own finite numeric values by column name; extra
+fields are ignored. Reference values are captured when this method is called.
+Inputs are converted privately to DOUBLE, which can lose precision for large
+integers and exact decimals; source columns and types remain unchanged.
 
 Requires more rows than dimensions and finite, non-null, consistent features
 with invertible, numerically stable covariance. Invalid inputs leave the source
@@ -5732,20 +5741,22 @@ unchanged.
 ##### Signature
 
 ```typescript
-mahalanobis(columns: string | string[], referencePoint: number[], newColumn: string, options?: { similarityScoreColumn?: string }): this;
+similarityMahalanobis(columns: string | string[], referencePoint: number[] | Record<string, unknown>, newColumn: string, options?: { similarityScoreColumn?: string | boolean }): this;
 ```
 
 ##### Parameters
 
 - **`columns`**: A numeric vector column, or numeric scalar columns in feature
   order.
-- **`referencePoint`**: One finite number per feature dimension; may be outside
-  the dataset.
+- **`referencePoint`**: An array of finite numbers in feature order, or an
+  object with an own finite numeric value for each scalar feature column; may be
+  outside the dataset.
 - **`newColumn`**: The name of the new DOUBLE distance column.
 - **`options`**: Optional output settings.
-- **`options.similarityScoreColumn`**: A new DOUBLE column for the
-  dataset-relative score `1 - distance / maxDistance`. Exact matches score 1 and
-  the farthest rows score 0; if all distances are zero, every score is 1.
+- **`options.similarityScoreColumn`**: A custom name, or true for a new DOUBLE
+  column named "similarity"; false or omitted adds no score. The
+  dataset-relative score is `1 - distance / maxDistance`. Exact matches score 1
+  and the farthest rows score 0; if all distances are zero, every score is 1.
 
 ##### Returns
 
@@ -5756,19 +5767,30 @@ The table, so methods can be chained.
 ```ts
 // Measure distance from a reference height and weight.
 await table
-  .mahalanobis(["height", "weight"], [175, 70], "distance")
+  .similarityMahalanobis(["height", "weight"], [175, 70], "distance")
   .log();
 ```
 
 ```ts
 // Compare feature vectors and add a dataset-relative similarity score.
 await table
-  .mahalanobis("features", [175, 70], "distance", {
+  .similarityMahalanobis("features", [175, 70], "distance", {
     similarityScoreColumn: "similarity",
   })
   .log();
 ```
 
+```ts
+// Compare profiles directly with a row and use the default score column.
+const reference = await table.getFirstRow();
+if (!reference) throw new Error("The table is empty.");
+await table
+  .similarityMahalanobis(["height", "weight"], reference, "distance", {
+    similarityScoreColumn: true,
+  })
+  .log();
+```
+
 #### `unnest`
 
 Unnests (expands) rows by splitting a column's string values into multiple rows
@@ -7028,7 +7050,9 @@ array of objects. This method offers high flexibility for data manipulation but
 can be slow for large tables as it involves transferring data between DuckDB and
 JavaScript. Before writing a JavaScript callback, check for an existing SDA
 method that performs the same operation; it will usually be faster and more
-efficient.
+efficient. Existing integer and enum columns retain their types. Fractional or
+out-of-range integers and unknown enum members throw when written. The original
+table is replaced after all callback results have been converted successfully.
 
 If the table has geometry columns, the callback can read and modify their
 GeoJSON geometry objects directly. Extra properties added to these objects are

package/llms.txt

@@ -3,7 +3,7 @@
 > Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.
 
 - Package: `@nshiab/simple-data-analysis-core`
-- Version: `2.1.2`
+- Version: `2.1.4`
 
 Install with Deno: `deno add jsr:@nshiab/simple-data-analysis-core`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshiab/simple-data-analysis-core",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.",
   "keywords": [
     "data-analysis",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@duckdb/node-api": "1.5.5-r.4"
+    "@duckdb/node-api": "1.5.5-r.5"
   },
   "_generatedBy": "dnt@dev"
 }

package/script/_dnt.polyfills.d.ts

@@ -4,4 +4,15 @@ declare global {
     }
 }
 export {};
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};
 //# sourceMappingURL=_dnt.polyfills.d.ts.map

package/script/_dnt.polyfills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC"}
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC;AAgBV,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd;;;;WAIG;QACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;KAC5C;CACF;AAED,OAAO,EAAE,CAAC"}

package/script/_dnt.polyfills.js

@@ -1,2 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}

package/script/class/SimpleDB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimpleDB.d.ts","sourceRoot":"","sources":["../../src/class/SimpleDB.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SimpleDB.d.ts","sourceRoot":"","sources":["../../src/class/SimpleDB.ts"],"names":[],"mappings":"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"}

package/script/class/SimpleDB.js

@@ -1102,6 +1102,7 @@ _SimpleDB_closePromise = new WeakMap(), _SimpleDB_startPromise = new WeakMap(),
         (0, queueOp_js_1.discardAllPending)(this);
     }
     const cleanupErrors = [];
+    const cacheCleanupMessages = [];
     if (this.db instanceof node_api_1.DuckDBInstance) {
         try {
             this.connection.closeSync();
@@ -1122,25 +1123,15 @@ _SimpleDB_closePromise = new WeakMap(), _SimpleDB_startPromise = new WeakMap(),
         if ((0, node_fs_1.existsSync)(tmpDir)) {
             (0, node_fs_1.rmSync)(tmpDir, { recursive: true });
         }
-        (0, cleanCache_js_1.default)(this);
+        // Defer cache logs until after the summary, while timing cleanup too.
+        (0, cleanCache_js_1.default)(this, (message) => cacheCleanupMessages.push(message));
     }
     catch (error) {
         cleanupErrors.push(error);
     }
     this.lifecycleState = "closed";
-    if (operationError !== undefined && cleanupErrors.length > 0) {
-        throw new AggregateError([operationError, ...cleanupErrors], "Pending execution and database cleanup both failed.", { cause: operationError });
-    }
-    if (operationError !== undefined) {
-        throw operationError;
-    }
-    if (cleanupErrors.length === 1) {
-        throw cleanupErrors[0];
-    }
-    if (cleanupErrors.length > 1) {
-        throw new AggregateError(cleanupErrors, "Multiple errors occurred while cleaning up the database.", { cause: cleanupErrors[0] });
-    }
-    if (typeof this.durationStart === "number") {
+    if (operationError === undefined && cleanupErrors.length === 0 &&
+        typeof this.durationStart === "number") {
         let string = (0, prettyDuration_js_1.default)(this.durationStart, {
             prefix: "\n\nSimpleDB ran for ",
         });
@@ -1156,6 +1147,24 @@ _SimpleDB_closePromise = new WeakMap(), _SimpleDB_startPromise = new WeakMap(),
         }
         console.log(`${string}\n`);
     }
+    for (const message of cacheCleanupMessages) {
+        console.log(message);
+    }
+    if (cacheCleanupMessages.length > 0) {
+        console.log();
+    }
+    if (operationError !== undefined && cleanupErrors.length > 0) {
+        throw new AggregateError([operationError, ...cleanupErrors], "Pending execution and database cleanup both failed.", { cause: operationError });
+    }
+    if (operationError !== undefined) {
+        throw operationError;
+    }
+    if (cleanupErrors.length === 1) {
+        throw cleanupErrors[0];
+    }
+    if (cleanupErrors.length > 1) {
+        throw new AggregateError(cleanupErrors, "Multiple errors occurred while cleaning up the database.", { cause: cleanupErrors[0] });
+    }
     return await this;
 };
 exports.default = SimpleDB;

package/script/class/SimpleTable.d.ts

@@ -193,6 +193,8 @@ export default class SimpleTable extends Simple {
      * numbers, bigints, strings, booleans, and Date values. Array and object cells
      * require an explicit supported type in columnTypes. Types can also be
      * specified for scalar columns instead of inferred from their values.
+     * Inferred bigints use signed 64-bit `BIGINT`; values outside that range throw
+     * when written instead of wrapping.
      *
      * JavaScript `Date` values are inferred as DuckDB `TIMESTAMP` values. Their
      * instant is preserved, but JavaScript `Date` does not retain the timezone or
@@ -4233,13 +4235,22 @@ export default class SimpleTable extends Simple {
         normalization?: "dimensionMinMax" | "rowL2";
     }): this;
     /**
-     * Calculates each row's Mahalanobis distance from a supplied reference point
-     * and stores it in a new DOUBLE column. Sample covariance (`n - 1`) is
-     * estimated from the dataset, independently of the reference point.
+     * Measures numeric profile similarity using each row's Mahalanobis distance
+     * from a supplied reference point and stores it in a new DOUBLE column.
+     * Smaller distances indicate more similar profiles. Optionally adds a
+     * dataset-relative similarity score, where larger values mean more similar.
+     * Sample covariance (`n - 1`) is estimated from the dataset, independently
+     * of the reference point.
+     *
+     * Accounts for differences in feature scales and correlations between features,
+     * making it useful for comparing profiles with measurements in different units.
      *
      * Pass one numeric LIST or ARRAY column, or an array of numeric scalar columns.
-     * Reference values follow the same dimension order. Inputs are converted
-     * privately to DOUBLE, which can lose precision for large integers and exact
+     * Reference arrays follow the same dimension order. For scalar columns, a
+     * reference object supplies its own finite numeric values by column name; extra
+     * fields are ignored. Reference values are captured when this method is called.
+     * Inputs are converted privately to DOUBLE, which can lose precision for large
+     * integers and exact
      * decimals; source columns and types remain unchanged.
      *
      * Requires more rows than dimensions and finite, non-null, consistent features
@@ -4250,7 +4261,7 @@ export default class SimpleTable extends Simple {
      * ```ts
      * // Measure distance from a reference height and weight.
      * await table
-     *   .mahalanobis(["height", "weight"], [175, 70], "distance")
+     *   .similarityMahalanobis(["height", "weight"], [175, 70], "distance")
      *   .log();
      * ```
      *
@@ -4258,23 +4269,37 @@ export default class SimpleTable extends Simple {
      * ```ts
      * // Compare feature vectors and add a dataset-relative similarity score.
      * await table
-     *   .mahalanobis("features", [175, 70], "distance", {
+     *   .similarityMahalanobis("features", [175, 70], "distance", {
      *     similarityScoreColumn: "similarity",
      *   })
      *   .log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Compare profiles directly with a row and use the default score column.
+     * const reference = await table.getFirstRow();
+     * if (!reference) throw new Error("The table is empty.");
+     * await table
+     *   .similarityMahalanobis(["height", "weight"], reference, "distance", {
+     *     similarityScoreColumn: true,
+     *   })
+     *   .log();
+     * ```
      * @param columns - A numeric vector column, or numeric scalar columns in feature order.
-     * @param referencePoint - One finite number per feature dimension; may be outside the dataset.
+     * @param referencePoint - An array of finite numbers in feature order, or an object with an own finite numeric value for each scalar feature column; may be outside the dataset.
      * @param newColumn - The name of the new DOUBLE distance column.
      * @param options - Optional output settings.
-     * @param options.similarityScoreColumn - A new DOUBLE column for the dataset-relative
-     * score `1 - distance / maxDistance`. Exact matches score 1 and the farthest
+     * @param options.similarityScoreColumn - A custom name, or true for a new DOUBLE column named "similarity"; false or omitted adds no score. The dataset-relative
+     * score is `1 - distance / maxDistance`. Exact matches score 1 and the farthest
      * rows score 0; if all distances are zero, every score is 1.
      * @returns The table, so methods can be chained.
      * @category Analyzing Data
      */
-    mahalanobis(columns: string | string[], referencePoint: number[], newColumn: string, options?: {
-        similarityScoreColumn?: string;
+    similarityMahalanobis(columns: string | string[], referencePoint: number[] | {
+        [key: string]: unknown;
+    }, newColumn: string, options?: {
+        similarityScoreColumn?: string | boolean;
     }): this;
     /**
      * Unnests (expands) rows by splitting a column's string values into multiple rows based on a separator.
@@ -5278,6 +5303,10 @@ export default class SimpleTable extends Simple {
      * This method offers high flexibility for data manipulation but can be slow for large tables as it involves transferring data between DuckDB and JavaScript.
      * Before writing a JavaScript callback, check for an existing SDA method that
      * performs the same operation; it will usually be faster and more efficient.
+     * Existing integer and enum columns retain their types. Fractional or
+     * out-of-range integers and unknown enum members throw when written. The
+     * original table is replaced after all callback results have been converted
+     * successfully.
      *
      * If the table has geometry columns, the callback can read and modify their
      * GeoJSON geometry objects directly. Extra properties added to these objects