ST_RelateMatch

What is ST_RelateMatch?

ST_RelateMatch returns true if a given DE-9IM intersection matrix (a 9-character string like FF1FF0102) satisfies a DE-9IM intersection matrix pattern (which may use *, T, F, 0, 1, 2). It is a string-level comparator on DE-9IM codes — it does not take geometry arguments.

ST_RelateMatch(text intersectionMatrix, text intersectionMatrixPattern) → boolean

This is useful when you have a precomputed DE-9IM matrix from ST_Relate(a, b) and want to test it against several patterns without recomputing the full topology.

When would you use ST_RelateMatch?

Use ST_RelateMatch when you compute ST_Relate(a, b) once and want to classify the pair against multiple topological categories cheaply — for example, in a QA report that tags each geometry pair as "contains", "overlaps", "touches", or "disjoint" by matching the single DE-9IM result against several patterns. It is also useful in analytics pipelines where the DE-9IM matrix is stored alongside feature pairs.

1-- Classify each feature pair by its relationship
2SELECT a.id, b.id,
3       CASE
4         WHEN ST_RelateMatch(m, 'T*F**F***') THEN 'within'
5         WHEN ST_RelateMatch(m, 'T*T***T**') THEN 'overlaps'
6         WHEN ST_RelateMatch(m, 'FT*******') THEN 'touches'
7         ELSE 'other'
8       END AS relation
9FROM (
10  SELECT a.id AS a_id, b.id AS b_id, ST_Relate(a.geom, b.geom) AS m
11  FROM features a, features b WHERE a.id < b.id
12) AS pairs;

FAQs

What are valid pattern characters?

T (any intersection — 0, 1, or 2), F (no intersection), 0/1/2 (exact dimension), and * (any). The pattern must be exactly 9 characters long, just like a DE-9IM matrix.

How is it different from ST_Relate with a pattern?

ST_Relate(a, b, pattern) computes the full DE-9IM from geometries and tests it against the pattern in one call. ST_RelateMatch(matrix, pattern) skips the geometry computation entirely and just compares two strings — useful when the matrix is already known.

Where does the matrix come from?

Typically from ST_Relate(a, b), which returns the full 9-character DE-9IM matrix. You can also construct matrices manually or store them in a table for pairs you have already analysed.

Is it index-accelerated?

It is a pure string comparator, so it does not use a spatial index. The cost of computing the underlying DE-9IM matrix with ST_Relate dominates; ST_RelateMatch itself is free.