Spatial Engine

Spatial is a peer engine sharing storage with columnar and timeseries. Collections selected via WITH (engine='spatial') and a GEOMETRY SPATIAL_INDEX column get automatic R*-tree indexing over the geometry column.

DDL

-- Spatial peer engine (R-tree + geohash + OGC predicates)
CREATE COLLECTION restaurants (
    location GEOMETRY SPATIAL_INDEX,
    name VARCHAR,
    cuisine VARCHAR,
    rating FLOAT
) WITH (engine='spatial');

-- Or add a spatial index to any collection
CREATE COLLECTION restaurants;
CREATE SPATIAL INDEX ON restaurants FIELDS location;

Queries

-- Find within 1km
SELECT name, ST_Distance(location, ST_Point(-73.990, 40.750)) AS dist
FROM restaurants
WHERE ST_DWithin(location, ST_Point(-73.990, 40.750), 1000)
ORDER BY dist;

-- Geofencing (point-in-polygon)
SELECT name FROM restaurants
WHERE ST_Within(location, ST_GeomFromGeoJSON('{
    "type": "Polygon",
    "coordinates": [[[-74.0, 40.7], [-73.9, 40.7], [-73.9, 40.8], [-74.0, 40.8], [-74.0, 40.7]]]
}'));

-- H3 hexagonal binning
SELECT h3_latlngtocell(40.748, -73.985, 9) AS hex;

-- Spatial join
SELECT r.name, z.zone_name
FROM restaurants r, delivery_zones z
WHERE ST_Contains(z.boundary, r.location);

-- Hybrid spatial-vector: nearby AND semantically similar
SELECT name, vector_distance(embedding, $query_vec) AS similarity
FROM restaurants
WHERE ST_DWithin(location, ST_Point(-73.990, 40.750), 2000) AND embedding <-> $query_vec
LIMIT 10;

Geometry Functions

• Predicates — ST_Contains, ST_Within, ST_Intersects, ST_Disjoint, ST_DWithin, ST_IsValid
• Constructors — ST_Point, ST_MakePoint, ST_GeomFromText, ST_GeomFromWKB, ST_GeomFromGeoJSON, ST_MakeLine, ST_MakePolygon, ST_MakeEnvelope
• Accessors — ST_AsText, ST_AsGeoJSON, ST_X, ST_Y, ST_GeometryType, ST_NPoints, ST_SRID
• Spatial reference systems — ST_SRID, ST_SetSRID, ST_Transform
• Measures — ST_Distance, ST_Length, ST_Perimeter, ST_Area (meters; geodesic for 4326, planar for a projected SRID)
• Operations — ST_Buffer, ST_Envelope, ST_Centroid, ST_Union, ST_Intersection

Each works in every geometry position — INSERT values, projections, and predicate arguments — and constructors nest. See Spatial Queries for the full reference.

SRID

Every geometry carries an SRID, 4326 by default. Supported SRIDs are 4326, 32647, 32648, 3375, and 3376. Operands in different SRIDs raise a data exception (SQLSTATE 22000) instead of transforming implicitly. Use ST_Transform to convert. A spatial index fixes its SRID at its first entry and refuses geometries in another SRID. See Spatial Reference Systems.

Format Support

WKB, WKT, and GeoJSON interchange. GeoParquet v1.1.0 and GeoArrow metadata for bulk export.

Combined with Timeseries

-- Fleet tracking: spatial + time
CREATE COLLECTION fleet (
    ts TIMESTAMP TIME_KEY,
    vehicle_id VARCHAR,
    position GEOMETRY SPATIAL_INDEX,
    speed FLOAT
) WITH (engine='timeseries', partition_by='1d');