ST_Equals(geometry A, geometry B) tests the spatial equality of two geometries. It returns TRUE if two geometries of the same type have identical shapes. This is generally only the case if they have identical x,y coordinate values.

For example, let’s use a point geometry from the nyc_subway_stations table. We’ll query the feature for the Broad St station, and display it using an exact data representation (known as WKB) and in a more readable text format (called WKT):

SELECT name, geom, ST_AsText(geom)
FROM nyc_subway_stations
WHERE name = 'Broad St';

   name   |                      geom                          |      st_astext
----------+----------------------------------------------------+-----------------------
 Broad St | 0101000020266900000EEBD4CF27CF2141BC17D69516315141 | POINT(583571 4506714)

The geometry value can be used with a ST_Equals test to retrieve the original record:

SELECT name
FROM nyc_subway_stations
WHERE ST_Equals(geom, '0101000020266900000EEBD4CF27CF2141BC17D69516315141');

Broad St

NOTE: The WKB data format of the point is not human readable, but it is an exact representation of the coordinate values. For a test like equality, using the exact value is necessary.

ST_Intersects(geometry A, geometry B) returns t (TRUE) if the two shapes have any space in common, i.e., if their boundaries or interiors intersect.

Let's take our Broad Street subway station and determine its neighborhood using the ST_Intersects function:

SELECT name, ST_AsText(geom)
FROM nyc_subway_stations
WHERE name = 'Broad St';

    POINT(583571 4506714)

SELECT name, boroname
FROM nyc_neighborhoods
WHERE ST_Intersects(geom, ST_GeomFromText('POINT(583571 4506714)',26918));

       name        | boroname
-------------------+-----------
Financial District | Manhattan

ST_Disjoint

ST_Disjoint(geometry A , geometry B) is the opposite of ST_Intersects. If two geometries are disjoint, they do not intersect, and vice-versa. In fact, it is often more efficient to test "not intersects" than to test "disjoint" because the intersects tests can be spatially indexed, while the disjoint test cannot.

ST_Within and ST_Contains is a pair of functions which have related but opposite meanings.

ST_Within(geometry A , geometry B) returns TRUE if the first geometry is completely within the second geometry, and they have at least one interior point in common.

ST_Contains(geometry A, geometry B) returns TRUE if the first geometry completely contains the second geometry, and they have at least one interior point in common.

ST_Contains tests for the opposite relationship of ST_Within. Symbolically, this means

  ST_Contains(A,B) = ST_Within(B, A)

PostGIS provides another pair of functions for testing containment, ST_Covers and ST_CoveredBy.

These functions are not part of the SQL/MM standard, but they address a subtlety of ST_Contains and ST_Within which can occasionally cause problems. The standard definition of ST_Contains has the quirk that polygons do not contain Linestrings which lie along their edge (in their boundary).

SELECT ST_Contains(
    'POLYGON ((0 1, 1 1, 1 0, 0 0, 0 1))'::geometry,
    'LINESTRING (0 0, 1 0)'::geometry );

  f

ST_Covers(geometry A, geometry B) is defined so that this anomaly does not occur, which generally corresponds more closely to what you would expect.

SELECT ST_Covers(
    'POLYGON ((0 1, 1 1, 1 0, 0 0, 0 1))'::geometry,
    'LINESTRING (0 0, 1 0)'::geometry );

  t

ST_CoveredBy(geometry A, geometry B) has the opposite meaning to ST_Covers, so that:

  ST_Covers(A,B) = ST_CoveredBy(B, A)

SELECT ST_CoveredBy(
    'LINESTRING (0 0, 1 0)'::geometry,
    'POLYGON ((0 1, 1 1, 1 0, 0 0, 0 1))'::geometry );

  t

ST_Crosses, ST_Overlaps, and ST_Touches are less commonly-used functions which test specific aspects of spatial relationship between geometries.

ST_Crosses(geometry A, geometry B) tests if the intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries. It applies only to Point/Polygon, Point/Linestring, Linestring/Linestring, and Linestring/Polygon comparisons.

