Module: ActiveRecordSpatial::SpatialScopes

Extended by:
ActiveSupport::Concern
Defined in:
lib/activerecord-spatial/spatial_scopes.rb

Overview

Creates named scopes for spatial relationships. The scopes created follow the nine relationships established by the standard Dimensionally Extended 9-Intersection Matrix functions plus a couple of extra ones provided by PostGIS.

Scopes provided are:

  • st_contains

  • st_containsproperly

  • st_covers

  • st_coveredby

  • st_crosses

  • st_disjoint

  • st_equals

  • st_intersects

  • st_orderingequals

  • st_overlaps

  • st_touches

  • st_within

  • st_dwithin

  • st_dfullywithin

The first argument to each of these methods can be a Geos::Geometry-based object or anything readable by Geos.read along with an optional options Hash.

For ordering, we have the following:

The following scopes take no arguments:

  • order_by_st_area

  • order_by_st_ndims

  • order_by_st_npoints

  • order_by_st_nrings

  • order_by_st_numgeometries

  • order_by_st_numinteriorring

  • order_by_st_numinteriorrings

  • order_by_st_numpoints

  • order_by_st_length3d

  • order_by_st_length

  • order_by_st_length2d

  • order_by_st_perimeter

  • order_by_st_perimeter2d

  • order_by_st_perimeter3d

These next scopes allow you to specify a geometry argument for measurement:

  • order_by_st_distance

  • order_by_st_distance_sphere

  • order_by_st_maxdistance

  • order_by_st_hausdorffdistance (additionally allows you to set the densify_frac argument)

  • order_by_st_distance_spheroid (requires an additional SPHEROID string to calculate against)

These next scopes allow you to specify a SPHEROID string to calculate against:

  • order_by_st_length2d_spheroid

  • order_by_st_length3d_spheroid

  • order_by_st_length_spheroid

Options

  • :column - the column to compare against. This option can either be a straight-up column name or a Hash that contains a handful of options that can be used to wrap a geometry column in an ST_ function. When wrapping a geometry column in a function, you can set the name of the function and its methods like so:

    Foo.st_within(geom, column: {
  name: :the_geom,
  wrapper: :centroid
})

Foo.st_within(geom, column: {
  wrapper: {
    snap: [ 'POINT (0 0)', 1 ]
  }
})

    In the first example, the name of the function is the value to the :wrapper+ option. In the second example, :snap is the function name and the Array value is used as the arguments to the ST_snap function. We can also see the column name being set in the first example.

    In all cases, the default column name is ‘the_geom’. You can override the default column name for the ActiveRecordSpatial by setting it via ActiveRecordSpatial.default_column_name=, which is useful if you have a common geometry name you tend to use, such as geom, wkb, feature, etc.

  • :use_index - whether to use the “ST_” methods or the “_ST_” variants which don’t use indexes. The default is true.

  • :allow_null - relationship scopes have the option of treating NULL geometry values as TRUE, i.e.

    ST_within(the_geom, ...) OR the_geom IS NULL

  • :desc - the order_by scopes have an additional :desc option to alllow for DESC ordering.

  • :nulls - the order_by scopes also allow you to specify whether you want NULL values to be sorted first or last.

  • :invert - inverts the relationship query from ST_*(A, B) to ST_*(B, A).

Because it’s quite common to only want to flip the ordering to DESC, you can also just pass :desc on its own rather than as an options Hash.

SRID Detection

  • the default SRID according to the SQL-MM standard is 0, but versions of PostGIS prior to 2.0 would return -1. We do some detection here and set the value of ActiveRecordSpatial::UNKNOWN_SRIDS accordingly.

  • if the geometry itself has an SRID, we’ll compare it to the geometry of the column. If they differ, we’ll use ST_Transform to transform the geometry to the proper SRID for comparison. If they’re the same, no conversion is necessary.

  • if no SRID is specified in the geometry, we’ll use ST_SetSRID to set the SRID to the column’s SRID.

  • in cases where the column has been defined with an SRID of UNKNOWN_SRIDS, no transformation is done, but we’ll set the SRID of the geometry to UNKNOWN_SRIDS to perform the query using ST_SetSRID, as we’ll assume the SRID of the column to be whatever the SRID of the geometry is.

  • when using geography types, the SRID is never transformed since it’s assumed that all of your geometries will be in 4326.

Constant Summary collapse

DEFAULT_OPTIONS = 
{
  column: ActiveRecordSpatial.default_column_name,
  use_index: true
}.freeze