NAME
DBIO::PostgreSQL::PostGIS::ResultSet - Spatial query helpers for PostGIS-aware result classes
VERSION
version 0.900000
SYNOPSIS
# Auto-set as resultset_class when load_components('PostgreSQL::PostGIS')
# registers the first geometry/geography column.
# Within distance (geography metres, geometry units of the SRID)
my $rs = $schema->resultset('Place')->within_distance(
geom => $point, 1000,
);
# Bounding-box / index-friendly intersect
my $rs = $schema->resultset('Place')->bbox_intersects(geom => $bbox);
# Exact spatial predicates
$places->intersects(geom => $polygon);
$places->contains (geom => $point);
$places->within (geom => $polygon);
# KNN order — uses the <-> operator on a GIST index
my $nearest = $schema->resultset('Place')->nearest_to(geom => $point, 10);DESCRIPTION
Mixin of common spatial-query shortcuts. Every helper returns a chainable resultset, so they compose with regular ->search calls.
The geometry argument can be either a DBIO::PostgreSQL::PostGIS::Geometry instance, an EWKT string, or a raw scalarref \['ST_...'] for fully custom SQL.
Generated spatial predicate methods
The following methods are generated from @_SIMPLE_PREDICATES: intersects, contains, within, touches, crosses, overlaps.
Each takes ($column, $geometry) and returns a filtered resultset using the corresponding PostGIS function.
METHODS
within_distance
$rs->within_distance($column, $geometry, $distance);Filter to rows where ST_DWithin($column, $geometry, $distance) is true. Distance is in metres for geography, in SRID units for geometry.
bbox_intersects
$rs->bbox_intersects($column, $geometry);Bounding-box overlap using the && operator. This is the cheapest spatial predicate and the only one that uses a GIST index without extra hints.
nearest_to
$rs->nearest_to($column, $geometry);
$rs->nearest_to($column, $geometry, $limit);Order rows by distance from $geometry using the <-> KNN operator, optionally limited.
order_by_distance
$rs->order_by_distance($column, $geometry);Like "nearest_to" but uses ST_Distance (exact, not the KNN operator). Use this when you need the actual distance values; use "nearest_to" when you just want the closest N rows.
with_distance
my $rs = $places->with_distance(geom => $point);
while (my $row = $rs->next) {
print $row->name, ' is ', $row->get_column('distance'), ' away';
}Selects an extra distance column computed by ST_Distance.
AUTHOR
DBIO Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.