postgis_topology

PostGIS topology spatial types and functions

https://git.osgeo.org/gitea/postgis/postgis

Overview

Package	Version	Category	License	Language
`postgis`	`3.6.2`	GIS	GPL-2.0	C

ID	Extension	Bin	Lib	Load	Create	Trust	Reloc	Schema
1500	`postgis`	No	Yes	No	Yes	No	No	-
1501	`postgis_topology`	No	Yes	No	Yes	No	No	`topology`
1502	`postgis_raster`	No	Yes	No	Yes	No	No	-
1503	`postgis_sfcgal`	No	Yes	No	Yes	No	Yes	-
1504	`postgis_tiger_geocoder`	No	Yes	No	Yes	Yes	No	`tiger`
1505	`address_standardizer`	No	Yes	No	Yes	No	Yes	-
1506	`address_standardizer_data_us`	No	Yes	No	Yes	No	Yes	-

Related	`postgis` `pgrouting` `pointcloud` `pointcloud_postgis` `h3` `h3_postgis` `q3c` `ogr_fdw` `geoip`

Version

Type	Repo	Version	PG Ver	Package	Deps
EXT	PGDG	`3.6.2`	1817161514	`postgis`	`postgis`
RPM	PGDG	`3.6.2`	1817161514	`postgis36_$v`	-
DEB	PGDG	`3.6.2`	1817161514	`postgresql-$v-postgis-3`	-

OS / PG	PG18	PG17	PG16	PG15	PG14
el8.x86_64	PGDG 3.6.1	PGDG 3.6.1	PGDG 3.6.1	PGDG 3.6.1	PGDG 3.6.1
el8.aarch64	PGDG 3.6.1	PGDG 3.6.1	PGDG 3.6.1	PGDG 3.6.1	PGDG 3.6.1
el9.x86_64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
el9.aarch64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
el10.x86_64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
el10.aarch64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
d12.x86_64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
d12.aarch64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
d13.x86_64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
d13.aarch64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
u22.x86_64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
u22.aarch64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
u24.x86_64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2
u24.aarch64	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2	PGDG 3.6.2

Install

You can install postgis directly. First, make sure the PGDG repository is added and enabled:

pig repo add pgdg -u          # Add PGDG repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install postgis;          # Install for current active PG version

pig ext install -y postgis -v 18  # PG 18
pig ext install -y postgis -v 17  # PG 17
pig ext install -y postgis -v 16  # PG 16
pig ext install -y postgis -v 15  # PG 15
pig ext install -y postgis -v 14  # PG 14

dnf install -y postgis36_18       # PG 18
dnf install -y postgis36_17       # PG 17
dnf install -y postgis36_16       # PG 16
dnf install -y postgis36_15       # PG 15
dnf install -y postgis36_14       # PG 14

apt install -y postgresql-18-postgis-3   # PG 18
apt install -y postgresql-17-postgis-3   # PG 17
apt install -y postgresql-16-postgis-3   # PG 16
apt install -y postgresql-15-postgis-3   # PG 15
apt install -y postgresql-14-postgis-3   # PG 14

Create Extension:

CREATE EXTENSION postgis_topology CASCADE;  -- requires: postgis

Usage

PostGIS Topology: Topological data model support for PostGIS

PostGIS Topology implements the SQL/MM topology model for PostgreSQL. It represents spatial data as a graph of nodes, edges, and faces, ensuring that shared boundaries are stored only once and geometric consistency is enforced.

Topology Reference

Setup

CREATE EXTENSION postgis_topology;

This creates the topology schema with management tables and functions.

Creating a Topology

A topology is a named schema with a defined SRID and tolerance for snapping:

-- Create a topology named 'city_topo' with SRID 4326 and 0.00001 degree tolerance
SELECT topology.CreateTopology('city_topo', 4326, 0.00001);

List all topologies:

SELECT * FROM topology.topology;

Building Topology Primitives

Adding Edges

Edges are the fundamental building blocks. Nodes are created automatically at edge endpoints.

-- Add isolated nodes
SELECT topology.ST_AddIsoNode('city_topo', NULL, ST_Point(-73.98, 40.75));

-- Add an edge between two points (creates nodes if needed)
SELECT topology.ST_AddEdgeModFace('city_topo',
    ST_MakeLine(ST_Point(-73.99, 40.74), ST_Point(-73.98, 40.74)));

SELECT topology.ST_AddEdgeModFace('city_topo',
    ST_MakeLine(ST_Point(-73.98, 40.74), ST_Point(-73.98, 40.75)));

SELECT topology.ST_AddEdgeModFace('city_topo',
    ST_MakeLine(ST_Point(-73.98, 40.75), ST_Point(-73.99, 40.75)));

SELECT topology.ST_AddEdgeModFace('city_topo',
    ST_MakeLine(ST_Point(-73.99, 40.75), ST_Point(-73.99, 40.74)));

Inspecting Primitives

-- List nodes
SELECT node_id, ST_AsText(geom) FROM city_topo.node;

-- List edges
SELECT edge_id, ST_AsText(geom) FROM city_topo.edge_data;

-- List faces (face_id 0 is the universal face)
SELECT face_id, ST_AsText(mbr) FROM city_topo.face;

-- Get the geometry of a face
SELECT topology.ST_GetFaceGeometry('city_topo', 1);

TopoGeometry

A TopoGeometry is a spatial object defined by references to topology primitives rather than coordinates. This ensures shared boundaries stay consistent.

Creating a TopoGeometry Layer

-- Create a table with a topogeometry column
CREATE TABLE city_topo.blocks (
    id serial PRIMARY KEY,
    name text
);

-- Register a topogeometry column (returns a layer_id)
SELECT topology.AddTopoGeometryColumn('city_topo', 'city_topo', 'blocks', 'topo', 'POLYGON');

Assigning TopoGeometry Values

-- Create a TopoGeometry from a regular geometry (snaps to existing topology)
INSERT INTO city_topo.blocks (name, topo) VALUES
    ('Block A', topology.toTopoGeom(
        ST_GeomFromText('POLYGON((-73.99 40.74,-73.98 40.74,-73.98 40.75,-73.99 40.75,-73.99 40.74))', 4326),
        'city_topo', 1));

-- Convert a TopoGeometry back to a regular geometry
SELECT name, topo::geometry FROM city_topo.blocks;

Validating Topology

-- Validate the entire topology
SELECT * FROM topology.ValidateTopology('city_topo');

-- Check for topology errors
SELECT error FROM topology.ValidateTopology('city_topo')
WHERE error IS NOT NULL;

Cleanup

-- Drop a topology and all its objects
SELECT topology.DropTopology('city_topo');

Feedback

Was this page helpful?

Thanks for the feedback! Please let us know how we can improve.

Sorry to hear that. Please let us know how we can improve.

Last Modified 2026-03-12: add pg extension catalog (95749bf)