Geospatial
Geospatial values say where things are, and what is near or inside what: a bakery's position, the patches it delivers to, the shops within five kilometres of a customer, the pins inside the map a person is looking at.
The types are standard types, listed under
Geospatial types: Point,
with a named latitude and longitude, five other geometries such as
Polygon, and Geometry, which holds any one of the six. All of them
are in WGS84, the coordinate system GPS uses, and are sent as GeoJSON.
This page covers what you do with them:
| Part | What | Builds on |
|---|---|---|
| Geometry operations | 10 in geo: distance, length, bearing, area, intersects, contains, within (with or without distance:), centroid, bounding box; and the two for WKT text |
The standard library's operations and its whole-number maths |
| Storing geometries | One PostGIS geography column per geometry, checked to its type and WGS84; GiST indexes derived from your queries |
Storage types |
| Finding records by place | geo.within, geo.contains, geo.intersects as where: conditions; order: by geo.distance inside a radius |
Reads and writes |
| GeoJSON and other formats | GeoJSON Feature and FeatureCollection; WKT where other systems use it |
The standard library's GeoJSON |
PostGIS is the PostgreSQL extension for geographic data. Where this page
says a PostGIS behaviour was verified, it was checked against PostGIS
3.4.2 on PostgreSQL 16. Some compiler messages cite a decision by number,
as in question 10; the Decisions table in the
design notes lists them.
| What every geospatial operation follows Every |
| Geometry operations The |
| Predicates and shapes Whether one shape contains, is within or intersects another, and a shape's centre and bounding box. |
| Storing geometries A geometry field of an entity is stored in one PostgreSQL column of PostGIS's |
| Finding records by place You find records by where they are with a |
| GeoJSON and other formats Other systems send and expect geometries in their own formats: map libraries take GeoJSON layers, spreadsheets and other systems' APIs hold WKT text, and trackers send pairs of numbers. |
| What geospatial leaves out, and what to use instead Some geospatial work is left out of the language. |
What is built says which of this works today.
Details
The exact rules, for when you hit an edge case.
| Precision and determinism A |
Markdown for agents: /docs/geospatial.md.Built from Jadpo main at aee2e8f.