ST_Buffer

ST_Buffer takes a geometry, a distance, and, optionally, a unit as input parameters and returns the geometry that surrounds the given geometry by the specified distance, measured in the given unit.

Each point on the boundary of the resulting geometry is the specified distance away from the given geometry. The resulting geometry is represented in the spatial reference system of the given geometry.

Any circular curve in the boundary of the resulting geometry is approximated by linear strings. For example, the buffer around a point, which would result in a circular region, is approximated by a polygon whose boundary is a linestring.

If the given geometry is null or is empty, null will be returned.

Note: After you apply APAR PM92224, the results that are returned by the ST_Buffer function might be different than before the APAR was applied.

Syntax

Parameter

geometry: A value of one of the seven distinct spatial data types that represents the geometry to create the buffer around.
distance: A DOUBLE PRECISION value that specifies the distance to be used for the buffer around geometry.
unit: A VARCHAR(128) value that identifies the unit in which distance is measured. The supported units of measure are listed in the DB2GSE.ST_UNITS_OF_MEASURE catalog view.

If the unit parameter is omitted, the following rules are used to determine the unit of measure that is used for distance:

If geometry is in a projected or geocentric coordinate system, the linear unit associated with this coordinate system is the default.
If geometry is in a geographic coordinate system, the angular unit associated with this coordinate system is the default.
If geometry is in a geographic coordinate system, and a linear unit is specified, the geometry type must be ST_Point. If the distance is shorter than 1 meter, ST_Buffer regards the distance as 1 meter.

Restrictions on unit conversions: An error (SQLSTATE 38SU4) is returned if any of the following conditions occur:

The geometry is in an unspecified coordinate system and the unit parameter is specified.
The geometry is in a projected coordinate system and an angular unit is specified.
The geometry in the geographic coordinate system is not ST_Point, and a linear unit is specified.

Return type

db2gse.ST_Geometry

Examples

In the following examples, the results have been reformatted for readability.

Example 1

The following code creates a spatial reference system, creates the SAMPLE_GEOMETRIES table, and populates it.


DSN5SCLP /create_srs STLEC1  -srsId 4000 -srsName new_york1983 
    -xOffset 0 -yOffset 0 -xScale 1 -yScale 1 
    -coordsysName NAD_1983_StatePlane_New_York_East_FIPS_3101_Feet

SET CURRENT PATH = CURRENT PATH, db2gse; 

CREATE TABLE 
    sample_geometries (id INTEGER, spatial_type varchar(18), 
    geometry ST_GEOMETRY);

INSERT INTO sample_geometries(id, spatial_type, geometry)
VALUES
    (1, 'st_point', ST_GEOMETRY(ST_Point(50, 50, 4000)));

INSERT INTO sample_geometries(id, spatial_type, geometry)
VALUES
    (2, 'st_linestring',
         ST_GEOMETRY(ST_LineString('linestring(200 100, 210 130, 
         220 140)', 4000)));

INSERT INTO sample_geometries(id, spatial_type, geometry)
VALUES
    (3, 'st_polygon', 
         ST_GEOMETRY(ST_Polygon('polygon((110 120, 110 140, 130 140, 
         130 120, 110 120))',4000)));

INSERT INTO sample_geometries(id, spatial_type, geometry)
VALUES
    (4, 'st_multipolygon', 
         ST_GEOMETRY(ST_MultiPolygon('multipolygon(((30 30, 30 40, 
         35 40, 35 30, 30 30),(35 30, 35 40, 45 40, 
         45 30, 35 30)))', 4000)));

Example 2

The following SELECT statement uses the ST_Buffer function to apply a buffer of 10.


SELECT id, spatial_type,
       cast(ST_AsText(ST_Buffer(geometry, 10)) AS varchar(470)) AS buffer_10
FROM   sample_geometries

Results:


ID          SPATIAL_TYPE       BUFFER_10                                 
----------- ------------------ ------------------------------------------
1           st_point           POLYGON (( 60 50, 59 55, 54 59, 49 
   60, 44 58, 41 53, 40 48, 42 43, 47 41, 52 40, 57 42, 60 50))    

2             st_linestring    POLYGON (( 230 140, 229 145, 224 149, 
	 219 150, 213 147, 203 137, 201 133, 191 103, 191 99, 192 95, 
   196 91, 200 91, 204 91, 209 97, 218 124, 227 133, 230 140))

3              st_polygon         POLYGON (( 140 120, 140 140, 139 145,
	 130 150, 110 150, 105 149, 100 140, 100 120, 101  115, 110 110, 
	 130 110, 135 111, 140 120))  
                                      
4              st_multipolygon    POLYGON (( 55 30, 55 40, 54 45, 45
   50, 30 50, 25 49, 20 40, 20 30, 21 25, 30 20, 45 20, 50 21, 55 30))

Example 3

The following SELECT statement uses the ST_Buffer function to apply a negative buffer of 5.


SELECT id, spatial_type,
       cast(ST_AsText(ST_Buffer(geometry, -5)) AS varchar(150)) 
       AS buffer_negative_5
FROM   sample_geometries
WHERE  id = 3

Results:


ID          SPATIAL_TYPE       BUFFER_NEGATIVE_5  
----------- ------------------ --------------------------------------         
3           st_polygon         POLYGON (( 115 125, 125 125, 125 135, 
	 115 135, 115 125))

Example 4

The following SELECT statement shows the result of applying a buffer with the unit parameter specified.


SELECT id, spatial_type,
    cast(ST_AsText(ST_Buffer(geometry, 10, 'METER')) AS varchar(680)) 
    AS buffer_10_meter
FROM   sample_geometries
WHERE  id = 3

Results:


ID          SPATIAL_TYPE       BUFFER_10_METER
----------- ------------------ --------------------------------------         
3           st_polygon         POLYGON (( 163 120, 163 140, 162 149, 
	 159 157, 152 165, 143 170, 130 173, 110 173, 101 172, 92 167, 
	 84 160, 79 151, 77 140, 77 120, 78 111, 83 102, 90 94, 99 89, 
	 110 87, 130 87, 139 88, 147 91, 155 98, 160 107, 163 120))