# Miscellaneous Functions

ST_Accum Aggregate. Constructs an array of geometries.
geometry[] `ST_Accum` geometry set geomfield

### Description

Aggregate. Constructs an array of geometries.

&Z_support;

&curve_support;

### Examples

    SELECT (ST_Accum(the_geom)) As all_em, ST_AsText((ST_Accum(the_geom))[1]) As grabone,
    (ST_Accum(the_geom))[2:4] as grab_rest
    			FROM (SELECT ST_MakePoint(a*CAST(random()*10 As integer), a*CAST(random()*10 As integer), a*CAST(random()*10 As integer)) As the_geom
    				FROM generate_series(1,4) a) As foo;

    all_em|grabone   | grab_rest

    -------------------------------------------------------------------------------+

     {0101000080000000000000144000000000000024400000000000001040:
     0101000080000000000
    00018400000000000002C400000000000003040:
    0101000080000000000000354000000000000038400000000000001840:
    010100008000000000000040400000000000003C400000000000003040} |
     POINT(5 10) | {010100008000000000000018400000000000002C400000000000003040:
     0101000080000000000000354000000000000038400000000000001840:
     010100008000000000000040400000000000003C400000000000003040}
    (1 row)

### See Also

Box2D Returns a BOX2D representing the maximum extents of the geometry.
box2d `Box2D` geometry geomA

### Description

Returns a BOX2D representing the maximum extents of the geometry.

&curve_support;

### Examples

    SELECT Box2D(ST_GeomFromText('LINESTRING(1 2, 3 4, 5 6)'));
    	box2d
    	---------
    	BOX(1 2,5 6)

    	SELECT Box2D(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));
    	box2d
    	--------
    	BOX(220186.984375 150406,220288.25 150506.140625)

### See Also

,

Box3D Returns a BOX3D representing the maximum extents of the geometry.
box3d `Box3D` geometry geomA

### Description

Returns a BOX3D representing the maximum extents of the geometry.

&Z_support;

&curve_support;

### Examples

    SELECT Box3D(ST_GeomFromEWKT('LINESTRING(1 2 3, 3 4 5, 5 6 5)'));
    	Box3d
    	---------
    	BOX3D(1 2 3,5 6 5)

    	SELECT Box3D(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 1,220227 150406 1)'));
    	Box3d
    	--------
    	BOX3D(220227 150406 1,220268 150415 1)

### See Also

,

ST_Estimated_Extent Return the 'estimated' extent of the given spatial table. The estimated is taken from the geometry column's statistics. The current schema will be used if not specified.
box2d `ST_Estimated_Extent` text schema_name text table_name text geocolumn_name box2d `ST_Estimated_Extent` text table_name text geocolumn_name

### Description

Return the 'estimated' extent of the given spatial table. The estimated is taken from the geometry column's statistics. The current schema will be used if not specified.

For PostgreSQL>=8.0.0 statistics are gathered by VACUUM ANALYZE and resulting extent will be about 95% of the real one.

For PostgreSQL<8.0.0 statistics are gathered by update_geometry_stats() and resulting extent will be exact.

&curve_support;

### Examples

    SELECT ST_Estimated_extent('ny', 'edges', 'the_geom');
    --result--
    BOX(-8877653 4912316,-8010225.5 5589284)

    SELECT ST_Estimated_Extent('feature_poly', 'the_geom');
    --result--
    BOX(-124.659652709961 24.6830825805664,-67.7798080444336 49.0012092590332)

### See Also

ST_Expand Returns bounding box expanded in all directions from the bounding box of the input geometry. Uses double-precision
geometry `ST_Expand` geometry g1 float units_to_expand box2d `ST_Expand` box2d g1 float units_to_expand box3d `ST_Expand` box3d g1 float units_to_expand

### Description

This function returns a bounding box expanded in all directions from the bounding box of the input geometry, by an amount specified in the second argument. Uses double-precision. Very useful for distance() queries, or bounding box queries to add an index filter to the query.

There are 3 variants of this. The one that takes a geometry will return a POLYGON geometry representation of the bounding box and is the most commonly used variant.

ST_Expand is similar in concept to ST_Buffer except while buffer expands the geometry in all directions, ST_Expand expands the bounding box an x,y,z unit amount.

Units are in the units of the spatial reference system in use denoted by the SRID

Pre 1.3, ST_Expand was used in conjunction with distance to do indexable queries. Something of the form `the_geom && ST_Expand('POINT(10 20)', 10) AND ST_Distance(the_geom, 'POINT(10 20)') < 10` Post 1.2, this was replaced with the easier ST_DWithin construct.

Bounding boxes of all geometries are currently 2-d even if they are 3-dimensional geometries.

