@duckdb/node-api 1.1.3-alpha.9 → 1.2.0-alpha.14

package/README.md

@@ -140,6 +140,16 @@ const result = await connection.run('select $a, $b, $c', {
 });
 ```
 
+Unspecified types will be inferred:
+
+```ts
+const result = await connection.run('select $a, $b, $c', {
+  'a': 'duck',
+  'b': 42,
+  'c': listValue([10, 11, 12]),
+});
+```
+
 ### Stream Results
 
 Streaming results evaluate lazily when rows are read.
@@ -148,7 +158,7 @@ Streaming results evaluate lazily when rows are read.
 const result = await connection.stream('from range(10_000)');
 ```
 
-### Inspect Result
+### Inspect Result Metadata
 
 Get column names and types:
 ```ts
@@ -156,7 +166,7 @@ const columnNames = result.columnNames();
 const columnTypes = result.columnTypes();
 ```
 
-### Result Reader
+### Read Result Data
 
 Run and read all data:
 ```ts
@@ -167,7 +177,10 @@ const rows = reader.getRows();
 
 Stream and read up to (at least) some number of rows:
 ```ts
-const reader = await connection.streamAndReadUntil('from range(5000)', 1000);
+const reader = await connection.streamAndReadUntil(
+  'from range(5000)',
+  1000
+);
 const rows = reader.getRows();
 // rows.length === 2048. (Rows are read in chunks of 2048.)
 ```
@@ -186,7 +199,183 @@ reader.readUntil(6000);
 // reader.done === true
 ```
 
