postgis_topology

postgis : PostGIS topology spatial types and functions

Overview

ID	Extension	Package	Version	Category	License	Language
1501	postgis_topology	postgis	`3.6.2`	GIS	GPL-2.0	C

Attribute	Has Binary	Has Library	Need Load	Has DDL	Relocatable	Trusted
--s-d--	No	Yes	No	Yes	no	no

Relationships
Schemas	`topology`
Requires	postgis
See Also	pgrouting pointcloud pointcloud_postgis h3 h3_postgis q3c ogr_fdw geoip
Siblings	postgis postgis_raster postgis_sfcgal postgis_tiger_geocoder address_standardizer address_standardizer_data_us

Packages

Type	Repo	Version	PG Major Compatibility	Package Pattern	Dependencies
EXT	PGDG	`3.6.2`	18 17 16 15 14	`postgis`	`postgis`
RPM	PGDG	`3.6.2`	18 17 16 15 14	`postgis36_$v`	-
DEB	PGDG	`3.6.2`	18 17 16 15 14	`postgresql-$v-postgis-3`	-

Linux / 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

Source

Repository

git.osgeo.org/gitea/postgis/postgis

Install

Make sure PGDG repo available:

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

Install this extension with pig:

pig install postgis;		# install via package name, for the active PG version
pig install postgis_topology;		# install by extension name, for the current active PG version

pig install postgis_topology -v 18;   # install for PG 18
pig install postgis_topology -v 17;   # install for PG 17
pig install postgis_topology -v 16;   # install for PG 16
pig install postgis_topology -v 15;   # install for PG 15
pig install postgis_topology -v 14;   # install for PG 14

Create this extension with:

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');

Last updated on 2026-03-12

postgis postgis_raster