This topic describes the ST_Buffer function. This function returns a geometry object representing all points whose distance from the input geometry object is less than or equal to the specified distance with the input geometry object as the center. The returned geometry object is the buffer that surrounds the input geometry object. The ST_Buffer function calculates the result based on a spatial reference system (SRS) of the specified geometry object.

Syntax

geometry  ST_Buffer(geometry  g1 , float radiusOfBuffer);
geometry  ST_Buffer(geometry g1 , float radiusOfBuffer , integer numSegQuarterCircle);
geometry  ST_Buffer(geometry g1 , float radiusOfBuffer , text bufferStyleParameters);
geography ST_Buffer(geography g1 , float radiusOfBufferInMeters);
geography ST_Buffer(geography g1 , float radiusOfBuffer , integer numSegQuarterCircle);
geography ST_Buffer(geography g1 , float radiusOfBuffer , text bufferStyleParameters);

Parameters

Parameter Description
g1 The geometry or geography object that you want to specify.
radiusOfBuffer The radius of a buffer. This parameter is valid only when you specify a geometry object.
numSegQuarterCircle Specifies the number of segments that are performed on a quarter circle. Default value: 7.
bufferStyleParameters The buffer. The value of this parameter is key-value pairs that are separated by spaces.
radiusOfBufferInMeters The radius of a buffer. Unit: meters. This parameter is valid only when you specify a geography object.

Description

  • If you specify a polygon object and set the radius of the buffer to a negative value, the ST_Buffer function scales the polygon object rather than expanding the object.
  • If you specify a geography object, the radius of the buffer is measured in the unit that is specified by the SRS of the geography object.
  • If you specify a geography object, the ST_Buffer function is a wrapper around a geometry object. The ST_Buffer function first selects a proper Spatial Reference Identifier (SRID) that fits the bounding box of the geography object. For the coordinate system, the ST_Buffer function preferentially uses the Universal Transverse Mercator (UTM), Lambert Azimuthal Equal Area (LAEA), or Universal Polar Stereographic (UPS). In the worst scenario, the Mercator projection is used. Then, the ST_Buffer function calculates buffers in the SRS of the geography object and transforms the buffers back to the World Geodetic System 1984 (WGS 84) coordinate system.
  • The ST_Buffer function ignores z coordinates. If you specify a 3D geometry object, the ST_Buffer function still returns a 2D geometry object that represents a buffer.
  • In some cases, the ST_Buffer function is used for radius searches. However, if you create a buffer for a radius search, the search is slow and pointless. We recommend that you use the ST_DWithin function for radius searches.
  • The following table describes the fields of the bufferStyleParameters parameter.
Field Description Type Default value Description
quad_segs The number of segments that are used to approximate a quarter circle. integer 8 A greater value indicates a smoother quarter circle.
endcap The endcap style of the buffer. string round Valid values: round, flat, and square.
join The join style of the buffer. string round Valid values: round, mitre, and bevel.
mitre_limit The limit of the mitre ratio. float 5.0 This parameter is valid only when you set the join parameter to mitre.
side The position of the buffer. string -- Valid values: both, left, and right. If you set this parameter to left or right, the ST_Buffer function performs a single-sided buffer on the input geometry object with the buffered side relative to the direction of the line. This parameter takes effect only when you specify a LineString object. This parameter does not affect the results for point objects or polygon objects.

Examples

  • Results returned with different values of the quad_segs parameter:
    SELECT ST_Buffer('POINT(0 0)'::geometry,1),ST_Buffer('POINT(3 0)'::geometry,1,'quad_segs=2');
    1
  • Results returned with different values of the endcap parameter:
    SELECT ST_Buffer('LINESTRING(0 0,0 3)'::geometry,1,'endcap=round'),
            ST_Buffer('LINESTRING(6 0,6 3)'::geometry,1,'endcap=flat'),
         ST_Buffer('LINESTRING(12 0,12 3)'::geometry,1,'endcap=square');
    2
  • Results returned with different values of the joins parameter:
    SELECT ST_Buffer('LINESTRING(0 0,3 0,3 3)'::geometry,1.2,'join=round'),
         ST_Buffer('LINESTRING(6 0,9 0,9 3)'::geometry,1.2,'join=mitre'),
         ST_Buffer('LINESTRING(12 0,15 0,15 3)'::geometry,1.2,'join=bevel');
    3
  • Results returned with different values of the mitre_limit parameter:
    SELECT ST_Buffer('LINESTRING(0 0,3 0,3 3)'::geometry,1.2,'join=mitre mitre_limit=1.0'),
         ST_Buffer('LINESTRING(6 0,9 0,9 3)'::geometry,1.2,'join=mitre mitre_limit=0.5'),
         ST_Buffer('LINESTRING(12 0,15 0,15 3)'::geometry,1.2,'join=mitre mitre_limit=0.1');
    4
  • Results returned with different values of the side parameter:
    SELECT ST_Buffer('LINESTRING(0 0,3 0,3 3,0 3)'::geometry,1,'side=both'),
       ST_Buffer('LINESTRING(6 0,9 0,9 3,6 3)'::geometry,1,'side=right'),
       ST_Buffer('LINESTRING(12 0,15 0,15 3,12 3)'::geometry,1,'side=left');
    5