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

package/llm.md

@@ -1,7 +1,7 @@
 # The Simple Data Analysis (Core) Library
 
 - Package: `@nshiab/simple-data-analysis-core`
-- Version: `2.0.4`
+- Version: `2.0.6`
 
 To install the library with Deno, use:
 
@@ -91,12 +91,16 @@ schema is reserved for versioned SDA metadata. SQLite files can be imported with
 - **`options.logDuration`**: A flag indicating whether to log the total
   execution duration.
 - **`options.rowsToLog`**: The number of rows to display when logging a table.
-- **`options.charsToLog`**: The maximum number of characters to display for
-  text-based cells.
+- **`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.
 - **`options.typesToLog`**: A flag indicating whether to include data types when
   logging a table.
 - **`options.cacheVerbose`**: Whether to log cache hits and misses, code and
   input changes, TTL status, and cache read/write timing.
+- **`options.expressionSyntax`**: Operator syntax for expressions and custom
+  queries: `"js"` (default) translates JavaScript-style operators in SQL
+  expressions; `"sql"` preserves SQL unchanged.
 - **`options.logSQL`**: A flag indicating whether to log SQL immediately before
   execution.
 - **`options.explainSQL`**: A flag indicating whether to log DuckDB query plans
@@ -116,7 +120,8 @@ schema is reserved for versioned SDA metadata. SQLite files can be imported with
 
 #### `newTable`
 
-Creates a new SimpleTable instance within the database.
+Creates a new SimpleTable instance within the database. The name must be unique
+among registered tables, ignoring ASCII letter case.
 
 ##### Signature
 
@@ -385,9 +390,11 @@ console.log(extensions); // Output: [{ extension_name: "spatial", loaded: true,
 
 #### `customQuery`
 
-Executes a custom SQL query directly against the DuckDB instance. Queries run in
-UTC. When data is returned, temporal values use the same JavaScript
-representations as `SimpleTable.getData()`.
+Executes a custom SQL query directly against the DuckDB instance. With the
+default `SimpleDB.expressionSyntax: "js"`, queries support JavaScript-style
+operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for
+unchanged SQL. Queries run in UTC. When data is returned, temporal values use
+the same JavaScript representations as `SimpleTable.getData()`.
 
 `customQuery()` bypasses the dependency and table-generation tracking used by
 `SimpleTable.cache()`. Reading or changing a table with `customQuery()` can
@@ -643,8 +650,9 @@ Creates an instance of SimpleTable.
 - **`simpleDB`**: The SimpleDB instance that this table belongs to.
 - **`options`**: An optional object with configuration options:
 - **`options.rowsToLog`**: The number of rows to log when displaying table data.
-- **`options.charsToLog`**: The maximum number of characters to log for strings.
-  Useful to avoid logging large text content.
+- **`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.
 - **`options.typesToLog`**: A boolean indicating whether to include data types
   when logging a table.
 
@@ -701,7 +709,8 @@ await table.log();
 
 #### `renameTable`
 
-Renames the current table.
+Renames the current table. The new name must not belong to another registered
+table, ignoring ASCII letter case.
 
 ##### Signature
 
@@ -731,19 +740,17 @@ 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.
-
 ##### Signature
 
 ```typescript
-setTypes(types: Record<string, "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | geometry('${string}') | GEOMETRY('${string}')>): this;
+setTypes(types: Record<string, "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | "json" | "JSON" | float[${number}] | FLOAT[${number}] | geometry('${string}') | GEOMETRY('${string}')>): this;
 ```
 
 ##### Parameters
 
 - **`types`**: An object specifying the column names and their target data types
-  (JavaScript or SQL types).
+  (JavaScript or SQL types), including JSON, FLOAT[n] vectors, and GEOMETRY with
+  a CRS.
 
 ##### Returns
 
@@ -760,27 +767,44 @@ await table.setTypes({
 }).log();
 ```
 
+```ts
+// Create an empty table with JSON, embedding, and geometry columns.
+await table.setTypes({
+  details: "JSON",
+  embedding: "FLOAT[3]",
+  geom: "GEOMETRY('EPSG:4326')",
+}).log();
+```
+
 #### `loadArray`
 
-Loads an array of JavaScript objects into the table. 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.
 
 ##### Signature
 
 ```typescript
