Skip to main content

PyCanopy

PyPI version Total downloads Python versions CI License: MIT Docs Open In Colab

A spatial query layer for Polars. Rust core, Python API.


PyCanopy vs SedonaDB, DuckDB, and GeoPandas on Apache SpatialBench SF1

Apache SpatialBench SF1 · lower is better · bars past the cap truncated with their value · TIMEOUT / ERROR annotated


Installation

pip install pycanopy

Pre-built wheels for Linux, macOS, and Windows. No Rust toolchain required.

import polars as pl
from pycanopy import SpatialFrame

sf = SpatialFrame(pl.read_parquet("cities.parquet"), x_col="lon", y_col="lat")
result = sf.lazy().filter(pl.col("population") > 100_000).range_query(-10.0, 35.0, 40.0, 70.0).collect()

Why PyCanopy

The driving motivator behind creating this library was to provide the optimizations of relational DBs (query planning, indexing, etc) in a fast, Polars-like interface meant for in-memory spatial work.

Capability PyCanopy GeoPandas DuckDB SedonaDB Spatial Polars
Uses Polars DataFrames directly ✓ ✗ ✗ ✗ ✓
Spatial-aware query planning ✓ ✗ ✓ ✓ ✗
Automatically accelerates spatial joins with an index ✓ ✓ ✓ ✓ ✗
Explicit cost-based choice between scanning and building an index ✓ ✗ ✗ ✗ ✗
Selects among multiple spatial index types by workload ✓ ✗ ✗ ✗ ✗

Example Operations

Optimized range query

lf = (
    sf.lazy()
    .range_query(min_x=-10.0, min_y=35.0, max_x=40.0, max_y=70.0)
    .filter(pl.col("population") > 100_000)
)
print(lf.explain())
# RANGE_QUERY [(-10, 35) → (40, 70)]
# FROM
#   FILTER [(col("population")) > (dyn int: 100000)]
#   FROM
#     DF [N=100,000; path: EXPR]

The optimizer runs the scalar filter first. On the EXPR path, the surviving original row indices are passed to Rust, which returns a spatial Boolean mask over those candidates.

kNN join

query_df = pl.DataFrame({"qx": [2.35, 13.4], "qy": [48.85, 52.5]})

result = sf.lazy().knn_join(query_df, x_col="qx", y_col="qy", k=3).collect()

For each row in query_df, returns the 3 nearest rows in the SpatialFrame. Large probes are streamed in morsels automatically.

Point-in-polygon join with aggregation

import pycanopy as pc

zones = SpatialFrame.from_wkb_polygons(
    pl.read_parquet("zones.parquet"),
    geometry_col="geometry",
)
trips = pl.read_parquet("trips.parquet")

stats = (
    zones.lazy()
    .within_join(trips, x_col="lon", y_col="lat")
    .group_by(["zone_id"])
    .agg(trip_count=pc.agg.count(), avg_fare=pc.agg.mean("fare"))
)

Each query-side batch is joined and aggregated before the next begins, so the complete pair frame is never materialized.


Benchmarks

Apache SpatialBench

Run on a single m7i.2xlarge (8 vCPU, 32 GB), the same hardware used by Apache SpatialBench. PyCanopy is measured live with index_mode="auto". Results were produced using the benchmark harness in bench/spatial_bench.

PyCanopy is fastest on 11/24 testcases and lands within 5% of the fastest time on 14/24 testcases (there is some variance among benchmark runs).

SF1 (~6M trips)

PyCanopy vs SedonaDB, DuckDB, and GeoPandas on Apache SpatialBench SF1

Apache SpatialBench SF1 · lower is better · linear axis, bars past the cap truncated with their value · TIMEOUT / ERROR annotated

SF10 (~60M trips)

PyCanopy vs SedonaDB, DuckDB, and GeoPandas on Apache SpatialBench SF10

Apache SpatialBench SF10 · lower is better · linear axis, bars past the cap truncated with their value · TIMEOUT / ERROR annotated

SedonaDB, DuckDB, and GeoPandas baselines come from published SpatialBench results. See the full per-query results and methodology.


How It Works

Spatial-aware Logical Planning

  • Predicate pushdown: moves compatible scalar filters ahead of spatial predicates
  • Filter fusion: combines eligible range and contains predicates in a single Rust call
  • Projection pushdown: narrows join inputs before gathering rows
  • Join orientation: flips supported joins based on relative input sizes