-### Read chunks
+### Get Result Data
+
+Result data can be retrieved in a variety of forms:
+
+```ts
+const reader = await connection.runAndReadAll(
+  'from range(3) select range::int as i, 10 + i as n'
+);
+
+const rows = reader.getRows();
+// [ [0, 10], [1, 11], [2, 12] ]
+
+const rowObjects = reader.getRowObjects();
+// [ { i: 0, n: 10 }, { i: 1, n: 11 }, { i: 2, n: 12 } ]
+
+const columns = reader.getColumns();
+// [ [0, 1, 2], [10, 11, 12] ]
+
+const columnsObject = reader.getColumnsObject();
+// { i: [0, 1, 2], n: [10, 11, 12] }
+```
+
+### Convert Result Data to JSON
+
+By default, data values that cannot be represented as JS primitives
+are returned as rich JS objects; see `Inspect Data Values` below.
+
+To retrieve data in a form that can be losslessly serialized to JSON,
+use the `Json` forms of the above result data methods:
+
+```ts
+const reader = await connection.runAndReadAll(
+  'from test_all_types() select bigint, date, interval limit 2'
+);
+
+const rows = reader.getRowsJson();
+// [
+//   [
+//     "-9223372036854775808",
+//     "5877642-06-25 (BC)",
+//     { "months": 0, "days": 0, "micros": "0" }
+//   ],
+//   [
+//     "9223372036854775807",
+//     "5881580-07-10",
+//     { "months": 999, "days": 999, "micros": "999999999" }
+//   ]
+// ]
+
+const rowObjects = reader.getRowObjectsJson();
+// [
+//   {
+//     "bigint": "-9223372036854775808",
+//     "date": "5877642-06-25 (BC)",
+//     "interval": { "months": 0, "days": 0, "micros": "0" }
+//   },
+//   {
+//     "bigint": "9223372036854775807",
+//     "date": "5881580-07-10",
+//     "interval": { "months": 999, "days": 999, "micros": "999999999" }
+//   }
+// ]
+
+const columns = reader.getColumnsJson();
+// [
+//   [ "-9223372036854775808", "9223372036854775807" ],
+//   [ "5877642-06-25 (BC)", "5881580-07-10" ],
+//   [
+//     { "months": 0, "days": 0, "micros": "0" },
+//     { "months": 999, "days": 999, "micros": "999999999" }
+//   ]
+// ]
+
+const columnsObject = reader.getColumnsObjectJson();
+// {
+//   "bigint": [ "-9223372036854775808", "9223372036854775807" ],
+//   "date": [ "5877642-06-25 (BC)", "5881580-07-10" ],
+//   "interval": [
+//     { "months": 0, "days": 0, "micros": "0" },
+//     { "months": 999, "days": 999, "micros": "999999999" }
+//   ]
+// }
+```
+
+These methods handle nested types as well:
+
+```ts
+const reader = await connection.runAndReadAll(
+  'from test_all_types() select int_array, struct, map, "union" limit 2'
+);
+
+const rows = reader.getRowsJson();
+// [
+//   [
+//     [],
+//     { "a": null, "b": null },
+//     [],
+//     { "tag": "name", "value": "Frank" }
+//   ],
+//   [
+//     [ 42, 999, null, null, -42],
+//     { "a": 42, "b": "🦆🦆🦆🦆🦆🦆" },
+//     [
+//       { "key": "key1", "value": "🦆🦆🦆🦆🦆🦆" },
+//       { "key": "key2", "value": "goose" }
+//     ],
+//     { "tag": "age", "value": 5 }
+//   ]
+// ]
+
+const rowObjects = reader.getRowObjectsJson();
+// [
+//   {
+//     "int_array": [],
+//     "struct": { "a": null, "b": null },
+//     "map": [],
+//     "union": { "tag": "name", "value": "Frank" }
+//   },
+//   {
+//     "int_array": [ 42, 999, null, null, -42 ],
+//     "struct": { "a": 42, "b": "🦆🦆🦆🦆🦆🦆" },
+//     "map": [
+//       { "key": "key1", "value": "🦆🦆🦆🦆🦆🦆" },
+//       { "key": "key2", "value": "goose" }
+//     ],
+//     "union": { "tag": "age", "value": 5 }
+//   }
+// ]
+
+const columns = reader.getColumnsJson();
+// [
+//   [
+//     [],
+//     [42, 999, null, null, -42]
+//   ],
+//   [
+//     { "a": null, "b": null },
+//     { "a": 42, "b": "🦆🦆🦆🦆🦆🦆" }
+//   ],
+//   [
+//     [],
+//     [
+//       { "key": "key1", "value": "🦆🦆🦆🦆🦆🦆" },
+//       { "key": "key2", "value": "goose"}
+//     ]
+//   ],
+//   [
+//     { "tag": "name", "value": "Frank" },
+//     { "tag": "age", "value": 5 }
+//   ]
+// ]
+
+const columnsObject = reader.getColumnsObjectJson();
+// {
+//   "int_array": [
+//     [],
+//     [42, 999, null, null, -42]
+//   ],
+//   "struct": [
+//     { "a": null, "b": null },
+//     { "a": 42, "b": "🦆🦆🦆🦆🦆🦆" }
+//   ],
+//   "map": [
+//     [],
+//     [
+//       { "key": "key1", "value": "🦆🦆🦆🦆🦆🦆" },
+//       { "key": "key2", "value": "goose" }
+//     ]
+//   ],
+//   "union": [
+//     { "tag": "name", "value": "Frank" },
+//     { "tag": "age", "value": 5 }
+//   ]
+// }
+```
+
+### Fetch Chunks
 
 Fetch all chunks:
 ```ts
@@ -216,19 +405,18 @@ for (let i = 0; i < chunkCount; i++) {
 }
 ```
 
-Read chunk data (column-major):
+Get chunk data:
 ```ts
-// array of columns, each as an array of values
-const columns = chunk.getColumns(); 
-```
+const rows = chunk.getRows();
 
-Read chunk data (row-major):
-```ts
-// array of rows, each as an array of values
-const rows = chunk.getRows(); 
+const rowObjects = chunk.getRowObjects();
+
+const columns = chunk.getColumns();
+
+const columnsObject = chunk.getColumnsObject();
 ```
 
