org.apache.lucene.document

## Class LongPoint

- java.lang.Object
- - org.apache.lucene.document.Field
  - - org.apache.lucene.document.LongPoint

- All Implemented Interfaces:
    IndexableField

      public final class LongPoint
      extends Field

  An indexed `long` field for fast range filters. If you also need to store the value, you should add a separate `StoredField` instance.

  Finding all documents within an N-dimensional shape or range 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, long)` for matching an exact 1D point.
  - `newSetQuery(String, long...)` for matching a set of 1D values.
  - `newRangeQuery(String, long, long)` for matching a 1D range.
  - `newRangeQuery(String, long[], long[])` 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 inherited from class org.apache.lucene.document.Field

      `fieldsData, name, tokenStream, type`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LongPoint(String name, long... point)` Creates a new LongPoint, indexing the provided N-dimensional long point.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static long` | `decodeDimension(byte[] value, int offset)` Decode single long dimension
    `static void` | `encodeDimension(long value, byte[] dest, int offset)` Encode single long dimension
    `static Query` | `newDistanceFeatureQuery(String field, float weight, long origin, long pivotDistance)` Given a field that indexes the same long values into a `LongPoint` and doc values (either `NumericDocValuesField` or `SortedNumericDocValuesField`), this returns a query that scores documents based on their distance to `origin`: `score = weight * pivotDistance / (pivotDistance + distance)`, ie.
    `static Query` | `newExactQuery(String field, long value)` Create a query for matching an exact long value.
    `static Query` | `newRangeQuery(String field, long[] lowerValue, long[] upperValue)` Create a range query for n-dimensional long values.
    `static Query` | `newRangeQuery(String field, long lowerValue, long upperValue)` Create a range query for long values.
    `static Query` | `newSetQuery(String field, Collection<Long> values)` Create a query matching any of the specified 1D values.
    `static Query` | `newSetQuery(String field, long... values)` Create a query matching any of the specified 1D values.
    `Number` | `numericValue()` Non-null if this field has a numeric value
    `static BytesRef` | `pack(long... point)` Pack a long point into a BytesRef
    `void` | `setBytesValue(BytesRef bytes)` Expert: change the value of this field.
    `void` | `setLongValue(long value)` Expert: change the value of this field.
    `void` | `setLongValues(long... point)` Change the values of this field
    `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, setFloatValue, setIntValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue`

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

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

- - ### Constructor Detail

    - #### LongPoint

          public LongPoint(String name,
                           long... point)

      Creates a new LongPoint, indexing the provided N-dimensional long point.
      Parameters:
        `name` - field name
        `point` - long[] value
      Throws:
        `IllegalArgumentException` - if the field name or value is null.

  - ### Method Detail

    - #### setLongValue

          public void setLongValue(long value)

      Description copied from class: `Field`
      Expert: change the value of this field. See `Field.setStringValue(String)`.
      Overrides:
        `setLongValue` in class `Field`

    - #### setLongValues

          public void setLongValues(long... 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

          public static BytesRef pack(long... point)

      Pack a long point into a BytesRef
      Parameters:
        `point` - long[] value
      Throws:
        `IllegalArgumentException` - is the value is null or of zero length

    - #### 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(long value,
                                             byte[] dest,
                                             int offset)

      Encode single long dimension

    - #### decodeDimension

          public static long decodeDimension(byte[] value,
                                             int offset)

      Decode single long dimension

    - #### newExactQuery

          public static Query newExactQuery(String field,
                                            long value)

      Create a query for matching an exact long value.

      This is for simple one-dimension points, for multidimensional points use `newRangeQuery(String, long[], long[])` instead.

      Parameters:
        `field` - field name. must not be `null`.
        `value` - exact value
      Returns:
        a query matching documents with this exact value
      Throws:
        `IllegalArgumentException` - if `field` is null.

    - #### newRangeQuery

          public static Query newRangeQuery(String field,
                                            long lowerValue,
                                            long upperValue)

      Create a range query for long values.

      This is for simple one-dimension ranges, for multidimensional ranges use `newRangeQuery(String, long[], long[])` instead.

      You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting `lowerValue = Long.MIN_VALUE` or `upperValue = Long.MAX_VALUE`.

      Ranges are inclusive. For exclusive ranges, pass `Math.addExact(lowerValue, 1)` or `Math.addExact(upperValue, -1)`.

      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,
                                            long[] lowerValue,
                                            long[] upperValue)

      Create a range query for n-dimensional long values.

      You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting `lowerValue[i] = Long.MIN_VALUE` or `upperValue[i] = Long.MAX_VALUE`.

      Ranges are inclusive. For exclusive ranges, pass `Math.addExact(lowerValue[i], 1)` or `Math.addExact(upperValue[i], -1)`.

      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,
                                          long... 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

    - #### newSetQuery

          public static Query newSetQuery(String field,
                                          Collection<Long> 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

    - #### newDistanceFeatureQuery

          public static Query newDistanceFeatureQuery(String field,
                                                      float weight,
                                                      long origin,
                                                      long pivotDistance)

      Given a field that indexes the same long values into a `LongPoint` and doc values (either `NumericDocValuesField` or `SortedNumericDocValuesField`), this returns a query that scores documents based on their distance to `origin`: `score = weight * pivotDistance / (pivotDistance + distance)`, ie. score is in the `[0, weight]` range, is equal to `weight` when the document's value is equal to `origin` and is equal to `weight/2` when the document's value is distant of `pivotDistance` from `origin`. In case of multi-valued fields, only the closest point to `origin` will be considered. This query is typically useful to boost results based on recency by adding this query to a `BooleanClause.Occur.SHOULD` clause of a `BooleanQuery`.

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.