--- title: SQL data sources description: Query database-backed data sources as rows or Arrow tables. hide_title: true page_style: designed --- import {DocPageHeader} from '@site/src/components/docs/doc-page-header'; import {DocOrientation, ReferenceBoundary} from '@site/src/components/docs/designed-doc'; SQL data sources provide `createDataSource()` integration for external and embedded databases. ## Sources - `DuckDBSQLSource` connects to local DuckDB databases in Node.js and DuckDB wasm in the browser. - `SnowflakeSQLSource` connects to Snowflake through the SQL API. ## Core methods - `queryRows(sqlText, options)` returns object rows. - `queryArrow(sqlText, options)` returns an Apache Arrow `Table`. - `getMetadata()` returns catalogs, schemas, tables, and adapter capabilities. ## DuckDB Arrow interoperability The browser adapter exchanges Arrow IPC bytes with DuckDB-Wasm. DuckDB retains its Arrow 17 dependency; loaders.gl decodes query results with Arrow 21. Do not force DuckDB's Arrow dependency to a different major through package-manager resolutions or bundler deduplication. IPC results are materialized in memory before decoding. `DuckDBSQLDataSource.insertArrowTable(table, options)` uploads an Apache Arrow `Table` by serializing it as an IPC stream. `options.tableName` identifies the destination, `schemaName` optionally selects a schema, and `create` defaults to `true`. Set `create: false` to append to an existing table. Uploads currently require the browser DuckDB-Wasm adapter; the Node adapter reports an unsupported operation. `insertArrowIPC(bytes, options)` also accepts an already serialized IPC stream. Custom adapters can implement `insertArrowIPC(bytes, options)`. ```typescript await source.insertArrowTable(arrowTable, {tableName: 'events'}); await source.insertArrowTable(moreEvents, {tableName: 'events', create: false}); const result = await source.queryArrow('SELECT * FROM events'); ``` ## Sources and credits See the [package source and license inventory](https://github.com/visgl/loaders.gl/blob/master/modules/sql/THIRD-PARTY-NOTICES.md) and the project-wide [Attributions and Credits](/docs/references-and-credits). ### Common queries on DuckDB tables Resolve a DuckDB table once with `await source.getTable(name)` and pass the handle as `source` to `query` or `queryInBatches` from `@loaders.gl/core/query`. You can also use a structured `from: {source, table}` reference with a registered DuckDB source. Reuse the table handle for adjacent pages to avoid repeating schema and table discovery. For base tables with an accessible DuckDB `rowid`, the reader uses row ID order and passes `OFFSET` and `LIMIT` into SQL. Page boundaries assume the underlying table stays unchanged between calls. Deep offsets can still cost work inside DuckDB. The planner accepts signed integer identity and widening casts that preserve Arrow semantics. Other casts run in Arrow. For example, Arrow truncates fractional values when casting to integers, while DuckDB can round them. The common reader currently supports signed integer, floating-point, Boolean, and VARCHAR columns. DuckDB also pushes down signed integer casts to `DOUBLE PRECISION` for input widths up to 32 bits, whose full range is exactly representable. In a mixed projection, a safe cast can run in DuckDB while other SELECT expressions run in Arrow on the same filtered and paged rows.