@nshiab/simple-data-analysis-core 2.0.5 → 2.0.6

package/esm/class/SimpleTable.js

@@ -10,6 +10,8 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 var _SimpleTable_name;
+import logBottom from "../methods/logBottom.js";
+import log from "../methods/log.js";
 import quoteIdentifier from "../helpers/quoteIdentifier.js";
 import csvFormat from "../helpers/csvFormat.js";
 import getDescription from "../methods/getDescription.js";
@@ -223,7 +225,7 @@ class SimpleTable extends Simple {
      * @param simpleDB - The SimpleDB instance that this table belongs to.
      * @param options - An optional object with configuration options:
      * @param options.rowsToLog - The number of rows to log when displaying table data.
-     * @param options.charsToLog - The maximum number of characters to log for strings. Useful to avoid logging large text content.
+     * @param options.charsToLog - The maximum characters to display for text and stringified nested cells, including truncation markers (default: 75). Independent of column width. Use Infinity for unlimited text.
      * @param options.typesToLog - A boolean indicating whether to include data types when logging a table.
      * @category Constructor
      */
@@ -299,6 +301,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Renames the current table.
+     * The new name must not belong to another registered table, ignoring ASCII letter case.
      *
      * @param name - The new name for the table.
      * @returns A promise that resolves to the renamed table.
@@ -320,9 +323,7 @@ class SimpleTable extends Simple {
      * Sets the data types for columns in a new table. If the table already exists, it will be replaced.
      * To convert the types of an existing table, use the `.convert()` method instead.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
-     * @param types - An object specifying the column names and their target data types (JavaScript or SQL types).
+     * @param types - An object specifying the column names and their target data types (JavaScript or SQL types), including JSON, FLOAT[n] vectors, and GEOMETRY with a CRS.
      * @returns The table, so methods can be chained.
      * @category Table Management
      *
@@ -335,28 +336,43 @@ class SimpleTable extends Simple {
      *   raise: "float",
      * }).log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Create an empty table with JSON, embedding, and geometry columns.
+     * await table.setTypes({
+     *   details: "JSON",
+     *   embedding: "FLOAT[3]",
+     *   geom: "GEOMETRY('EPSG:4326')",
+     * }).log();
+     * ```
      */
     setTypes(types) {
         setTypes(this, types);
         return this;
     }
     /**
-     * Loads an array of JavaScript objects into the table. Types can also be specified for individual columns instead of inferred from their values. This method queues the load; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * 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.
      *
      * JavaScript `Date` values are inferred as DuckDB `TIMESTAMP` values. Their
      * instant is preserved, but JavaScript `Date` does not retain the timezone or
-     * offset originally used to construct it. String values remain `VARCHAR`;
-     * use `convert()` to parse them as temporal values.
+     * offset originally used to construct it.
+     *
+     * Declare `JSON` for general nested data, `FLOAT[n]` for a fixed-size float
+     * vector, or `GEOMETRY('EPSG:4326')` for GeoJSON geometries in WGS84.
      *
      * @param rows - An array of objects, where each object represents a row and its properties represent columns.
      * @param options - Options for loading the array, captured when called.
-     * @param options.columnTypes - Types for specific columns; omitted columns are inferred. Values must be compatible with the selected type without losing information.
+     * @param options.columnTypes - Types for specific columns. Required for array and object cells; omitted scalar columns are inferred, and all-null columns default to VARCHAR. Values must be compatible with the selected type without losing information.
      * @returns The table, so methods can be chained.
      * @category Importing Data
      *
      * @example
      * ```ts
-     * // Load data from an array of objects
+     * // Load scalar columns without columnTypes; strings and numbers are inferred.
      * const data = [
      *   { letter: "a", number: 1 },
      *   { letter: "b", number: 2 }
@@ -366,7 +382,7 @@ class SimpleTable extends Simple {
      *
      * @example
      * ```ts
-     * // Specify a numeric type for an all-null column
+     * // Choose a numeric type when all-null values provide nothing to infer.
      * await table.loadArray(
      *   [{ name: "A", value: null }, { name: "B", value: null }],
      *   { columnTypes: { value: "DOUBLE" } },
@@ -375,12 +391,39 @@ class SimpleTable extends Simple {
      *
      * @example
      * ```ts
-     * // The offset determines the instant; the loaded TIMESTAMP is returned as
-     * // the equivalent UTC JavaScript Date.
+     * // Store the Date as a UTC timestamp with JavaScript's millisecond precision.
+     * // The original -04:00 offset is not retained.
      * await table.loadArray([{
      *   observedAt: new Date("2024-04-07T13:00:00-04:00"),
      * }]).log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Declare JSON to load nested objects and variable-length arrays directly.
+     * await table.loadArray([{
+     *   name: "Station",
+     *   metadata: { active: true, tags: ["weather", "urban"] },
+     *   measurements: [1, 2.5, null],
+     * }], { columnTypes: { metadata: "JSON", measurements: "JSON" } }).log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Declare FLOAT[3] to store each three-element array as a fixed-size vector.
+     * await table.loadArray([{ vector: [1, 2, 3] }], {
+     *   columnTypes: { vector: "FLOAT[3]" },
+     * }).log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Declare a geometry type to store WGS84 GeoJSON as a spatial column.
+     * await table.loadArray([{
+     *   name: "Montreal",
+     *   geom: { type: "Point", coordinates: [-73.57, 45.50] },
+     * }], { columnTypes: { geom: "GEOMETRY('EPSG:4326')" } }).log();
+     * ```
      */
     loadArray(rows, options = {}) {
         loadArray(this, rows, options);
@@ -389,17 +432,18 @@ class SimpleTable extends Simple {
     /**
      * Loads data from one or more local or remote files into the table.
      * Supported file formats include CSV, JSON, Parquet, and Excel.
-     * This method queues the load; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     *
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param files - The path(s) or URL(s) of the file(s) containing the data to be loaded.
      * @param options - An optional object with configuration options:
      * @param options.fileType - The type of file to load ("csv", "dsv", "json", "parquet", "excel"). Defaults to being inferred from the file extension.
      * @param options.autoDetect - A boolean indicating whether to automatically detect the data format. Defaults to `true`.
-     * @param options.conditions - A SQL `WHERE` clause expression, without the `WHERE` keyword, to filter source rows before applying `limit`. Uses the same syntax as `filter()`, including JavaScript operators. Can reference source columns excluded from `columns`. Defaults to no filtering; an empty string behaves the same as omitting this option.
+     * @param options.conditions - A SQL `WHERE` clause expression, without the `WHERE` keyword, to filter source rows before applying `limit`. Can reference source columns excluded from `columns`.
      * @param options.limit - A number indicating the maximum number of matching rows to load, after applying `conditions` if provided. Defaults to all matching rows.
      * @param options.includeFilename - A boolean indicating whether to include the filename as a new column in the loaded data. Defaults to `false`.
      * @param options.unifyColumns - A boolean indicating whether to unify columns across multiple files when their structures differ. Missing columns will be filled with `NULL` values. Defaults to `false`.
-     * @param options.columnTypes - An object mapping column names to their expected data types. By default, types are inferred.
+     * @param options.columnTypes - An object mapping column names to their expected data types. By default, types are inferred. Geometry types are not supported; use loadGeoData() instead.
      * @param options.columns - An array of column names to load. When provided, only the specified columns are loaded, reducing memory usage and improving load times. Not supported for Excel files — combining `columns` with Excel files throws an error. If an invalid column name is provided, DuckDB will throw its native error. An empty array behaves the same as omitting the option (loads all columns). Defaults to loading all columns.
      * @param options.header - A boolean indicating whether the file has a header row. Applicable to CSV files. Defaults to `true`.
      * @param options.allText - A boolean indicating whether all columns should be treated as text. Applicable to CSV files. Defaults to `false`.
@@ -476,8 +520,6 @@ class SimpleTable extends Simple {
     }
     /**
      * Downloads a complete Statistics Canada table and loads it into this table.
-     * The method queues the download and load; they run when an async observer
-     * method (like `getData()` or `log()`) is awaited, or when `run()` is called.
      *
      * Results are cached as Parquet files in `.sda-cache/statcan` by default.
      * Cached data does not expire unless a TTL is provided.
@@ -531,9 +573,6 @@ class SimpleTable extends Simple {
      * research, and journalistic purposes. Before using it, review Yahoo's terms
      * and any applicable data-provider restrictions.
      *
-     * The method queues the download and load; they run when an async observer
-     * method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param symbol - The stock or index symbol, such as `"AAPL"` or `"^GSPTSE"`.
      * @param startDate - The inclusive UTC start of the requested range.
      * @param endDate - The inclusive UTC end of the requested range. The UTC day,
@@ -580,14 +619,13 @@ class SimpleTable extends Simple {
     }
     /**
      * Loads geospatial data from an external file or URL into the table.
-     *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param file - The path or URL of the external file containing the geospatial data.
      * @param options - An optional object with configuration options:
      * @param options.toEPSG4326 - If `true`, the method will attempt to reproject the data to EPSG:4326 (WGS84).
      * @param options.columns - The columns to load. Include the geometry column that should remain in the resulting table, usually `"geom"`. By default, all columns are loaded.
-     * @param options.conditions - A SQL `WHERE` clause expression, without the `WHERE` keyword, to filter source rows before materialization and reprojection. Uses the same syntax as `filter()`, including JavaScript operators. Can reference source columns excluded from `columns`. Geometry conditions use the source coordinate system. Defaults to no filtering; an empty string behaves the same as omitting this option.
+     * @param options.conditions - A SQL `WHERE` clause expression, without the `WHERE` keyword, to filter source rows before materialization and reprojection. Can reference source columns excluded from `columns`. Geometry conditions use the source coordinate system.
      * @returns The table, so methods can be chained.
      * @category Geospatial
      *
@@ -641,7 +679,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Loads OpenStreetMap data into the table from a local `.osm` or `.osm.pbf` file, a remote file URL, or an Overpass bounding-box query. Pass a path or URL string to load an existing file, or pass a bounding box with `filters` to download matching features. The method queues the load; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Loads OpenStreetMap data into the table from a local `.osm` or `.osm.pbf` file, a remote file URL, or an Overpass bounding-box query. Pass a path or URL string to load an existing file, or pass a bounding box with `filters` to download matching features.
      *
      * DuckDB's [Osmium community extension](https://duckdb.org/community_extensions/extensions/osmium) materializes the complete result and reconstructs `geom` as EPSG:4326. By default, that canonical result is cached as GeoParquet in `.sda-cache/osm`. Distinct paths, local file fingerprints, normalized URLs, endpoints, queries, and bounding boxes retain independent entries. The cache has no expiration unless `ttl` is set and can be cleared by removing `.sda-cache/osm`. Immutable URLs can safely use the default indefinite cache; mutable URLs should set a TTL.
      *
@@ -728,8 +766,6 @@ class SimpleTable extends Simple {
      * DuckDB FTS indexes do not update automatically when the table changes; use
      * `overwrite: true` to rebuild the index after modifying the table.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param idColumn - The column containing the document identifiers.
      * @param textColumn - The column containing the text to search.
      * @param options - An optional object with configuration options:
@@ -788,8 +824,6 @@ class SimpleTable extends Simple {
      * If a VSS index already exists on the table, this method will skip creation and log a message (when verbose is enabled), unless the `overwrite` option is set to `true`.
      * The index definition is recorded in {@link indexes}.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing vector embeddings (must be FLOAT array type).
      * @param options - An optional object with configuration options:
      * @param options.overwrite - If `true`, drops and recreates the index even if it already exists. Defaults to `false`.
@@ -850,8 +884,6 @@ class SimpleTable extends Simple {
      * changes; use `overwriteIndex: true` to rebuild the index after modifying
      * the table.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param text - The search query text to match against the text column.
      * @param idColumn - The name of the column containing unique identifiers for each row.
      * @param textColumn - The name of the column containing the text to search.
@@ -953,8 +985,6 @@ class SimpleTable extends Simple {
     /**
      * Inserts rows, provided as an array of JavaScript objects, into the table.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param rows - An array of objects, where each object represents a row to be inserted and its properties correspond to column names.
      * @returns The table, so methods can be chained.
      * @category Importing Data
@@ -974,7 +1004,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Inserts all rows from one or more other tables into this table. If tables do not have the same columns, an error will be thrown unless the `unifyColumns` option is set to `true`. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Inserts all rows from one or more other tables into this table. If tables do not have the same columns, an error will be thrown unless the `unifyColumns` option is set to `true`.
      *
      * @param tables - The name(s) of the table(s) or SimpleTable instance(s) from which rows will be inserted.
      * @param options - An optional object with configuration options:
@@ -1007,8 +1037,6 @@ class SimpleTable extends Simple {
     /**
      * Fetches sample data from the simple-data-analysis-core GitHub repository.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param sample - The name of the sample to load.
      *
      * Tabular data:
@@ -1034,13 +1062,12 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns a new table with the same structure and data as this table. The data can be optionally filtered, limited to a specific number of rows, and offset.
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * If `conditions`, `limit`, and `offset` are all used, they are applied in this order: `conditions` (WHERE clause) first, then `offset`, and finally `limit` (LIMIT).
      *
      * Note that cloning large tables can be a slow operation.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param nameOrOptions - Either a string specifying the name of the new table, or an optional object with configuration options. If not provided, a default name (e.g., "table1", "table2") will be generated.
      * @param nameOrOptions.name - The name of the new table to be created in the database. If not provided, a default name (e.g., "table1", "table2") will be generated.
      * @param nameOrOptions.conditions - A SQL `WHERE` clause condition to filter the data during cloning. Defaults to no condition (clones all rows).
@@ -1109,8 +1136,6 @@ class SimpleTable extends Simple {
     /**
      * Clones an existing column in this table, creating a new column with identical values.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the original column to clone.
      * @param newColumn - The name of the new column to be created.
      * @returns The table, so methods can be chained.
@@ -1132,8 +1157,6 @@ class SimpleTable extends Simple {
      *
      * **Important:** The offset is applied based on the current row order in the table. For meaningful results, ensure your data is sorted appropriately (e.g., by date/time for time-series analysis) before calling this method.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the original column.
      * @param newColumn - The name of the new column to be created with offset values.
      * @param options - An optional object with configuration options:
@@ -1179,8 +1202,6 @@ class SimpleTable extends Simple {
     /**
      * Fills `NULL` values in specified columns. By default, each `NULL` is replaced with the last non-`NULL` value from the preceding row. When `interpolate` is `true`, `NULL` values are replaced using linear interpolation (or extrapolation at the ends). Pass `interpolateBy` with a real numeric or date column name to use it as the X-axis, so that interpolated values are proportional to the actual distances between X-axis values rather than treating every row as equidistant. When `interpolateBy` is set, `interpolate` is automatically assumed `true`.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The column(s) for which to fill `NULL` values.
      * @param options - An optional object with configuration options:
      * @param options.by - A column name or an array of column names to partition by. The fill is applied independently within each group.
@@ -1239,7 +1260,7 @@ class SimpleTable extends Simple {
      * Sorts the rows of the table based on specified column(s) and order(s).
      * If no columns are specified, all columns are sorted from left to right in ascending order.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called. Order-preserving transformations queued after a sort retain that order. Operations such as joins, grouping, aggregation, and sampling do not guarantee input order; chain `sort()` after them when deterministic output order matters.
+     * Order-preserving transformations after a sort retain that order. Operations such as joins, grouping, aggregation, and sampling do not guarantee input order; chain `sort()` after them when deterministic output order matters.
      *
      * @param order - An object mapping column names to their sorting order: `"asc"` for ascending or `"desc"` for descending. If `null`, all columns are sorted ascendingly.
      * @param options - An optional object with configuration options:
@@ -1276,7 +1297,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Selects specific columns in the table, removing all others. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Selects specific columns in the table, removing all others.
      *
      * @param columns - The name or an array of names of the columns to be selected.
      * @returns The table, so methods can be chained.
@@ -1301,8 +1322,6 @@ class SimpleTable extends Simple {
     /**
      * Skips the first `n` rows of the table, effectively removing them.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param count - The number of rows to skip from the beginning of the table.
      * @returns The table, so methods can be chained.
      * @category Selecting or Filtering Data
@@ -1338,8 +1357,6 @@ class SimpleTable extends Simple {
     /**
      * Selects random rows from the table, removing all others. You can optionally specify a seed to ensure repeatable sampling.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param count - The number of rows to select (e.g., `100`) or a percentage string (e.g., `"10%"`) specifying the sampling size.
      * @param options - An optional object with configuration options:
      * @param options.seed - A number specifying the seed for repeatable sampling. Using the same seed will always yield the same random rows. Defaults to a random seed.
@@ -1371,8 +1388,6 @@ class SimpleTable extends Simple {
     /**
      * Selects a specified number of rows from this table. An offset can be applied to skip initial rows, and the results can be output to a new table.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param count - The number of rows to select.
      * @param options - An optional object with configuration options:
      * @param options.offset - The number of rows to skip from the beginning of the table before selecting. Defaults to `0`.
@@ -1411,8 +1426,6 @@ class SimpleTable extends Simple {
      * Removes duplicate rows from this table, keeping only unique rows.
      * Note that the resulting data order might differ from the original.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param options - An optional object with configuration options:
      * @param options.on - A column name or an array of column names to consider when identifying duplicates. If specified, duplicates are determined based only on the values in these columns. If omitted, all columns are considered.
      * @returns The table, so methods can be chained.
@@ -1443,7 +1456,6 @@ class SimpleTable extends Simple {
     /**
      * Removes rows with missing values from this table.
      * By default, missing values include SQL `NULL`, as well as string representations like `"NULL"`, `"null"`, `"NaN"`, `"undefined"`, and empty strings `""`.
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
      *
      * @param options - An optional object with configuration options:
      * @param options.columns - A string or an array of strings specifying the columns to consider for missing values. If omitted, all columns are considered.
@@ -1481,7 +1493,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Trims specified characters from the beginning, end, or both sides of string values in the given columns. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Trims specified characters from the beginning, end, or both sides of string values in the given columns.
      *
      * @param columns - The column name or an array of column names to trim.
      * @param options - An optional object with configuration options:
@@ -1514,8 +1526,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Filters rows from this table based on SQL conditions. Note that it's often faster to use the `removeRows` method for simple removals.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param conditions - The filtering conditions specified as a SQL `WHERE` clause (e.g., `"column1 > 10 AND column2 = 'value'"`).
      * @returns The table, so methods can be chained.
@@ -1552,8 +1563,6 @@ class SimpleTable extends Simple {
     /**
      * Keeps rows in this table that have specific values in specified columns, removing all other rows.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columnsAndValues - An object where keys are column names and values are the specific values (or an array of values) to keep in those columns. Use `null` to keep rows where a column is `NULL`.
      * @returns The table, so methods can be chained.
      * @category Selecting or Filtering Data
@@ -1583,8 +1592,6 @@ class SimpleTable extends Simple {
     /**
      * Removes rows from this table that have specific values in specified columns.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columnsAndValues - An object where keys are column names and values are the specific values (or an array of values) to remove from those columns. Use `null` to remove rows where a column is `NULL`; otherwise, `NULL` rows are retained.
      * @returns The table, so methods can be chained.
      * @category Selecting or Filtering Data
@@ -1613,9 +1620,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Removes rows from this table based on SQL conditions. This method is similar to `filter()`, but removes rows instead of keeping them.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
-     *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param conditions - The filtering conditions specified as a SQL `WHERE` clause (e.g., `"fruit = 'apple'"`).
      * @returns The table, so methods can be chained.
@@ -1653,8 +1658,6 @@ class SimpleTable extends Simple {
      * Renames one or more columns in the table. Throws if a source column does
      * not exist, so a typo fails loudly instead of being silently ignored.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param names - An object mapping old column names to their new column names (e.g., `{ "oldName": "newName", "anotherOld": "anotherNew" }`).
      * @param options - Configuration options.
      * @param options.strict - Whether to verify the source columns exist before renaming. Defaults to `true`. Set to `false` to skip the check and its schema lookup when you know the columns exist and are renaming across many tables where the extra round-trip adds up.
@@ -1686,8 +1689,6 @@ class SimpleTable extends Simple {
     /**
      * Cleans column names by removing non-alphanumeric characters and formatting them to camel case.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @returns The table, so methods can be chained.
      * @category Column Operations
      *
@@ -1740,8 +1741,6 @@ class SimpleTable extends Simple {
      * | Sales      | 2022 | 75        |
      * | Sales      | 2023 | 98        |
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - An array of strings representing the names of the columns to be stacked (unpivoted).
      * @param namesTo - The name of the new column that will contain the original column names (e.g., "Year").
      * @param valuesTo - The name of the new column that will contain the values from the stacked columns (e.g., "Employees").
@@ -1783,8 +1782,6 @@ class SimpleTable extends Simple {
      *
      * When multiple rows share the same `namesFrom`/grouping combination, their `valuesFrom` values are combined with the `options.stat` function (`"sum"` by default).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param namesFrom - The name of the column containing the values that will be transformed into new column headers (e.g., "Year").
      * @param valuesFrom - The name of the column containing the values to be spread across the new columns (e.g., "Employees").
      * @param options - An optional object with configuration options:
@@ -1809,9 +1806,7 @@ class SimpleTable extends Simple {
      *
      * When converting strings to numbers, commas (often used as thousand separators) will be automatically removed before conversion.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called. If a column doesn't exist, the error is thrown at that point too.
-     *
-     * @param types - An object mapping column names to their target data types for conversion.
+     * @param types - An object mapping column names to their target data types for conversion, including JSON, FLOAT[n] vectors, and GEOMETRY with a CRS.
      * @param options - An optional object with configuration options:
      * @param options.strict - If `false`, values that cannot be converted will be replaced by `NULL` instead of throwing an error. Defaults to `true`.
      * @param options.datetimeFormat - A string specifying the format for date and time conversions. Uses `strftime` and `strptime` functions from DuckDB. For format specifiers, see [DuckDB's documentation](https://duckdb.org/docs/sql/functions/dateformat).
@@ -1858,6 +1853,18 @@ class SimpleTable extends Simple {
      * // Convert 'amount' to float, replacing unconvertible values with NULL
      * await table.convert({ amount: "float" }, { strict: false }).log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Parse JSON, a fixed-size float vector, and WKT geometry from text.
+     * await table.loadArray([{
+     *   details: '{"count":3}',
+     *   embedding: "[0.25,0.5,0.75]",
+     *   geom: "POINT (-73 45)",
+     * }])
+     *   .convert({ details: "JSON", embedding: "FLOAT[3]", geom: "GEOMETRY('EPSG:4326')" })
+     *   .log();
+     * ```
      */
     convert(types, options = {}) {
         convert(this, types, options);
@@ -1880,7 +1887,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Removes one or more columns from this table. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Removes one or more columns from this table.
      *
      * @param columns - The name or an array of names of the columns to be removed.
      * @returns The table, so methods can be chained.
@@ -1903,10 +1910,11 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Adds a new column to the table based on a specified data type (JavaScript or SQL types) and a SQL definition. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Adds a new column to the table based on a specified data type (JavaScript or SQL types) and a SQL definition.
+     * With the default `SimpleDB.expressionSyntax: "js"`, expressions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param newColumn - The name of the new column to be added.
-     * @param type - The data type for the new column. Can be a JavaScript type (e.g., `"number"`, `"string"`) or a SQL type (e.g., `"integer"`, `"varchar"`).
+     * @param type - The data type for the new column. Can be a JavaScript type (e.g., `"number"`, `"string"`) or a SQL type (e.g., `"integer"`, `"varchar"`, `"JSON"`, `"FLOAT[3]"`, `"GEOMETRY('EPSG:4326')"`).
      * @param definition - A SQL expression defining how the values for the new column should be computed (e.g., `"column1 + column2"`, `"ST_Centroid(geom_column)"`).
      * @returns The table, so methods can be chained.
      * @category Column Operations
@@ -1922,6 +1930,25 @@ class SimpleTable extends Simple {
      * // Add a new geometry column 'centroid' using the centroid of an existing 'country' geometry column
      * await table.addColumn("centroid", "geometry('EPSG:4326')", `ST_Centroid("country")`).log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Read a number from a JSON object into a new column using dot notation.
+     * await table.loadArray([{ details: { count: 3 } }], {
+     *   columnTypes: { details: "JSON" },
+     * })
+     *   .addColumn("count", "integer", "details.count")
+     *   .log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Create JSON and fixed-size vector columns with DuckDB expressions.
+     * await table.loadArray([{ count: 3 }])
+     *   .addColumn("details", "JSON", "json_object('count', count)")
+     *   .addColumn("embedding", "FLOAT[3]", "[0.25, 0.5, 0.75]")
+     *   .log();
+     * ```
      */
     addColumn(newColumn, type, definition) {
         addColumn(this, newColumn, type, definition);
@@ -1941,9 +1968,6 @@ class SimpleTable extends Simple {
      * values produce `NULL` extracted values. Parts extracted from
      * `TIMESTAMP WITH TIME ZONE` values use UTC.
      *
-     * This method queues the operation; it runs when an async observer method
-     * (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The temporal column from which to extract components.
      * @param parts - A part to extract using its name as the new column, or an object mapping each custom new-column name to the part it should contain.
      * @returns The table, so methods can be chained.
@@ -1971,8 +1995,6 @@ class SimpleTable extends Simple {
     /**
      * Adds a new column to the table containing the row number, starting at 0 (like an index).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column that will store the row number.
      * @param options - An optional object with configuration options:
      * @param options.by - A column name or an array of column names to partition by. The row number restarts at 0 within each group.
@@ -1999,8 +2021,6 @@ class SimpleTable extends Simple {
      * Performs a cross join operation with another table. A cross join returns the Cartesian product of the rows from both tables, meaning all possible pairs of rows will be in the resulting table.
      * This means that if the left table has `n` rows and the right table has `m` rows, the result will have `n * m` rows.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param rightTable - The SimpleTable instance to cross join with.
      * @param options - An optional object with configuration options:
      * @param options.outputTable - If `true`, the results will be stored in a new table with a generated name. If a string, it will be used as the name for the new table. If `false` or omitted, the current table will be overwritten. Defaults to `false`.
@@ -2032,7 +2052,6 @@ class SimpleTable extends Simple {
      * Merges the data of this table (considered the left table) with another table (the right table) based on a common column or multiple columns.
      * Note that the order of rows in the returned data is not guaranteed to be the same as in the original tables.
      * This operation might create temporary files in a `.tmp` folder; consider adding `.tmp` to your `.gitignore`.
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called. The join uses the other table's state as of this call: operations queued on it afterwards run after the join.
      *
      * @param rightTable - The SimpleTable instance to be joined with this table.
      * @param options - An optional object with configuration options:
@@ -2080,8 +2099,6 @@ class SimpleTable extends Simple {
      *
      * This operation might create temporary files in a `.tmp` folder; consider adding `.tmp` to your `.gitignore`.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called. The join uses the other table's state as of this call: operations queued on it afterwards run after the join.
-     *
      * @param rightTable - The SimpleTable instance to be joined with this table.
      * @param leftColumn - The name of the column in this (left) table containing the text to compare.
      * @param rightColumn - The name of the column in the right table containing the text to compare.
@@ -2148,8 +2165,6 @@ class SimpleTable extends Simple {
      * Similarity is computed using the [rapidfuzz](https://query.farm/duckdb_extension_rapidfuzz) DuckDB community extension,
      * which is installed and loaded automatically.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to normalize.
      * @param newColumn - The name of the column to write the normalized values to. Use the same name as `column` to normalize in-place.
      * @param threshold - The minimum similarity score (0–100) for two strings to be considered duplicates. For `method: "ratio"`, a length-based pre-filter is automatically applied based on the threshold to improve performance without losing accuracy.
@@ -2203,8 +2218,6 @@ class SimpleTable extends Simple {
     /**
      * Replaces specified strings in the selected columns.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The column name, an array of column names, or `"all"` to apply the replacement to every column in the table.
      * @param replacements - An object mapping old strings to new strings (e.g., `{ "oldValue": "newValue" }`).
      * @param options - An optional object with configuration options:
@@ -2248,7 +2261,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Converts string values in the specified columns to lowercase. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Converts string values in the specified columns to lowercase.
      *
      * @param columns - The column name or an array of column names to be converted to lowercase.
      * @returns The table, so methods can be chained.
@@ -2271,7 +2284,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Converts string values in the specified columns to uppercase. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Converts string values in the specified columns to uppercase.
      *
      * @param columns - The column name or an array of column names to be converted to uppercase.
      * @returns The table, so methods can be chained.
@@ -2294,7 +2307,7 @@ class SimpleTable extends Simple {
         return this;
     }
     /**
-     * Capitalizes the first letter of each string in the specified columns and converts the rest of the string to lowercase. This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Capitalizes the first letter of each string in the specified columns and converts the rest of the string to lowercase.
      *
      * @param columns - The column name or an array of column names to be capitalized.
      * @returns The table, so methods can be chained.
@@ -2319,8 +2332,6 @@ class SimpleTable extends Simple {
     /**
      * Truncates string values in a specified column to a maximum number of characters.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The column name containing strings to be truncated.
      * @param length - The maximum number of characters to keep.
      * @returns The table, so methods can be chained.
@@ -2349,8 +2360,6 @@ class SimpleTable extends Simple {
      * column is of a different type. `null` values remain `null`. If any string
      * already exceeds the target length, an error is thrown (no silent truncation).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The column name(s) containing strings to be padded.
      * @param length - The target length of the padded strings.
      * @param options - An optional object with configuration options:
@@ -2390,8 +2399,6 @@ class SimpleTable extends Simple {
      * Splits strings in a specified column by a separator and extracts a substring at a given index, storing the result in a new or existing column.
      * If the index is out of bounds, an empty string will be returned for that row.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to be split.
      * @param separator - The substring to use as a delimiter for splitting the strings.
      * @param index - The zero-based index of the substring to extract after splitting. For example, `0` for the first part, `1` for the second, etc.
@@ -2424,8 +2431,6 @@ class SimpleTable extends Simple {
      * If a row has fewer parts than the number of new columns, a warning will be logged and the extra columns will contain empty strings (unless `strict` is set to `false`).
      * If a row has more parts than the number of new columns, an error will be thrown unless `strict` is set to `false`.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to be split.
      * @param separator - The substring to use as a delimiter for splitting the strings.
      * @param newColumns - An array of column names for the extracted parts.
@@ -2461,8 +2466,6 @@ class SimpleTable extends Simple {
     /**
      * Extracts a specific number of characters from the beginning (left side) of string values in the specified column.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to be modified.
      * @param count - The number of characters to extract from the left side of each string.
      * @returns The table, so methods can be chained.
@@ -2482,8 +2485,6 @@ class SimpleTable extends Simple {
     /**
      * Extracts a specific number of characters from the end (right side) of string values in the specified column.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to be modified.
      * @param count - The number of characters to extract from the right side of each string.
      * @returns The table, so methods can be chained.
@@ -2503,8 +2504,6 @@ class SimpleTable extends Simple {
     /**
      * Replaces `NULL` values in the specified columns with a given value.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The column name, an array of column names, or `"all"` to apply the replacement to every column in the table.
      * @param value - The value to replace `NULL` occurrences with.
      * @returns The table, so methods can be chained.
@@ -2541,8 +2540,6 @@ class SimpleTable extends Simple {
     /**
      * Concatenates values from specified columns into a new column.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - An array of column names whose values will be concatenated.
      * @param newColumn - The name of the new column to store the concatenated values.
      * @param options - An optional object with configuration options:
@@ -2577,8 +2574,6 @@ class SimpleTable extends Simple {
      *
      * If a column value is `NULL`, it will be replaced by `'Unknown'` in the concatenated result.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - An array of column names whose values will be concatenated with labels.
      * @param newColumn - The name of the new column to create with the concatenated values.
      * @returns The table, so methods can be chained.
@@ -2626,8 +2621,6 @@ class SimpleTable extends Simple {
      *
      * Each value in the specified column is split using the provided separator, and a new row is created for each resulting substring. All other column values are duplicated across the newly created rows.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing string values to be split and unnested.
      * @param separator - The delimiter string used to split the column values.
      * @returns The table, so methods can be chained.
@@ -2660,8 +2653,6 @@ class SimpleTable extends Simple {
      *
      * If a row has a value of 3 in the specified column, it will be repeated 3 times. If the value is 0 or negative, the row will be removed.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the number of times each row should be repeated.
      * @param options - An optional object with configuration options:
      * @param options.index - The name of a new column to store the index of the repeated row (starting at 0).
@@ -2693,8 +2684,6 @@ class SimpleTable extends Simple {
      *
      * This is the inverse operation of `unnest()`. Multiple rows are combined into fewer rows by grouping on specified category columns and concatenating the target column values with a separator.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column whose values will be aggregated and concatenated.
      * @param separator - The delimiter string used to join the column values.
      * @param by - The column name or an array of column names to group by.
@@ -2727,8 +2716,6 @@ class SimpleTable extends Simple {
     /**
      * Rounds numeric values in specified columns.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The column name or an array of column names containing numeric values to be rounded.
      * @param options - An optional integer specifying the number of decimal places, or an object with configuration options:
      * @param options.decimals - The number of decimal places to round to. Defaults to `0` (rounds to the nearest integer).
@@ -2774,8 +2761,6 @@ class SimpleTable extends Simple {
      * Adds independently generated uniform random noise to numeric values in one or more columns.
      * Each changed value receives an offset between `-max` and `max`. Selected integer and decimal columns become `DOUBLE` columns so fractional noise is retained. This method adds random jitter; it does not provide anonymization or differential privacy guarantees.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The numeric column name or array of numeric column names to which noise will be added. When multiple columns are provided, each value receives an independent random offset.
      * @param max - The maximum absolute offset, expressed in each column's units. Must be a finite number greater than or equal to `0`.
      * @param options - An optional object with configuration options:
@@ -2803,8 +2788,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Updates values in a specified column using a SQL expression.
-     *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * With the default `SimpleDB.expressionSyntax: "js"`, expressions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param column - The name of the column to be updated.
      * @param definition - The SQL expression used to set the new values in the column (e.g., `"column1 * 2"`, `"UPPER(column_name)"`).
@@ -2828,6 +2812,16 @@ class SimpleTable extends Simple {
      * // Set 'status' to 'active' where 'isActive' is true
      * await table.updateColumn("status", `CASE WHEN isActive THEN 'active' ELSE 'inactive' END`).log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Update an existing column with a value from a JSON object using dot notation.
+     * await table.loadArray([{ count: 0, details: { count: 3 } }], {
+     *   columnTypes: { details: "JSON" },
+     * })
+     *   .updateColumn("count", "details.count")
+     *   .log();
+     * ```
      */
     updateColumn(column, definition) {
         updateColumn(this, column, definition);
@@ -2836,8 +2830,6 @@ class SimpleTable extends Simple {
     /**
      * Assigns ranks to rows in a new column based on the values of a specified column.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The column containing the values to be used for ranking.
      * @param newColumn - The name of the new column where the ranks will be stored.
      * @param options - An optional object with configuration options:
@@ -2878,8 +2870,6 @@ class SimpleTable extends Simple {
     /**
      * Assigns quantiles to rows in a new column based on specified column values.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The column containing values from which quantiles will be assigned.
      * @param count - The number of quantiles to divide the data into (e.g., `4` for quartiles, `10` for deciles).
      * @param newColumn - The name of the new column where the assigned quantiles will be stored.
@@ -2913,8 +2903,6 @@ class SimpleTable extends Simple {
     /**
      * Assigns bins for specified column values based on an interval size.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The column containing values from which bins will be computed.
      * @param interval - The interval size for binning the values.
      * @param newColumn - The name of the new column where the bins will be stored.
@@ -2990,8 +2978,6 @@ class SimpleTable extends Simple {
      * await table.rowProportions(["Men", "Women", "NonBinary"], { base: 100, decimals: 1 }).log();
      * ```
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - An array of column names for which proportions will be computed on each row.
      * @param options - An optional object with configuration options:
      * @param options.suffix - A string suffix to append to the names of the new columns storing the computed proportions. Defaults to `"Perc"`.
@@ -3015,9 +3001,6 @@ class SimpleTable extends Simple {
      * option can therefore increase the table's row count. If null values leave
      * a row without the requested rank, the new columns contain null.
      *
-     * This method queues the operation; it runs when an async observer method
-     * (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The numeric columns to rank within each row.
      * @param options - The output columns and ranking configuration. At least one of `nameColumn` or `valueColumn` is required.
      * @param options.nameColumn - The name of a new column containing the selected source column's name.
@@ -3054,8 +3037,6 @@ class SimpleTable extends Simple {
     /**
      * Computes proportions vertically over a column's values, relative to the sum of all values in that column or group.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The column containing values for which proportions will be computed. The proportions are calculated based on the sum of values in the specified column.
      * @param newColumn - The name of the new column where the proportions will be stored.
      * @param options - An optional object with configuration options:
@@ -3097,8 +3078,6 @@ class SimpleTable extends Simple {
      * Creates a summary table from selected columns, optionally grouped by other columns.
      * This method allows you to aggregate data, calculate statistics (e.g., count, mean, sum), and group results by categorical columns.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param options - An object with configuration options for summarization:
      * @param options.columns - The column name or an array of column names to summarize. If omitted, only the row count is returned.
      * @param options.by - The column name or an array of column names to group by.
@@ -3197,9 +3176,6 @@ class SimpleTable extends Simple {
      * string is also used as its row label; pass an object to customize that
      * label. If `options.stats` is omitted, every supported stat is added.
      *
-     * This method queues the operation; it runs when an async observer method
-     * (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param columns - The numeric column name, an array of numeric column names, or `"all"` to summarize every numeric column.
      * @param labelColumn - The existing string column in which stat row labels will be written.
      * @param options - An optional object with configuration options:
@@ -3241,8 +3217,6 @@ class SimpleTable extends Simple {
     /**
      * Computes the cumulative sum of values in a column. For this method to work properly, ensure your data is sorted first.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the values to be accumulated.
      * @param newColumn - The name of the new column in which the computed cumulative values will be stored.
      * @param options - An optional object with configuration options:
@@ -3279,8 +3253,6 @@ class SimpleTable extends Simple {
      * For rows without enough preceding or following rows to form a complete window, `NULL` will be returned.
      * For this method to work properly, ensure your data is sorted by the relevant column(s) first.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the values to be aggregated.
      * @param newColumn - The name of the new column in which the computed rolling values will be stored.
      * @param stat - The aggregation function to apply: `"min"`, `"max"`, `"mean"`, `"median"`, or `"sum"`.
@@ -3319,8 +3291,6 @@ class SimpleTable extends Simple {
      * Calculates correlations between columns. If no `x` and `y` columns are specified, the method computes the correlations for all numeric column combinations.
      * Note that correlation is symmetrical: the correlation of `x` with `y` is the same as `y` with `x`.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param options - An optional object with configuration options:
      * @param options.x - The name of the column for the x-values. If omitted, correlations will be computed for all numeric columns.
      * @param options.y - The name of the column for the y-values. It can be provided only when `options.x` is also set. If both are omitted, correlations will be computed for all numeric column pairs.
@@ -3368,8 +3338,6 @@ class SimpleTable extends Simple {
      * If no `x` and `y` columns are specified, the method computes linear regression analysis for all numeric column permutations.
      * Note that linear regression analysis is asymmetrical: the linear regression of `x` over `y` is not the same as `y` over `x`.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param options - An optional object with configuration options:
      * @param options.x - The name of the column for the independent variable (x-values). If omitted, linear regressions will be computed for all numeric columns as x.
      * @param options.y - The name of the column for the dependent variable (y-values). It can be provided only when `options.x` is also set. If both are omitted, linear regressions will be computed for all numeric column permutations.
@@ -3415,8 +3383,6 @@ class SimpleTable extends Simple {
     /**
      * Identifies outliers in a specified column using the Interquartile Range (IQR) method.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column in which outliers will be identified.
      * @param newColumn - The name of the new column where the boolean results (`TRUE` for outlier, `FALSE` otherwise) will be stored.
      * @param options - An optional object with configuration options:
@@ -3443,8 +3409,6 @@ class SimpleTable extends Simple {
     /**
      * Computes the Z-score for values in a specified column.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column for which Z-scores will be calculated.
      * @param newColumn - The name of the new column where the computed Z-scores will be stored.
      * @param options - An optional object with configuration options:
@@ -3478,8 +3442,6 @@ class SimpleTable extends Simple {
     /**
      * Normalizes the values in a column using min-max normalization.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column in which values will be normalized.
      * @param newColumn - The name of the new column where normalized values will be stored.
      * @param options - An optional object with configuration options:
@@ -3524,8 +3486,6 @@ class SimpleTable extends Simple {
      *
      * Exact temporal references are compared at their full DuckDB precision. JavaScript `Date` objects only have millisecond precision and always represent an instant. Construct them with an explicit timezone, such as `new Date("2001-01-01T00:00:00Z")`; date-time strings without `Z` or an offset use the user's local timezone.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The numeric column containing the values to index.
      * @param newColumn - The name of the new column where indexed values will be stored.
      * @param reference - A statistic calculated from `column`, a column and exact non-null `equals` value selecting a row, or a column and `at` set to `min` or `max` selecting its unique extreme row. The selected row's `column` value becomes the reference.
@@ -3583,48 +3543,84 @@ class SimpleTable extends Simple {
     /**
      * Updates data in the table using a JavaScript function. The function receives the existing rows as an array of objects and must return the modified rows as an 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.
-     * This method does not work with tables containing geometries.
+     * Before writing a JavaScript callback, check for an existing SDA method that
+     * performs the same operation; it will usually be faster and more efficient.
      *
-     * This method queues the update; the dataModifier function runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * If the table has geometry columns, the callback can read and modify their
+     * GeoJSON geometry objects directly. Extra properties added to these objects
+     * are ignored; create new columns on the returned rows to store additional
+     * attributes. All geometry columns must use EPSG:4326; use reproject() first
+     * if needed.
      *
      * @param dataModifier - A synchronous or asynchronous function that takes the existing rows (as an array of objects) and returns the modified rows (as an array of objects).
      * @param options - An optional object with configuration options:
-     * @param options.batchSize - If provided, rows are processed in batches of this size instead of all at once, so large tables don't have to be materialized entirely in memory. The modifier function is called once per batch.
+     * @param options.batchSize - If provided, rows are processed in batches of this size instead of all at once, so large tables don't have to be materialized entirely in memory. This limits input rows per batch, but does not eliminate conversion work or bound geometry size or callback output expansion. The modifier function is called once per batch. Tables with a column named `rowid` or `__sda_rowid` (case-insensitive) are rejected before the modifier runs; rename the column or omit batchSize.
+     * @param options.columnTypes - Explicit types for newly added columns, following loadArray's columnTypes contract. Declare geometry as GEOMETRY('EPSG:4326'); geometry is never inferred from object shape. Existing columns cannot be redeclared.
      * @returns The table, so methods can be chained.
      * @category Updating Data
      *
      * @example
      * ```ts
-     * // Extract hostnames with JavaScript's URL parser.
-     * const table = await sdb
-     *   .newTable()
-     *   .loadData("websites.csv")
-     *   .updateWithJS((rows) => {
-     *     return rows.map((row) => ({
-     *       ...row,
-     *       hostname: typeof row.url === "string"
-     *         ? new URL(row.url).hostname
-     *         : null,
-     *     }));
-     *   })
+     * // Double the value in each row with a JavaScript callback.
+     * await table.loadArray([{ value: 1 }, { value: 2 }])
+     *   .updateWithJS((rows) => rows.map((row) => ({
+     *     value: Number(row.value) * 2,
+     *   })))
      *   .log();
      * ```
      *
      * @example
      * ```ts
-     * // Enrich reviews with scores from an external service, 100 at a time.
-     * const reviews = await table
-     *   .updateWithJS(async (rows) => {
-     *     const response = await fetch("https://api.example.com/score", {
-     *       method: "POST",
-     *       headers: { "content-type": "application/json" },
-     *       body: JSON.stringify(rows.map((row) => row.review)),
-     *     });
-     *     const scores = await response.json() as number[];
-     *     return rows.map((row, index) => ({ ...row, score: scores[index] }));
-     *   }, { batchSize: 100 })
+     * // Process two rows per callback to limit how many rows are handled at once.
+     * await table.loadArray([{ value: 1 }, { value: 2 }, { value: 3 }])
+     *   .updateWithJS((rows) => rows.map((row) => ({
+     *     value: Number(row.value) * 2,
+     *   })), { batchSize: 2 })
      *   .log();
      * ```
+     *
+     * @example
+     * ```ts
+     * // Add a JSON object column to keep related attributes together.
+     * await table.loadArray([{ name: "Station" }])
+     *   .updateWithJS((rows) => rows.map((row) => ({
+     *     ...row, details: { active: true, category: "weather" },
+     *   })), { columnTypes: { details: "JSON" } })
+     *   .log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Add a three-element float vector, such as an embedding.
+     * await table.loadArray([{ name: "Station" }])
+     *   .updateWithJS((rows) => rows.map((row) => ({
+     *     ...row, embedding: [0.25, 0.5, 0.75],
+     *   })), { columnTypes: { embedding: "FLOAT[3]" } })
+     *   .log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Move each point slightly east by editing its longitude.
+     * await sdb.newTable().loadArray([{
+     *   geom: { type: "Point", coordinates: [-73, 45] },
+     * }], { columnTypes: { geom: "GEOMETRY('EPSG:4326')" } })
+     *   .updateWithJS((rows) => rows.map((row) => {
+     *     // This example loads only Points. Narrow the type for coordinate access.
+     *     const geom = row.geom as { type: "Point"; coordinates: number[] } | null;
+     *     if (geom !== null) geom.coordinates[0] += 0.01;
+     *     return row;
+     *   })).log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Create a geometry column from longitude and latitude values.
+     * await sdb.newTable().loadArray([{ longitude: -73, latitude: 45 }])
+     *   .updateWithJS((rows) => rows.map((row) => ({
+     *     ...row, geom: { type: "Point", coordinates: [row.longitude, row.latitude] },
+     *   })), { columnTypes: { geom: "GEOMETRY('EPSG:4326')" } }).log();
+     * ```
      */
     updateWithJS(dataModifier, options = {}) {
         updateWithJS(this, dataModifier, options);
@@ -3705,8 +3701,6 @@ class SimpleTable extends Simple {
      * Produces identical output to `journalism-format`'s `normalizeString()` function
      * for all common cases including accented Latin characters.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column The column containing the text to normalize
      * @param newColumn The column to store the normalized results
      * @param options Configuration options
@@ -3757,8 +3751,6 @@ class SimpleTable extends Simple {
      * Counts are based on Unicode code points, not grapheme clusters. A user-perceived character composed of multiple code points, such as some emoji or decomposed accented letters, counts as multiple characters.
      * `NULL` input values produce `NULL` counts.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to count.
      * @param newColumn - The name of the new column where the character counts will be stored.
      * @returns The table, so methods can be chained.
@@ -3778,8 +3770,6 @@ class SimpleTable extends Simple {
      * Adds a new column containing the word count for each string in the specified column.
      * A word is any contiguous sequence of non-whitespace characters. Spaces, tabs, and line breaks separate words. Punctuation is not removed, so a standalone punctuation sequence counts as a word. Text without whitespace counts as one word, regardless of language. Empty or whitespace-only strings produce `0`, and `NULL` input values produce `NULL` counts.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column containing the strings to count.
      * @param newColumn - The name of the new column where the word counts will be stored.
      * @returns The table, so methods can be chained.
@@ -3815,6 +3805,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns the number of rows in the table.
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param options - An optional object with configuration options:
      * @param options.conditions - The filtering conditions specified as a SQL `WHERE` clause (e.g., `"category = 'Book'"`).
@@ -4155,7 +4146,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns the first row of the table, optionally filtered by SQL conditions.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Temporal values use the same JavaScript representations as `getData()`.
      *
      * @param options - An optional object with configuration options:
@@ -4182,7 +4173,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns the last row of the table, optionally filtered by SQL conditions.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Temporal values use the same JavaScript representations as `getData()`.
      *
      * @param options - An optional object with configuration options:
@@ -4209,7 +4200,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns the top `n` rows of the table, optionally filtered by SQL conditions.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Temporal values use the same JavaScript representations as `getData()`.
      *
      * @param count - The number of rows to return from the top of the table.
@@ -4238,7 +4229,7 @@ class SimpleTable extends Simple {
     /**
      * Returns the bottom `n` rows of the table, optionally filtered by SQL conditions.
      * By default, the last row will be returned first. To preserve the original order, use the `originalOrder` option.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Temporal values use the same JavaScript representations as `getData()`.
      *
      * @param count - The number of rows to return from the bottom of the table.
@@ -4274,7 +4265,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns a single row that matches the specified conditions. If no row matches or if more than one row matches, an error is thrown by default.
-     * You can also use JavaScript syntax for conditions (e.g., `AND`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Temporal values use the same JavaScript representations as `getData()`.
      *
      * @param conditions - The conditions to match, specified as a SQL `WHERE` clause.
@@ -4319,13 +4310,26 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns the data from the table as an array of objects, optionally filtered by SQL conditions.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * Top-level DuckDB `DATE` and `TIMESTAMP` columns are returned as JavaScript
      * `Date` objects interpreted in UTC. `TIMESTAMP WITH TIME ZONE` values are
      * returned as UTC strings, preserving DuckDB's microsecond precision;
      * JavaScript `Date` supports only milliseconds.
      *
+     * Top-level `BIGINT`, `UBIGINT`, `HUGEINT`, and `UHUGEINT` columns are
+     * returned as JavaScript numbers. Values outside `Number.MIN_SAFE_INTEGER`
+     * through `Number.MAX_SAFE_INTEGER` throw instead of losing precision.
+     * Use `convert({ columnName: "string" })` before `getData()` to retrieve
+     * their exact digits as strings.
+     *
+     * SQL arrays and lists, including float vectors, return their actual elements
+     * as JavaScript arrays. Null cells and null elements remain null.
+     *
+     * Nested SQL lists and structs become JavaScript arrays and objects. Within
+     * them, `BIGINT`, `UBIGINT`, `HUGEINT`, `UHUGEINT`, and `DECIMAL` values remain
+     * strings to preserve precision, even for small integers.
+     *
      * @param options - An optional object with configuration options:
      * @param options.columns - An array of column names to include in the result. If omitted, all columns will be included.
      * @param options.conditions - The filtering conditions specified as a SQL `WHERE` clause (e.g., `"category = 'Book'"`).
@@ -4359,6 +4363,18 @@ class SimpleTable extends Simple {
      * // Return at most two rows.
      * const preview = await table.getData({ limit: 2 });
      * ```
+     *
+     * @example
+     * ```ts
+     * // Read nested integers without losing digits. SQL creates the nested types.
+     * await sdb.customQuery(`CREATE TABLE nested_example AS SELECT
+     *   [42::BIGINT, 9007199254740993::BIGINT] AS ids,
+     *   {'count': 2::INTEGER, 'amount': 123.450::DECIMAL(6,3)} AS details`);
+     * const nested = sdb.newTable("nested_example");
+     * const rows = await nested.getData();
+     * // [{ ids: ["42", "9007199254740993"], details: { count: 2, amount: "123.450" } }]
+     * await nested.log();
+     * ```
      */
     async getData(options = {}) {
         return await getData(this, options);
@@ -4367,6 +4383,7 @@ class SimpleTable extends Simple {
      * Streams the table rows one by one as an async iterator, without
      * materializing the whole table in memory. Values are converted to
      * JavaScript types the same way as `getData()`.
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * The underlying DuckDB result is streamed chunk by chunk, so tables
      * larger than the available memory can be iterated. Avoid running other
@@ -4399,7 +4416,7 @@ class SimpleTable extends Simple {
     }
     /**
      * Returns the data from the table as a CSV string, optionally filtered by SQL conditions.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      * Temporal values are first converted as they are in `getData()`, then
      * serialized using UTC date and timestamp text.
      *
@@ -4438,8 +4455,6 @@ class SimpleTable extends Simple {
     /**
      * Creates point geometries from latitude (y) and longitude (x) columns.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param latColumn - The name of the column storing the latitude (y-coordinate) values.
      * @param lonColumn - The name of the column storing the longitude (x-coordinate) values.
      * @param newColumn - The name of the new column where the point geometries will be stored.
@@ -4469,8 +4484,6 @@ class SimpleTable extends Simple {
     /**
      * Adds a column with boolean values indicating the validity of geometries.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the boolean results (`TRUE` for valid, `FALSE` for invalid) will be stored.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries to be checked. If omitted, the method will automatically attempt to find a geometry column.
@@ -4497,8 +4510,6 @@ class SimpleTable extends Simple {
     /**
      * Adds a column with the number of vertices (points) in each geometry.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the vertex counts will be stored.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -4525,8 +4536,6 @@ class SimpleTable extends Simple {
     /**
      * Attempts to make invalid geometries valid without removing any vertices.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the geometries to be fixed. If omitted, the method will automatically attempt to find a geometry column.
      * @returns The table, so methods can be chained.
      * @category Geospatial
@@ -4550,8 +4559,6 @@ class SimpleTable extends Simple {
     /**
      * Adds a column with boolean values indicating whether geometries are closed (e.g., polygons) or open (e.g., linestrings).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the boolean results (`TRUE` for closed, `FALSE` for open) will be stored.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -4577,8 +4584,6 @@ class SimpleTable extends Simple {
     /**
      * Adds a column with the geometry type (e.g., `"POINT"`, `"LINESTRING"`, `"POLYGON"`) for each geometry.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the geometry types will be stored.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -4605,8 +4610,6 @@ class SimpleTable extends Simple {
      * Flips the coordinate order of geometries in a specified column (e.g., from `[longitude (x), latitude (y)]` to `[latitude (y), longitude (x)]` or vice-versa).
      * **Warning:** This method should be used with caution as it directly manipulates coordinate order and can affect the accuracy of geospatial operations if not used correctly.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
      * @returns The table, so methods can be chained.
      * @category Geospatial
@@ -4632,7 +4635,7 @@ class SimpleTable extends Simple {
      *
      * Points are sampled uniformly within the requested distance using the spherical direct geodesic (destination-point) formula and the same spherical Earth model as DuckDB's `ST_Distance_Sphere()`. This accounts for longitude scale changing with latitude. This method adds random jitter; it does not provide anonymization or differential privacy guarantees.
      *
-     * This method supports only `POINT` geometries in `EPSG:4326`. Null and empty geometries are preserved. It queues the operation; the operation runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * This method supports only `POINT` geometries in `EPSG:4326`. Null and empty geometries are preserved.
      *
      * @param maxDistance - The maximum great-circle displacement in the selected unit. Must be a finite number greater than or equal to `0` and no greater than half Earth's circumference.
      * @param options - An optional object with configuration options:
@@ -4665,8 +4668,6 @@ class SimpleTable extends Simple {
     /**
      * Reduces the precision of geometries in a specified column to a given number of decimal places.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param decimals - The number of decimal places to keep in the coordinates of the geometries.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -4692,8 +4693,6 @@ class SimpleTable extends Simple {
     /**
      * Reprojects the geometries in a specified column to another Spatial Reference System (SRS).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param crs - The target SRS (e.g., `"EPSG:3347"`, or `"EPSG:4326"` for EPSG:4326 (WGS84)).
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -4720,8 +4719,6 @@ class SimpleTable extends Simple {
      * Computes the area of geometries in square meters (`"m2"`) or optionally square kilometers (`"km2"`).
      * The input geometry is assumed to be in EPSG:4326 (WGS84).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the computed areas will be stored.
      * @param options - An optional object with configuration options:
      * @param options.unit - The unit for the computed area: `"m2"` (square meters) or `"km2"` (square kilometers). Defaults to `"m2"`.
@@ -4762,8 +4759,6 @@ class SimpleTable extends Simple {
      * Computes the length of line geometries in meters (`"m"`) or optionally kilometers (`"km"`).
      * The input geometry is assumed to be in EPSG:4326 (WGS84).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the computed lengths will be stored.
      * @param options - An optional object with configuration options:
      * @param options.unit - The unit for the computed length: `"m"` (meters) or `"km"` (kilometers). Defaults to `"m"`.
@@ -4804,8 +4799,6 @@ class SimpleTable extends Simple {
      * Computes the perimeter of polygon geometries in meters (`"m"`) or optionally kilometers (`"km"`).
      * The input geometry is assumed to be in EPSG:4326 (WGS84).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the computed perimeters will be stored.
      * @param options - An optional object with configuration options:
      * @param options.unit - The unit for the computed perimeter: `"m"` (meters) or `"km"` (kilometers). Defaults to `"m"`.
@@ -4846,8 +4839,6 @@ class SimpleTable extends Simple {
      * Computes a buffer (a polygon representing a specified distance around a geometry) for geometries in a specified column.
      * The distance is in the Spatial Reference System (SRS) unit of the input geometries.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the buffered geometries will be stored.
      * @param distance - The distance for the buffer. This value is in the units of the geometry's SRS.
      * @param options - An optional object with configuration options:
@@ -4875,7 +4866,6 @@ class SimpleTable extends Simple {
      * Merges the data of this table (considered the left table) with another table (the right table) based on a spatial relationship.
      * Note that the order of rows in the returned data is not guaranteed to be the same as in the original tables.
      * This operation might create temporary files in a `.tmp` folder; consider adding `.tmp` to your `.gitignore`.
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called. The join uses the other table's state as of this call: operations queued on it afterwards run after the join.
      *
      * @param rightTable - The SimpleTable instance to be joined with this table.
      * @param method - The spatial join method to use: `"intersect"` (geometries overlap), `"inside"` (geometries of the left table are entirely within geometries of the right table), or `"withinDistance"` (geometries of the left table are within a specified distance of geometries in the right table).
@@ -4947,8 +4937,6 @@ class SimpleTable extends Simple {
     /**
      * Computes the intersection of two sets of geometries, creating new geometries where they overlap.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column1 - The name of the first column storing geometries.
      * @param column2 - The name of the second column storing geometries. Both columns must have the same projection.
      * @param newColumn - The name of the new column where the computed intersection geometries will be stored.
@@ -4968,8 +4956,6 @@ class SimpleTable extends Simple {
     /**
      * Computes the geometric difference between two geometries, returning the portion of the first geometry that does not intersect the second.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column1 - The name of the column storing the geometries from which the second geometries will be subtracted.
      * @param column2 - The name of the column storing the geometries to subtract. Both columns must have the same projection.
      * @param newColumn - The name of the new column where the geometric differences will be stored.
@@ -4989,8 +4975,6 @@ class SimpleTable extends Simple {
     /**
      * Fills holes in polygon geometries.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
      * @returns The table, so methods can be chained.
      * @category Geospatial
@@ -5014,8 +4998,6 @@ class SimpleTable extends Simple {
     /**
      * Returns `TRUE` if two geometries intersect (overlap in any way), and `FALSE` otherwise.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column1 - The name of the first column storing geometries.
      * @param column2 - The name of the second column storing geometries. Both columns must have the same projection.
      * @param newColumn - The name of the new column where the boolean results (`TRUE` for intersection, `FALSE` otherwise) will be stored.
@@ -5035,8 +5017,6 @@ class SimpleTable extends Simple {
     /**
      * Returns `TRUE` if every point of a geometry in `column` is covered by a geometry in `containerColumn`, including their boundaries, and `FALSE` otherwise.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the geometries to be tested for containment.
      * @param containerColumn - The name of the column storing the geometries to be tested as containers. Both columns must have the same projection.
      * @param newColumn - The name of the new column where the boolean results (`TRUE` when covered, `FALSE` otherwise) will be stored.
@@ -5056,8 +5036,6 @@ class SimpleTable extends Simple {
     /**
      * Computes the union of two geometries, creating a new geometry that represents the merged area of both.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column1 - The name of the first column storing geometries.
      * @param column2 - The name of the second column storing geometries. Both columns must have the same projection.
      * @param newColumn - The name of the new column where the computed union geometries will be stored.
@@ -5078,8 +5056,6 @@ class SimpleTable extends Simple {
      * Extracts the latitude (y) and longitude (x) coordinates from point geometries.
      * The input geometry is assumed to be in EPSG:4326 (WGS84).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the point geometries.
      * @param latColumn - The name of the new column where the extracted latitude (y-coordinate) values will be stored.
      * @param lonColumn - The name of the new column where the extracted longitude (x-coordinate) values will be stored.
@@ -5099,8 +5075,6 @@ class SimpleTable extends Simple {
     /**
      * Simplifies geometries while preserving their overall coverage. A higher tolerance results in more significant simplification.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param tolerance - A numeric value representing the simplification tolerance. A higher value leads to greater simplification.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -5128,8 +5102,6 @@ class SimpleTable extends Simple {
      * Computes the centroid of geometries.
      * The values are returned in the SRS unit of the input geometries.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the computed centroid geometries will be stored.
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -5155,8 +5127,6 @@ class SimpleTable extends Simple {
     /**
      * Generates a random point within the geometries of a specified column.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param newColumn - The name of the new column where the random points will be stored.
      * @param tries - The number of points to generate within the bounding box of each geometry to find one that is within the geometry itself.
      * @param options - An optional object with configuration options:
@@ -5191,8 +5161,6 @@ class SimpleTable extends Simple {
      * You can optionally specify `"spheroid"` or `"haversine"` methods to get results in meters or kilometers.
      * If using `"spheroid"` or `"haversine"`, the input geometries must be in EPSG:4326 (WGS84).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column1 - The name of the first column storing geometries.
      * @param column2 - The name of the second column storing geometries.
      * @param newColumn - The name of the new column where the computed distances will be stored.
@@ -5237,8 +5205,6 @@ class SimpleTable extends Simple {
     /**
      * Unnests geometries recursively, transforming multi-part geometries (e.g., MultiPolygon) into individual single-part geometries (e.g., Polygon).
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the geometries to be unnested. If omitted, the method will automatically attempt to find a geometry column.
      * @returns The table, so methods can be chained.
      * @category Geospatial
@@ -5262,8 +5228,6 @@ class SimpleTable extends Simple {
     /**
      * Adds the bounding box coordinates of geometries in a specified column as four new columns: `minLon`, `minLat`, `maxLon`, and `maxLat`.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries for which the bounding box will be computed. If omitted, the method will automatically attempt to find a geometry column.
      * @param options.decimals - The number of decimal places to round the bounding box coordinates. Defaults to `undefined` (no rounding).
@@ -5291,8 +5255,6 @@ class SimpleTable extends Simple {
     /**
      * Aggregates geometries in a specified column based on a chosen aggregation method.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param method - The aggregation method to apply: `"union"` (combines all geometries into a single multi-geometry) or `"intersection"` (computes the intersection of all geometries).
      * @param options - An optional object with configuration options:
      * @param options.column - The name of the column storing the geometries to be aggregated. If omitted, the method will automatically attempt to find a geometry column.
@@ -5325,8 +5287,6 @@ class SimpleTable extends Simple {
     /**
      * Transforms closed linestring geometries into polygon geometries.
      *
-     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
-     *
      * @param column - The name of the column storing the linestring geometries. If omitted, the method will automatically attempt to find a geometry column.
      * @returns The table, so methods can be chained.
      * @category Geospatial
@@ -5373,7 +5333,9 @@ class SimpleTable extends Simple {
         return await getBoundingBox(this, column);
     }
     /**
-     * Returns the table's geospatial data as a GeoJSON object.
+     * Returns the table's geospatial data as a GeoJSON FeatureCollection.
+     * Each row becomes a Feature: the selected geometry column becomes its geometry,
+     * and the remaining columns become its properties.
      * If the table has multiple geometry columns, you must specify which one to use.
      *
      * @param column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
@@ -5411,12 +5373,13 @@ class SimpleTable extends Simple {
     }
     /**
      * Writes the table's data to a file in various formats (CSV, JSON, Parquet, DuckDB, SQLite).
+     * Tables with geometry columns must use `writeGeoData()` instead.
      * If the specified path does not exist, it will be created.
      *
      * @param file - The absolute path to the output file (e.g., `"./output.csv"`, `"./output.json"`).
      * @param options - An optional object with configuration options:
      * @param options.compression - A boolean indicating whether to compress the output file. If `true`, CSV and JSON files will be compressed with GZIP, while Parquet files will use ZSTD. Defaults to `false`.
-     * @param options.dataAsArrays - For JSON files only. If `true`, JSON files are written as a single object with arrays for each column (e.g., `{ "col1": [v1, v2], "col2": [v3, v4] }`) instead of an array of objects. This can reduce file size for web projects. You can use the `arraysToData` function from the [journalism library](https://jsr.io/@nshiab/journalism/doc/~/arraysToData) to convert it back.
+     * @param options.dataAsArrays - For JSON files only. If `true`, JSON files are written as a single object with arrays for each column (e.g., `{ "col1": [v1, v2], "col2": [v3, v4] }`) instead of an array of objects. This can reduce file size for web projects. You can use the `arraysToData` function from the [journalism-format library](https://jsr.io/@nshiab/journalism-format/doc/~/arraysToData) to convert it back.
      * @param options.formatDates - For CSV and JSON files only. If `true`, date and timestamp columns will be formatted as ISO 8601 strings (e.g., `"2025-01-01T01:00:00.000Z"`). Defaults to `false`.
      * @returns A promise that resolves to the table, so methods can be chained.
      * @category File Operations
@@ -5517,28 +5480,28 @@ class SimpleTable extends Simple {
      * Caches the results of computations in `./.sda-cache`.
      * You should add `./.sda-cache` to your `.gitignore` file.
      *
-     * Cache entries are stored as DuckDB database files. Full-text search (FTS)
-     * indexes are persisted in the cache file and restored directly on a cache
-     * hit. Vector similarity search (VSS/HNSW) indexes are not persisted in the
-     * cache file; their definitions are stored as metadata and used to rebuild
-     * the indexes on every cache hit. If loading the entry or restoring its
-     * indexes fails, the computation runs again and replaces the cache entry.
-     *
      * `cache()` automatically tracks whether earlier SDA operations changed the
      * table. It also records every other already registered `SimpleTable` read
      * through `SimpleTable` methods while `compute` runs and invalidates the
      * cached step when any of their generations change. Tables created inside
      * `compute` are part of the computation itself and are not dependencies.
      *
+     * Inside `compute`, you may modify the table being cached and create or
+     * modify temporary tables, provided you remove them before the callback
+     * finishes. Other tables that already existed may be read but not modified,
+     * renamed, or removed. `customQuery()` bypasses enforcement of these rules.
+     *
      * `SimpleDB.customQuery()` bypasses this tracking. Reading or changing a
      * table with `customQuery()` can therefore return stale cached data. Include
      * a value that identifies the custom query's dependencies in `options.inputs`
      * (such as a table content hash), or use tracked `SimpleTable` methods.
      *
-     * `compute` may modify only the table being cached. Other tables that existed
-     * before `compute` must remain read-only. Temporary tables may be created and
-     * modified inside `compute`, but they must be removed before it finishes
-     * because a cache hit does not run `compute` again.
+     * Cache entries are stored as DuckDB database files. Full-text search (FTS)
+     * indexes are persisted in the cache file and restored directly on a cache
+     * hit. Vector similarity search (VSS/HNSW) indexes are not persisted in the
+     * cache file; their definitions are stored as metadata and used to rebuild
+     * the indexes on every cache hit. If loading the entry or restoring its
+     * indexes fails, the computation runs again and replaces the cache entry.
      *
      * @param compute - A function wrapping the computations to be cached. It receives the table on which `cache()` was called. This function will be executed on the first run or if the cached data is invalid/expired.
      * @param options - An optional object with configuration options:
@@ -5623,7 +5586,16 @@ class SimpleTable extends Simple {
     /**
      * Logs a specified number of rows from the table to the console. By default, the first 10 rows are logged.
      * You can optionally log the column types and filter the data based on conditions.
-     * You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
+     * SQL dates and timestamps retain their native precision for display, including
+     * temporal infinities. Lists and objects are stringified using the same nested
+     * representations as `getData()`, then truncated according to `charsToLog`.
+     * Unsafe top-level large integers throw, just as with `getData()`.
+     * Type annotations describe the SQL type and the JavaScript extraction type
+     * before display formatting; nulls do not determine the column's annotation.
+     * Colors reflect the SQL value's meaning, so exact decimal strings use numeric
+     * coloring. Column width is independent of the content truncation budget.
+     *
+     * With the default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
      *
      * @param options - Either the number of rows to log (a specific number or `"all"`) or an object with configuration options:
      * @param options.count - The number of rows to log. Defaults to 10 or the value set in the SimpleDB instance. Use `"all"` to log all rows.
@@ -5663,57 +5635,7 @@ class SimpleTable extends Simple {
      * ```
      */
     async log(options = {}) {
-        if (this.connection === undefined) {
-            await this.sdb.start();
-            this.db = this.sdb.db;
-            this.connection = this.sdb.connection;
-        }
-        if (this.connection === undefined) {
-            throw new Error("this.connection is undefined");
-        }
-        let count;
-        if (typeof options === "number") {
-            count = options;
-        }
-        else if (options === "all") {
-            count = await this.getRowCount();
-        }
-        else if (typeof options === "object") {
-            if (options.count === "all") {
-                count = await this.getRowCount();
-            }
-            else if (typeof options.count === "number") {
-                count = options.count;
-            }
-            else {
-                count = this.rowsToLog;
-            }
-        }
-        else {
-            count = this.rowsToLog;
-        }
-        const types = typeof options === "object"
-            ? options.types ?? this.typesToLog
-            : this.typesToLog;
-        const conditions = typeof options === "object"
-            ? options.conditions ?? undefined
-            : undefined;
-        if (this.connection === undefined ||
-            !(await this.sdb.hasTable(this.name))) {
-            console.log(`\nTable ${this.name}: no data`);
-        }
-        else {
-            console.log(`\nTable ${this.name}:`);
-            conditions && console.log(`Conditions: ${conditions}`);
-            const data = await this.getTop(count, { conditions });
-            logData(types ? await this.getTypes() : null, data, this.charsToLog);
-            const rowCount = conditions
-                ? parseInt((await this.sdb.customQuery(`select count(*) as count from ${quoteIdentifier(this.name)} where ${conditions}`, { returnData: true }))[0].count)
-                : await this.getRowCount();
-            console.log(`${formatNumber(rowCount)} rows in total ${`(count: ${count}${typeof this.charsToLog === "number"
-                ? `, charsToLog: ${this.charsToLog}`
-                : ""})`}`);
-        }
+        await log(this, options);
         return this;
     }
     /**
@@ -5915,6 +5837,10 @@ class SimpleTable extends Simple {
     /**
      * Logs the bottom `n` rows of the table to the console. By default, the last row will be returned first. To preserve the original order, use the `originalOrder` option.
      *
+     * Uses the same precision-preserving temporal display, nested stringification,
+     * numeric coloring, and `charsToLog` truncation as `log()`. Unsafe top-level
+     * large integers throw, just as with `getData()`.
+     *
      * @param count - The number of rows to log from the bottom of the table. Defaults to the table's `rowsToLog` option if not specified.
      * @param options - An optional object with logging preferences.
      * @param options.originalOrder - If true, the rows are displayed in their original order (top to bottom). Defaults to false.
@@ -5940,10 +5866,7 @@ class SimpleTable extends Simple {
      * ```
      */
     async logBottom(count, options = {}) {
-        const rows = count ?? this.rowsToLog;
-        console.log(`\nTable ${this.name} (${rows} bottom rows):`);
-        const data = await this.getBottom(rows, options);
-        logData(null, data, this.charsToLog);
+        await logBottom(this, count, options);
         return this;
     }
     /**