Class HalfFloatPoint
- All Implemented Interfaces:
IndexableField
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:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.lucene.document.Field
Field.Store
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
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
ConstructorDescriptionHalfFloatPoint
(String name, float... point) Creates a new FloatPoint, indexing the provided N-dimensional float point. -
Method Summary
Modifier and TypeMethodDescriptionstatic float
decodeDimension
(byte[] value, int offset) Decode single float dimensionstatic void
encodeDimension
(float value, byte[] dest, int offset) Encode single float dimensionstatic 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, float... values) Create a query matching any of the specified 1D values.static Query
newSetQuery
(String field, Collection<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 thanv
.static float
nextUp
(float v) Return the first half float which is immediately greater thanv
.void
setBytesValue
(BytesRef bytes) void
setFloatValue
(float value) void
setFloatValues
(float... point) Change the values of this fieldstatic float
sortableShortToHalfFloat
(short bits) Convert short bits to a half-float value that maintains ordering.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
-
Field Details
-
BYTES
public static final int BYTESThe number of bytes used to represent a half-float value.- See Also:
-
-
Constructor Details
-
HalfFloatPoint
Creates a new FloatPoint, indexing the provided N-dimensional float point.- Parameters:
name
- field namepoint
- float[] value- Throws:
IllegalArgumentException
- if the field name or value is null.
-
-
Method Details
-
nextUp
public static float nextUp(float v) Return the first half float which is immediately greater thanv
. If the argument isFloat.NaN
then the return value isFloat.NaN
. If the argument isFloat.POSITIVE_INFINITY
then the return value isFloat.POSITIVE_INFINITY
. -
nextDown
public static float nextDown(float v) Return the first half float which is immediately smaller thanv
. If the argument isFloat.NaN
then the return value isFloat.NaN
. If the argument isFloat.NEGATIVE_INFINITY
then the return value isFloat.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 classField
-
setFloatValues
public void setFloatValues(float... point) Change the values of this field -
setBytesValue
- Overrides:
setBytesValue
in classField
-
numericValue
- Specified by:
numericValue
in interfaceIndexableField
- Overrides:
numericValue
in classField
-
toString
-
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
Create a query for matching an exact half-float value. It will be rounded to the closest half-float ifvalue
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 benull
.value
- half-float value- Returns:
- a query matching documents with this exact value
- Throws:
IllegalArgumentException
- iffield
is null.
-
newRangeQuery
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
orupperValue = Float.POSITIVE_INFINITY
.Ranges are inclusive. For exclusive ranges, pass
nextUp(lowerValue)
ornextDown(upperValue)
.Range comparisons are consistent with
Float.compareTo(Float)
.- Parameters:
field
- field name. must not benull
.lowerValue
- lower portion of the range (inclusive).upperValue
- upper portion of the range (inclusive).- Returns:
- a query matching documents within this range.
- Throws:
IllegalArgumentException
- iffield
is null.
-
newRangeQuery
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
orupperValue[i] = Float.POSITIVE_INFINITY
.Ranges are inclusive. For exclusive ranges, pass
nextUp(lowerValue[i])
ornextDown(upperValue[i])
.Range comparisons are consistent with
Float.compareTo(Float)
.- Parameters:
field
- field name. must not benull
.lowerValue
- lower portion of the range (inclusive). must not benull
.upperValue
- upper portion of the range (inclusive). must not benull
.- Returns:
- a query matching documents within this range.
- Throws:
IllegalArgumentException
- iffield
is null, iflowerValue
is null, ifupperValue
is null, or iflowerValue.length != upperValue.length
-
newSetQuery
Create a query matching any of the specified 1D values. This is the points equivalent ofTermsQuery
. 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 benull
.values
- all values to match
-
newSetQuery
Create a query matching any of the specified 1D values. This is the points equivalent ofTermsQuery
.- Parameters:
field
- field name. must not benull
.values
- all values to match
-