Availability: 1.5.0 behavior changed to output double precision instead of float4 coordinates.

### Examples

Examples below use US National Atlas Equal Area (SRID=2163) which is a meter projection

    --10 meter expanded box around bbox of a linestring
    SELECT CAST(ST_Expand(ST_GeomFromText('LINESTRING(2312980 110676,2312923 110701,2312892 110714)', 2163),10) As box2d);
    					 st_expand
    ------------------------------------
     BOX(2312882 110666,2312990 110724)

    --10 meter expanded 3d box of a 3d box
    SELECT ST_Expand(CAST('BOX3D(778783 2951741 1,794875 2970042.61545891 10)' As box3d),10)
    							  st_expand
    -----------------------------------------------------
     BOX3D(778773 2951731 -9,794885 2970052.61545891 20)

     --10 meter geometry astext rep of a expand box around a point geometry
     SELECT ST_AsEWKT(ST_Expand(ST_GeomFromEWKT('SRID=2163;POINT(2312980 110676)'),10));
    											st_asewkt
    -------------------------------------------------------------------------------------------------
     SRID=2163;POLYGON((2312970 110666,2312970 110686,2312990 110686,2312990 110666,2312970 110666))

### See Also

, , , ,,

ST_Extent an aggregate function that returns the bounding box that bounds rows of geometries.
box3d_extent `ST_Extent` geometry set geomfield

### Description

ST_Extent returns a bounding box that encloses a set of geometries. The ST_Extent function is an "aggregate" function in the terminology of SQL. That means that it operates on lists of data, in the same way the SUM() and AVG() functions do.

Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID

ST_Extent is similar in concept to Oracle Spatial/Locator's SDO_AGGR_MBR

Since ST_Extent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the orginal geometries.

ST_Extent will return boxes with only an x and y component even with (x,y,z) coordinate geometries. To maintain x,y,z use ST_Extent3D instead.

Availability: 1.4.0 As of 1.4.0 now returns a box3d_extent instead of box2d object.

### Examples

Examples below use Massachusetts State Plane ft (SRID=2249)

    SELECT ST_Extent(the_geom) as bextent FROM sometable;
    					 st_bextent
    ------------------------------------
    BOX(739651.875 2908247.25,794875.8125 2970042.75)

    --Return extent of each category of geometries
    SELECT ST_Extent(the_geom) as bextent
    FROM sometable
    GROUP BY category ORDER BY category;

    					  bextent                       |         name
    ----------------------------------------------------+----------------
     BOX(778783.5625 2951741.25,794875.8125 2970042.75) | A
     BOX(751315.8125 2919164.75,765202.6875 2935417.25) | B
     BOX(739651.875 2917394.75,756688.375 2935866)      | C

     --Force back into a geometry
     -- and render the extended text representation of that geometry
    SELECT ST_SetSRID(ST_Extent(the_geom),2249) as bextent FROM sometable;

    				bextent
    --------------------------------------------------------------------------------
     SRID=2249;POLYGON((739651.875 2908247.25,739651.875 2970042.75,794875.8125 2970042.75,
     794875.8125 2908247.25,739651.875 2908247.25))

### See Also

, , ,

ST_Extent3D an aggregate function that returns the box3D bounding box that bounds rows of geometries.
box3d `ST_Extent3D` geometry set geomfield

### Description

ST_Extent3D returns a box3d (includes Z coordinate) bounding box that encloses a set of geometries. The ST_Extent3D function is an "aggregate" function in the terminology of SQL. That means that it operates on lists of data, in the same way the SUM() and AVG() functions do.

Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID

Since ST_Extent3D returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the orginal geometries.

&Z_support;

&curve_support;

### Examples

    SELECT ST_Extent3D(foo.the_geom) As b3extent
    FROM (SELECT ST_MakePoint(x,y,z) As the_geom
    	FROM generate_series(1,3) As x
    		CROSS JOIN generate_series(1,2) As y
    		CROSS JOIN generate_series(0,2) As Z) As foo;
    	  b3extent
    --------------------
     BOX3D(1 1 0,3 2 2)

    --Get the extent of various elevated circular strings
    SELECT ST_Extent3D(foo.the_geom) As b3extent
    FROM (SELECT ST_Translate(ST_Force_3DZ(ST_LineToCurve(ST_Buffer(ST_MakePoint(x,y),1))),0,0,z) As the_geom
    	FROM generate_series(1,3) As x
    		CROSS JOIN generate_series(1,2) As y
    		CROSS JOIN generate_series(0,2) As Z) As foo;

    	b3extent
    --------------------
     BOX3D(1 0 0,4 2 2)

### See Also

,

