duckdb-spatial

Clarify DuckDB spatial extension pitfalls for ST_Read and read_parquet with remote files.

4|1|Updated Feb 24, 2026
One-click install
npx skills add https://github.com/boettiger-lab/agent-skills --skill duckdb-spatial-boettiger-lab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: duckdb-spatial
Source: https://github.com/boettiger-lab/agent-skills/tree/main/duckdb-spatial
Command: npx skills add https://github.com/boettiger-lab/agent-skills --skill duckdb-spatial-boettiger-lab

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Clarifies and prevents common misconfigurations when using DuckDB's spatial extension with geospatial data, including the differences between ST_Read() and read_parquet(), URL handling, and S3 endpoint secrets.

Core Features & Use Cases

  • Clarifies how ST_Read() and read_parquet() read geospatial data and which URL schemes they accept.
  • Explains enabling and using the spatial extension to interpret geometry columns in Parquet files.
  • Use cases include remote geodata on S3 or HTTPS and troubleshooting errors related to geospatial data ingestion.

Quick Start

Install and load the DuckDB spatial extension, then try a remote geodata read to validate correct URL handling.

Frequently Asked Questions about duckdb-spatial

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I read geospatial data from remote S3 or HTTPS URLs in DuckDB?

DuckDB reads remote geospatial data by using ST_Read or read_parquet with correctly formatted S3 or HTTPS URLs. You must configure S3 endpoint secrets to ensure the spatial extension can properly access and interpret remote files.

What is the difference between ST_Read and read_parquet for geospatial workflows?

ST_Read and read_parquet differ in how they ingest geospatial data and which URL schemes they accept. ST_Read is designed for spatial formats, while read_parquet handles Parquet files and requires the spatial extension to interpret geometry columns.

Why does read_parquet not recognize geometry columns in my Parquet files?

read_parquet fails to recognize geometry columns when the DuckDB spatial extension is not installed and loaded. Enabling the spatial extension allows DuckDB to properly interpret and parse the geospatial geometry data stored in Parquet files.

Do I need to install the spatial extension to parse GIS data with DuckDB?

Yes, you need to install and load the DuckDB spatial extension to parse GIS data. The extension provides the necessary functions like ST_Read and enables geometry column interpretation for geospatial workflows.

How do I configure S3 endpoint secrets for reading remote geospatial data?

Configuring S3 endpoint secrets involves setting up the correct authentication credentials within DuckDB. This ensures that ST_Read and read_parquet can securely access and read geospatial data stored on remote S3 endpoints.

What are common limitations when using DuckDB spatial extension with remote files?

Limitations of the DuckDB spatial extension include URL handling misconfigurations and secret setup errors when accessing remote files. Understanding the specific URL schemes accepted by ST_Read and read_parquet is crucial to avoid ingestion errors.