org.apache.lucene.spatial.bbox

Class BBoxStrategy

java.lang.Object

org.apache.lucene.spatial.SpatialStrategy

org.apache.lucene.spatial.bbox.BBoxStrategy

public class BBoxStrategy
extends SpatialStrategy

A SpatialStrategy for indexing and searching Rectangles by storing its coordinates in numeric fields. It supports all SpatialOperations and has a custom overlap relevancy. It is based on GeoPortal's SpatialClauseAdapter.

Characteristics:

• Only indexes Rectangles; just one per field value. Other shapes can be provided and the bounding box will be used.
• Can query only by a Rectangle. Providing other shapes is an error.
• Supports most SpatialOperations but not Overlaps.
• Uses the DocValues API for any sorting / relevancy.

Implementation:

This uses 4 double fields for minX, maxX, minY, maxY and a boolean to mark a dateline cross. Depending on the particular SpatialOperations, there are a variety of NumericRangeQuerys to be done. The makeOverlapRatioValueSource(com.spatial4j.core.shape.Rectangle, double) works by calculating the query bbox overlap percentage against the indexed shape overlap percentage. The indexed shape's coordinates are retrieved from AtomicReader.getNumericDocValues(java.lang.String).

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

Field Summary

Fields

Modifier and Type	Field and Description
protected String	field_bbox
protected String	field_maxX
protected String	field_maxY
protected String	field_minX
protected String	field_minY
protected String	field_xdl
protected FieldType	fieldType
static String	SUFFIX_MAXX
static String	SUFFIX_MAXY
static String	SUFFIX_MINX
static String	SUFFIX_MINY
static String	SUFFIX_XDL
protected FieldType	xdlFieldType

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

ctx

Constructor Summary

Constructors

Constructor and Description
BBoxStrategy(com.spatial4j.core.context.SpatialContext ctx, String fieldNamePrefix)

Method Summary

Methods

Modifier and Type	Method and Description
Field[]	createIndexableFields(com.spatial4j.core.shape.Rectangle bbox)
Field[]	createIndexableFields(com.spatial4j.core.shape.Shape shape) Returns the IndexableField(s) from the shape that are to be added to the Document.
FieldType	getFieldType()
ValueSource	makeDistanceValueSource(com.spatial4j.core.shape.Point queryPoint, double multiplier) Make a ValueSource returning the distance between the center of the indexed shape and queryPoint.
Filter	makeFilter(SpatialArgs args) Make a Filter based principally on SpatialOperation and Shape from the supplied args.
ValueSource	makeOverlapRatioValueSource(com.spatial4j.core.shape.Rectangle queryBox, double queryTargetProportion) Returns a similarity based on BBoxOverlapRatioValueSource.
ConstantScoreQuery	makeQuery(SpatialArgs args) Make a Query based principally on SpatialOperation and Shape from the supplied args.
ValueSource	makeShapeValueSource() Provides access to each rectangle per document as a ValueSource in which FunctionValues.objectVal(int) returns a Shape.
void	setFieldType(FieldType fieldType) Used to customize the indexing options of the 4 number fields, and to a lesser degree the XDL field too.

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 Detail

SUFFIX_MINX

public static final String SUFFIX_MINX

See Also:

Constant Field Values

SUFFIX_MAXX

public static final String SUFFIX_MAXX

See Also:

Constant Field Values

SUFFIX_MINY

public static final String SUFFIX_MINY

See Also:

Constant Field Values

SUFFIX_MAXY

public static final String SUFFIX_MAXY

See Also:

Constant Field Values

SUFFIX_XDL

public static final String SUFFIX_XDL

See Also:

Constant Field Values

field_bbox

protected final String field_bbox

field_minX

protected final String field_minX

field_minY

protected final String field_minY

field_maxX

protected final String field_maxX

field_maxY

protected final String field_maxY

field_xdl

protected final String field_xdl

fieldType

protected FieldType fieldType

xdlFieldType

protected FieldType xdlFieldType

Constructor Detail

BBoxStrategy

public BBoxStrategy(com.spatial4j.core.context.SpatialContext ctx,
            String fieldNamePrefix)

Method Detail

getFieldType

public FieldType getFieldType()

setFieldType

public void setFieldType(FieldType fieldType)

Used to customize the indexing options of the 4 number fields, and to a lesser degree the XDL field too. Search requires indexed=true, and relevancy requires docValues. If these features aren't needed then disable them. FieldType.freeze() is called on the argument.

createIndexableFields

public Field[] createIndexableFields(com.spatial4j.core.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(com.spatial4j.core.shape.Rectangle bbox)

makeShapeValueSource

public ValueSource makeShapeValueSource()

Provides access to each rectangle per document as a ValueSource in which FunctionValues.objectVal(int) returns a Shape.

makeDistanceValueSource

public ValueSource makeDistanceValueSource(com.spatial4j.core.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

makeOverlapRatioValueSource

public ValueSource makeOverlapRatioValueSource(com.spatial4j.core.shape.Rectangle queryBox,
                                      double queryTargetProportion)

Returns a similarity based on BBoxOverlapRatioValueSource. This is just a convenience method.

makeFilter

public Filter makeFilter(SpatialArgs args)

Description copied from class: SpatialStrategy

Make a Filter based principally on SpatialOperation and Shape from the supplied args.

If a subclasses implements SpatialStrategy.makeQuery(org.apache.lucene.spatial.query.SpatialArgs) then this method could be simply:

return new QueryWrapperFilter(makeQuery(args).getQuery());

Specified by:

makeFilter in class SpatialStrategy

makeQuery

public ConstantScoreQuery makeQuery(SpatialArgs args)

Description copied from class: SpatialStrategy

Make a Query based principally on SpatialOperation and Shape from the supplied args. The default implementation is

return new ConstantScoreQuery(makeFilter(args));

Overrides:

makeQuery in class SpatialStrategy