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 specified geometry by the specified distance, measured in the specified unit.

Each point on the boundary of the resulting geometry is the specified distance away from the specified geometry. The resulting geometry is represented in the spatial reference system of the specified 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 specified geometry is null or is empty, null will be returned.

Syntax

Parameter

geometry: A value of type ST_Geometry or one of its subtypes 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 SYSGEO.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 96.

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, the angular unit associated with this coordinate system is the default.

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, and a linear unit is specified.

Return type

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 the SAMPLE_GEOMETRIES table, and populates it with spatial data in reference system 4326.



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, 4326)),
    (2, 'st_linestring',
         ST_LineString('linestring(100 80, 110 81, 
         120 83)', 4326)),
    (3, 'st_polygon', 
         ST_Polygon('polygon((110 70, 110 75, 130 75, 
         130 70, 110 70))', 4326)),
    (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)))', 4326))

Example 2

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


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

Results:


ID          SPATIAL_TYPE       BUFFER_10                                 
----------- ------------------ ------------------------------------------
          1 st_point           POLYGON ((50.000000000 50.000089905, 
              49.999901374 50.000063572, 49.999860522 50.000000000, 
              49.999901374 49.999936428, 50.000000000 49.999910095, 
              50.000098626 49.999936428, 50.000139478 50.000000000, 
              50.000098626 50.000063572, 50.000000000 50.000089905)) 
                                                                                                                                                                                                                                                                                                                                                                                                 
          2 st_linestring      POLYGON ((99.999696379 80.000072386, 
              99.999490607 80.000013896, 99.999583232 79.999947266, 
              99.999919991 79.999911527, 100.000303617 79.999927614, 
              101.008881075 80.124462191, 102.042636376 80.245920134, 
              103.101855625 80.364185228, 104.186771032 80.479138613, 
              105.297553974 80.590659031, 106.434307814 80.698623117, 
              107.597060526 80.802905740, 108.785757236 80.903380395, 
              110.000252787 80.999919655, 110.000467280 80.999957868, 
              110.000495913 80.999955286, 110.884732453 81.232827537, 
              111.816598790 81.463529984, 112.799559514 81.691882283, 
              113.837353689 81.917685643, 114.934009949 82.140720765, 
              116.09                         
SQL0445W  Value "POLYGON ((99.999696379 80.000072386, 99.999490607 80.0000138"    
has been truncated.  SQLSTATE=01004                                               

          3 st_polygon         POLYGON ((109.999654003 75.000000000, 
             109.999666063 74.444565138, 109.999677281 73.889102163, 
             109.999687742 73.333610177, 109.999697518 72.778088289, 
             109.999706674 72.222535622, 109.999715266 71.666951309, 
             109.999723344 71.111334494, 109.999730951 70.555684335, 
             109.999738128 70.000000000, 109.999814829 69.999936618, 
             110.000000000 69.999910364, 110.000040604 69.999916121, 
             110.000042807 69.999911569, 112.194612170 70.110242396, 
             114.409739963 70.193393168, 116.639800135 70.249021173, 
             118.878920947 70.276893916, 121.121079053 70.276893916, 
             123.360199865 70.249021173, 125.590260037 70.193393168, 
             12                         
SQL0445W  Value "POLYGON ((109.999654003 75.000000000, 109.999666063 74.44456"    
has been truncated.  SQLSTATE=01004                                               

          4 st_multipolygon    POLYGON ((29.999882896 40.000000000, 
              29.999884740 38.889713813, 29.999886486 37.779215903, 
              29.999888139 36.668508151, 29.999889703 35.557592758, 
              29.999891184 34.446472240, 29.999892587 33.335149421, 
              29.999893914 32.223627435, 29.999895170 31.111909717, 
              29.999896358 30.000000000, 29.999926714 29.999936212, 
              30.000000000 29.999909790, 30.000002242 29.999910598, 
              30.000002262 29.999909811, 30.555435320 30.009291084, 
              31.110959848 30.016328190, 31.666549749 30.021020144, 
              32.222178889 30.023366285, 32.777821111 30.023366285, 
              33.333450251 30.021020144, 33.889040152 30.016328190, 
              34.444564680 30.0092910                         
SQL0445W  Value "POLYGON ((29.999882896 40.000000000, 29.999884740 38.8897138"    
has been truncated.  SQLSTATE=01004

Example 3

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


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

Results:


ID          SPATIAL_TYPE       BUFFER_NEGATIVE_5  
----------- ------------------ --------------------------------------         
         3 st_polygon         POLYGON ((110.000130936 70.000052175, 
            111.516862578 70.079303767, 113.044407204 70.145594692, 
            114.580791208 70.198786957, 116.124124428 70.238774964, 
            117.672461656 70.265478577, 119.223817566 70.278843921, 
            120.776182434 70.278843921, 122.327538344 70.265478577, 
            123.875875572 70.238774964, 125.419208792 70.198786957, 
            126.955592796 70.145594692, 128.483137422 70.079303767, 
            129.999869064 70.000052175, 129.999866602 70.384708218, 
            129.999864039 70.769399934, 129.999861370 71.154075422, 
            129.999858587 71.538734960, 129.999855684 71.923378825, 
            129.999852652 72.308007302, 129.999849483 72.692620673, 
            129.999846168 73.077219229, 129.999842696 73.461803257, 
            129.999839056 73.846373052, 129.999835236 74.230928909, 
            129.999831223 74.615471124, 129.999827002 74.999961688, 
            128.484292350 75.061530074, 126.957366369 75.113036219, 
            125.421110106 75.154369626, 123.877515883 75.185445261, 
            122.328636191 75.206198568, 120.776567403 75.216586133, 
            119.223432597 75.216586133, 117.671363809 75.206198568, 
            116.122484117 75.185445261, 114.578889894 75.154369626, 
            113.042633631 75.113036219, 111.515707650 75.061530074, 
            110.000172998 74.999961688, 110.000168777 74.615471124, 
            110.000164764 74.230928909, 110.000160944 73.846373052, 
            110.000157304 73.461803257, 110.000153832 73.077219229, 
            110.000150517 72.692620673, 110.000147348 72.308007302, 
            110.000144316 71.923378825, 110.000141413 71.538734960, 
            110.000138630 71.154075422, 110.000135961 70.769399934, 
            110.000133398 70.384708218, 110.000130936 70.000052175))

Example 4

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


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

Results:


ID          SPATIAL_TYPE       BUFFER_10_METER
----------- ------------------ --------------------------------------         
          3 st_polygon         POLYGON ((109.999654003 75.000000000, 
             109.999666063 74.444565138, 109.999677281 73.889102163, 
             109.999687742 73.333610177, 109.999697518 72.778088289, 
             109.999706674 72.222535622, 109.999715266 71.666951309, 
             109.999723344 71.111334494, 109.999730951 70.555684335, 
             109.999738128 70.000000000, 109.999814829 69.999936618, 
             110.000000000 69.999910364, 110.000040604 69.999916121, 
             110.000042807 69.999911569, 112.194612170 70.110242396, 
             114.409739963 70.193393168, 116.639800135 70.249021173, 
             118.878920947 70.276893916, 121.121079053 70.276893916, 
             123.360199865 70.249021173, 125.590260037 70.193393168, 
             127.805387830 70.110242396, 129.999957193 69.999911569, 
             130.000152411 69.999927109, 130.000258350 69.999985347, 
             130.000248395 70.000000000, 130.000261872 70.000000000, 
             130.000269049 70.555684335, 130.000276656 71.111334494, 
             130.000284734 71.666951309, 130.000293326 72.222535622, 
             130.000302482 72.778088289, 130.000312258 73.333610177, 
             130.000322719 73.889102163, 130.000333937 74.444565138, 
             130.000345997 75.000000000, 130.000244658 75.000063350, 
             130.000055047 75.000083687, 130.000058094 75.000088319, 
             127.807003645 75.085804552, 125.592254016 75.150415987, 
             123.361736945 75.193646708, 121.121648680 75.215309408, 
             118.878351320 75.215309408, 116.638263055 75.193646708, 
             114.407745984 75.150415987, 112.192996355 75.085804552, 
             109.999941906 75.000088319, 109.999717737 75.000051814, 
             109.999672150 75.000000000, 109.999654003 75.000000000))