org.apache.lucene.spatial.prefix

## Class PrefixTreeStrategy

- java.lang.Object
- - org.apache.lucene.spatial.SpatialStrategy
  - - org.apache.lucene.spatial.prefix.PrefixTreeStrategy

- Direct Known Subclasses:
    RecursivePrefixTreeStrategy, TermQueryPrefixTreeStrategy

      public abstract class PrefixTreeStrategy
      extends SpatialStrategy

  An abstract SpatialStrategy based on `SpatialPrefixTree`. The two subclasses are `RecursivePrefixTreeStrategy` and `TermQueryPrefixTreeStrategy`. This strategy is most effective as a fast approximate spatial search filter.

  Characteristics:

  - Can index any shape; however only `RecursivePrefixTreeStrategy` can effectively search non-point shapes.
  - Can index a variable number of shapes per field value. This strategy can do it via multiple calls to `createIndexableFields(org.locationtech.spatial4j.shape.Shape)` for a document or by giving it some sort of Shape aggregate (e.g. JTS WKT MultiPoint). The shape's boundary is approximated to a grid precision.
  - Can query with any shape. The shape's boundary is approximated to a grid precision.
  - Only `SpatialOperation.Intersects` is supported. If only points are indexed then this is effectively equivalent to IsWithin.
  - The strategy supports `makeDistanceValueSource(org.locationtech.spatial4j.shape.Point,double)` even for multi-valued data, so long as the indexed data is all points; the behavior is undefined otherwise. However, it will likely be removed in the future in lieu of using another strategy with a more scalable implementation. Use of this call is the only circumstance in which a cache is used. The cache is simple but as such it doesn't scale to large numbers of points nor is it real-time-search friendly.

  Implementation:

  The `SpatialPrefixTree` does most of the work, for example returning a list of terms representing grids of various sizes for a supplied shape. An important configuration item is `setDistErrPct(double)` which balances shape precision against scalability. See those javadocs.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `PrefixTreeStrategy.ShapeTokenStream`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `defaultFieldValuesArrayLen`
    `protected double` | `distErrPct`
    `static FieldType` | `FIELD_TYPE`
    `protected SpatialPrefixTree` | `grid`
    `protected boolean` | `pointsOnly`

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

      `ctx`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PrefixTreeStrategy(SpatialPrefixTree grid, String fieldName)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `HeatmapFacetCounter.Heatmap` | `calcFacets(IndexReaderContext context, Bits topAcceptDocs, org.locationtech.spatial4j.shape.Shape inputShape, int facetLevel, int maxCells)` Computes spatial facets in two dimensions as a grid of numbers.
    `protected Iterator<Cell>` | `createCellIteratorToIndex(org.locationtech.spatial4j.shape.Shape shape, int detailLevel, Iterator<Cell> reuse)`
    `Field[]` | `createIndexableFields(org.locationtech.spatial4j.shape.Shape shape)` Returns the IndexableField(s) from the `shape` that are to be added to the `Document`.
    `Field[]` | `createIndexableFields(org.locationtech.spatial4j.shape.Shape shape, double distErr)` Turns `SpatialPrefixTree.getTreeCellIterator(Shape, int)` into a `TokenStream`.
    `Field[]` | `createIndexableFields(org.locationtech.spatial4j.shape.Shape shape, int detailLevel)`
    `double` | `getDistErrPct()`
    `SpatialPrefixTree` | `getGrid()`
    `protected boolean` | `isPointShape(org.locationtech.spatial4j.shape.Shape shape)` Returns true if the `shape` is a `Point`.
    `boolean` | `isPointsOnly()`
    `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`.
    `protected CellToBytesRefIterator` | `newCellToBytesRefIterator()`
    `void` | `setDefaultFieldValuesArrayLen(int defaultFieldValuesArrayLen)` A memory hint used by `SpatialStrategy.makeDistanceValueSource(org.locationtech.spatial4j.shape.Point)` for how big the initial size of each Document's array should be.
    `void` | `setDistErrPct(double distErrPct)` The default measure of shape precision affecting shapes at index and query times.
    `void` | `setPointsOnly(boolean pointsOnly)` True if only indexed points shall be supported.
    `PrefixTreeStrategy.ShapeTokenStream` | `tokenStream()`

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

      `getFieldName, getSpatialContext, makeDistanceValueSource, makeQuery, makeRecipDistanceValueSource, toString`

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

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

