duckdb / duckdb/duckdb-spatial
Add ST_Relate and ST_RelateMatch (DE-9IM topological relations)
- Dominant language
- C
- Stars
- 708
- Forks
- 96
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 5
Description
duckdb-spatial ships the named predicates (ST_Intersects, ST_Contains, ST_Within, ST_Touches, ST_Crosses, ST_Overlaps, ST_Covers, ST_CoveredBy) but has no general DE-9IM relate. A grep for relate across `src` returns nothing today. PostGIS exposes this as ST_Relate and ST_RelateMatch, and the GEOS C API duckdb-spatial already links provides every primitive needed.
**This is a small, self contained add that follows the existing ST_Intersects binding shape.**
| Proposed function | Returns | GEOS reentrant call |
|---|---|---|
| `ST_Relate(geom1, geom2)` | VARCHAR, the 9 char DE-9IM matrix | `GEOSRelate_r` |
| `ST_Relate(geom1, geom2, pattern)` | BOOLEAN, test against a pattern | `GEOSRelatePattern_r` |
| `ST_RelateMatch(matrix, pattern)` | BOOLEAN, match a matrix to a pattern | `GEOSRelatePatternMatch_r` |
Implementer tips
- The 2 arg and 3 arg ST_Relate overloads disambiguate by arity, no conflict.
- **The one new wrinkle for this module is returning a GEOS allocated C string.** `GEOSRelate_r` mallocs the matrix, so copy into a std::string and free with `GEOSFree_r` in the same scope. The other two return a plain char (1, 0, or 2 for exception), no free needed.
- The matrix is computed in literal (geom1, geom2) order, so the argument swap used by ST_Contains and ST_Within does not apply here.
- Default boundary node rule OGC matches PostGIS (`relate_full` in `lwgeom_geos_predicates.c`, `ST_RelateMatch` in `lwgeom_geos_relatematch.c`).
Known matrices for tests, equal 2FFF1FFF2, disjoint FF2FF1212, overlapping 212101212, within pattern T\*F\*\*F\*\*\*.
Open question for the implementer, expose a boundary node rule argument or keep just the 2 and 3 argument forms. PostGIS defaults to OGC and rarely needs the others.
Sharing this as research in case it helps whoever picks it up.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the existing ST_Intersects binding under src and tracing how spatial functions are registered and tested. Add the two ST_Relate overloads and ST_RelateMatch using the listed GEOS reentrant calls, handling the allocated matrix string in the same scope. Use the provided known matrices and pattern to verify the three functions and confirm the chosen boundary-node API remains consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- database
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100