Find_SRID The syntax is find_srid(<db/schema>, <table>, <column>) and the function returns the integer SRID of the specified column by searching through the GEOMETRY_COLUMNS table.
integer `Find_SRID` varchar a_schema_name varchar a_table_name varchar a_geomfield_name

### Description

The syntax is find_srid(<db/schema>, <table>, <column>) and the function returns the integer SRID of the specified column by searching through the GEOMETRY_COLUMNS table. If the geometry column has not been properly added with the AddGeometryColumns() function, this function will not work either.

### Examples

     SELECT Find_SRID('public', 'tiger_us_state_2007', 'the_geom_4269');
    find_srid
    ----------
    4269

### See Also

ST_Mem_Size Returns the amount of space (in bytes) the geometry takes.
integer `ST_Mem_Size` geometry geomA

### Description

Returns the amount of space (in bytes) the geometry takes.

This is a nice compliment to PostgreSQL built in functions pg_size_pretty, pg_relation_size, pg_total_relation_size.

pg_relation_size which gives the byte size of a table may return byte size lower than ST_Mem_Size. This is because pg_relation_size does not add toasted table contribution and large geometries are stored in TOAST tables.

pg_total_relation_size - includes, the table, the toasted tables, and the indexes.

&Z_support;

&curve_support;

