Package org.apache.lucene.spatial.bbox

Class BBoxStrategy

  • public class BBoxStrategy
extends 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.

    Characteristics:

    • 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.

    Implementation:

    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,
                    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

      • getFieldType

        public 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 Field[] createIndexableFields​(org.locationtech.spatial4j.shape.Shape shape)
        Description copied from class: SpatialStrategy
        Returns the IndexableField(s) from the shape that are to be added to the Document. These fields are expected to be marked as indexed and not stored.

        Note: If you want to store the shape as a string for retrieval in search results, you could add it like this: 

        document.add(new StoredField(fieldName,ctx.toString(shape)));
        The particular string representation used doesn't matter to the Strategy since it doesn't use it.
        Specified by:
        createIndexableFields in class SpatialStrategy
        Returns:
        Not null nor will it have null elements.

      • makeDistanceValueSource

        public DoubleValuesSource makeDistanceValueSource​(org.locationtech.spatial4j.shape.Point queryPoint,
                                                  double multiplier)
        Description copied from class: SpatialStrategy
        Make a ValueSource returning the distance between the center of the indexed shape and queryPoint. If there are multiple indexed shapes then the closest one is chosen. The result is multiplied by multiplier, which conveniently is used to get the desired units.
        Specified by:
        makeDistanceValueSource in class SpatialStrategy

      • makeOverlapRatioValueSource

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