For example, this tests that a line crosses a polygon:

SELECT ST_Crosses('POLYGON ((100 100, 100 200, 200 200, 200 100, 100 100))',
'LINESTRING (50 150, 150 150)');

t

ST_Overlaps(geometry A, geometry B) compares two geometries of the same dimension and returns true if their intersection set results in a geometry different from both, but having the same dimension.

ST_Touches(geometry A, geometry B) tests if either of the geometries' boundaries intersect, or if only one of the geometry's interiors intersects the other's boundary.

The spatial relationship functions in the previous sections are special cases of the more general function ST_Relate. It computes the full topological relationship between two geometries, using the Dimensionally-Extended 9 Intersection Model (DE-9IM). This can be expressed as a textual code specifying the dimension of the intersections of the interior, bounday and exterior of each input geometry. Since there are nine combinations of these, the code has nine symbols, each having the value of the dimension of intersection (0, 1 or 2) or F if there is no intersection.

For example, the intersection of a line crossing a polygon has the code 1020F1102:

SELECT ST_Relate('POLYGON ((100 100, 100 200, 200 200, 200 100, 100 100))',
'LINESTRING (50 150, 150 150)');

1020F1102

Specific spatial relationships are determined by comparing the DE-9IM code to a pattern mask specifying the relationship desired. In addition to the DE-9IM symbols masks can contain T, indicating intersection of any dimension, and *, indicating a wildcard or "don't care" value. For example, the pattern mask for 'Crosses' for the Polygon/Line case is T*****T**.

This can be confirmed for the above case by using ST_Relate with the mask:

SELECT ST_Relate('POLYGON ((100 100, 100 200, 200 200, 200 100, 100 100))',
'LINESTRING (50 150, 150 150)',
'T*****T**' );

t

Usually it is more convenient to use the named relationship functions. But there are a few situations where there is no function providing the relationship required. For example, the GIS data structure known as a polygonal coverage is a collection of polygons in which no polygons have interiors which intersect. This is expressed by the matrix pattern F******. There is no named spatial relationship function testing for this condition, so it must be tested using ST_Relate.

Here are two polygons whose interiors intersect, and thus do not form a polygonal coverage:

SELECT ST_Relate('POLYGON ((100 100, 100 200, 200 200, 200 100, 100 100))',
'POLYGON ((250 250, 250 150, 150 150, 150 250, 250 250))',
'F********' );

f

Here are two polygons which do form a valid polygonal coverage:

SELECT ST_Relate('POLYGON ((100 100, 100 200, 200 200, 200 100, 100 100))',
'POLYGON ((300 100, 200 100, 200 200, 300 200, 300 100))',
'F********' );

t

A common GIS question is "find all the stuff within distance X of this other stuff".

The ST_Distance(geometry A, geometry B) function calculates the shortest distance between two geometries and returns it as a floating point number. This is useful for reporting the actual distance between objects.

SELECT ST_Distance(
  ST_GeometryFromText('POINT(0 5)'),
  ST_GeometryFromText('LINESTRING(-2 2, 2 2)'));

    3

NOTE: The distance value returned is in the units of the spatial reference system of the input geometries

ST_DWithin

For testing whether two objects are within a given distance of one another, the ST_DWithin function provides an index-accelerated true/false test. This is useful for questions like "how many trees are within a 500 meter buffer of the road?". You don't have to calculate an actual buffer, you just have to test the distance relationship.

Using the Broad Street subway station again, we can find the streets nearby (within 10 meters of) the subway stop:

SELECT name
FROM nyc_streets
WHERE ST_DWithin(
        geom,
        ST_GeomFromText('POINT(583571 4506714)',26918),
        10
      );

    name
--------------
Wall St
Broad St
Nassau St

And we can verify the answer on a map. The Broad St station is actually at the intersection of Wall, Broad and Nassau Streets.

Here are some more queries using the NYC dataset tables:

• nyc_census_blocks
  • blkid, popn_total, boroname, geom
• nyc_streets
  • name, type, geom