-Read chunk data (one value at a time)
+Get chunk data (one value at a time)
 ```ts
 const columns = [];
 const columnCount = chunk.columnCount;
@@ -417,6 +605,38 @@ if (columnType.typeId === DuckDBTypeId.UUID) {
 // other possible values are: null, boolean, number, bigint, or string
 ```
 
+### Displaying Timezones
+
+Converting a TIMESTAMP_TZ value to a string depends on a timezone offset.
+By default, this is set to the offset for the local timezone when the Node
+process is started.
+
+To change it, set the `timezoneOffsetInMinutes`
+property of `DuckDBTimestampTZValue`:
+
+```ts
+DuckDBTimestampTZValue.timezoneOffsetInMinutes = -8 * 60;
+const pst = DuckDBTimestampTZValue.Epoch.toString();
+// 1969-12-31 16:00:00-08
+
+DuckDBTimestampTZValue.timezoneOffsetInMinutes = +1 * 60;
+const cet = DuckDBTimestampTZValue.Epoch.toString();
+// 1970-01-01 01:00:00+01
+```
+
+Note that the timezone offset used for this string
+conversion is distinct from the `TimeZone` setting of DuckDB.
+
+The following sets this offset to match the `TimeZone` setting of DuckDB:
+
+```ts
+const reader = await connection.runAndReadAll(
+  `select (timezone(current_timestamp) / 60)::int`
+);
+DuckDBTimestampTZValue.timezoneOffsetInMinutes =
+  reader.getColumns()[0][0];
+```
+
 ### Append To Table
 
 ```ts
@@ -510,3 +730,184 @@ console.log('ready');
 const result = await pending.getResult();
 // ...
 ```