### Examples

    --Return how much byte space Boston takes up  in our Mass data set
    SELECT pg_size_pretty(SUM(ST_Mem_Size(the_geom))) as totgeomsum,
    pg_size_pretty(SUM(CASE WHEN town = 'BOSTON' THEN st_mem_size(the_geom) ELSE 0 END)) As bossum,
    CAST(SUM(CASE WHEN town = 'BOSTON' THEN st_mem_size(the_geom) ELSE 0 END)*1.00 /
    		SUM(st_mem_size(the_geom))*100 As numeric(10,2)) As perbos
    FROM towns;

    totgeomsum	bossum	perbos
    ----------	------	------
    1522 kB		30 kB	1.99

    SELECT ST_Mem_Size(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'));

    ---
    73

    --What percentage of our table is taken up by just the geometry
    SELECT pg_total_relation_size('public.neighborhoods') As fulltable_size, sum(ST_Mem_Size(the_geom)) As geomsize,
    sum(ST_Mem_Size(the_geom))*1.00/pg_total_relation_size('public.neighborhoods')*100 As pergeom
    FROM neighborhoods;
    fulltable_size geomsize  pergeom
    ------------------------------------------------
    262144         96238	 36.71188354492187500000

### See Also

ST_Point_Inside_Circle Is the point geometry insert circle defined by center_x, center_y , radius
boolean `ST_Point_Inside_Circle` geometry a_point float center_x float center_y float radius

### Description

The syntax for this functions is point_inside_circle(<geometry>,<circle_center_x>,<circle_center_y>,<radius>). Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

This only works for points as the name suggests

### Examples

    SELECT ST_Point_Inside_Circle(ST_Point(1,2), 0.5, 2, 3);
     st_point_inside_circle
    ------------------------
     t

### See Also

ST_XMax Returns X maxima of a bounding box 2d or 3d or a geometry.
float `ST_XMax` box3d aGeomorBox2DorBox3D

### Description

Returns X maxima of a bounding box 2d or 3d or a geometry.

Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior defined for geometries and box2d. However you can not feed it a geometry or box2d text represenation, since that will not auto-cast.

&Z_support;

&curve_support;

### Examples

    SELECT ST_XMax('BOX3D(1 2 3, 4 5 6)');
    st_xmax
    -------
    4

    SELECT ST_XMax(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
    st_xmax
    -------
    5

    SELECT ST_XMax(CAST('BOX(-3 2, 3 4)' As box2d));
    st_xmax
    -------
    3
    --Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
    SELECT ST_XMax('LINESTRING(1 3, 5 6)');

    --ERROR:  BOX3D parser - doesnt start with BOX3D(

    SELECT ST_XMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
    st_xmax
    --------
    220288.248780547

### See Also

, , , ,

ST_XMin Returns X minima of a bounding box 2d or 3d or a geometry.
float `ST_XMin` box3d aGeomorBox2DorBox3D

### Description

Returns X minima of a bounding box 2d or 3d or a geometry.

Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior defined for geometries and box2d. However you can not feed it a geometry or box2d text represenation, since that will not auto-cast.

&Z_support;

&curve_support;

### Examples

    SELECT ST_XMin('BOX3D(1 2 3, 4 5 6)');
    st_xmin
    -------
    1

    SELECT ST_XMin(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
    st_xmin
    -------
    1

    SELECT ST_XMin(CAST('BOX(-3 2, 3 4)' As box2d));
    st_xmin
    -------
    -3
    --Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
    SELECT ST_XMin('LINESTRING(1 3, 5 6)');

    --ERROR:  BOX3D parser - doesnt start with BOX3D(

    SELECT ST_XMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
    st_xmin
    --------
    220186.995121892

### See Also

, , , ,

ST_YMax Returns Y maxima of a bounding box 2d or 3d or a geometry.
float `ST_YMax` box3d aGeomorBox2DorBox3D

### Description

Returns Y maxima of a bounding box 2d or 3d or a geometry.

Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior defined for geometries and box2d. However you can not feed it a geometry or box2d text represenation, since that will not auto-cast.

&Z_support;

&curve_support;

### Examples

    SELECT ST_YMax('BOX3D(1 2 3, 4 5 6)');
    st_ymax
    -------
    5

    SELECT ST_YMax(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
    st_ymax
    -------
    6

    SELECT ST_YMax(CAST('BOX(-3 2, 3 4)' As box2d));
    st_ymax
    -------
    4
    --Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
    SELECT ST_YMax('LINESTRING(1 3, 5 6)');

    --ERROR:  BOX3D parser - doesnt start with BOX3D(

    SELECT ST_YMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
    st_ymax
    --------
    150506.126829327

### See Also

, , , ,

ST_YMin Returns Y minima of a bounding box 2d or 3d or a geometry.
float `ST_YMin` box3d aGeomorBox2DorBox3D

### Description

Returns Y minima of a bounding box 2d or 3d or a geometry.

Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior defined for geometries and box2d. However you can not feed it a geometry or box2d text represenation, since that will not auto-cast.

&Z_support;

&curve_support;

### Examples

    SELECT ST_YMin('BOX3D(1 2 3, 4 5 6)');
    st_ymin
    -------
    2

    SELECT ST_YMin(ST_GeomFromText('LINESTRING(1 3 4, 5 6 7)'));
    st_ymin
    -------
    3

    SELECT ST_YMin(CAST('BOX(-3 2, 3 4)' As box2d));
    st_ymin
    -------
    2
    --Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
    SELECT ST_YMin('LINESTRING(1 3, 5 6)');

    --ERROR:  BOX3D parser - doesnt start with BOX3D(

    SELECT ST_YMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
    st_ymin
    --------
    150406

### See Also

, , , , ,

ST_ZMax Returns Z minima of a bounding box 2d or 3d or a geometry.
float `ST_ZMax` box3d aGeomorBox2DorBox3D

### Description

Returns Z maxima of a bounding box 2d or 3d or a geometry.

Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior defined for geometries and box2d. However you can not feed it a geometry or box2d text represenation, since that will not auto-cast.

&Z_support;

&curve_support;

### Examples

    SELECT ST_ZMax('BOX3D(1 2 3, 4 5 6)');
    st_zmax
    -------
    6

    SELECT ST_ZMax(ST_GeomFromEWKT('LINESTRING(1 3 4, 5 6 7)'));
    st_zmax
    -------
    7

    SELECT ST_ZMax('BOX3D(-3 2 1, 3 4 1)' );
    st_zmax
    -------
    1
    --Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
    SELECT ST_ZMax('LINESTRING(1 3 4, 5 6 7)');

    --ERROR:  BOX3D parser - doesnt start with BOX3D(

    SELECT ST_ZMax(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
    st_zmax
    --------
    3

### See Also

, , , , ,

ST_ZMin Returns Z minima of a bounding box 2d or 3d or a geometry.
float `ST_ZMin` box3d aGeomorBox2DorBox3D

### Description

Returns Z minima of a bounding box 2d or 3d or a geometry.

Although this function is only defined for box3d, it will work for box2d and geometry because of the auto-casting behavior defined for geometries and box2d. However you can not feed it a geometry or box2d text represenation, since that will not auto-cast.

&Z_support;

&curve_support;

### Examples

    SELECT ST_ZMin('BOX3D(1 2 3, 4 5 6)');
    st_zmin
    -------
    3

    SELECT ST_ZMin(ST_GeomFromEWKT('LINESTRING(1 3 4, 5 6 7)'));
    st_zmin
    -------
    4

    SELECT ST_ZMin('BOX3D(-3 2 1, 3 4 1)' );
    st_zmin
    -------
    1
    --Observe THIS DOES NOT WORK because it will try to autocast the string representation to a BOX3D
    SELECT ST_ZMin('LINESTRING(1 3 4, 5 6 7)');

    --ERROR:  BOX3D parser - doesnt start with BOX3D(

    SELECT ST_ZMin(ST_GeomFromEWKT('CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)'));
    st_zmin
    --------
    1

### See Also

, , , , , ,