Class HalfFloatPoint
- java.lang.Object
-
- org.apache.lucene.document.Field
-
- org.apache.lucene.sandbox.document.HalfFloatPoint
-
- All Implemented Interfaces:
IndexableField
public final class HalfFloatPoint extends Field
An indexedhalf-float
field for fast range filters. If you also need to store the value, you should add a separateStoredField
instance. If you need doc values, you can store them in aNumericDocValuesField
and usehalfFloatToSortableShort(float)
andsortableShortToHalfFloat(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 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 Description HalfFloatPoint(java.lang.String name, float... point)
Creates a new FloatPoint, indexing the provided N-dimensional float point.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static float
decodeDimension(byte[] value, int offset)
Decode single float dimensionstatic void
encodeDimension(float value, byte[] dest, int offset)
Encode single float dimensionprivate static FieldType
getType(int numDims)
(package private) static short
halfFloatToShortBits(float v)
static short
halfFloatToSortableShort(float v)
Convert a half-float to a short value that maintains ordering.static Query
newExactQuery(java.lang.String field, float value)
Create a query for matching an exact half-float value.static Query
newRangeQuery(java.lang.String field, float[] lowerValue, float[] upperValue)
Create a range query for n-dimensional half-float values.static Query
newRangeQuery(java.lang.String field, float lowerValue, float upperValue)
Create a range query for half-float values.static Query
newSetQuery(java.lang.String field, float... values)
Create a query matching any of the specified 1D values.static Query
newSetQuery(java.lang.String field, java.util.Collection<java.lang.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
.java.lang.Number
numericValue()
Non-null if this field has a numeric valueprivate static BytesRef
pack(float... point)
(package private) static int
roundShift(int i, int shift)
void
setBytesValue(BytesRef bytes)
Expert: change the value of this field.void
setFloatValue(float value)
Expert: change the value of this field.void
setFloatValues(float... point)
Change the values of this field(package private) static float
shortBitsToHalfFloat(short s)
(package private) static void
shortToSortableBytes(short value, byte[] result, int offset)
(package private) static short
sortableBytesToShort(byte[] encoded, int offset)
private static short
sortableShortBits(short s)
static float
sortableShortToHalfFloat(short bits)
Convert short bits to a half-float value that maintains ordering.java.lang.String
toString()
Prints a Field for human consumption.-
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 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(java.lang.String name, float... point)
Creates a new FloatPoint, indexing the provided N-dimensional float point.- Parameters:
name
- field namepoint
- float[] value- Throws:
java.lang.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 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.
-
sortableShortBits
private static short sortableShortBits(short s)
-
halfFloatToShortBits
static short halfFloatToShortBits(float v)
-
roundShift
static int roundShift(int i, int shift)
-
shortBitsToHalfFloat
static float shortBitsToHalfFloat(short s)
-
shortToSortableBytes
static void shortToSortableBytes(short value, byte[] result, int offset)
-
sortableBytesToShort
static short sortableBytesToShort(byte[] encoded, int offset)
-
getType
private static FieldType getType(int numDims)
-
setFloatValue
public void setFloatValue(float value)
Description copied from class:Field
Expert: change the value of this field. SeeField.setStringValue(String)
.- Overrides:
setFloatValue
in classField
-
setFloatValues
public void setFloatValues(float... point)
Change the values of this field
-
setBytesValue
public void setBytesValue(BytesRef bytes)
Description copied from class:Field
Expert: change the value of this field. SeeField.setStringValue(String)
.NOTE: the provided BytesRef is not copied so be sure not to change it until you're done with this field.
- Overrides:
setBytesValue
in classField
-
numericValue
public java.lang.Number numericValue()
Description copied from interface:IndexableField
Non-null if this field has a numeric value- Specified by:
numericValue
in interfaceIndexableField
- Overrides:
numericValue
in classField
-
pack
private static BytesRef pack(float... point)
-
toString
public java.lang.String toString()
Description copied from class:Field
Prints a Field for human consumption.
-
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(java.lang.String field, float value)
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:
java.lang.IllegalArgumentException
- iffield
is null.
-
newRangeQuery
public static Query newRangeQuery(java.lang.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
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:
java.lang.IllegalArgumentException
- iffield
is null.
-
newRangeQuery
public static Query newRangeQuery(java.lang.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
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:
java.lang.IllegalArgumentException
- iffield
is null, iflowerValue
is null, ifupperValue
is null, or iflowerValue.length != upperValue.length
-
newSetQuery
public static Query newSetQuery(java.lang.String field, float... values)
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
public static Query newSetQuery(java.lang.String field, java.util.Collection<java.lang.Float> values)
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
-
-