title: 'DuckLake Catalog Connector' sidebar_label: 'DuckLake' description: 'Connect to a DuckLake catalog for federated SQL query.' sidebar_position: 6 pagination_prev: null pagination_next: null tags:
Connect to a DuckLake catalog for federated SQL query. DuckLake is an open lakehouse format that stores metadata in a SQLite-compatible database (or PostgreSQL) and data in Parquet files, providing lakehouse-style operations without a separate metadata service.
For connecting to individual DuckLake tables, see the DuckLake Data Connector documentation.
fromThe from field specifies the DuckLake catalog connection. Use ducklake:<connection_string>, where connection_string is the location of the DuckLake metadata.
Supported connection string formats:
| Backend | Example |
|---|---|
| Local file | ducklake:/path/to/metadata.ducklake |
| AWS S3 | ducklake:s3://bucket/path/metadata.ducklake |
| PostgreSQL | ducklake:postgres:dbname=mydb host=localhost user=postgres password=secret |
The connection string can also be provided via the ducklake_connection_string parameter.
nameThe name field specifies the name of the catalog in Spice. Tables from the DuckLake catalog will be available using this name in Spice. The schema hierarchy of the DuckLake catalog is preserved.
includeUse the include field to specify which tables to include from the catalog. The include field supports glob patterns to match multiple tables.
accessThe access field controls what operations are allowed on the catalog:
| Access Mode | Description |
|---|---|
read (default) | Query tables only. DuckDB opens in read-only mode. |
read_write | Query and write data (INSERT). DuckDB opens in read-write mode. |
read_write_create | Full access including CREATE/DROP SCHEMA and TABLE. DuckDB opens in read-write mode. |
params| Parameter Name | Description |
|---|---|
ducklake_connection_string | The DuckLake metadata location (e.g., s3://bucket/path/metadata.ducklake). If omitted, the value from from: ducklake:<connection_string> is used. |
ducklake_name | The name to attach the DuckLake catalog as in DuckDB. Default: ducklake. |
ducklake_open | Path to an existing DuckDB file for persistent storage. If not provided, an in-memory DuckDB instance is used. |
ducklake_aws_region | Optional. The AWS region for S3 storage. Default: us-east-1 when explicit credentials are provided. |
ducklake_aws_access_key_id | Optional. The AWS access key ID for S3 storage. Must be set together with ducklake_aws_secret_access_key. |
ducklake_aws_secret_access_key | Optional. The AWS secret access key for S3 storage. Must be set together with ducklake_aws_access_key_id. |
ducklake_aws_endpoint |
When no explicit S3 credentials are configured, DuckDB falls back to its built-in credential chain provider:
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)~/.aws/credentials)To provide explicit S3 credentials, use the ducklake_aws_* parameters:
For S3-compatible storage (e.g., MinIO), use ducklake_aws_endpoint:
Use PostgreSQL as the metadata storage for multi-user access (note: from field does not support secrets replacement):
This catalog supports writing data to DuckLake tables using SQL INSERT INTO statements when access is set to read_write or read_write_create.
Spice integrates with multiple secret stores to help manage sensitive data securely. For detailed information on supported secret stores, refer to the secret stores documentation. Additionally, learn how to use referenced secrets in component parameters by visiting the using referenced secrets guide.
:::warning[Limitations]
information_schema and pg_catalog system schemas are automatically filtered out during discovery.information_schema is performed on each refresh cycle.:::
| Optional. Custom S3-compatible endpoint URL (e.g., for MinIO). |
ducklake_aws_allow_http | Optional. Set to true to allow HTTP (non-TLS) connections to S3. Default: false. |