Class BBoxStrategy

  • public class BBoxStrategy
    extends org.apache.lucene.spatial.SpatialStrategy
    A SpatialStrategy for indexing and searching Rectangles by storing its coordinates in numeric fields. It supports all SpatialOperations and has a custom overlap relevancy. It is based on GeoPortal's SpatialClauseAdapter.


    • Only indexes Rectangles; just one per field value. Other shapes can be provided and the bounding box will be used.
    • Can query only by a Rectangle. Providing other shapes is an error.
    • Supports most SpatialOperations but not Overlaps.
    • Uses the DocValues API for any sorting / relevancy.


    This uses 4 double fields for minX, maxX, minY, maxY and a boolean to mark a dateline cross. Depending on the particular SpatialOperations, there are a variety of range queries on DoublePoints to be done. The makeOverlapRatioValueSource(org.locationtech.spatial4j.shape.Rectangle, double) works by calculating the query bbox overlap percentage against the indexed shape overlap percentage. The indexed shape's coordinates are retrieved from LeafReader.getNumericDocValues(java.lang.String).

    WARNING: This API is experimental and might change in incompatible ways in the next release.
    • Constructor Detail

      • BBoxStrategy

        public BBoxStrategy​(org.locationtech.spatial4j.context.SpatialContext ctx,
                            String fieldNamePrefix,
                            org.apache.lucene.document.FieldType fieldType)
        Creates this strategy. fieldType is used to customize the indexing options of the 4 number fields, and to a lesser degree the XDL field too. Search requires pointValues (or legacy numerics), and relevancy requires docValues. If these features aren't needed then disable them.
    • Method Detail

      • newInstance

        public static BBoxStrategy newInstance​(org.locationtech.spatial4j.context.SpatialContext ctx,
                                               String fieldNamePrefix)
        Creates a new BBoxStrategy instance that uses DoublePoint and DoublePoint.newRangeQuery(java.lang.String, double, double)
      • newLegacyInstance

        public static BBoxStrategy newLegacyInstance​(org.locationtech.spatial4j.context.SpatialContext ctx,
                                                     String fieldNamePrefix)
        LegacyNumerics will be removed
        Creates a new BBoxStrategy instance that uses LegacyDoubleField for backwards compatibility
      • getFieldType

        public org.apache.lucene.document.FieldType getFieldType()
        Returns a field type representing the set of field options. This is identical to what was passed into the constructor. It's frozen.
      • createIndexableFields

        public org.apache.lucene.document.Field[] createIndexableFields​(org.locationtech.spatial4j.shape.Shape shape)
        Specified by:
        createIndexableFields in class org.apache.lucene.spatial.SpatialStrategy
      • makeShapeValueSource

        public org.apache.lucene.spatial.ShapeValuesSource makeShapeValueSource()
        Provides access to each rectangle per document
      • makeDistanceValueSource

        public makeDistanceValueSource​(org.locationtech.spatial4j.shape.Point queryPoint,
                                                                                   double multiplier)
        Specified by:
        makeDistanceValueSource in class org.apache.lucene.spatial.SpatialStrategy
      • makeOverlapRatioValueSource

        public makeOverlapRatioValueSource​(org.locationtech.spatial4j.shape.Rectangle queryBox,
                                                                                       double queryTargetProportion)
        Returns a similarity based on BBoxOverlapRatioValueSource. This is just a convenience method.
      • makeQuery

        public makeQuery​(org.apache.lucene.spatial.query.SpatialArgs args)
        Specified by:
        makeQuery in class org.apache.lucene.spatial.SpatialStrategy