Module org.apache.lucene.sandbox
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:

See Also:

  • Field Details

    • BYTES

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

  • 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.

    • 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. See Field.setStringValue(String).
      Overrides:
      setFloatValue in class Field

    • 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. See Field.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 class Field

    • numericValue

      public Number numericValue()
      Description copied from interface: IndexableField
      Non-null if this field has a numeric value
      Specified by:
      numericValue in interface IndexableField
      Overrides:
      numericValue in class Field

    • pack

      private static BytesRef pack(float... point)

    • toString

      public String toString()
      Description copied from class: Field
      Prints a Field for human consumption.
      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