ST_Buffer function

The ST_Buffer function takes a geometry, a distance, and, optionally, a unit or a segment 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.

This function can also be called as a method.

Syntax

Read syntax diagramSkip visual syntax diagramdb2gse.ST_Buffer ( geometry , distance,segments,unit )

Parameter

geometry
A value of type ST_Geometry or one of its subtypes that represents the geometry to create the buffer around.For geodetic data, ST_Buffer supports only ST_Point and ST_MultiPoint data types.
distance
A DOUBLE PRECISION value that specifies the distance to be used for the buffer around geometry. For geodetic data, the distance must not be greater than the Earth's equatorial radius. For the WGS-84 ellipsoid, this length is 6378137.0 meters.
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.
segments
An INTEGER value that identifies how many polygon edges are to be used in approximating a quarter circle. The default is 8.
If the unit parameter is omitted, the following rules are used to determine the unit of measure 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, but is not in a geodetic spatial reference system (SRS), the angular unit associated with this coordinate system is the default.
  • If geometry is in a geodetic SRS, the default unit of measure is meters.
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 is in a geographic coordinate system, but is not an ST_Point value or not in a geodetic SRS, and a linear unit is specified.
  • The geometry is in a geographic coordinate system, is in a geodetic SRS, and an angular unit is specified.

Return type

db2gse.ST_Geometry

Examples

In the following examples, the results have been reformatted for readability. The spacing in your results will vary according to your display.

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

db2se create_srs se_bank  -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 FUNCTION PATH = CURRENT FUNCTION 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_Point(50, 50, 4000)),
    (2, 'st_linestring',
         ST_LineString('linestring(200 100, 210 130, 
         220 140)',  4000)),
    (3, 'st_polygon', 
         ST_Polygon('polygon((110 120, 110 140, 130 140, 
         130 120, 110 120))',4000)),
    (4, 'st_multipolygon', 
         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(geometry..ST_Buffer(10)..ST_AsText AS varchar(470)) AS buffer_10
FROM   sample_geometries
Results: 

ID          SPATIAL_TYPE       BUFFER_10                                 
----------- ------------------ ------------------------------------------
1           st_point           POLYGON (( 60.00000000 50.00000000, 
   59.00000000 55.00000000, 54.00000000 59.00000000, 49.00000000 
   60.00000000, 44.00000000 58.00000000, 41.00000000 53.00000000, 
   40.00000000 48.00000000,42.00000000 43.00000000, 47.00000000
   41.00000000, 52.00000000 40.00000000, 57.00000000 42.00000000, 
   60.00000000 50.00000000))    

2             st_linestring    POLYGON (( 230.00000000 
   140.00000000, 229.00000000 145.00000000, 224.00000000 
   149.00000000, 219.00000000 150.00000000, 213.00000000 147.00000000,
   203.00000000 137.00000000, 201.00000000 133.00000000, 191.00000000
   103.00000000, 191.00000000 99.00000000, 192.00000000  95.00000000, 
   196.00000000 91.00000000, 200.00000000 91.00000000,204.00000000 
   91.00000000, 209.00000000 97.00000000, 218.00000000 124.00000000,
   227.00000000 133.00000000, 230.00000000 140.00000000))

3              st_polygon         POLYGON (( 140.00000000 120.00000000, 
   140.00000000 140.00000000, 139.00000000  145.00000000, 130.00000000 
   150.00000000, 110.00000000 150.00000000, 105.00000000 149.00000000,
   100.00000000 140.00000000,100.00000000 120.00000000, 101.00000000 
   115.00000000, 110.00000000 110.00000000,130.00000000 110.00000000, 
   135.00000000 111.00000000, 140.00000000 120.00000000))  
                                      
4              st_multipolygon    POLYGON (( 55.00000000 30.00000000, 
   55.00000000 40.00000000, 54.00000000 45.00000000, 45.00000000
   50.00000000, 30.00000000 50.00000000, 25.00000000 49.00000000, 
   20.00000000 40.00000000, 20.00000000 30.00000000, 21.00000000
   25.00000000, 30.00000000 20.00000000, 45.00000000 20.00000000, 
   50.00000000 21.00000000, 55.00000000 30.00000000))
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.00000000 125.00000000, 
   125.00000000 125.00000000, 125.00000000 135.00000000, 115.00000000 
   135.00000000, 115.00000000 125.00000000))
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.00000000 120.00000000, 
   163.00000000 140.00000000, 162.00000000 149.00000000, 159.00000000 
   157.00000000, 152.00000000 165.00000000, 143.00000000 170.00000000, 
   130.00000000 173.00000000, 110.00000000 173.00000000, 101.00000000 
   172.00000000, 92.00000000 167.00000000, 84.00000000 160.00000000, 
   79.00000000 151.00000000, 77.00000000 140.00000000, 77.00000000 
   120.00000000, 78.00000000 111.00000000, 83.00000000 102.00000000, 
   90.00000000 94.00000000, 99.00000000 89.00000000, 110.00000000 
   87.00000000, 130.00000000 87.00000000, 139.00000000 88.00000000,
   147.00000000 91.00000000, 155.00000000 98.00000000, 160.00000000 
   107.00000000, 163.00000000 120.00000000))
