duckdb / duckdb/duckdb-spatial

Add ST_Relate and ST_RelateMatch (DE-9IM topological relations)

Open
#820 2 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.