Data connectors

Connectors are declared in sources.yaml and loaded lazily the first time a query asks for that type. Each backend's heavy dependencies are an optional pip extra, so you only install what you use. A query's connector= chooses which one runs it; omitted, the default source answers.

# sources.yaml
sales_data:
  type: csv
  directory: data

warehouse:
  type: postgres
  host: ${PG_HOST}        # ${ENV_VAR} expansion is supported everywhere
  database: analytics
  user: ${PG_USER}
  password: ${PG_PASSWORD}

The default source #

A query with no connector= runs on the project's default source:

1. the source named by the top-level default: key in sources.yaml;
2. otherwise, if exactly one source is configured, that one — a single-source project never needs connector= anywhere.

# sources.yaml
default: warehouse        # queries without connector= run here

warehouse:
  type: postgres
  host: ${PG_HOST}
  database: analytics

archive:
  type: duckdb
  path: data/archive.duckdb

Source names carry no meaning — call them whatever reads well (default is the one reserved word). A default: naming an unknown source fails at startup, and with several sources and no default: there is no default: a query that omits connector= fails with a message asking you to set one.

The built-in connectors #

The csv, json, parquet, duckdb, excel, and sheets connectors all run SQL on an embedded DuckDB — so files and spreadsheets answer the same SQL as a real database.