-loadArray(rows: Record<string, unknown>[]): this;
+loadArray(rows: Record<string, unknown>[], options?: { columnTypes?: Record<string, "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | "INTEGER" | "BIGINT" | "DOUBLE" | "VARCHAR" | "BOOLEAN" | "DATE" | "TIME" | "TIMESTAMP" | "TIMESTAMP WITH TIME ZONE" | "GEOMETRY('EPSG:4326')" | "geometry('EPSG:4326')" | "JSON" | "json" | FLOAT[${number}] | float[${number}]> }): this;
 ```
 
 ##### Parameters
 
 - **`rows`**: An array of objects, where each object represents a row and its
   properties represent columns.
+- **`options`**: Options for loading the array, captured when called.
+- **`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
 
@@ -789,7 +813,7 @@ The table, so methods can be chained.
 ##### Examples
 
 ```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 },
@@ -798,19 +822,53 @@ await table.loadArray(data).log();
 ```
 
 ```ts
-// The offset determines the instant; the loaded TIMESTAMP is returned as
-// the equivalent UTC JavaScript Date.
+// 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" } },
+).log();
+```
+
+```ts
+// 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();
 ```
 
+```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();
+```
+
+```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();
+```
+
+```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();
+```
+
 #### `loadData`
 
 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.
+formats include CSV, JSON, Parquet, and Excel.
+
+With the default `SimpleDB.expressionSyntax: "js"`, conditions support
+JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set
+`expressionSyntax: "sql"` for unchanged SQL.
 
 ##### Signature
 
@@ -828,10 +886,8 @@ loadData(files: string | string[], options?: { fileType?: "csv" | "dsv" | "json"
 - **`options.autoDetect`**: A boolean indicating whether to automatically detect
   the data format. Defaults to `true`.
 - **`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.
+  keyword, to filter source rows before applying `limit`. Can reference source
+  columns excluded from `columns`.
 - **`options.limit`**: A number indicating the maximum number of matching rows
   to load, after applying `conditions` if provided. Defaults to all matching
   rows.
@@ -841,7 +897,8 @@ loadData(files: string | string[], options?: { fileType?: "csv" | "dsv" | "json"
   across multiple files when their structures differ. Missing columns will be
   filled with `NULL` values. Defaults to `false`.
 - **`options.columnTypes`**: An object mapping column names to their expected
-  data types. By default, types are inferred.
+  data types. By default, types are inferred. Geometry types are not supported;
+  use loadGeoData() instead.
 - **`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
@@ -931,9 +988,7 @@ await table
 
 #### `loadStatCanData`
 
-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.
+Downloads a complete Statistics Canada table and loads it into this table.
 
 Results are cached as Parquet files in `.sda-cache/statcan` by default. Cached
 data does not expire unless a TTL is provided.
@@ -979,12 +1034,81 @@ await table
   .log();
 ```
 
-#### `loadGeoData`
+#### `loadYahooFinanceData`
 
-Loads geospatial data from an external file or URL into the table.
+Downloads historical market data from Yahoo Finance and loads it into this table
+as `datetime`, `open`, `high`, `low`, `close`, `adjustedClose`, and `volume`
+columns. `datetime` contains Yahoo's timestamps as JavaScript `Date` values.
+Unavailable values are preserved as `null`.
 
-This method queues the operation; it runs when an async observer method (like
-`getData()` or `log()`) is awaited, or when `run()` is called.
+All range boundaries are evaluated in UTC. Use ISO date-time strings ending in
+`Z`. Yahoo trading sessions may occur on a different UTC date from their
+exchange-local date, so choose the range appropriate for the market and
+interval. Avoid numeric constructors such as `new Date(2025, 2, 15)`, which use
+the runtime's local timezone.
+
+This method uses an undocumented Yahoo Finance endpoint and is not affiliated
+with or endorsed by Yahoo. It is provided for educational, research, and
+journalistic purposes. Before using it, review Yahoo's terms and any applicable
+data-provider restrictions.
+
+##### Signature
+
+```typescript
+loadYahooFinanceData(symbol: string, startDate: Date, endDate: Date, interval: "1d" | "1h" | "1m"): this;
+```
+
+##### Parameters
+
+- **`symbol`**: The stock or index symbol, such as `"AAPL"` or `"^GSPTSE"`.
+- **`startDate`**: The inclusive UTC start of the requested range.
+- **`endDate`**: The inclusive UTC end of the requested range. The UTC day,
+  hour, or minute containing this instant is included, according to `interval`.
+- **`interval`**: The interval between observations: daily, hourly, or every
+  minute.
+
+##### Returns
+
+The table, so methods can be chained.
+
+##### Throws
+
+- **`RangeError`**: If either date is invalid or `endDate` is before
+  `startDate`.
+- **`Error`**: If Yahoo rejects the request or returns no data.
+
+##### Examples
+
+```ts
+// Request daily observations using explicit UTC boundaries.
+await table
+  .loadYahooFinanceData(
+    "^GSPTSE",
+    new Date("2025-03-01T00:00:00Z"),
+    new Date("2025-03-15T00:00:00Z"),
+    "1d",
+  )
+  .log();
+```
+
+```ts
+// Include the UTC hours from 13:00 through 16:00.
+await table
+  .loadYahooFinanceData(
+    "AAPL",
+    new Date("2025-03-14T13:00:00Z"),
+    new Date("2025-03-14T16:00:00Z"),
+    "1h",
+  )
+  .log();
+```
+
+#### `loadGeoData`
+
+Loads geospatial data from an external file or URL into the table. With the
+default `SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style
+operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for
+unchanged SQL.
 
 ##### Signature
 
@@ -1003,11 +1127,9 @@ loadGeoData(file: string, options?: { toEPSG4326?: boolean; columns?: string[];
   should remain in the resulting table, usually `"geom"`. By default, all
   columns are loaded.
 - **`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.
+  keyword, to filter source rows before materialization and reprojection. Can
+  reference source columns excluded from `columns`. Geometry conditions use the
+  source coordinate system.
 
 ##### Returns
 
@@ -1060,8 +1182,7 @@ await table
 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.
+matching features.
 
 DuckDB's
 [Osmium community extension](https://duckdb.org/community_extensions/extensions/osmium)
@@ -1194,9 +1315,6 @@ method requires an FTS index and creates one automatically when needed. 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.
-
 ##### Signature
 
 ```typescript
@@ -1270,9 +1388,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -1347,9 +1462,6 @@ It reuses the table's existing FTS index unless `overwriteIndex` is `true`.
 DuckDB FTS indexes do not update automatically when the source table 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.
-
 ##### Signature
 
 ```typescript
@@ -1472,9 +1584,6 @@ await table.bm25("italian sauce", "Dish", "Recipe", 5, {
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -1505,9 +1614,7 @@ await table.insertRows(newRows).log();
 
 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.
+is set to `true`.
 
 ##### Signature
 
@@ -1549,9 +1656,6 @@ await tableA.insertTables(["tableB", "tableC"], { unifyColumns: true }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -1583,7 +1687,10 @@ await table.loadSample("fires").log();
 #### `clone`
 
 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.
+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`
@@ -1591,9 +1698,6 @@ order: `conditions` (WHERE clause) first, then `offset`, and finally `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.
-
 ##### Signature
 
 ```typescript
@@ -1674,9 +1778,6 @@ const tableB = await tableA.clone({
 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.
-
 ##### Signature
 
 ```typescript
@@ -1709,9 +1810,6 @@ different time points.
 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.
-
 ##### Signature
 
 ```typescript
@@ -1776,9 +1874,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -1852,11 +1947,9 @@ 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.
 
 ##### Signature
 
@@ -1902,9 +1995,7 @@ await table.sort({ column1: "asc" }, { lang: { column1: "fr" } }).log();
 
 #### `selectColumns`
 
-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.
 
 ##### Signature
 
@@ -1936,9 +2027,6 @@ await table.selectColumns("productName").log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -1991,9 +2079,6 @@ console.log(hasAgeColumn); // Output: true or false
 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.
-
 ##### Signature
 
 ```typescript
@@ -2035,9 +2120,6 @@ await table.sample("10%", { seed: 123 }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -2089,9 +2171,6 @@ const topCustomersTable = await table.selectRows(75, {
 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.
-
 ##### Signature
 
 ```typescript
@@ -2130,9 +2209,7 @@ await table.removeDuplicates({ on: ["firstName", "lastName"] }).log();
 
 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.
+`"NaN"`, `"undefined"`, and empty strings `""`.
 
 ##### Signature
 
@@ -2180,9 +2257,7 @@ await table.removeMissing({ columns: "age", missingValues: [-1] }).log();
 #### `trim`
 
 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.
+values in the given columns.
 
 ##### Signature
 
@@ -2224,10 +2299,9 @@ await table.trim(["description", "notes"], { side: "right" }).log();
 #### `filter`
 
 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.
+faster to use the `removeRows` method for simple removals. With the default
+`SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators
+(`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
 
 ##### Signature
 
@@ -2272,9 +2346,6 @@ await table.filter(`lastPurchaseDate >= '2023-01-01'`).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -2313,9 +2384,6 @@ await table.keepValues({ status: null }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -2354,11 +2422,9 @@ await table.removeValues({ status: null }).log();
 #### `removeRows`
 
 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.
+`filter()`, but removes rows instead of keeping them. With the default
+`SimpleDB.expressionSyntax: "js"`, conditions support JavaScript-style operators
+(`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
 
 ##### Signature
 
@@ -2404,9 +2470,6 @@ await table.removeRows(
 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.
-
 ##### Signature
 
 ```typescript
@@ -2450,9 +2513,6 @@ await table.renameColumns({ "product_id": "productId" }, { strict: false })
 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.
-
 ##### Signature
 
 ```typescript
@@ -2523,9 +2583,6 @@ The table will then look like this:
 | 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.
-
 #### `wider`
 
 Restructures this table by unstacking (pivoting) values, transforming data from
@@ -2584,9 +2641,6 @@ 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.
-
 #### `convert`
 
 Converts data types of specified columns to target types (JavaScript or SQL
@@ -2606,20 +2660,16 @@ UTC).
 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.
-
 ##### Signature
 
 ```typescript
-convert(types: Record<string, "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean">, options?: { strict?: boolean; datetimeFormat?: string }): this;
+convert(types: Record<string, "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | "json" | "JSON" | float[${number}] | FLOAT[${number}] | geometry('${string}') | GEOMETRY('${string}')>, options?: { strict?: boolean; datetimeFormat?: string }): this;
 ```
 
 ##### Parameters
 
 - **`types`**: An object mapping column names to their target data types for
-  conversion.
+  conversion, including JSON, FLOAT[n] vectors, and GEOMETRY with a CRS.
 - **`options`**: An optional object with configuration options:
 - **`options.strict`**: If `false`, values that cannot be converted will be
   replaced by `NULL` instead of throwing an error. Defaults to `true`.
@@ -2672,6 +2722,21 @@ await table.convert({ column3: "string" }, {
 await table.convert({ amount: "float" }, { strict: false }).log();
 ```
 
+```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();
+```
+
 #### `removeTable`
 
 Removes the table from the database. After this operation, invoking methods on
@@ -2696,9 +2761,7 @@ await table.removeTable();
 
 #### `removeColumns`
 
-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.
 
 ##### Signature
 
@@ -2729,21 +2792,22 @@ await table.removeColumns("tempColumn").log();
 #### `addColumn`
 
 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.
+types) and a SQL definition. With the default `SimpleDB.expressionSyntax: "js"`,
+expressions support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set
+`expressionSyntax: "sql"` for unchanged SQL.
 
 ##### Signature
 
 ```typescript
-addColumn(newColumn: string, type: "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | geometry('${string}') | GEOMETRY('${string}'), definition: string): this;
+addColumn(newColumn: string, type: "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | "json" | "JSON" | float[${number}] | FLOAT[${number}] | geometry('${string}') | GEOMETRY('${string}'), definition: string): this;
 ```
 
 ##### Parameters
 
 - **`newColumn`**: The name of the new column to be added.
 - **`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"`).
+  `"number"`, `"string"`) or a SQL type (e.g., `"integer"`, `"varchar"`,
+  `"JSON"`, `"FLOAT[3]"`, `"GEOMETRY('EPSG:4326')"`).
 - **`definition`**: A SQL expression defining how the values for the new column
   should be computed (e.g., `"column1 + column2"`,
   `"ST_Centroid(geom_column)"`).
@@ -2768,6 +2832,23 @@ await table.addColumn(
 ).log();
 ```
 
+```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();
+```
+
+```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();
+```
+
 #### `extractDatePart`
 
 Extracts one or more components from a temporal column into new columns. Pass a
@@ -2782,9 +2863,6 @@ time parts apply to times and timestamps. `NULL` input 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.
-
 ##### Signature
 
 ```typescript
@@ -2821,9 +2899,6 @@ await table.extractDatePart("publishedAt", {
 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.
-
 ##### Signature
 
 ```typescript
@@ -2860,9 +2935,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -2906,10 +2978,7 @@ 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.
+consider adding `.tmp` to your `.gitignore`.
 
 ##### Signature
 
@@ -2972,11 +3041,6 @@ order alphabetically by the left column and then by the right column.
 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.
-
 ##### Signature
 
 ```typescript
@@ -3061,9 +3125,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -3135,9 +3196,6 @@ await table.fuzzyClean("category", "category", 80, {
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -3195,9 +3253,7 @@ await table.replace("all", { "%": "" }).log();
 
 #### `lower`
 
-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.
 
 ##### Signature
 
@@ -3228,9 +3284,7 @@ await table.lower(["column1", "column2"]).log();
 
 #### `upper`
 
-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.
 
 ##### Signature
 
@@ -3262,9 +3316,7 @@ await table.upper(["column1", "column2"]).log();
 #### `capitalize`
 
 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.
+converts the rest of the string to lowercase.
 
 ##### Signature
 
@@ -3296,9 +3348,6 @@ await table.capitalize(["column1", "column2"]).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -3334,9 +3383,6 @@ The columns must contain string (VARCHAR) values. An error is thrown if any
 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.
-
 ##### Signature
 
 ```typescript
@@ -3386,9 +3432,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -3435,9 +3478,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -3482,9 +3522,6 @@ await table.splitSpread("data", "|", ["col1", "col2"], { strict: false }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -3514,9 +3551,6 @@ await table.firstChars("productCode", 2).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -3545,9 +3579,6 @@ await table.lastChars("productCode", 2).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -3590,9 +3621,6 @@ await table.replaceNulls("all", 0).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -3639,9 +3667,6 @@ All values must be string, otherwise an error will be thrown. Use the
 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.
-
 ##### Signature
 
 ```typescript
@@ -3701,9 +3726,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -3745,9 +3767,6 @@ Repeats rows based on the values in a column.
 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.
-
 ##### Signature
 
 ```typescript
@@ -3791,9 +3810,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -3834,9 +3850,6 @@ await table.nest("tags", ",", ["country", "city"]).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -3888,12 +3901,57 @@ await table.round(["columnA", "columnB"], { decimals: 1, method: "ceiling" })
 await table.round("column1", 2).log();
 ```
 
-#### `updateColumn`
+#### `addNoise`
+
+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.
 
-Updates values in a specified column using a SQL expression.
+##### Signature
 
-This method queues the operation; it runs when an async observer method (like
-`getData()` or `log()`) is awaited, or when `run()` is called.
+```typescript
+addNoise(columns: string | string[], max: number, options?: { onlyDuplicates?: boolean }): this;
+```
+
+##### Parameters
+
+- **`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.
+- **`max`**: The maximum absolute offset, expressed in each column's units. Must
+  be a finite number greater than or equal to `0`.
+- **`options`**: An optional object with configuration options:
+- **`options.onlyDuplicates`**: If `true`, adds noise only to values that occur
+  more than once in their column. Each selected column is evaluated
+  independently, and every occurrence of a duplicated value is changed. Defaults
+  to `false`.
+
+##### Returns
+
+The table, so methods can be chained.
+
+##### Examples
+
+```ts
+// Add an offset between -0.01 and 0.01 to every value
+await table.addNoise("measurement", 0.01).log();
+```
+
+```ts
+// Add noise independently to duplicated x values and duplicated y values
+await table.addNoise(["x", "y"], 0.1, {
+  onlyDuplicates: true,
+}).log();
+```
+
+#### `updateColumn`
+
+Updates values in a specified column using a SQL expression. With the default
+`SimpleDB.expressionSyntax: "js"`, expressions support JavaScript-style
+operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for
+unchanged SQL.
 
 ##### Signature
 
@@ -3931,13 +3989,19 @@ await table.updateColumn(
 ).log();
 ```
 
+```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();
+```
+
 #### `ranks`
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -3988,9 +4052,6 @@ await table.ranks("sales", "salesRank", { by: ["department", "city"] }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -4034,9 +4095,6 @@ await table.quantiles("sales", 4, "salesQuartile").log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -4089,7 +4147,7 @@ each row, adding new columns for these proportions.
 ##### Signature
 
 ```typescript
-rowProportions(columns: string[], options?: { suffix?: string; decimals?: number }): this;
+rowProportions(columns: string[], options?: { suffix?: string; base?: number; decimals?: number }): this;
 ```
 
 ##### Parameters
@@ -4099,6 +4157,8 @@ rowProportions(columns: string[], options?: { suffix?: string; decimals?: number
 - **`options`**: An optional object with configuration options:
 - **`options.suffix`**: A string suffix to append to the names of the new
   columns storing the computed proportions. Defaults to `"Perc"`.
+- **`options.base`**: A finite positive value that the proportions in each row
+  sum to before rounding. Defaults to `1`.
 - **`options.decimals`**: The number of decimal places to round the computed
   proportions. Defaults to `undefined` (no rounding).
 
@@ -4141,8 +4201,13 @@ The table will then look like this:
 | 2022 | 354 | 278   | 56        | 0.51    | 0.4       | 0.08          |
 | 2023 | 856 | 321   | 221       | 0.61    | 0.23      | 0.16          |
 
-This method queues the operation; it runs when an async observer method (like
-`getData()` or `log()`) is awaited, or when `run()` is called.
+```ts
+// Compute percentages that sum to 100 on each row before rounding
+await table.rowProportions(["Men", "Women", "NonBinary"], {
+  base: 100,
+  decimals: 1,
+}).log();
+```
 
 #### `rowRanks`
 
@@ -4156,9 +4221,6 @@ to produce one row for each tied column. The `"all"` 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.
-
 ##### Signature
 
 ```typescript
@@ -4210,13 +4272,10 @@ await table.rowRanks(["CAQ", "PLQ", "PQ"], {
 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.
-
 ##### Signature
 
 ```typescript
-columnProportions(column: string, newColumn: string, options?: { by?: string | string[]; decimals?: number }): this;
+columnProportions(column: string, newColumn: string, options?: { by?: string | string[]; base?: number; decimals?: number }): this;
 ```
 
 ##### Parameters
@@ -4229,6 +4288,8 @@ columnProportions(column: string, newColumn: string, options?: { by?: string | s
 - **`options`**: An optional object with configuration options:
 - **`options.by`**: The column name or an array of column names to partition by.
   Proportions are calculated independently within each group.
+- **`options.base`**: A finite positive value that the proportions in the column
+  or each group sum to before rounding. Defaults to `1`.
 - **`options.decimals`**: The number of decimal places to round the computed
   proportions. Defaults to `undefined` (no rounding).
 
@@ -4249,6 +4310,14 @@ await table.columnProportions("column1", "perc", { by: "column2", decimals: 2 })
   .log();
 ```
 
+```ts
+// Compute percentages that sum to 100 before rounding
+await table.columnProportions("sales", "sales_percentage", {
+  base: 100,
+  decimals: 1,
+}).log();
+```
+
 ```ts
 // Compute proportions for 'sales' by 'region' and 'product_type'
 await table.columnProportions("sales", "sales_proportion", {
@@ -4262,9 +4331,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -4392,9 +4458,6 @@ summarized nor used for labels contain `NULL` in the added rows. A stat 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.
-
 ##### Signature
 
 ```typescript
@@ -4449,9 +4512,6 @@ await table.addSummaryRows("all", "region", {
 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.
-
 ##### Signature
 
 ```typescript
@@ -4500,9 +4560,6 @@ column. 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.
-
 ##### Signature
 
 ```typescript
@@ -4559,9 +4616,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -4628,9 +4682,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -4695,9 +4746,6 @@ await table.linearRegressions({ decimals: 3 }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -4733,9 +4781,6 @@ await table.outliersIQR("salary", "salaryOutlier", { by: "gender" }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -4778,9 +4823,6 @@ await table.zScore("score", "scoreZScore", { decimals: 2 }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -4846,9 +4888,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -4927,16 +4966,19 @@ 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.
+JavaScript. Before writing a JavaScript callback, check for an existing SDA
+method that performs the same operation; it will usually be faster and more
+efficient.
 
-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.
 
 ##### Signature
 
 ```typescript
-updateWithJS(dataModifier: ((rows: Record<string, unknown>[]) => Promise<Record<string, unknown>[]>) | ((rows: Record<string, unknown>[]) => Record<string, unknown>[]), options?: { batchSize?: number }): this;
+updateWithJS(dataModifier: ((rows: Record<string, unknown>[]) => Promise<Record<string, unknown>[]>) | ((rows: Record<string, unknown>[]) => Record<string, unknown>[]), options?: { batchSize?: number; columnTypes?: Record<string, string> }): this;
 ```
 
 ##### Parameters
@@ -4947,7 +4989,15 @@ updateWithJS(dataModifier: ((rows: Record<string, unknown>[]) => Promise<Record<
 - **`options`**: An optional object with configuration options:
 - **`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.
+  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.
+- **`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
 
@@ -4956,38 +5006,73 @@ The table, so methods can be chained.
 ##### Examples
 
 ```ts
-// Count words correctly across multilingual article text.
-const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
-const table = await sdb
-  .newTable()
-  .loadData("articles.csv")
-  .updateWithJS((rows) => {
-    return rows.map((row) => ({
+// 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();
+```
+
+```ts
+// 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();
+```
+
+```ts
+// Add a JSON object column to keep related attributes together.
+await table.loadArray([{ name: "Station" }])
+  .updateWithJS((rows) =>
+    rows.map((row) => ({
       ...row,
-      wordCount: typeof row.text === "string"
-        ? [...segmenter.segment(row.text)].filter((part) => part.isWordLike)
-          .length
-        : null,
-    }));
-  })
+      details: { active: true, category: "weather" },
+    })), { columnTypes: { details: "JSON" } })
   .log();
 ```
 
 ```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 })
+// 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();
 ```
 
+```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();
+```
+
+```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();
+```
+
 #### `getSchema`
 
 Returns the schema of the table, including column names and their data types.
@@ -5093,9 +5178,6 @@ Normalizes string values in a column by:
 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.
-
 ##### Signature
 
 ```typescript
@@ -5155,9 +5237,75 @@ const columnCount = await table.getColumnCount();
 console.log(columnCount); // e.g., 3
 ```
 
+#### `addCharacterCount`
+
+Adds a new column containing the number of characters in each string in the
+specified column. 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.
+
+##### Signature
+
+```typescript
+addCharacterCount(column: string, newColumn: string): this;
+```
+
+##### Parameters
+
+- **`column`**: The name of the column containing the strings to count.
+- **`newColumn`**: The name of the new column where the character counts will be
+  stored.
+
+##### Returns
+
+The table, so methods can be chained.
+
+##### Examples
+
+```ts
+// Add a character count for each value in the 'name' column
+await table.addCharacterCount("name", "nameCharacterCount").log();
+```
+
+#### `addWordCount`
+
+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.
+
+##### Signature
+
+```typescript
+addWordCount(column: string, newColumn: string): this;
+```
+
+##### Parameters
+
+- **`column`**: The name of the column containing the strings to count.
+- **`newColumn`**: The name of the new column where the word counts will be
+  stored.
+
+##### Returns
+
+The table, so methods can be chained.
+
+##### Examples
+
+```ts
+// Add a word count for each value in the 'article' column
+await table.addWordCount("article", "wordCount").log();
+```
+
 #### `getCharacterCount`
 
-Returns the total number of characters in a column storing strings.
+Returns the total number of characters in a column storing strings. 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.
 
 ##### Signature
 
@@ -5184,7 +5332,9 @@ console.log(totalChars); // e.g., 523
 
 #### `getRowCount`
 
-Returns the number of rows in the table.
+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.
 
 ##### Signature
 
@@ -5674,9 +5824,11 @@ console.log(uniqueCategories); // e.g., ["Books", "Clothing", "Electronics"]
 
 #### `getFirstRow`
 
-Returns the first row of the table, optionally filtered by SQL conditions. You
-can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
-Temporal values use the same JavaScript representations as `getData()`.
+Returns the first row of the table, optionally filtered by SQL conditions. 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()`.
 
 ##### Signature
 
@@ -5713,9 +5865,11 @@ console.log(firstRowBooks);
 
 #### `getLastRow`
 
-Returns the last row of the table, optionally filtered by SQL conditions. You
-can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`, `!==`).
-Temporal values use the same JavaScript representations as `getData()`.
+Returns the last row of the table, optionally filtered by SQL conditions. 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()`.
 
 ##### Signature
 
@@ -5753,8 +5907,10 @@ console.log(lastRowBooks);
 #### `getTop`
 
 Returns the top `n` rows of the table, optionally filtered by SQL conditions.
-You can also use JavaScript syntax for conditions (e.g., `&&`, `||`, `===`,
-`!==`). Temporal values use the same JavaScript representations as `getData()`.
+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()`.
 
 ##### Signature
 
@@ -5791,9 +5947,10 @@ console.log(top5Books);
 
 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., `&&`, `||`, `===`, `!==`). Temporal values use the same
-JavaScript representations as `getData()`.
+use the `originalOrder` option. 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()`.
 
 ##### Signature
 
@@ -5842,9 +5999,10 @@ console.log(bottom5Books);
 #### `getRow`
 
 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`, `||`, `===`, `!==`). Temporal
-values use the same JavaScript representations as `getData()`.
+if more than one row matches, an error is thrown by default. 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()`.
 
 ##### Signature
 
@@ -5893,14 +6051,28 @@ console.log(flexibleRow);
 #### `getData`
 
 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., `&&`,
-`||`, `===`, `!==`).
+SQL conditions. 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.
+
 ##### Signature
 
 ```typescript
@@ -5950,11 +6122,24 @@ console.log(booksData);
 const preview = await table.getData({ limit: 2 });
 ```
 
+```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();
+```
+
 #### `stream`
 
 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()`.
+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 queries on the same
@@ -6001,9 +6186,10 @@ for await (
 #### `getDataAsCSV`
 
 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., `&&`, `||`,
-`===`, `!==`). Temporal values are first converted as they are in `getData()`,
-then serialized using UTC date and timestamp text.
+conditions. 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.
 
 ##### Signature
 
@@ -6053,9 +6239,6 @@ console.log(booksDataCSV);
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -6096,9 +6279,6 @@ await table.createPoints("y", "x", "geom", { projection: "EPSG:3347" }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -6135,9 +6315,6 @@ await table.addGeoValidity("isValidMyGeom", { column: "myGeom" }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -6173,9 +6350,6 @@ await table.addVertexCount("myGeomVertices", { column: "myGeom" }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -6208,9 +6382,6 @@ await table.fixGeo("myGeom").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6247,9 +6418,6 @@ await table.addGeoClosedStatus("boundaryClosed", { column: "boundaryGeom" })
 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.
-
 ##### Signature
 
 ```typescript
@@ -6288,9 +6456,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -6318,14 +6483,65 @@ await table.flipCoordinates().log();
 await table.flipCoordinates("myGeom").log();
 ```
 
+#### `addGeoNoise`
+
+Moves EPSG:4326 point geometries to random locations within a maximum
+great-circle distance of their original positions.
+
+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.
+
+##### Signature
+
+```typescript
+addGeoNoise(maxDistance: number, options?: { column?: string; unit?: "m" | "km"; onlyDuplicates?: boolean }): this;
+```
+
+##### Parameters
+
+- **`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.
+- **`options`**: An optional object with configuration options:
+- **`options.column`**: The name of the EPSG:4326 point geometry column. If
+  omitted, the method will automatically attempt to find a geometry column.
+- **`options.unit`**: The unit of `maxDistance`: `"m"` for metres or `"km"` for
+  kilometres. Defaults to `"m"`.
+- **`options.onlyDuplicates`**: If `true`, moves only points whose complete
+  original geometry occurs more than once in the selected geometry column. Every
+  point in a duplicated group is moved. Defaults to `false`.
+
+##### Returns
+
+The table, so methods can be chained.
+
+##### Examples
+
+```ts
+// Move every point by no more than 500 metres
+await table.addGeoNoise(500).log();
+```
+
+```ts
+// Separate duplicated points by up to 0.1 kilometres
+await table.addGeoNoise(0.1, {
+  column: "geom",
+  unit: "km",
+  onlyDuplicates: true,
+}).log();
+```
+
 #### `reducePrecision`
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -6361,9 +6577,6 @@ await table.reducePrecision(2, { column: "myGeom" }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6399,9 +6612,6 @@ await table.reproject("EPSG:3347", { column: "myGeom" }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6451,9 +6661,6 @@ await table.area("myGeomArea", { column: "myGeom" }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6503,9 +6710,6 @@ await table.length("routeLength", { column: "routeGeom" }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6557,9 +6761,6 @@ 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.
-
 ##### Signature
 
 ```typescript
@@ -6598,10 +6799,7 @@ 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.
+`.tmp` to your `.gitignore`.
 
 ##### Signature
 
@@ -6694,9 +6892,6 @@ const tableC = await tableA.joinGeo(tableB, "intersect", {
 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.
-
 ##### Signature
 
 ```typescript
@@ -6727,9 +6922,6 @@ await table.intersection("geomA", "geomB", "intersectGeom").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6760,9 +6952,6 @@ await table.difference("geomA", "geomB", "geomA_minus_geomB").log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -6795,9 +6984,6 @@ await table.fillHoles("polygonGeom").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6828,9 +7014,6 @@ await table.intersects("geomA", "geomB", "doIntersect").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6862,9 +7045,6 @@ await table.coveredBy("pointGeom", "polygonGeom", "isCovered").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6895,9 +7075,6 @@ await table.union("geomA", "geomB", "unionGeom").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6928,9 +7105,6 @@ await table.extractLatLon("geom", "lat", "lon").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -6969,9 +7143,6 @@ await table.simplify(0.05, { column: "myGeom", simplifyBoundary: false }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -7006,9 +7177,6 @@ await table.centroid("areaCentroid", { column: "areaGeom" }).log();
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -7054,9 +7222,6 @@ input geometries. 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.
-
 ##### Signature
 
 ```typescript
@@ -7121,9 +7286,6 @@ await table.distance("area1", "area2", "distance_spheroid_km", {
 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.
-
 ##### Signature
 
 ```typescript
@@ -7156,9 +7318,6 @@ await table.unnestGeo("multiGeom").log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -7197,9 +7356,6 @@ await table.addBoundingBox({ column: "geom", decimals: 2 }).log();
 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.
-
 ##### Signature
 
 ```typescript
@@ -7251,9 +7407,6 @@ const intersectionTable = await table.aggregateGeo("intersection", {
 
 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.
-
 ##### Signature
 
 ```typescript
@@ -7319,8 +7472,10 @@ console.log(areaBbox);
 
 #### `getGeoData`
 
-Returns the table's geospatial data as a GeoJSON object. If the table has
-multiple geometry columns, you must specify which one to use.
+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.
 
 ##### Signature
 
@@ -7364,7 +7519,8 @@ console.log(rewoundGeojson);
 #### `writeData`
 
 Writes the table's data to a file in various formats (CSV, JSON, Parquet,
-DuckDB, SQLite). If the specified path does not exist, it will be created.
+DuckDB, SQLite). Tables with geometry columns must use `writeGeoData()` instead.
+If the specified path does not exist, it will be created.
 
 ##### Signature
 
@@ -7385,8 +7541,8 @@ async writeData(file: string, options?: { compression?: boolean; dataAsArrays?:
   `{ "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.
+  [journalism-format library](https://jsr.io/@nshiab/journalism-format/doc/~/arraysToData)
+  to convert it back.
 - **`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`.
@@ -7503,28 +7659,28 @@ await table.writeGeoData("./output_high_precision.geojson", {
 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.
 
 ##### Signature
 
@@ -7624,8 +7780,18 @@ await summary.log();
 
 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., `&&`, `||`, `===`, `!==`).
+data based on conditions. 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.
 
 ##### Signature
 
@@ -7866,6 +8032,10 @@ 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()`.
+
 ##### Signature
 
 ```typescript