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

Package org.apache.lucene.spatial.vector

# Class PointVectorStrategy

java.lang.Object
org.apache.lucene.spatial.SpatialStrategy
org.apache.lucene.spatial.vector.PointVectorStrategy

public class PointVectorStrategy extends SpatialStrategy
Simple `SpatialStrategy` which represents Points in two numeric fields. The Strategy's best feature is decent distance sort.

Characteristics:

- Only indexes points; just one per field value.
- Can query by a rectangle or circle.
- `SpatialOperation.Intersects` and `SpatialOperation.IsWithin` is supported.
- Requires DocValues for `SpatialStrategy.makeDistanceValueSource(org.locationtech.spatial4j.shape.Point)` and for searching with a Circle.

Implementation:

This is a simple Strategy. Search works with a pair of range queries on two `DoublePoint`s representing x & y fields. A Circle query does the same bbox query but adds a ValueSource filter on `SpatialStrategy.makeDistanceValueSource(org.locationtech.spatial4j.shape.Point)`.

One performance shortcoming with this strategy is that a scenario involving both a search using a Circle and sort will result in calculations for the spatial distance being done twice -- once for the filter and second for the sort.

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_X`
  `static final String`
  `SUFFIX_Y`

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

  `ctx`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PointVectorStrategy(org.locationtech.spatial4j.context.SpatialContext ctx, String fieldNamePrefix, FieldType fieldType)`
  Create a new instance configured with the provided FieldType options.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Field[]`
  `createIndexableFields(org.locationtech.spatial4j.shape.Point point)`
  `Field[]`
  `createIndexableFields(org.locationtech.spatial4j.shape.Shape shape)`
  Returns the IndexableField(s) from the `shape` that are to be added to the `Document`.
  `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`.
  `Query`
  `makeQuery(SpatialArgs args)`
  Make a Query based principally on `SpatialOperation` and `Shape` from the supplied `args`.
  `static PointVectorStrategy`
  `newInstance(org.locationtech.spatial4j.context.SpatialContext ctx, String fieldNamePrefix)`
  Create a new `PointVectorStrategy` 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_X

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

  - ### SUFFIX_Y

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

- ## Constructor Details

  - ### PointVectorStrategy

    public PointVectorStrategy(org.locationtech.spatial4j.context.SpatialContext ctx, String fieldNamePrefix, FieldType fieldType)
    Create a new instance configured with the provided FieldType options. See `DEFAULT_FIELDTYPE`. a field type is used to articulate the desired options (namely pointValues, docValues, stored). Legacy numerics is configurable this way too.

- ## Method Details

  - ### newInstance

    public static PointVectorStrategy newInstance(org.locationtech.spatial4j.context.SpatialContext ctx, String fieldNamePrefix)
    Create a new `PointVectorStrategy` instance that uses `DoublePoint` and `DoublePoint.newRangeQuery(java.lang.String, double, double)`

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

  - ### createIndexableFields

    public Field[] createIndexableFields(org.locationtech.spatial4j.shape.Point point)
    See Also:
      - `createIndexableFields(org.locationtech.spatial4j.shape.Shape)`

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

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