Physical Planning

  • IO path: directly queries the spatial index and slices source rows for selective predicates
  • EXPR path: applies scalar filters in Polars before evaluating broader spatial predicates in Rust
  • Morsel streaming: processes large query-side joins in batches for incremental collection, lazy pipelines, or direct Parquet sinks
  • Streaming aggregation: aggregates each join batch as it is produced, avoiding materialization of the complete join result

Automatic Indexing

  • Tracks dataset extent, spatial distribution, and density to estimate query selectivity
  • Uses a cost model to compare brute-force scanning, reusing an existing index, and building and probing a new index
  • Selects among grid, KD-tree, and R-tree indexes based on the query and workload

Why Rust

The hot paths benefit from packed immutable index structures, parallel loops, and efficient access to contiguous NumPy buffers. PyO3 and Maturin provide direct Python bindings and cross-platform extension packaging.

For a detailed overview of PyCanopy's design, see the How It Works documentation.


Acknowledgements

Some works that inspired this project:

  • Polars: a columnar DataFrame engine that PyCanopy builds on
  • geo-index: provides packed, immutable, zero-copy KD-tree and R-tree structures used
  • Spatial Polars: an earlier effort to bring spatial functionality to Polars
  • Apache Sedona: state-of-the-art spatial SQL engine + benchmark for evals

License

MIT

Metadata

Release files for pycanopy 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycanopy 0.4.1
File Size Uploaded Provenance Actions
pycanopy-0.4.1.tar.gz 415.6 kB With provenance Details for pycanopy-0.4.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pycanopy 0.4.1
File Actions
pycanopy-0.4.1-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for pycanopy-0.4.1-cp310-abi3-win_amd64.whl
pycanopy-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for pycanopy-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
pycanopy-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for pycanopy-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pycanopy-0.4.1-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for pycanopy-0.4.1-cp310-abi3-macosx_11_0_arm64.whl
pycanopy-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for pycanopy-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 5.2 MB

Release files / pycanopy-0.4.1.tar.gz

Download URL pycanopy-0.4.1.tar.gz
Size 415.6 kB
Tags Source
SHA-256 checksum
How to use checksums
cb009771eb38050c371afaef33004ed673f197bd296ecdfdcf26b5af12144010
BLAKE2b-256 checksum
How to use checksums
178cd1a4cc98867a31bf8ed114cfc5d9d2deb164943aaabe2818e8bbf1559a00
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

Release files / pycanopy-0.4.1-cp310-abi3-win_amd64.whl

Download URL pycanopy-0.4.1-cp310-abi3-win_amd64.whl
Size 886.5 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
ed320550240da9a86d744ab65f711918a53e6ef012f4490b228032f8208a6b59
BLAKE2b-256 checksum
How to use checksums
5f19c4dcd2d4500bcdbf7430bd3d90773a5d5e5375bc548564d6e45a55c5fb5e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

Release files / pycanopy-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL pycanopy-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 1.0 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
bb2fcd8cd8f0bd3a63c690ad8c028cf20bbe4f9b979923b4c5a443b59541288f
BLAKE2b-256 checksum
How to use checksums
0195c47a46b0f6e8db6dc1ca27d95f97ecf73d231e9e77d01222b34fdcd2a845
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

Release files / pycanopy-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL pycanopy-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 963.0 kB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
fbf1c0b09cbbeb700d0435ec6b88ac45d15c87a25f58ec2413e14483b245c235
BLAKE2b-256 checksum
How to use checksums
d134b3b7c8ce3fb0b8d019f8be59a3e6f48d4a828240198486fbc1ee213b0a68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

Release files / pycanopy-0.4.1-cp310-abi3-macosx_11_0_arm64.whl

Download URL pycanopy-0.4.1-cp310-abi3-macosx_11_0_arm64.whl
Size 918.1 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
e5c4870c825dd04725ec97f8e890548061b28e1686192e2204063cca8fa2b940
BLAKE2b-256 checksum
How to use checksums
d0f817de183c7afde3057bccfe5f43bf161b4fc547648f1bf74a1f3e88ff080a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

Release files / pycanopy-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl

Download URL pycanopy-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl
Size 977.8 kB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
213b63dd81c15ce09c470a2fa53c05ff4308e4b29624a034b38930ccb10a84bb
BLAKE2b-256 checksum
How to use checksums
f93614c826174fa688f05f2bf50d63e1f6750eebc4118d7613ea9d27cba3ed80
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

Security for pycanopy 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for pycanopy-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page