ST_Difference
Prev | 8.13. Overlay Functions | Next

## Name

ST_Difference — Computes a geometry representing the part of geometry A that does not intersect geometry B.

## Synopsis

`geometry ST_Difference(`geometry geomA, geometry geomB, float8 gridSize = -1`)`;

## Description

Returns a geometry representing the part of geometry A that does not intersect geometry B. This is equivalent to `A - ST_Intersection(A,B)`. If A is completely contained in B then an empty atomic geometry of appropriate type is returned.

This is the only overlay function where input order matters. ST_Difference(A, B) always returns a portion of A.

If the optional `gridSize` parameter is given (GEOS-3.9.0 or higher required), all result vertices are guaranteed to fall on a grid of the specified size. For the operation to give predictable results all the input vertices must fall already on the specified grid, see ST_ReducePrecision.

Performed by the GEOS module

Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0

This method implements the OGC Simple Features Implementation Specification for SQL 1.1. s2.1.1.3

This method implements the SQL/MM specification. SQL-MM 3: 5.1.20

This function supports 3d and will not drop the z-index. However, the result is computed using XY only. The result Z values are copied, averaged or interpolated.

## Examples

The input linestrings | The difference of the two linestrings

The difference of 2D linestrings.

    SELECT ST_AsText(
        ST_Difference(
                'LINESTRING(50 100, 50 200)'::geometry,
                'LINESTRING(50 50, 50 150)'::geometry
            )
        );

    st_astext
    ---------
    LINESTRING(50 150,50 200)

The difference of 3D points.

    SELECT ST_AsEWKT( ST_Difference(
                       'MULTIPOINT(-118.58 38.38 5,-118.60 38.329 6,-118.614 38.281 7)' :: geometry,
                       'POINT(-118.614 38.281 5)' :: geometry
                      ) );

    st_asewkt
    ---------
    MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)

## See Also

ST_SymDifference, ST_Intersection, ST_Union, ST_ReducePrecision

Prev | Up | Next
ST_ClipByBox2D | Home | ST_Intersection