Class DuckDbDialect

Kysely dialect for duckdb.

Quick Start and Usage Example

Please see also Kysely Docs and Duckdb Docs

Install

$ npm install --save kysely @duckdb/node-api kysely-duckdb

Basic Usage Example

reding data from json file.

import { DuckDBInstance } from "@duckdb/node-api";
import { Kysely } from "kysely";
import { DuckDbDialect } from "kysely-duckdb"

interface PersonTable {
  first_name: string,
  gender: string,
  last_name: string,
};
interface DatabaseSchema {
  person: PersonTable,
};

const db = await DuckDBInstance.create(":memory:");
const duckdbDialect = new DuckDbDialect({
  database: db,
  tableMappings: {
    person:
      `read_json('./person.json', columns={"first_name": "STRING", "gender": "STRING", "last_name": "STRING"})`,
  },
});
const kysely = new Kysely<DatabaseSchema>({ dialect: duckdbDialect });

const res = await kysely.selectFrom("person").selectAll().execute();

Implements

  • Dialect

Constructors

constructor

Properties

config

Methods

createAdapter createDriver createIntrospector createQueryCompiler

Constructors

constructor

  • new DuckDbDialect(config): DuckDbDialect

  • Parameters

    • config: {
          database: DuckDBInstance | (() => Promise<DuckDBInstance>);
          onCreateConnection?: ((conection) => Promise<void>);
          tableMappings?: {
              [tableName: string]: string;
          };
      }

      configulations for DuckDbDialect

      • database: DuckDBInstance | (() => Promise<DuckDBInstance>)

        DuckDBInstance instance or a function returns a Promise of DuckDBInstance instance.

      • Optional onCreateConnection?: ((conection) => Promise<void>)

        called when a connection is created.

        Returns

        Promise

          • (conection): Promise<void>

          • Parameters

            • conection: DuckDBConnection

              DuckDBConnection instance that is created.

            Returns Promise<void>

      • Optional tableMappings?: {
            [tableName: string]: string;
        }

        Mappings of table name in kysely to duckdb table expressions.

        Duckdb can read external source(file, url or database) as table like: SELECT * FROM read_json_objects('path/to/file/*.json'). You can use raw duckdb table expression as table name, but it may be too long, preserving too many implementation details.

        This mappings is used to replace table name string to duckdb table expression.

        Keys can be plain table names or schema-qualified names (e.g., "schema.table").

        • Plain table names match only when no schema is specified in the query.
        • Schema-qualified keys match when using .withSchema("schema").selectFrom("table").
        • When a schema is specified but not found in any mapping key, the table is resolved normally (useful for attached databases like Postgres via ATTACH).

        Example

        const dialect = new DuckDbDialect({
         database: db,
         tableMappings: {
           // Matches: db.selectFrom("person")
           person: 'read_json_object("s3://my-bucket/person.json")',
           // Matches: db.withSchema("archive").selectFrom("person")
           "archive.person": 'read_parquet("s3://my-bucket/archive/person.parquet")',
         }
        });

        const db = new Kysely<Database>({ dialect });

        // Uses the "person" mapping (reads from JSON)
        await db.selectFrom("person").selectAll().execute();

        // Uses the "archive.person" mapping (reads from Parquet)
        await db.withSchema("archive").selectFrom("person").selectAll().execute();

        // No mapping for "neon.person", queries the attached database directly
        await db.withSchema("neon").selectFrom("person").selectAll().execute();
        • [tableName: string]: string

    Returns DuckDbDialect

Properties

Private Readonly config

config: {
    database: DuckDBInstance | (() => Promise<DuckDBInstance>);
    onCreateConnection?: ((conection) => Promise<void>);
    tableMappings?: {
        [tableName: string]: string;
    };
}

configulations for DuckDbDialect

Type declaration

  • database: DuckDBInstance | (() => Promise<DuckDBInstance>)

    DuckDBInstance instance or a function returns a Promise of DuckDBInstance instance.

  • Optional onCreateConnection?: ((conection) => Promise<void>)

    called when a connection is created.

    Returns

    Promise

      • (conection): Promise<void>

      • Parameters

        • conection: DuckDBConnection

          DuckDBConnection instance that is created.

        Returns Promise<void>

  • Optional tableMappings?: {
        [tableName: string]: string;
    }

    Mappings of table name in kysely to duckdb table expressions.

    Duckdb can read external source(file, url or database) as table like: SELECT * FROM read_json_objects('path/to/file/*.json'). You can use raw duckdb table expression as table name, but it may be too long, preserving too many implementation details.

    This mappings is used to replace table name string to duckdb table expression.

    Keys can be plain table names or schema-qualified names (e.g., "schema.table").

    • Plain table names match only when no schema is specified in the query.
    • Schema-qualified keys match when using .withSchema("schema").selectFrom("table").
    • When a schema is specified but not found in any mapping key, the table is resolved normally (useful for attached databases like Postgres via ATTACH).

    Example

    const dialect = new DuckDbDialect({
     database: db,
     tableMappings: {
       // Matches: db.selectFrom("person")
       person: 'read_json_object("s3://my-bucket/person.json")',
       // Matches: db.withSchema("archive").selectFrom("person")
       "archive.person": 'read_parquet("s3://my-bucket/archive/person.parquet")',
     }
    });

    const db = new Kysely<Database>({ dialect });

    // Uses the "person" mapping (reads from JSON)
    await db.selectFrom("person").selectAll().execute();

    // Uses the "archive.person" mapping (reads from Parquet)
    await db.withSchema("archive").selectFrom("person").selectAll().execute();

    // No mapping for "neon.person", queries the attached database directly
    await db.withSchema("neon").selectFrom("person").selectAll().execute();
    • [tableName: string]: string

Methods

createAdapter

  • createAdapter(): DialectAdapter

  • Returns DialectAdapter

createDriver

  • createDriver(): Driver

  • Returns Driver

createIntrospector

  • createIntrospector(db): DatabaseIntrospector

  • Parameters

    • db: Kysely<any>

    Returns DatabaseIntrospector

createQueryCompiler

  • createQueryCompiler(): QueryCompiler

  • Returns QueryCompiler

Settings

Member Visibility

Theme

On This Page

constructorconfigcreateAdaptercreateDrivercreateIntrospectorcreateQueryCompiler