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

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.