Package 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 | Description
    --- | --- | ---
    `class` | `PrefixTreeStrategy.ShapeTokenStream` | Tokenstream for indexing cells of a shape

  - ### Field Summary

    Fields
    Modifier and Type | Field | 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 | Description
    --- | ---
    `PrefixTreeStrategy​(SpatialPrefixTree grid, String fieldName)` |

  - ### Method Summary

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