SortedNumericDocValuesField (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.document, class: SortedNumericDocValuesField

Package org.apache.lucene.document

# Class SortedNumericDocValuesField

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.document.SortedNumericDocValuesField

All Implemented Interfaces:
  `IndexableField`

public class SortedNumericDocValuesField extends Field
Field that stores a per-document `long` values for scoring, sorting or value retrieval. Here's an example usage:

       document.add(new SortedNumericDocValuesField(name, 5L));
       document.add(new SortedNumericDocValuesField(name, 14L));

Note that if you want to encode doubles or floats with proper sort order, you will need to encode them with `NumericUtils`:

       document.add(new SortedNumericDocValuesField(name, NumericUtils.floatToSortableInt(-5.3f)));

If you also need to store the value, you should add a separate `StoredField` instance.

- ## 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 FieldType`
  `TYPE`
  Type for sorted numeric DocValues.

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

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SortedNumericDocValuesField(String name, long value)`
  Creates a new DocValues field with the specified 64-bit long value

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static SortedNumericDocValuesField`
  `indexedField(String name, long value)`
  Creates a new `SortedNumericDocValuesField` with the specified 64-bit long value that also creates a `skip index`.
  `static Query`
  `newSlowExactQuery(String field, long value)`
  Create a query for matching an exact long value.
  `static Query`
  `newSlowRangeQuery(String field, long lowerValue, long upperValue)`
  Create a range query that matches all documents whose value is between `lowerValue` and `upperValue` included.
  `static Query`
  `newSlowSetQuery(String field, long... values)`
  Create a query matching any of the specified values.

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

  `binaryValue, fieldType, getCharSequenceValue, invertableType, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue, toString`

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

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

- ## Field Details

  - ### TYPE

    public static final FieldType TYPE
    Type for sorted numeric DocValues.

- ## Constructor Details

  - ### SortedNumericDocValuesField

    public SortedNumericDocValuesField(String name, long value)
    Creates a new DocValues field with the specified 64-bit long value
    Parameters:
      `name` - field name
      `value` - 64-bit long value
    Throws:
      `IllegalArgumentException` - if the field name is null

- ## Method Details

  - ### indexedField

    public static SortedNumericDocValuesField indexedField(String name, long value)
    Creates a new `SortedNumericDocValuesField` with the specified 64-bit long value that also creates a `skip index`.
    Parameters:
      `name` - field name
      `value` - 64-bit long value
    Throws:
      `IllegalArgumentException` - if the field name is null

  - ### newSlowRangeQuery

    public static Query newSlowRangeQuery(String field, long lowerValue, long upperValue)
    Create a range query that matches all documents whose value is between `lowerValue` and `upperValue` included.

    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)`.

    This query also works with fields that have indexed `NumericDocValuesField`s.

    NOTE: Such queries cannot efficiently advance to the next match, which makes them slow if they are not ANDed with a selective query. As a consequence, they are best used wrapped in an `IndexOrDocValuesQuery`, alongside a range query that executes on points, such as `LongPoint.newRangeQuery(java.lang.String, long, long)`.

    See Also:
      - `IntField.newRangeQuery(java.lang.String, int, int)`
      - `LongField.newRangeQuery(java.lang.String, long, long)`
      - `FloatField.newRangeQuery(java.lang.String, float, float)`
      - `DoubleField.newRangeQuery(java.lang.String, double, double)`

  - ### newSlowSetQuery

    public static Query newSlowSetQuery(String field, long... values)
    Create a query matching any of the specified values.

    NOTE: Such queries cannot efficiently advance to the next match, which makes them slow if they are not ANDed with a selective query. As a consequence, they are best used wrapped in an `IndexOrDocValuesQuery`, alongside a set query that executes on points, such as `LongPoint.newSetQuery(java.lang.String, long...)`.

    See Also:
      - `IntField.newSetQuery(java.lang.String, int...)`
      - `LongField.newSetQuery(java.lang.String, long...)`
      - `FloatField.newSetQuery(java.lang.String, float...)`
      - `DoubleField.newSetQuery(java.lang.String, double...)`

  - ### newSlowExactQuery

    public static Query newSlowExactQuery(String field, long value)
    Create a query for matching an exact long value.

    This query also works with fields that have indexed `NumericDocValuesField`s.

    NOTE: Such queries cannot efficiently advance to the next match, which makes them slow if they are not ANDed with a selective query. As a consequence, they are best used wrapped in an `IndexOrDocValuesQuery`, alongside a range query that executes on points, such as `LongPoint.newExactQuery(java.lang.String, long)`.

    See Also:
      - `IntField.newExactQuery(java.lang.String, int)`
      - `LongField.newExactQuery(java.lang.String, long)`
      - `FloatField.newExactQuery(java.lang.String, float)`
      - `DoubleField.newExactQuery(java.lang.String, double)`