Package org.apache.lucene.sandbox.document

# 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 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
  Description
  `static final int`
  `BYTES`
  The number of bytes used to represent a half-float value.

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

  `fieldsData, name, type`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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, 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 than `v`.
  `static float`
  `nextUp(float v)`
  Return the first half float which is immediately greater than `v`.
  `Number`
  `numericValue()`
  `static BytesRef`
  `pack(float... point)`
  `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, invertableType, name, readerValue, setBytesValue, setByteValue, setDoubleValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### BYTES

    public static final int BYTES
    The number of bytes used to represent a half-float value.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### 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 Details

  - ### 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`

  - ### pack

    public static BytesRef pack(float... point)

  - ### 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