Test custom relationships using the ST

Test custom relationships using the ST_Relate method

For best performance, you should always use methods like ST_Within, or ST_Touches to test single, specific relationships between geometries. However, if you have more than one relationship to test, ST_Relate can be a better method, since you can test for several relationships at once. ST_Relate is also good when you want to test for a different interpretation of a predicate such as within (ST_Within). For example, when testing if a point is within another geometry, ST_Within returns false if the point falls on the boundary of the other geometry. The interpretation of within you want to test for, however, may include having a point on a boundary. In this case, you perform a custom relationship test using ST_Relate to test for the condition.

The most common use of ST_Relate is as a predicate, where you specify the exact relationship(s) to test for. However, you can also use ST_Relate to determine all possible relationships between two geometries.

Predicate use of ST_Relate

ST_Relate assesses how geometries are related by performing intersection tests of their interiors, boundaries, and exteriors. The relationship between the geometries is then described in a 9-character string in DE-9IM (Dimensionally Extended 9 Intersection Model) format, where each character of the string represents the result of an intersection test.

When you use ST_Relate as a predicate, you pass a DE-9IM string reflecting intersection results to test for. If the geometries satisfy the conditions in the DE-9IM string you specified, then ST_Relate returns a 1. If the conditions are not satisfied, then 0 is returned. If either or both of the geometries is NULL, then NULL is returned.

The 9-character DE-9IM string is a flattened representation of a pair-wise matrix of the intersection tests between interiors, boundaries, and exteriors. The next table shows the 9 intersection tests in the order they are performed: left to right, top to bottom:

	g2 interior	g2 boundary	g2 exterior
g1 interior	`Interior(g1) ∩ Interior(g2)`	`Interior(g1) ∩ Boundary(g2)`	`Interior(g1) ∩ Exterior(g2)`
g1 boundary	`Boundary(g1) ∩ Interior(g2)`	`Boundary(g1) ∩ Boundary(g2)`	`Boundary(g1) ∩ Exterior(g2)`
g1 exterior	`Exterior(g1) ∩ Interior(g2)`	`Exterior(g1) ∩ Boundary(g2)`	`Exterior(g1) ∩ Exterior(g2)`

When you specify the DE-9IM string, you can specify *, 0, 1, 2, T, or F for any of the 9 characters. These values refer to the number of dimensions of the geometry created by the intersection.

When you specify:	The intersection test result must return:
T	one of: 0, 1, 2 (an intersection of any dimension)
F	-1
*	-1, 0, 1, 2 (any value)
0	0
1	1
2	2

Suppose you want to test whether a geometry is within another geometry using ST_Relate and a custom DE-9IM string for the within predicate:

SELECT new ST_Polygon('Polygon(( 2 3, 8 3, 4 8, 2 3 ))').ST_Relate( new ST_Polygon('Polygon((-3 3, 3 3, 3 6, -3 6, -3 3))'), 'T*F**F***' );

This is equivalent to asking ST_Relate to look for the following conditions when performing the intersection tests:

	g2 interior	g2 boundary	g2 exterior
g1 interior	one of: 0, 1, 2	one of: 0, 1, 2, -1	-1
g1 boundary	one of: 0, 1, 2, -1	one of: 0, 1, 2, -1	-1
g1 exterior	one of: 0, 1, 2, -1	one of: 0, 1, 2, -1	one of: 0, 1, 2, -1

When you execute the query, however, ST_Relate returns 0 indicating that the first geometry is not within the second geometry.

To view the two geometries and compare their appearance to what is being tested, execute the following statement in the Interactive SQL Spatial Viewer (Tools » Spatial Viewer):

SELECT NEW ST_Polygon('Polygon(( 2 3, 8 3, 4 8, 2 3 ))') 
UNION ALL
SELECT NEW ST_Polygon('Polygon((-3 3, 3 3, 3 6, -3 6, -3 3))');

Screenshot of the SVG Preview tab showing a rectangle with triangle. One corner of the rectangle overlaps a corner of the triangle.

Non-predicate use of ST_Relate

The non-predicate use of ST_Relate returns the full relationship between two geometries.

For example, suppose you have the same two geometries used in the previous example and you want to know how they are related. You would execute the following statement in Interactive SQL to return the DE-9IM string defining their relationship.

SELECT new ST_Polygon('Polygon(( 2 3, 8 3, 4 8, 2 3 ))').ST_Relate(new ST_Polygon('Polygon((-3 3, 3 3, 3 6, -3 6, -3 3))'));

ST_Relate returns the DE-9IM string, 212111212.

The matrix view of this value shows that there are many points of intersection:

	g2 interior	g2 boundary	g2 exterior
g1 interior	2	1	2
g1 boundary	1	1	1
g1 exterior	2	1	2