+
+### Ways to run SQL
+
+```ts
+// Run to completion but don't yet retrieve any rows.
+// Optionally take values to bind to SQL parameters,
+// and (optionally) types of those parameters,
+// either as an array (for positional parameters),
+// or an object keyed by parameter name.
+const result = await connection.run(sql);
+const result = await connection.run(sql, values);
+const result = await connection.run(sql, values, types);
+
+// Run to completion but don't yet retrieve any rows.
+// Wrap in a DuckDBDataReader for convenient data retrieval.
+const reader = await connection.runAndRead(sql);
+const reader = await connection.runAndRead(sql, values);
+const reader = await connection.runAndRead(sql, values, types);
+
+// Run to completion, wrap in a reader, and read all rows.
+const reader = await connection.runAndReadAll(sql);
+const reader = await connection.runAndReadAll(sql, values);
+const reader = await connection.runAndReadAll(sql, values, types);
+
+// Run to completion, wrap in a reader, and read at least
+// the given number of rows. (Rows are read in chunks, so more than
+// the target may be read.)
+const reader = await connection.runAndReadUntil(sql, targetRowCount);
+const reader =
+  await connection.runAndReadAll(sql, targetRowCount, values);
+const reader =
+  await connection.runAndReadAll(sql, targetRowCount, values, types);
+
+// Create a streaming result and don't yet retrieve any rows.
+const result = await connection.stream(sql);
+const result = await connection.stream(sql, values);
+const result = await connection.stream(sql, values, types);
+
+// Create a streaming result and don't yet retrieve any rows.
+// Wrap in a DuckDBDataReader for convenient data retrieval.
+const reader = await connection.streamAndRead(sql);
+const reader = await connection.streamAndRead(sql, values);
+const reader = await connection.streamAndRead(sql, values, types);
+
+// Create a streaming result, wrap in a reader, and read all rows.
+const reader = await connection.streamAndReadAll(sql);
+const reader = await connection.streamAndReadAll(sql, values);
+const reader = await connection.streamAndReadAll(sql, values, types);
+
+// Create a streaming result, wrap in a reader, and read at least
+// the given number of rows.
+const reader = await connection.streamAndReadUntil(sql, targetRowCount);
+const reader =
+  await connection.streamAndReadUntil(sql, targetRowCount, values);
+const reader =
+  await connection.streamAndReadUntil(sql, targetRowCount, values, types);
+
+// Prepared Statements
+
+// Prepare a possibly-parametered SQL statement to run later.
+const prepared = await connection.prepare(sql);
+
+// Bind values to the parameters.
+prepared.bind(values);
+prepared.bind(values, types);
+
+// Run the prepared statement. These mirror the methods on the connection.
+const result = prepared.run();
+
+const reader = prepared.runAndRead();
+const reader = prepared.runAndReadAll();
+const reader = prepared.runAndReadUntil(targetRowCount);
+
+const result = prepared.stream();
+
+const reader = prepared.streamAndRead();
+const reader = prepared.streamAndReadAll();
+const reader = prepared.streamAndReadUntil(targetRowCount);
+
+// Pending Results
+
+// Create a pending result.
+const pending = await connection.start(sql);
+const pending = await connection.start(sql, values);
+const pending = await connection.start(sql, values, types);
+
+// Create a pending, streaming result.
+const pending = await connection.startStream(sql);
+const pending = await connection.startStream(sql, values);
+const pending = await connection.startStream(sql, values, types);
+
+// Create a pending result from a prepared statement.
+const pending = await prepared.start();
+const pending = await prepared.startStream();
+
+while (pending.runTask() !== DuckDBPendingResultState.RESULT_READY) {
+  // optionally sleep or do other work between tasks
+}
+
+// Retrieve the result. If not yet READY, will run until it is.
+const result = await pending.getResult();
+
+const reader = await pending.read();
+const reader = await pending.readAll();
+const reader = await pending.readUntil(targetRowCount);
+```
+
+### Ways to get result data
+
+```ts
+// From a result
+
+// Asynchronously retrieve data for all rows:
+const columns = await result.getColumns();
+const columnsJson = await result.getColumnsJson();
+const columnsObject = await result.getColumnsObject();
+const columnsObjectJson = await result.getColumnsObjectJson();
+const rows = await result.getRows();
+const rowsJson = await result.getRowsJson();
+const rowObjects = await result.getRowObjects();
+const rowObjectsJson = await result.getRowObjectsJson();
+
+// From a reader
+
+// First, (asynchronously) read some rows:
+await reader.readAll();
+// or:
+await reader.readUntil(targetRowCount);
+
+// Then, (synchronously) get result data for the rows read:
+const columns = reader.getColumns();
+const columnsJson = reader.getColumnsJson();
+const columnsObject = reader.getColumnsObject();
+const columnsObjectJson = reader.getColumnsObjectJson();
+const rows = reader.getRows();
+const rowsJson = reader.getRowsJson();
+const rowObjects = reader.getRowObjects();
+const rowObjectsJson = reader.getRowObjectsJson();
+
+// Individual values can also be read directly:
+const value = reader.value(columnIndex, rowIndex);
+
+// Using chunks
+
+// If desired, one or more chunks can be fetched from a result:
+const chunk = await result.fetchChunk();
+const chunks = await result.fetchAllChunks();
+
+// And then data can be retrieved from each chunk:
+const columnValues = chunk.getColumnValues(columnIndex);
+const columns = chunk.getColumns();
+const rowValues = chunk.getRowValues(rowIndex);
+const rows = chunk.getRows();
+
+// Or, values can be visited:
+chunk.visitColumnValues(columnIndex,
+  (value, rowIndex, columnIndex, type) => { /* ... */ }
+);
+chunk.visitColumns((column, columnIndex, type) => { /* ... */ });
+chunk.visitColumnMajor(
+  (value, rowIndex, columnIndex, type) => { /* ... */ }
+);
+chunk.visitRowValues(rowIndex,
+  (value, rowIndex, columnIndex, type) => { /* ... */ }
+);
+chunk.visitRows((row, rowIndex) => { /* ... */ });
+chunk.visitRowMajor(
+  (value, rowIndex, columnIndex, type) => { /* ... */ }
+);
+
+// Or converted:
+// The `converter` argument implements `DuckDBValueConverter`,
+// which has the single method convertValue(value, type).
+const columnValues = chunk.convertColumnValues(columnIndex, converter);
+const columns = chunk.convertColumns(converter);
+const rowValues = chunk.convertRowValues(rowIndex, converter);
+const rows = chunk.convertRows(converter);
+
+// The reader abstracts these low-level chunk manipulations
+// and is recommended for most cases.
+```

