> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ST_ConvexHull

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Given a shape *A*, `ST_ConvexHull(A)` returns another shape *B* that is the [convex hull](https://wikipedia.org/wiki/Convex_hull) of *A*. The convex hull of a shape is the smallest [convex set](https://wikipedia.org/wiki/Convex_set) of points that <InternalLink path="st_contains">contains</InternalLink> every point in the set that comprises that shape.

In other words, given a set of points *A* in the plane, the convex hull is the shape *B* created by stretching an imaginary rubber band around the outermost points in *A*.

`ST_ConvexHull` works on the following data types:

* <InternalLink path="architecture/glossary#geometry">`GEOMETRY`</InternalLink>

<Note>
  `ST_ConvexHull` is not an aggregate function. It operates on a single `GEOMETRY` object. This means that in practice
  it is most often used in combination with an aggregate function such as <InternalLink path="st_union">`ST_Union`</InternalLink>.
</Note>

## Examples

In this example, we will generate the convex hull of a single geometry. The geometry is made from many individual points using <InternalLink path="st_union">`ST_Union`</InternalLink>.

1. Create a temporary table to hold all the points, which will be in <InternalLink path="architecture/glossary#wkt">Well Known Text (WKT)</InternalLink> format:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE TABLE tmp (ID UUID DEFAULT gen_random_uuid(), geom_text STRING);
   ```

2. Insert the points with the following statement:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   INSERT INTO tmp (geom_text) VALUES
   ('POINT (-73.962090000000003 40.609226)'),
   ('POINT (-74.007309000000006 40.619892)'),
   ('POINT (-73.949724000000003 41.498103999999998)'),
   ('POINT (-72.390808000000007 40.961891999999999)'),
   ('POINT (-77.937476000000004 43.218451000000002)'),
   ('POINT (-73.842978000000002 40.944997999999998)'),
   ('POINT (-73.928291999999999 40.680906999999998)'),
   ('POINT (-73.914484999999999 40.775554)'),
   ('POINT (-73.993281999999994 40.722833000000001)'),
   ('POINT (-73.900373999999999 41.691662000000001)'),
   ('POINT (-73.787897999999998 42.250467)'),
   ('POINT (-75.062138000000004 42.454003)'),
   ('POINT (-73.992576 40.753692000000001)'),
   ('POINT (-75.647559999999999 44.590586000000002)'),
   ('POINT (-73.698974000000007 40.832500000000003)'),
   ('POINT (-73.957140999999993 40.728864000000002)'),
   ('POINT (-73.954773000000003 40.732667999999997)'),
   ('POINT (-74.024456000000001 41.521116999999997)'),
   ('POINT (-73.785302000000001 43.081800000000001)'),
   ('POINT (-74.860436000000007 43.040708000000002)'),
   ('POINT (-74.001165999999998 40.687367000000002)'),
   ('POINT (-78.809790000000007 42.845362000000002)'),
   ('POINT (-75.061370999999994 41.608192000000003)'),
   ('POINT (-76.499137000000005 42.440623000000002)'),
   ('POINT (-73.379208000000006 43.027712000000001)'),
   ('POINT (-73.684466999999998 41.259498000000001)'),
   ('POINT (-74.003300999999993 40.706865999999998)'),
   ('POINT (-76.384369000000007 43.034204000000003)'),
   ('POINT (-73.983408999999995 40.723255000000002)'),
   ('POINT (-74.670794000000001 42.371471999999997)'),
   ('POINT (-73.963970000000003 40.804766999999998)'),
   ('POINT (-73.989228999999995 40.743865)'),
   ('POINT (-73.487143000000003 42.587166000000003)'),
   ('POINT (-78.608046999999999 42.767758999999998)'),
   ('POINT (-78.824476000000004 42.754263999999999)'),
   ('POINT (-72.185676999999998 40.963121999999998)'),
   ('POINT (-78.639556999999996 43.001435000000001)'),
   ('POINT (-77.428916999999998 43.212463)'),
   ('POINT (-73.964771999999996 40.770071999999999)'),
   ('POINT (-73.937073999999996 40.578499000000001)'),
   ('POINT (-74.076237000000006 40.636749000000002)'),
   ('POINT (-73.923480999999995 41.091296)'),
   ('POINT (-78.00206 42.718395000000001)'),
   ('POINT (-74.992647000000005 43.018610000000002)'),
   ('POINT (-73.991900000000001 40.683962000000001)'),
   ('POINT (-74.119761999999994 42.040447)'),
   ('POINT (-73.955706000000006 40.785203000000003)'),
   ('POINT (-73.698363000000001 42.709778)'),
   ('POINT (-75.296575000000004 43.098322000000003)'),
   ('POINT (-73.804747000000006 42.709560000000003)'),
   ('POINT (-79.326158000000007 42.102457000000001)'),
   ('POINT (-73.938518000000002 40.837735000000002)'),
   ('POINT (-73.976410999999999 40.672561999999999)'),
   ('POINT (-73.978993000000003 40.745123999999997)'),
   ('POINT (-77.587306999999996 43.159300999999999)'),
   ('POINT (-74.001251999999994 40.734977000000001)'),
   ('POINT (-76.206723999999994 43.102012000000002)'),
   ('POINT (-78.876722000000001 42.922820999999999)'),
   ('POINT (-73.495369999999994 44.703318000000003)'),
   ('POINT (-79.052965999999998 43.105055)'),
   ('POINT (-73.551120999999995 41.189729)'),
   ('POINT (-73.760520999999997 40.809649999999998)'),
   ('POINT (-73.952360999999996 42.077744000000003)'),
   ('POINT (-76.511525000000006 43.456606000000001)'),
   ('POINT (-75.036815000000004 42.448793000000002)'),
   ('POINT (-75.544407000000007 42.826815000000003)'),
   ('POINT (-73.686974000000006 40.724902)'),
   ('POINT (-77.582922999999994 43.154963000000002)'),
   ('POINT (-78.836257000000003 42.960456999999998)'),
   ('POINT (-73.919056999999995 41.091124999999998)'),
   ('POINT (-73.998487999999995 40.733795999999998)'),
   ('POINT (-73.939606999999995 40.815913000000002)'),
   ('POINT (-74.058107000000007 41.083153000000003)'),
   ('POINT (-73.991060000000004 40.733919)'),
   ('POINT (-73.967905000000002 40.758032999999998)'),
   ('POINT (-73.875281000000001 41.016382999999998)'),
   ('POINT (-77.134634000000005 42.961303000000001)'),
   ('POINT (-78.885418999999999 42.906629000000002)'),
   ('POINT (-73.553145999999998 40.665826000000003)'),
   ('POINT (-73.834867000000003 42.621578999999997)'),
   ('POINT (-73.982307000000006 40.752575)'),
   ('POINT (-77.816855000000004 42.795613000000003)'),
   ('POINT (-73.962288000000001 40.671320999999999)'),
   ('POINT (-72.354918999999995 41.083874999999999)'),
   ('POINT (-73.965331000000006 40.806128999999999)'),
   ('POINT (-74.080895999999996 41.844256000000001)'),
   ('POINT (-73.942249000000004 40.812187000000002)'),
   ('POINT (-73.974255999999997 40.783757999999999)'),
   ('POINT (-73.990206999999998 40.754969000000003)'),
   ('POINT (-73.601747000000003 41.562685000000002)'),
   ('POINT (-74.117880999999997 42.040733000000003)'),
   ('POINT (-73.979851999999994 40.664327999999998)'),
   ('POINT (-73.960042999999999 40.657589000000002)'),
   ('POINT (-74.009314000000003 40.715324000000003)'),
   ('POINT (-73.903509 40.703226000000001)'),
   ('POINT (-74.030330000000006 40.624713999999997)'),
   ('POINT (-73.909406000000004 40.814979000000001)'),
   ('POINT (-73.903160999999997 40.744929999999997)'),
   ('POINT (-73.504622999999995 41.952860000000001)'),
   ('POINT (-73.865554000000003 42.219304000000001)'),
   ('POINT (-73.981960000000001 40.766441)'),
   ('POINT (-73.913732999999993 40.698230000000002)'),
   ('POINT (-73.596703000000005 40.874966000000001)'),
   ('POINT (-73.974082999999993 40.686098000000001)'),
   ('POINT (-73.996341999999999 40.725087000000002)'),
   ('POINT (-73.595579999999998 42.363210000000002)'),
   ('POINT (-73.952259999999995 40.674118999999997)'),
   ('POINT (-73.993341000000001 40.730010999999998)'),
   ('POINT (-73.989086999999998 40.721902)'),
   ('POINT (-73.955855999999997 40.655028000000001)'),
   ('POINT (-74.002930000000006 40.731848999999997)'),
   ('POINT (-76.086753000000002 44.242874)'),
   ('POINT (-73.839067 42.681877999999998)'),
   ('POINT (-74.020105000000001 41.935105)'),
   ('POINT (-73.980250999999996 44.279376999999997)'),
   ('POINT (-74.085936000000004 41.747742000000002)'),
   ('POINT (-77.227361999999999 43.063468)'),
   ('POINT (-74.093547000000001 40.924697999999999)'),
   ('POINT (-74.986999999999995 44.669899999999998)'),
   ('POINT (-73.793597000000005 41.135866)'),
   ('POINT (-78.889482000000001 42.924545000000002)'),
   ('POINT (-73.914946 41.936036999999999)'),
   ('POINT (-73.9071 41.721612999999998)'),
   ('POINT (-73.993579999999994 40.736569000000003)'),
   ('POINT (-73.900388000000007 41.691189000000001)'),
   ('POINT (-73.989261999999997 40.663339000000001)'),
   ('POINT (-73.918380999999997 41.090746000000003)'),
   ('POINT (-73.862252999999995 40.839613)'),
   ('POINT (-73.806933000000001 40.989787999999997)'),
   ('POINT (-73.635006000000004 40.744909)'),
   ('POINT (-73.794276999999994 41.008797000000001)'),
   ('POINT (-73.759060000000005 41.022123000000001)'),
   ('POINT (-73.711965000000006 40.968676000000002)'),
   ('POINT (-74.668248000000006 42.372920000000001)'),
   ('POINT (-73.992476999999994 40.739109999999997)'),
   ('POINT (-74.131673000000006 44.326892000000001)'),
   ('POINT (-73.974738000000002 40.732664)'),
   ('POINT (-73.812349999999995 40.798867000000001)'),
   ('POINT (-78.641949999999994 42.991985)'),
   ('POINT (-73.962226999999999 40.778944000000003)'),
   ('POINT (-74.374174999999994 43.006495000000001)'),
   ('POINT (-77.095714000000001 43.041158000000003)'),
   ('POINT (-73.425764000000001 40.871898000000002)'),
   ('POINT (-73.466729000000001 44.708036)'),
   ('POINT (-73.978020999999998 40.686546999999997)'),
   ('POINT (-73.974082999999993 40.686098000000001)'),
   ('POINT (-73.971849000000006 40.602485000000001)'),
   ('POINT (-73.983153999999999 40.690553000000001)'),
   ('POINT (-77.052417000000005 42.143089000000003)'),
   ('POINT (-73.776431000000002 40.934483)'),
   ('POINT (-74.002019000000004 40.730927999999999)'),
   ('POINT (-73.772469999999998 42.264814000000001)'),
   ('POINT (-73.772876999999994 41.158641000000003)'),
   ('POINT (-72.296062000000006 41.002409)'),
   ('POINT (-74.021124999999998 41.933720000000001)'),
   ('POINT (-74.058107000000007 41.083153000000003)'),
   ('POINT (-73.967922999999999 40.801301000000002)'),
   ('POINT (-72.294278000000006 41.000610999999999)'),
   ('POINT (-76.499340000000004 42.438741999999998)'),
   ('POINT (-73.976597999999996 40.786610000000003)'),
   ('POINT (-73.988552999999996 40.703600000000002)'),
   ('POINT (-74.004855000000006 40.741959000000001)'),
   ('POINT (-73.844444999999993 40.925654999999999)'),
   ('POINT (-74.005101999999994 40.746654999999997)'),
   ('POINT (-73.937281999999996 42.819218999999997)'),
   ('POINT (-74.001677000000001 40.736243000000002)'),
   ('POINT (-73.684112999999996 40.981757000000002)'),
   ('POINT (-73.919064000000006 40.832836999999998)'),
   ('POINT (-78.885268999999994 42.944516)'),
   ('POINT (-72.299519000000004 40.994070999999998)'),
   ('POINT (-73.833477999999999 40.940247999999997)'),
   ('POINT (-73.695717000000002 41.783996999999999)'),
   ('POINT (-73.926891999999995 40.807422000000003)'),
   ('POINT (-74.085899999999995 41.747892999999998)'),
   ('POINT (-73.957583 41.417974999999998)');
   ```

3. Run the query below, which gathers the points into a single geometry using <InternalLink path="st_union">`ST_Union`</InternalLink> that can be operated on by `ST_ConvexHull`, and converts the output to <InternalLink path="architecture/glossary#geojson">GeoJSON</InternalLink> so that we can view it with [geojson.io](http://geojson.io/):

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   WITH
       the_geoms_table
           AS (
               SELECT
                   st_union(st_geomfromtext(geom_text)) AS the_union
               FROM
                   tmp
           )
   SELECT
       st_asgeojson(st_convexhull(the_union))
   FROM
       the_geoms_table;
   ```

   ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   {
     "type": "Polygon",
     "coordinates": [
       [
         [-73.937074, 40.578499],
         [-79.326158, 42.102457],
         [-79.052966, 43.105055],
         [-75.64756, 44.590586],
         [-74.987, 44.6699],
         [-73.466729, 44.708036],
         [-72.185677, 40.963122],
         [-73.937074, 40.578499]
       ]
     ]
   }
   ```

4. Paste the JSON emitted in the previous step into [geojson.io](http://geojson.io/) and you should see an image like the following, which shows the convex hull surrounding the locations of [most of the independent bookstores in New York State](https://www.bookweb.org/member_directory/search/ABAmember/results/0/0/ny/0):

   <img src="https://mintcdn.com/cockroachlabs/Ww46ooILgIVlX3C1/images/v24.3/geospatial/st_convexhull.png?fit=max&auto=format&n=Ww46ooILgIVlX3C1&q=85&s=7f89080b9a1e802f4cdd8b90dff2f761" alt="ST_ConvexHull example" width="2473" height="1327" data-path="images/v24.3/geospatial/st_convexhull.png" />

5. Finally, drop the temporary table if you no longer need it:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   DROP TABLE tmp;
   ```

## See also

* <InternalLink path="export-spatial-data">Export Spatial Data</InternalLink>
* <InternalLink path="spatial-tutorial">Spatial tutorial</InternalLink>
* <InternalLink path="architecture/glossary">Spatial and GIS Glossary of Terms</InternalLink>
* <InternalLink path="spatial-indexes">Spatial indexes</InternalLink>
* <InternalLink path="functions-and-operators#spatial-functions">Spatial functions</InternalLink>
* <InternalLink path="st_covers">`ST_Covers`</InternalLink>
* <InternalLink path="st_coveredby">`ST_CoveredBy`</InternalLink>
* <InternalLink path="st_contains">`ST_Contains`</InternalLink>
* <InternalLink path="st_within">`ST_Within`</InternalLink>
* <InternalLink path="st_intersects">`ST_Intersects`</InternalLink>
* <InternalLink path="st_coveredby">`ST_CoveredBy`</InternalLink>
* <InternalLink path="st_covers">`ST_Covers`</InternalLink>
* <InternalLink path="st_disjoint">`ST_Disjoint`</InternalLink>
* <InternalLink path="st_equals">`ST_Equals`</InternalLink>
* <InternalLink path="st_overlaps">`ST_Overlaps`</InternalLink>
* <InternalLink path="st_touches">`ST_Touches`</InternalLink>
* <InternalLink path="st_union">`ST_Union`</InternalLink>
* <InternalLink path="migrate-from-shapefiles">Migrate from Shapefiles</InternalLink>
* <InternalLink path="migrate-from-geojson">Migrate from GeoJSON</InternalLink>
* <InternalLink path="migrate-from-geopackage">Migrate from GeoPackage</InternalLink>
* <InternalLink path="migrate-from-openstreetmap">Migrate from OpenStreetMap</InternalLink>
* [Introducing Distributed Spatial Data in CockroachDB](https://www.cockroachlabs.com/blog/spatial-data) (blog post)
* <InternalLink path="geoserver">Using GeoServer with CockroachDB</InternalLink>