NAME

DBIO::PostgreSQL::PostGIS::ResultSet - Spatial query helpers for PostGIS-aware result classes

VERSION

version 0.900007

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.

A Geometry object that was read from the database, or built with an ewkb_hex, is bound as that EWKB hex (?::geometry, with ST_SetSRID over it when the object has an SRID): the stored geometry, bit for bit, so a predicate that holds only for the exact value -- within_distance with a distance of 0, touches, contains on an edge -- holds for a geometry handed back from a row. An object without hex is bound as its WKT (ST_GeomFromText), 15 significant digits per ordinate. A hex without an SRID flag is SRID 0, as it is on the server.

The column name every helper takes is an identifier, not an expression: it names a column of the resultset's source, and the helper writes it quoted together with the source alias (me.geom, me."Geom"), so a MixedCase name keeps its case. A name the source does not have makes the helper throw a DBIO::Exception that names it.

A Geometry object with nothing to bind -- no hex, no WKT and no coordinates, or coordinates without a geometry_type -- is not an argument: the helper throws a DBIO::Exception that says what is missing. It used to bind NULL, and the search found nothing without saying why.

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.