Package com.yahoo.prelude.query

Class MultiRangeItem<Type extends Number>

java.lang.Object

com.yahoo.prelude.query.Item

com.yahoo.prelude.query.SimpleTaggableItem

com.yahoo.prelude.query.MultiRangeItem<Type>

All Implemented Interfaces:

TaggableItem, Cloneable

public class MultiRangeItem<Type extends Number>
extends SimpleTaggableItem

A term which contains a set of numerical ranges; a match with any of these indicates a match.

This is a stricter version of an OrItem containing multiple RangeItems, where all ranges must be specified against the same field, or pair of fields, and where all the left boundaries, and all the right boundaries, share whether they are MultiRangeItem.Limit.INCLUSIVE or MultiRangeItem.Limit.EXCLUSIVE. Furthermore, all overlapping ranges are joined, such that the set of ranges this represents is guaranteed to be non-overlapping, and thus, sorted order of start and end boundaries is the same, which allows efficient filtering of document points or ranges by whether they are included in any of the ranges contained in this term. Note that touching ranges, like [3, 5) and [5, 7), will be joined unless this item is declared to have exclusive boundaries at both ends, or if one of the items is contained within the other, e.g., (3, 5) and (5, 5) (see below for explanation of weirdness).

In the absence of a range type in the schema definition, all ranges (and points) contained in documents are taken to be inclusive at both ends. However, intersection of range starts from documents and range ends from the query is inclusive, i.e., matching on equality, iff. both boundaries are inclusive, and likewise for intersection between range starts from query and range ends from documents. It is therefore possible to achieve any matching by choosing inclusiveness for the query ranges appropriately. For the case where document ranges are to be treated as exclusive, and the query has single points, this becomes weird, since the ranges [1, 1), (1, 1] and (1, 1) are all logically empty, but this still works :)

Unless ranges are added in ascending start order, the implementation lazily sorts and merges ranges, when a representation of the item is required. This is typically when the query is serialized and sent to the backend, or when trace information is written, or Item.toString() is called on the item. Adding ranges in ascending order is much faster than not; ascending order here has the rather lax requirement that each added interval is not completely before the current last interval.

Author:

jonmv

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	MultiRangeItem.Limit
static class	MultiRangeItem.NumberType<Type extends Number>	Type of numbers stored used to describe the ranges stored in a MultiRangeItem.

Nested classes/interfaces inherited from class com.yahoo.prelude.query.Item

Item.ItemCreator, Item.ItemType

Field Summary

Fields inherited from class com.yahoo.prelude.query.Item

connectedBacklink, connectedItem, connectivity, DEFAULT_WEIGHT, explicitSignificance, significance, uniqueID

Method Summary

Modifier and Type	Method	Description
MultiRangeItem<Type>	addPoint(Type point)	Adds the given point to this item.
MultiRangeItem<Type>	addRange(Type start, Type end)	Adds the given range to this item.
protected void	appendBodyString(StringBuilder buffer)	Override to append the item body in the canonical query language of this item.
Item	clone()	Returns a deep copy of this item
void	disclose(Discloser discloser)
final int	encode(ByteBuffer buffer)
boolean	equals(Object o)	Returns whether this item is of the same class and contains the same state as the given item.
final Item.ItemType	getItemType()	Return the enumerated type of this item.
final String	getName()	Returns the name of this item
final int	getTermCount()
int	hashCode()
static <Type extends Number> MultiRangeItem<Type>	overPoints(MultiRangeItem.NumberType<Type> type, String index, MultiRangeItem.Limit startInclusive, MultiRangeItem.Limit endInclusive)	A multi range item to contain the points defined by the single given index name.
static <Type extends Number> MultiRangeItem<Type>	overRanges(MultiRangeItem.NumberType<Type> type, String startIndex, MultiRangeItem.Limit startInclusive, String endIndex, MultiRangeItem.Limit endInclusive)	A multi range item to intersect with the ranges defined by the two given index names.
void	setIndexName(String index)	Sets the index name of this item

Methods inherited from class com.yahoo.prelude.query.SimpleTaggableItem

getConnectedItem, getConnectivity, getSignificance, getUniqueID, hasExplicitSignificance, hasUniqueID, setConnectivity, setExplicitSignificance, setSignificance, setUniqueID

Methods inherited from class com.yahoo.prelude.query.Item

addAnnotation, appendHeadingString, encodeThis, getAnnotation, getBytes, getCode, getCreator, getLabel, getLanguage, getParent, getWeight, hasAnnotation, hasConnectivityBackLink, isFilter, isFromSpecialToken, isProtected, isRanked, isRoot, putBytes, putString, setCreator, setFilter, setFromSpecialToken, setHasUniqueID, setLabel, setLanguage, setParent, setPositionData, setProtected, setRanked, setWeight, shouldParenthesize, toString, usePositionData

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

overRanges

public static <Type extends Number>
MultiRangeItem<Type> overRanges(MultiRangeItem.NumberType<Type> type,
 String startIndex,
 MultiRangeItem.Limit startInclusive,
 String endIndex,
 MultiRangeItem.Limit endInclusive)

A multi range item to intersect with the ranges defined by the two given index names.

overPoints

public static <Type extends Number>
MultiRangeItem<Type> overPoints(MultiRangeItem.NumberType<Type> type,
 String index,
 MultiRangeItem.Limit startInclusive,
 MultiRangeItem.Limit endInclusive)

A multi range item to contain the points defined by the single given index name.

addPoint

public MultiRangeItem<Type> addPoint(Type point)

Adds the given point to this item. More efficient when each added point is not completely before the current last one.

addRange

public MultiRangeItem<Type> addRange(Type start,
 Type end)

Adds the given range to this item. More efficient when each added range is not completely before the current last one.

setIndexName

public void setIndexName(String index)

Description copied from class: Item

Sets the index name of this item

Specified by:

setIndexName in class Item

appendBodyString

protected void appendBodyString(StringBuilder buffer)

Description copied from class: Item

Override to append the item body in the canonical query language of this item. An item is usually represented by the string

 ([itemName] [body])
 

The body must be appended appended by this method.

Specified by:

appendBodyString in class Item

disclose

public void disclose(Discloser discloser)

Overrides:

disclose in class Item

clone

public Item clone()

Description copied from class: Item

Returns a deep copy of this item

Overrides:

clone in class Item

equals

public boolean equals(Object o)

Description copied from class: Item

Returns whether this item is of the same class and contains the same state as the given item.

Overrides:

equals in class Item

hashCode

public int hashCode()

Overrides:

hashCode in class Item

getItemType

public final Item.ItemType getItemType()

Description copied from class: Item

Return the enumerated type of this item.

Specified by:

getItemType in class Item

getName

public final String getName()

Description copied from class: Item

Returns the name of this item

Specified by:

getName in class Item

encode

public final int encode(ByteBuffer buffer)

Specified by:

encode in class Item

getTermCount

public final int getTermCount()

Specified by:

getTermCount in class Item