pygeofilter-duckdb¶

Translate parsed CQL2 filters into SQL predicates for DuckDB. The package extends pygeofilter's SQL evaluator with DuckDB geometry constructors and timestamp literals. It returns the expression used after WHERE; your application executes the query.

For client-supplied filters, prefer to_sql_where_params to keep literal values separate from SQL, with application-controlled property and function mappings.

Start here¶

Goal	Guide
Translate and execute a filter	First filter tutorial
Query a GeoParquet file	Query GeoParquet
Map properties and functions	Configure translation
Run checks or preview documentation	Development guide
Look up exact behavior	Python API and operators
Build a distribution	Package builds
Understand the evaluator	Architecture

Installation and compatibility¶

python -m pip install pygeofilter-duckdb

The project requires Python 3.10 or later and requires pygeofilter>=0.4.0,<0.5.0. The configured test matrix covers Python 3.10–3.14.

Python	DuckDB dependency
3.10–3.13	>=1.1.3,<1.6.0
3.14 and later	>=1.4.2,<1.6.0

These constraints come from pyproject.toml. The Python 3.14 constraint avoids building the older DuckDB dependency from source. The tests execute scalar and spatial queries across representative dependency versions; see verified compatibility.

The example notebooks show STAC Items, GeoParquet creation, and DuckDB queries. They may need additional dependencies and network access.