Module org.apache.lucene.core
Package org.apache.lucene.document

Class DoubleRange

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.document.DoubleRange
All Implemented Interfaces:
IndexableField
public class DoubleRange extends Field
An indexed Double Range field.

This field indexes dimensional ranges defined as min/max pairs. It supports up to a maximum of 4 dimensions (indexed as 8 numeric values). With 1 dimension representing a single double range, 2 dimensions representing a bounding box, 3 dimensions a bounding cube, and 4 dimensions a tesseract.

Multiple values for the same field in one document is supported, and open ended ranges can be defined using Double.NEGATIVE_INFINITY and Double.POSITIVE_INFINITY.

This field defines the following static factory methods for common search operations over double ranges:

  • Field Details

    • BYTES

      public static final int BYTES
      stores double values so number of bytes is 8
      See Also:

  • Constructor Details

    • DoubleRange

      public DoubleRange(String name, double[] min, double[] max)
      Create a new DoubleRange type, from min/max parallel arrays
      Parameters:
      name - field name. must not be null.
      min - range min values; each entry is the min value for the dimension
      max - range max values; each entry is the max value for the dimension

  • Method Details

    • getType

      private static FieldType getType(int dimensions)
      set the field type

    • setRangeValues

      public void setRangeValues(double[] min, double[] max)
      Changes the values of the field.
      Parameters:
      min - array of min values. (accepts Double.NEGATIVE_INFINITY)
      max - array of max values. (accepts Double.POSITIVE_INFINITY)
      Throws:
      IllegalArgumentException - if min or max is invalid

    • checkArgs

      private static void checkArgs(double[] min, double[] max)
      validate the arguments

    • encode

      static byte[] encode(double[] min, double[] max)
      Encodes the min, max ranges into a byte array

    • verifyAndEncode

      public static void verifyAndEncode(double[] min, double[] max, byte[] bytes)
      encode the ranges into a sortable byte array (Double.NaN not allowed)

      example for 4 dimensions (8 bytes per dimension value): minD1 ... minD4 | maxD1 ... maxD4

    • encode

      private static void encode(double val, byte[] bytes, int offset)
      encode the given value into the byte array at the defined offset

    • getMin

      public double getMin(int dimension)
      Get the min value for the given dimension
      Parameters:
      dimension - the dimension, always positive
      Returns:
      the decoded min value

    • getMax

      public double getMax(int dimension)
      Get the max value for the given dimension
      Parameters:
      dimension - the dimension, always positive
      Returns:
      the decoded max value

    • decodeMin

      static double decodeMin(byte[] b, int dimension)
      decodes the min value (for the defined dimension) from the encoded input byte array

    • decodeMax

      static double decodeMax(byte[] b, int dimension)
      decodes the max value (for the defined dimension) from the encoded input byte array

    • newIntersectsQuery

      public static Query newIntersectsQuery(String field, double[] min, double[] max)
      Create a query for matching indexed ranges that intersect the defined range.
      Parameters:
      field - field name. must not be null.
      min - array of min values. (accepts Double.NEGATIVE_INFINITY)
      max - array of max values. (accepts Double.POSITIVE_INFINITY)
      Returns:
      query for matching intersecting ranges (overlap, within, or contains)
      Throws:
      IllegalArgumentException - if field is null, min or max is invalid

    • newContainsQuery

      public static Query newContainsQuery(String field, double[] min, double[] max)
      Create a query for matching indexed ranges that contain the defined range.
      Parameters:
      field - field name. must not be null.
      min - array of min values. (accepts Double.MIN_VALUE)
      max - array of max values. (accepts Double.MAX_VALUE)
      Returns:
      query for matching ranges that contain the defined range
      Throws:
      IllegalArgumentException - if field is null, min or max is invalid

    • newWithinQuery

      public static Query newWithinQuery(String field, double[] min, double[] max)
      Create a query for matching indexed ranges that are within the defined range.
      Parameters:
      field - field name. must not be null.
      min - array of min values. (accepts Double.MIN_VALUE)
      max - array of max values. (accepts Double.MAX_VALUE)
      Returns:
      query for matching ranges within the defined range
      Throws:
      IllegalArgumentException - if field is null, min or max is invalid

    • newCrossesQuery

      public static Query newCrossesQuery(String field, double[] min, double[] max)
      Create a query for matching indexed ranges that cross the defined range. A CROSSES is defined as any set of ranges that are not disjoint and not wholly contained by the query. Effectively, its the complement of union(WITHIN, DISJOINT).
      Parameters:
      field - field name. must not be null.
      min - array of min values. (accepts Double.MIN_VALUE)
      max - array of max values. (accepts Double.MAX_VALUE)
      Returns:
      query for matching ranges within the defined range
      Throws:
      IllegalArgumentException - if field is null, min or max is invalid

    • newRelationQuery

      private static Query newRelationQuery(String field, double[] min, double[] max, RangeFieldQuery.QueryType relation)
      helper method for creating the desired relational query

    • toString

      public String toString()
      Description copied from class: Field
      Prints a Field for human consumption.
      Overrides:
      toString in class Field

    • toString

      private static String toString(byte[] ranges, int dimension)
      Returns the String representation for the range at the given dimension
      Parameters:
      ranges - the encoded ranges, never null
      dimension - the dimension of interest
      Returns:
      The string representation for the range at the provided dimension