- - ### Field Detail

    - #### grid

          protected final SpatialPrefixTree grid

    - #### defaultFieldValuesArrayLen

          protected int defaultFieldValuesArrayLen

    - #### distErrPct

          protected double distErrPct

    - #### pointsOnly

          protected boolean pointsOnly

    - #### FIELD_TYPE

          public static final FieldType FIELD_TYPE

  - ### Constructor Detail

    - #### PrefixTreeStrategy

          public PrefixTreeStrategy(SpatialPrefixTree grid,
                                    String fieldName)

  - ### Method Detail

    - #### getGrid

          public SpatialPrefixTree getGrid()

    - #### setDefaultFieldValuesArrayLen

          public void setDefaultFieldValuesArrayLen(int defaultFieldValuesArrayLen)

      A memory hint used by `SpatialStrategy.makeDistanceValueSource(org.locationtech.spatial4j.shape.Point)` for how big the initial size of each Document's array should be. The default is 2. Set this to slightly more than the default expected number of points per document.

    - #### getDistErrPct

          public double getDistErrPct()

    - #### setDistErrPct

          public void setDistErrPct(double distErrPct)

      The default measure of shape precision affecting shapes at index and query times. Points don't use this as they are always indexed at the configured maximum precision (`SpatialPrefixTree.getMaxLevels()`); this applies to all other shapes. Specific shapes at index and query time can use something different than this default value. If you don't set a default then the default is `SpatialArgs.DEFAULT_DISTERRPCT` -- 2.5%.
      See Also:
        `SpatialArgs.getDistErrPct()`

    - #### isPointsOnly

          public boolean isPointsOnly()

    - #### setPointsOnly

          public void setPointsOnly(boolean pointsOnly)

      True if only indexed points shall be supported. There are no "leafs" in such a case, except those at maximum precision.

    - #### 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.Shape shape,
                                               double distErr)

      Turns `SpatialPrefixTree.getTreeCellIterator(Shape, int)` into a `TokenStream`.

    - #### createIndexableFields

          public Field[] createIndexableFields(org.locationtech.spatial4j.shape.Shape shape,
                                               int detailLevel)

    - #### tokenStream

          public PrefixTreeStrategy.ShapeTokenStream tokenStream()

    - #### newCellToBytesRefIterator

          protected CellToBytesRefIterator newCellToBytesRefIterator()

    - #### createCellIteratorToIndex

          protected Iterator<Cell> createCellIteratorToIndex(org.locationtech.spatial4j.shape.Shape shape,
                                                             int detailLevel,
                                                             Iterator<Cell> reuse)

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

    - #### calcFacets

          public HeatmapFacetCounter.Heatmap calcFacets(IndexReaderContext context,
                                                        Bits topAcceptDocs,
                                                        org.locationtech.spatial4j.shape.Shape inputShape,
                                                        int facetLevel,
                                                        int maxCells)
                                                 throws IOException

      Computes spatial facets in two dimensions as a grid of numbers. The data is often visualized as a so-called "heatmap".
      Throws:
        `IOException`
      See Also:
        `HeatmapFacetCounter.calcFacets(PrefixTreeStrategy, IndexReaderContext, Bits, Shape, int, int)`

    - #### isPointShape

          protected boolean isPointShape(org.locationtech.spatial4j.shape.Shape shape)

      Returns true if the `shape` is a `Point`. For custom spatial contexts, it may make sense to have certain other shapes return true.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

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