BBoxStrategy (Lucene 10.5.0 spatial-extras API)
Description: declaration: package: org.apache.lucene.spatial.bbox, class: BBoxStrategy

Package org.apache.lucene.spatial.bbox

# Class BBoxStrategy

java.lang.Object
org.apache.lucene.spatial.SpatialStrategy
org.apache.lucene.spatial.bbox.BBoxStrategy

public class BBoxStrategy extends SpatialStrategy
A SpatialStrategy for indexing and searching Rectangles by storing its coordinates in numeric fields. It supports all `SpatialOperation`s 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 `SpatialOperation`s 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 `SpatialOperation`s, there are a variety of range queries on `DoublePoint`s 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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final FieldType`
  `DEFAULT_FIELDTYPE`
  pointValues, docValues, and nothing else.
  `static final String`
  `SUFFIX_MAXX`
  `static final String`
  `SUFFIX_MAXY`
  `static final String`
  `SUFFIX_MINX`
  `static final String`
  `SUFFIX_MINY`
  `static final String`
  `SUFFIX_XDL`

  ### Fields inherited from class org.apache.lucene.spatial.SpatialStrategy

  `ctx`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BBoxStrategy(org.locationtech.spatial4j.context.SpatialContext ctx, String fieldNamePrefix, FieldType fieldType)`
  Creates this strategy.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Field[]`
  `createIndexableFields(org.locationtech.spatial4j.shape.Shape shape)`
  Returns the IndexableField(s) from the `shape` that are to be added to the `Document`.
  `FieldType`
  `getFieldType()`
  Returns a field type representing the set of field options.
  `DoubleValuesSource`
  `makeDistanceValueSource(org.locationtech.spatial4j.shape.Point queryPoint, double multiplier)`
  Make a ValueSource returning the distance between the center of the indexed shape and `queryPoint`.
  `DoubleValuesSource`
  `makeOverlapRatioValueSource(org.locationtech.spatial4j.shape.Rectangle queryBox, double queryTargetProportion)`
  Returns a similarity based on `BBoxOverlapRatioValueSource`.
  `Query`
  `makeQuery(SpatialArgs args)`
  Make a Query based principally on `SpatialOperation` and `Shape` from the supplied `args`.
  `ShapeValuesSource`
  `makeShapeValueSource()`
  Provides access to each rectangle per document as a `ShapeValuesSource`
  `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)`

  ### Methods inherited from class org.apache.lucene.spatial.SpatialStrategy

  `getFieldName, getSpatialContext, makeDistanceValueSource, makeRecipDistanceValueSource, toString`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_FIELDTYPE

    public static final FieldType DEFAULT_FIELDTYPE
    pointValues, docValues, and nothing else.

  - ### SUFFIX_MINX

    public static final String SUFFIX_MINX
    See Also:
      - Constant Field Values

  - ### SUFFIX_MAXX

    public static final String SUFFIX_MAXX
    See Also:
      - Constant Field Values

  - ### SUFFIX_MINY

    public static final String SUFFIX_MINY
    See Also:
      - Constant Field Values

  - ### SUFFIX_MAXY

    public static final String SUFFIX_MAXY
    See Also:
      - Constant Field Values

  - ### SUFFIX_XDL

    public static final String SUFFIX_XDL
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### 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 Details

  - ### 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)`

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

  - ### makeShapeValueSource

    public ShapeValuesSource makeShapeValueSource()
    Provides access to each rectangle per document as a `ShapeValuesSource`

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

  - ### makeQuery

    public Query makeQuery(SpatialArgs args)
    Description copied from class: `SpatialStrategy`
    Make a Query based principally on `SpatialOperation` and `Shape` from the supplied `args`. It should be constant scoring of 1.
    Specified by:
      `makeQuery` in class `SpatialStrategy`