---
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.