package/lib/DuckDBConnection.d.ts

@@ -18,16 +18,16 @@ export declare class DuckDBConnection {
     disconnect(): void;
     interrupt(): void;
     get progress(): duckdb.QueryProgress;
-    run(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBMaterializedResult>;
-    runAndRead(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
-    runAndReadAll(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
-    runAndReadUntil(sql: string, targetRowCount: number, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
-    stream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResult>;
-    streamAndRead(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
-    streamAndReadAll(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
-    streamAndReadUntil(sql: string, targetRowCount: number, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBResultReader>;
-    start(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBPendingResult>;
-    startStream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType>): Promise<DuckDBPendingResult>;
+    run(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBMaterializedResult>;
+    runAndRead(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResultReader>;
+    runAndReadAll(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResultReader>;
+    runAndReadUntil(sql: string, targetRowCount: number, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResultReader>;
+    stream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResult>;
+    streamAndRead(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResultReader>;
+    streamAndReadAll(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResultReader>;
+    streamAndReadUntil(sql: string, targetRowCount: number, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBResultReader>;
+    start(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBPendingResult>;
+    startStream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBPendingResult>;
     prepare(sql: string): Promise<DuckDBPreparedStatement>;
     extractStatements(sql: string): Promise<DuckDBExtractedStatements>;
     createAppender(schema: string, table: string): Promise<DuckDBAppender>;

package/lib/DuckDBDataChunk.d.ts

@@ -1,5 +1,6 @@
 import duckdb from '@duckdb/node-bindings';
 import { DuckDBType } from './DuckDBType';
+import { DuckDBValueConverter } from './DuckDBValueConverter';
 import { DuckDBVector } from './DuckDBVector';
 import { DuckDBValue } from './values';
 export declare class DuckDBDataChunk {
@@ -9,13 +10,24 @@ export declare class DuckDBDataChunk {
     static create(types: readonly DuckDBType[], rowCount?: number): DuckDBDataChunk;
     reset(): void;
     get columnCount(): number;
+    get rowCount(): number;
+    set rowCount(count: number);
     getColumnVector(columnIndex: number): DuckDBVector;
+    visitColumnValues(columnIndex: number, visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
     getColumnValues(columnIndex: number): DuckDBValue[];
+    convertColumnValues<T>(columnIndex: number, converter: DuckDBValueConverter<T>): T[];
     setColumnValues(columnIndex: number, values: readonly DuckDBValue[]): void;
+    visitColumns(visitColumn: (column: DuckDBValue[], columnIndex: number, type: DuckDBType) => void): void;
     getColumns(): DuckDBValue[][];
+    convertColumns<T>(converter: DuckDBValueConverter<T>): T[][];
     setColumns(columns: readonly (readonly DuckDBValue[])[]): void;
+    visitColumnMajor(visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
+    visitRowValues(rowIndex: number, visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
+    getRowValues(rowIndex: number): DuckDBValue[];
+    convertRowValues<T>(rowIndex: number, converter: DuckDBValueConverter<T>): T[];
+    visitRows(visitRow: (row: DuckDBValue[], rowIndex: number) => void): void;
     getRows(): DuckDBValue[][];
+    convertRows<T>(converter: DuckDBValueConverter<T>): T[][];
     setRows(rows: readonly (readonly DuckDBValue[])[]): void;
-    get rowCount(): number;
-    set rowCount(count: number);
+    visitRowMajor(visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
 }