• nyc_subway_stations
  • name, geom
• nyc_neighborhoods
  • name, boroname, geom

What is the geometry value for the street named ‘Atlantic Commons’?

SELECT ST_AsText(geom)
  FROM nyc_streets
  WHERE name = 'Atlantic Commons';

MULTILINESTRING((586781.701577724 4504202.15314339,586863.51964484 4504215.9881701))

What neighborhood and borough is Atlantic Commons in?

SELECT name, boroname
FROM nyc_neighborhoods
WHERE ST_Intersects(
  geom,
  ST_GeomFromText('LINESTRING(586782 4504202,586864 4504216)', 26918)
);

    name    | boroname
------------+----------
 Fort Green | Brooklyn

“Hey, why did you change from a ‘MULTILINESTRING’ to a ‘LINESTRING’?” Spatially they describe the same shape, so going from a single-item multi-geometry to a singleton saves a few keystrokes.

More importantly, we also rounded the coordinates to make them easier to read, which does actually change results: we couldn’t use the ST_Touches() predicate to find out which roads join Atlantic Commons, because the coordinates are not exactly the same anymore.

What streets does Atlantic Commons join with?

SELECT name
FROM nyc_streets
WHERE ST_DWithin(
  geom,
  ST_GeomFromText('LINESTRING(586782 4504202,586864 4504216)', 26918),
  0.1
);

     name
------------------
 Cumberland St
 Atlantic Commons

Approximately how many people live on (within 50 meters of) Atlantic Commons?

SELECT Sum(popn_total)
  FROM nyc_census_blocks
  WHERE ST_DWithin(
   geom,
   ST_GeomFromText('LINESTRING(586782 4504202,586864 4504216)', 26918),
   50
  );

1438

You have now learned about how PostGIS supports a full set of standard spatial and distance relationship functions.

More technical details about spatial relationships and the Dimensionally-Extended 9 Intersection Model (DE-9IM) are available here.

The relationship functions and their definitions are summarized below:

Spatial Relationship functions

• ST_Contains(geometry A, geometry B): Returns true if and only if no points of B lie in the exterior of A, and at least one point of the interior of B lies in the interior of A. The converse of ST_Within.

• ST_CoveredBy(geometry A, geometry B): Returns true if and only if no points of A lie in the exterior of B. In other words, A lies completely inside B. The converse of ST_Covers.

• ST_Covers(geometry A, geometry B): Returns true if and only if no points of B lie in the exterior of A. In other words, B lies completely inside A. The converse of ST_CoveredBy.

• ST_Crosses(geometry A, geometry B): Returns true if the supplied geometries have some, but not all, interior points in common.

• ST_Disjoint(geometry A , geometry B): Returns true if the geometries do not spatially intersect - i.e. if they do not share any points in common. The inverse of ST_Intersects.

• ST_Equals(geometry A, geometry B): Returns true if the geometries have the exact same shape. Directionality is not considered.

• ST_Intersects(geometry A, geometry B): Returns true if the geometries “spatially intersect” - i.e. if they have at least one spatial point in common. The inverse of ST_Disjoint.

• ST_Overlaps(geometry A, geometry B): Returns true if the geometries share space, are of the same dimension, but are not completely contained by each other.

• ST_Touches(geometry A, geometry B): Returns true if the geometries have at least one point in common, but their interiors do not intersect.

• ST_Within(geometry A , geometry B): Returns true if the geometry A is completely inside geometry B. The converse of ST_Contains.

Relate functions

• ST_Relate(geometry A, geometry B): Returns the DE-9IM code indicating the full topological relationhips between A and B.

• ST_Relate(geometry A, geometry B, text mask): Tests whether the geometries A and B have a DE-9IM code which matches the given mask.

Distance Relationship functions

• ST_Distance(geometry A, geometry B): Returns the 2-dimensional cartesian minimum distance between two geometries, in the units of the spatial reference system.

• ST_DWithin(geometry A, geometry B, radius): Returns true if two geometries are within the specified distance (radius) of one another.