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 and Description
    --- | ---
    `static FieldType` | `DEFAULT_FIELDTYPE` pointValues, docValues, and nothing else.
    `static String` | `SUFFIX_MAXX`
    `static String` | `SUFFIX_MAXY`
    `static String` | `SUFFIX_MINX`
    `static String` | `SUFFIX_MINY`
    `static String` | `SUFFIX_XDL`

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

      `ctx`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

    - #### DEFAULT_FIELDTYPE

          public static 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 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

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

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.