Example 5
The following SELECT statement shows the result of applying a buffer with the unit parameter specified. 
SELECT id, substr(db2gse.ST_AsText(db2gse.ST_Buffer(g,30, 8, 'METER')) ,1, 900) 
    FROM db2se_fvt.polygons1 where id = 1003 or id=1013 order by id
Results: 

ID          2                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    
----------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------       
1003        POLYGON ((37.999620 45.000000, 37.999625 44.222645, 
   37.999629 43.445184, 37.999634 42.667617, 37.999639 41.889944, 
   37.999643 41.112165, 37.999647 40.334280, 37.999651 39.556291, 
   7.999655 38.778198, 37.999658 38.000000, 37.999758 37.999809, 
   38.000000 37.999730, 38.000064 37.999751, 38.000068 37.999735, 
   38.877345 38.137636, 39.757850 38.268959, 40.641452 38.393648, 
   41.528012 38.511651, 42.417387 38.622919, 43.309432 38.727405, 
   44.203993 38.825063, 45.100916 38.915852, 46.000039 38.999732, 
   46.000271 38.999832, 46.000324 38.999976, 46.000345 38.999974, 
   46.181764 40.447403, 46.371137 41.894172, 46.569255 43.340248, 
   46.777005 44.785598, 46.995388 46.230183, 47.225537 47.673963, 
   47.468743 49.116889, 47.726478 50.558911, 48.000434 51.999968, 
   48.000344 52.000166, 48.000210 52.000213, 48.000227 52.000230, 
   47.360899 52.237117, 46.714779 52.470495, 46.061840 52.700297, 
   45.402061 52.926458, 44.73542       
1013 POLYGON ((69.998453 79.999995, 69.998606 78.889288, 69.998731 
   77.778495, 69.998835 76.667611, 69.998923 75.556629, 69.998998 
   74.445542, 69.999063 73.334343, 69.999120 72.223024, 69.999170 
   71.111579, 69.999214 70.000000, 69.999444 69.999810, 70.000000 
   69.999731, 70.000062 69.999740, 70.000064 69.999732, 71.107715 
   70.027419, 72.217944 70.048210, 73.330024 70.062083, 74.443218 
   70.069022, 75.556782 70.069022, 76.669976 70.062083, 77.782056 
   70.048210, 78.892285 70.027419, 79.999936 69.999732, 80.000508 
   69.999795, 80.000783 69.999978, 80.000762 70.000000, 80.000786 
   70.000000, 80.000830 71.111579, 80.000880 72.223024, 80.000937 
   73.334343, 80.001002 74.445542, 80.001077 75.556629, 80.001165 
   76.667611, 80.001269 77.778495, 80.001394 78.889288, 80.001547 
   80.000000, 80.001094 80.000190, 80.000027 80.000267, 80.000027 
   80.000269, 80.000000 80.000269, 79.777829 80.000858, 79.555608 
   80.001301, 79.33337  

2 record(s) selected.