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 onSpatialPrefixTree
. The two subclasses areRecursivePrefixTreeStrategy
andTermQueryPrefixTreeStrategy
. 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 issetDistErrPct(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 theshape
that are to be added to theDocument
.Field[]
createIndexableFields(org.locationtech.spatial4j.shape.Shape shape, double distErr)
TurnsSpatialPrefixTree.getTreeCellIterator(Shape, int)
into aTokenStream
.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 theshape
is aPoint
.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 andqueryPoint
.protected CellToBytesRefIterator
newCellToBytesRefIterator()
void
setDefaultFieldValuesArrayLen(int defaultFieldValuesArrayLen)
A memory hint used bySpatialStrategy.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
-
-
-
-
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 bySpatialStrategy.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 isSpatialArgs.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 theshape
that are to be added to theDocument
. 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 classSpatialStrategy
- Returns:
- Not null nor will it have null elements.
-
createIndexableFields
public Field[] createIndexableFields(org.locationtech.spatial4j.shape.Shape shape, double distErr)
TurnsSpatialPrefixTree.getTreeCellIterator(Shape, int)
into aTokenStream
.
-
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 andqueryPoint
. If there are multiple indexed shapes then the closest one is chosen. The result is multiplied bymultiplier
, which conveniently is used to get the desired units.- Specified by:
makeDistanceValueSource
in classSpatialStrategy
-
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".
-
isPointShape
protected boolean isPointShape(org.locationtech.spatial4j.shape.Shape shape)
Returns true if theshape
is aPoint
. 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.
-
-