Merge pull request #187 from duckdb/jray/column-names-and-types-json

jraymakers · web-flow · commit 323bf1ec2279 · 2025-03-23T13:58:41.000-07:00
column names and types json
diff --git a/api/pkgs/@duckdb/node-api/README.md b/api/pkgs/@duckdb/node-api/README.md
@@ -405,6 +405,127 @@ const columnsObject = reader.getColumnsObjectJson();
 // }
 ```
 
+Column names and types can also be serialized to JSON:
+```ts
+const columnNamesAndTypes = reader.columnNamesAndTypesJson();
+// {
+//   "columnNames": [
+//     "int_array",
+//     "struct",
+//     "map",
+//     "union"
+//   ],
+//   "columnTypes": [
+//     {
+//       "typeId": 24,
+//       "valueType": {
+//         "typeId": 4
+//       }
+//     },
+//     {
+//       "typeId": 25,
+//       "entryNames": [
+//         "a",
+//         "b"
+//       ],
+//       "entryTypes": [
+//         {
+//           "typeId": 4
+//         },
+//         {
+//           "typeId": 17
+//         }
+//       ]
+//     },
+//     {
+//       "typeId": 26,
+//       "keyType": {
+//         "typeId": 17
+//       },
+//       "valueType": {
+//         "typeId": 17
+//       }
+//     },
+//     {
+//       "typeId": 28,
+//       "memberTags": [
+//         "name",
+//         "age"
+//       ],
+//       "memberTypes": [
+//         {
+//           "typeId": 17
+//         },
+//         {
+//           "typeId": 3
+//         }
+//       ]
+//     }
+//   ]
+// }
+
+const columnNameAndTypeObjects = reader.columnNameAndTypeObjectsJson();
+// [
+//   {
+//     "columnName": "int_array",
+//     "columnType": {
+//       "typeId": 24,
+//       "valueType": {
+//         "typeId": 4
+//       }
+//     }
+//   },
+//   {
+//     "columnName": "struct",
+//     "columnType": {
+//       "typeId": 25,
+//       "entryNames": [
+//         "a",
+//         "b"
+//       ],
+//       "entryTypes": [
+//         {
+//           "typeId": 4
+//         },
+//         {
+//           "typeId": 17
+//         }
+//       ]
+//     }
+//   },
+//   {
+//     "columnName": "map",
+//     "columnType": {
+//       "typeId": 26,
+//       "keyType": {
+//         "typeId": 17
+//       },
+//       "valueType": {
+//         "typeId": 17
+//       }
+//     }
+//   },
+//   {
+//     "columnName": "union",
+//     "columnType": {
+//       "typeId": 28,
+//       "memberTags": [
+//         "name",
+//         "age"
+//       ],
+//       "memberTypes": [
+//         {
+//           "typeId": 17
+//         },
+//         {
+//           "typeId": 3
+//         }
+//       ]
+//     }
+//   }
+// ]
+```
+
 ### Fetch Chunks
 
 Fetch all chunks:
diff --git a/api/src/DuckDBResult.ts b/api/src/DuckDBResult.ts
@@ -3,7 +3,8 @@ import { DuckDBDataChunk } from './DuckDBDataChunk';
 import { DuckDBLogicalType } from './DuckDBLogicalType';
 import { DuckDBType } from './DuckDBType';
 import { DuckDBTypeId } from './DuckDBTypeId';
-import { DuckDBValueToJsonConverter, Json } from './DuckDBValueToJsonConverter';
+import { DuckDBValueToJsonConverter } from './DuckDBValueToJsonConverter';
+import { Json } from './Json';
 import { convertColumnsFromChunks } from './convertColumnsFromChunks';
 import { convertColumnsObjectFromChunks } from './convertColumnsObjectFromChunks';
 import { convertRowObjectsFromChunks } from './convertRowObjectsFromChunks';
@@ -72,6 +73,9 @@ export class DuckDBResult {
       duckdb.column_logical_type(this.result, columnIndex)
     ).asType();
   }
+  public columnTypeJson(columnIndex: number): Json {
+    return this.columnType(columnIndex).toJson();
+  }
   public columnTypes(): DuckDBType[] {
     const columnTypes: DuckDBType[] = [];
     const columnCount = this.columnCount;
@@ -80,6 +84,31 @@ export class DuckDBResult {
     }
     return columnTypes;
   }
+  public columnTypesJson(): Json {
+    const columnTypesJson: Json[] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      columnTypesJson.push(this.columnTypeJson(columnIndex));
+    }
+    return columnTypesJson;
+  }
+  public columnNamesAndTypesJson(): Json {
+    return {
+      columnNames: this.columnNames(),
+      columnTypes: this.columnTypesJson(),
+    };
+  }
+  public columnNameAndTypeObjectsJson(): Json {
+    const columnNameAndTypeObjects: Json[] = [];
+    const columnCount = this.columnCount;
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      columnNameAndTypeObjects.push({
+        columnName: this.columnName(columnIndex),
+        columnType: this.columnTypeJson(columnIndex),
+      });
+    }
+    return columnNameAndTypeObjects;
+  }
   public get isStreaming(): boolean {
     return duckdb.result_is_streaming(this.result);
   }
diff --git a/api/src/DuckDBResultReader.ts b/api/src/DuckDBResultReader.ts
@@ -7,12 +7,13 @@ import { DuckDBLogicalType } from './DuckDBLogicalType';
 import { DuckDBResult } from './DuckDBResult';
 import { DuckDBType } from './DuckDBType';
 import { DuckDBTypeId } from './DuckDBTypeId';
-import { DuckDBValueToJsonConverter, Json } from './DuckDBValueToJsonConverter';
+import { DuckDBValueToJsonConverter } from './DuckDBValueToJsonConverter';
 import { ResultReturnType, StatementType } from './enums';
 import { getColumnsFromChunks } from './getColumnsFromChunks';
 import { getColumnsObjectFromChunks } from './getColumnsObjectFromChunks';
 import { getRowObjectsFromChunks } from './getRowObjectsFromChunks';
 import { getRowsFromChunks } from './getRowsFromChunks';
+import { Json } from './Json';
 import { DuckDBValue } from './values';
 
 interface ChunkSizeRun {
@@ -63,9 +64,21 @@ export class DuckDBResultReader {
   public columnType(columnIndex: number): DuckDBType {
     return this.result.columnType(columnIndex);
   }
+  public columnTypeJson(columnIndex: number): Json {
+    return this.result.columnTypeJson(columnIndex);
+  }
   public columnTypes(): DuckDBType[] {
     return this.result.columnTypes();
   }
+  public columnTypesJson(): Json {
+    return this.result.columnTypesJson();
+  }
+  public columnNamesAndTypesJson(): Json {
+    return this.result.columnNamesAndTypesJson();
+  }
+  public columnNameAndTypeObjectsJson(): Json {
+    return this.result.columnNameAndTypeObjectsJson();
+  }
   public get rowsChanged(): number {
     return this.result.rowsChanged;
   }
diff --git a/api/src/DuckDBType.ts b/api/src/DuckDBType.ts
@@ -1,6 +1,7 @@
 import duckdb from '@duckdb/node-bindings';
 import { DuckDBLogicalType } from './DuckDBLogicalType';
 import { DuckDBTypeId } from './DuckDBTypeId';
+import { Json } from './Json';
 import { quotedIdentifier, quotedString } from './sql';
 import {
   DuckDBDateValue,
@@ -33,6 +34,12 @@ export abstract class BaseDuckDBType<T extends DuckDBTypeId> {
     }
     return logicalType;
   }
+  public toJson(): Json {
+    return {
+      typeId: this.typeId,
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 
 export class DuckDBBooleanType extends BaseDuckDBType<DuckDBTypeId.BOOLEAN> {
@@ -401,6 +408,14 @@ export class DuckDBDecimalType extends BaseDuckDBType<DuckDBTypeId.DECIMAL> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      width: this.width,
+      scale: this.scale,
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
   public static readonly default = new DuckDBDecimalType(18, 3);
 }
 export function DECIMAL(
@@ -532,6 +547,14 @@ export class DuckDBEnumType extends BaseDuckDBType<DuckDBTypeId.ENUM> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      values: [...this.values],
+      internalTypeId: this.internalTypeId,
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 export function ENUM8(
   values: readonly string[],
@@ -586,6 +609,13 @@ export class DuckDBListType extends BaseDuckDBType<DuckDBTypeId.LIST> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      valueType: this.valueType.toJson(),
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 export function LIST(valueType: DuckDBType, alias?: string): DuckDBListType {
   return new DuckDBListType(valueType, alias);
@@ -641,6 +671,14 @@ export class DuckDBStructType extends BaseDuckDBType<DuckDBTypeId.STRUCT> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      entryNames: [...this.entryNames],
+      entryTypes: this.entryTypes.map(t => t.toJson()),
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 export function STRUCT(
   entries: Record<string, DuckDBType>,
@@ -676,6 +714,14 @@ export class DuckDBMapType extends BaseDuckDBType<DuckDBTypeId.MAP> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      keyType: this.keyType.toJson(),
+      valueType: this.valueType.toJson(),
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 export function MAP(
   keyType: DuckDBType,
@@ -706,6 +752,14 @@ export class DuckDBArrayType extends BaseDuckDBType<DuckDBTypeId.ARRAY> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      valueType: this.valueType.toJson(),
+      length: this.length,
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 export function ARRAY(
   valueType: DuckDBType,
@@ -782,6 +836,14 @@ export class DuckDBUnionType extends BaseDuckDBType<DuckDBTypeId.UNION> {
     }
     return logicalType;
   }
+  public override toJson(): Json {
+    return {
+      typeId: this.typeId,
+      memberTags: [...this.memberTags],
+      memberTypes: this.memberTypes.map(t => t.toJson()),
+      ...(this.alias ? { alias: this.alias } : {}),
+    };
+  }
 }
 export function UNION(
   members: Record<string, DuckDBType>,
diff --git a/api/src/DuckDBValueToJsonConverter.ts b/api/src/DuckDBValueToJsonConverter.ts
@@ -1,6 +1,7 @@
 import { DuckDBType } from './DuckDBType';
 import { DuckDBTypeId } from './DuckDBTypeId';
 import { DuckDBValueConverter } from './DuckDBValueConverter';
+import { Json } from './Json';
 import {
   DuckDBArrayValue,
   DuckDBIntervalValue,
@@ -11,14 +12,6 @@ import {
   DuckDBValue,
 } from './values';
 
-export type Json =
-  | null
-  | boolean
-  | number
-  | string
-  | Json[]
-  | { [key: string]: Json };
-
 export class DuckDBValueToJsonConverter implements DuckDBValueConverter<Json> {
   public static readonly default = new DuckDBValueToJsonConverter();
 
diff --git a/api/src/Json.ts b/api/src/Json.ts
@@ -0,0 +1,7 @@
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };
diff --git a/api/src/duckdb.ts b/api/src/duckdb.ts
@@ -1,9 +1,10 @@
 export {
-  hugeint_to_double,
   double_to_hugeint,
-  uhugeint_to_double,
   double_to_uhugeint,
+  hugeint_to_double,
+  uhugeint_to_double,
 } from '@duckdb/node-bindings';
+export * from './configurationOptionDescriptions';
 export * from './DuckDBAppender';
 export * from './DuckDBConnection';
 export * from './DuckDBDataChunk';
@@ -19,8 +20,8 @@ export * from './DuckDBTypeId';
 export * from './DuckDBValueConverter';
 export * from './DuckDBValueToJsonConverter';
 export * from './DuckDBVector';
-export * from './configurationOptionDescriptions';
 export * from './enums';
+export * from './Json';
 export * from './sql';
 export * from './values';
 export * from './version';
diff --git a/api/test/api.test.ts b/api/test/api.test.ts
diff --git a/api/test/util/testAllTypes.ts b/api/test/util/testAllTypes.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`import duckdb from '@duckdb/node-bindings';`
`2`	`2`	`import { DuckDBLogicalType } from './DuckDBLogicalType';`
`3`	`3`	`import { DuckDBTypeId } from './DuckDBTypeId';`
	`4`	`+import { Json } from './Json';`
`4`	`5`	`import { quotedIdentifier, quotedString } from './sql';`
`5`	`6`	`import {`
`6`	`7`	`DuckDBDateValue,`
`@@ -33,6 +34,12 @@ export abstract class BaseDuckDBType<T extends DuckDBTypeId> {`
`33`	`34`	`}`
`34`	`35`	`return logicalType;`
`35`	`36`	`}`
	`37`	`+ public toJson(): Json {`
	`38`	`+ return {`
	`39`	`+ typeId: this.typeId,`
	`40`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`41`	`+ };`
	`42`	`+ }`
`36`	`43`	`}`
`37`	`44`
`38`	`45`	`export class DuckDBBooleanType extends BaseDuckDBType<DuckDBTypeId.BOOLEAN> {`
`@@ -401,6 +408,14 @@ export class DuckDBDecimalType extends BaseDuckDBType<DuckDBTypeId.DECIMAL> {`
`401`	`408`	`}`
`402`	`409`	`return logicalType;`
`403`	`410`	`}`
	`411`	`+ public override toJson(): Json {`
	`412`	`+ return {`
	`413`	`+ typeId: this.typeId,`
	`414`	`+ width: this.width,`
	`415`	`+ scale: this.scale,`
	`416`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`417`	`+ };`
	`418`	`+ }`
`404`	`419`	`public static readonly default = new DuckDBDecimalType(18, 3);`
`405`	`420`	`}`
`406`	`421`	`export function DECIMAL(`
`@@ -532,6 +547,14 @@ export class DuckDBEnumType extends BaseDuckDBType<DuckDBTypeId.ENUM> {`
`532`	`547`	`}`
`533`	`548`	`return logicalType;`
`534`	`549`	`}`
	`550`	`+ public override toJson(): Json {`
	`551`	`+ return {`
	`552`	`+ typeId: this.typeId,`
	`553`	`+ values: [...this.values],`
	`554`	`+ internalTypeId: this.internalTypeId,`
	`555`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`556`	`+ };`
	`557`	`+ }`
`535`	`558`	`}`
`536`	`559`	`export function ENUM8(`
`537`	`560`	`values: readonly string[],`
`@@ -586,6 +609,13 @@ export class DuckDBListType extends BaseDuckDBType<DuckDBTypeId.LIST> {`
`586`	`609`	`}`
`587`	`610`	`return logicalType;`
`588`	`611`	`}`
	`612`	`+ public override toJson(): Json {`
	`613`	`+ return {`
	`614`	`+ typeId: this.typeId,`
	`615`	`+ valueType: this.valueType.toJson(),`
	`616`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`617`	`+ };`
	`618`	`+ }`
`589`	`619`	`}`
`590`	`620`	`export function LIST(valueType: DuckDBType, alias?: string): DuckDBListType {`
`591`	`621`	`return new DuckDBListType(valueType, alias);`
`@@ -641,6 +671,14 @@ export class DuckDBStructType extends BaseDuckDBType<DuckDBTypeId.STRUCT> {`
`641`	`671`	`}`
`642`	`672`	`return logicalType;`
`643`	`673`	`}`
	`674`	`+ public override toJson(): Json {`
	`675`	`+ return {`
	`676`	`+ typeId: this.typeId,`
	`677`	`+ entryNames: [...this.entryNames],`
	`678`	`+ entryTypes: this.entryTypes.map(t => t.toJson()),`
	`679`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`680`	`+ };`
	`681`	`+ }`
`644`	`682`	`}`
`645`	`683`	`export function STRUCT(`
`646`	`684`	`entries: Record<string, DuckDBType>,`
`@@ -676,6 +714,14 @@ export class DuckDBMapType extends BaseDuckDBType<DuckDBTypeId.MAP> {`
`676`	`714`	`}`
`677`	`715`	`return logicalType;`
`678`	`716`	`}`
	`717`	`+ public override toJson(): Json {`
	`718`	`+ return {`
	`719`	`+ typeId: this.typeId,`
	`720`	`+ keyType: this.keyType.toJson(),`
	`721`	`+ valueType: this.valueType.toJson(),`
	`722`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`723`	`+ };`
	`724`	`+ }`
`679`	`725`	`}`
`680`	`726`	`export function MAP(`
`681`	`727`	`keyType: DuckDBType,`
`@@ -706,6 +752,14 @@ export class DuckDBArrayType extends BaseDuckDBType<DuckDBTypeId.ARRAY> {`
`706`	`752`	`}`
`707`	`753`	`return logicalType;`
`708`	`754`	`}`
	`755`	`+ public override toJson(): Json {`
	`756`	`+ return {`
	`757`	`+ typeId: this.typeId,`
	`758`	`+ valueType: this.valueType.toJson(),`
	`759`	`+ length: this.length,`
	`760`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`761`	`+ };`
	`762`	`+ }`
`709`	`763`	`}`
`710`	`764`	`export function ARRAY(`
`711`	`765`	`valueType: DuckDBType,`
`@@ -782,6 +836,14 @@ export class DuckDBUnionType extends BaseDuckDBType<DuckDBTypeId.UNION> {`
`782`	`836`	`}`
`783`	`837`	`return logicalType;`
`784`	`838`	`}`
	`839`	`+ public override toJson(): Json {`
	`840`	`+ return {`
	`841`	`+ typeId: this.typeId,`
	`842`	`+ memberTags: [...this.memberTags],`
	`843`	`+ memberTypes: this.memberTypes.map(t => t.toJson()),`
	`844`	`+ ...(this.alias ? { alias: this.alias } : {}),`
	`845`	`+ };`
	`846`	`+ }`
`785`	`847`	`}`
`786`	`848`	`export function UNION(`
`787`	`849`	`members: Record<string, DuckDBType>,`