org.apache.lucene.document

Class HalfFloatPoint

java.lang.Object

org.apache.lucene.document.Field

org.apache.lucene.document.HalfFloatPoint

All Implemented Interfaces:

IndexableField

public final class HalfFloatPoint
extends Field

An indexed half-float field for fast range filters. If you also need to store the value, you should add a separate StoredField instance. If you need doc values, you can store them in a NumericDocValuesField and use halfFloatToSortableShort(float) and sortableShortToHalfFloat(short) for encoding/decoding.

The API takes floats, but they will be encoded to half-floats before being indexed. In case the provided floats cannot be represented accurately as a half float, they will be rounded to the closest value that can be represented as a half float. In case of tie, values will be rounded to the value that has a zero as its least significant bit.

Finding all documents within an N-dimensional at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for creating common queries:

• newExactQuery(String, float) for matching an exact 1D point.
• newSetQuery(String, float...) for matching a set of 1D values.
• newRangeQuery(String, float, float) for matching a 1D range.
• newRangeQuery(String, float[], float[]) for matching points/ranges in n-dimensional space.

See Also:

PointValues

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.lucene.document.Field

Field.Store

Field Summary

Fields

Modifier and Type	Field and Description
static int	BYTES The number of bytes used to represent a half-float value.

Fields inherited from class org.apache.lucene.document.Field

fieldsData, name, tokenStream, type

Constructor Summary

Constructors

Constructor and Description
HalfFloatPoint(String name, float... point) Creates a new FloatPoint, indexing the provided N-dimensional float point.

Method Summary

Modifier and Type	Method and Description
static float	decodeDimension(byte[] value, int offset) Decode single float dimension
static void	encodeDimension(float value, byte[] dest, int offset) Encode single float dimension
static short	halfFloatToSortableShort(float v) Convert a half-float to a short value that maintains ordering.
static Query	newExactQuery(String field, float value) Create a query for matching an exact half-float value.
static Query	newRangeQuery(String field, float[] lowerValue, float[] upperValue) Create a range query for n-dimensional half-float values.
static Query	newRangeQuery(String field, float lowerValue, float upperValue) Create a range query for half-float values.
static Query	newSetQuery(String field, Collection<Float> values) Create a query matching any of the specified 1D values.
static Query	newSetQuery(String field, float... values) Create a query matching any of the specified 1D values.
static float	nextDown(float v) Return the first half float which is immediately smaller than v.
static float	nextUp(float v) Return the first half float which is immediately greater than v.
Number	numericValue()
void	setBytesValue(BytesRef bytes)
void	setFloatValue(float value)
void	setFloatValues(float... point) Change the values of this field
static float	sortableShortToHalfFloat(short bits) Convert short bits to a half-float value that maintains ordering.
String	toString()

Methods inherited from class org.apache.lucene.document.Field

binaryValue, fieldType, getCharSequenceValue, name, readerValue, setBytesValue, setByteValue, setDoubleValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BYTES

public static final int BYTES

The number of bytes used to represent a half-float value.

See Also:

Constant Field Values

Constructor Detail

HalfFloatPoint

public HalfFloatPoint(String name,
                      float... point)

Creates a new FloatPoint, indexing the provided N-dimensional float point.

Parameters:

name - field name

point - float[] value

Throws:

IllegalArgumentException - if the field name or value is null.

Method Detail

nextUp

public static float nextUp(float v)

Return the first half float which is immediately greater than v. If the argument is Float.NaN then the return value is Float.NaN. If the argument is Float.POSITIVE_INFINITY then the return value is Float.POSITIVE_INFINITY.

nextDown

public static float nextDown(float v)

Return the first half float which is immediately smaller than v. If the argument is Float.NaN then the return value is Float.NaN. If the argument is Float.NEGATIVE_INFINITY then the return value is Float.NEGATIVE_INFINITY.

halfFloatToSortableShort

public static short halfFloatToSortableShort(float v)

Convert a half-float to a short value that maintains ordering.

sortableShortToHalfFloat

public static float sortableShortToHalfFloat(short bits)

Convert short bits to a half-float value that maintains ordering.

setFloatValue

public void setFloatValue(float value)

Overrides:

setFloatValue in class Field

setFloatValues

public void setFloatValues(float... point)

Change the values of this field

setBytesValue

public void setBytesValue(BytesRef bytes)

Overrides:

setBytesValue in class Field

numericValue

public Number numericValue()

Specified by:

numericValue in interface IndexableField

Overrides:

numericValue in class Field

toString

public String toString()

Overrides:

toString in class Field

encodeDimension

public static void encodeDimension(float value,
                                   byte[] dest,
                                   int offset)

Encode single float dimension

decodeDimension

public static float decodeDimension(byte[] value,
                                    int offset)

Decode single float dimension

newExactQuery

public static Query newExactQuery(String field,
                                  float value)

Create a query for matching an exact half-float value. It will be rounded to the closest half-float if value cannot be represented accurately as a half-float.

This is for simple one-dimension points, for multidimensional points use newRangeQuery(String, float[], float[]) instead.

Parameters:

field - field name. must not be null.

value - half-float value

Returns:

a query matching documents with this exact value

Throws:

IllegalArgumentException - if field is null.

newRangeQuery

public static Query newRangeQuery(String field,
                                  float lowerValue,
                                  float upperValue)

Create a range query for half-float values. Bounds will be rounded to the closest half-float if they cannot be represented accurately as a half-float.

This is for simple one-dimension ranges, for multidimensional ranges use newRangeQuery(String, float[], float[]) instead.

You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting lowerValue = Float.NEGATIVE_INFINITY or upperValue = Float.POSITIVE_INFINITY.

Ranges are inclusive. For exclusive ranges, pass nextUp(lowerValue) or nextDown(upperValue).

Range comparisons are consistent with Float.compareTo(Float).

Parameters:

field - field name. must not be null.

lowerValue - lower portion of the range (inclusive).

upperValue - upper portion of the range (inclusive).

Returns:

a query matching documents within this range.

Throws:

IllegalArgumentException - if field is null.

newRangeQuery

public static Query newRangeQuery(String field,
                                  float[] lowerValue,
                                  float[] upperValue)

Create a range query for n-dimensional half-float values. Bounds will be rounded to the closest half-float if they cannot be represented accurately as a half-float.

You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting lowerValue[i] = Float.NEGATIVE_INFINITY or upperValue[i] = Float.POSITIVE_INFINITY.

Ranges are inclusive. For exclusive ranges, pass nextUp(lowerValue[i]) or nextDown(upperValue[i]).

Range comparisons are consistent with Float.compareTo(Float).

Parameters:

field - field name. must not be null.

lowerValue - lower portion of the range (inclusive). must not be null.

upperValue - upper portion of the range (inclusive). must not be null.

Returns:

a query matching documents within this range.

Throws:

IllegalArgumentException - if field is null, if lowerValue is null, if upperValue is null, or if lowerValue.length != upperValue.length

newSetQuery

public static Query newSetQuery(String field,
                                float... values)

Create a query matching any of the specified 1D values. This is the points equivalent of TermsQuery. Values will be rounded to the closest half-float if they cannot be represented accurately as a half-float.

Parameters:

field - field name. must not be null.

values - all values to match

newSetQuery

public static Query newSetQuery(String field,
                                Collection<Float> values)

Create a query matching any of the specified 1D values. This is the points equivalent of TermsQuery.

Parameters:

field - field name. must not be null.

values - all values to match