org.apache.lucene.document

## Class NumericField

- java.lang.Object
- - org.apache.lucene.document.AbstractField
  - - org.apache.lucene.document.NumericField

- All Implemented Interfaces:
    java.io.Serializable, Fieldable

      public final class NumericField
      extends AbstractField

  This class provides a `Field` that enables indexing of numeric values for efficient range filtering and sorting. Here's an example usage, adding an int value:

        document.add(new NumericField(name).setIntValue(value));

  For optimal performance, re-use the `NumericField` and `Document` instance for more than one document:

        NumericField field = new NumericField(name);
        Document document = new Document();
        document.add(field);

        for(all documents) {
          ...
          field.setIntValue(value)
          writer.addDocument(document);
          ...
        }

  The java native types `int`, `long`, `float` and `double` are directly supported. However, any value that can be converted into these native types can also be indexed. For example, date/time values represented by a `Date` can be translated into a long value using the `Date.getTime()` method. If you don't need millisecond precision, you can quantize the value, either by dividing the result of `Date.getTime()` or using the separate getters (for year, month, etc.) to construct an `int` or `long` value.

  To perform range querying or filtering against a `NumericField`, use `NumericRangeQuery` or `NumericRangeFilter`. To sort according to a `NumericField`, use the normal numeric sort types, eg `SortField.INT` (note that `SortField.AUTO` will not work with these fields). `NumericField` values can also be loaded directly from `FieldCache`.

  By default, a `NumericField`'s value is not stored but is indexed for range filtering and sorting. You can use the `NumericField(String,Field.Store,boolean)` constructor if you need to change these defaults.

  You may add the same field name as a `NumericField` to the same document more than once. Range querying and filtering will be the logical OR of all values; so a range query will hit all documents that have at least one value in the range. However sort behavior is not defined. If you need to sort, you should separately index a single-valued `NumericField`.

  A `NumericField` will consume somewhat more disk space in the index than an ordinary single-valued field. However, for a typical index that includes substantial textual content per document, this increase will likely be in the noise.

  Within Lucene, each numeric value is indexed as a trie structure, where each term is logically assigned to larger and larger pre-defined brackets (which are simply lower-precision representations of the value). The step size between each successive bracket is called the `precisionStep`, measured in bits. Smaller `precisionStep` values result in larger number of brackets, which consumes more disk space in the index but may result in faster range search performance. The default value, 4, was selected for a reasonable tradeoff of disk space consumption versus performance. You can use the expert constructor `NumericField(String,int,Field.Store,boolean)` if you'd like to change the value. Note that you must also specify a congruent value when creating `NumericRangeQuery` or `NumericRangeFilter`. For low cardinality fields larger precision steps are good. If the cardinality is < 100, it is fair to use `Integer.MAX_VALUE`, which produces one term per value.

  For more information on the internals of numeric trie indexing, including the `precisionStep` configuration, see `NumericRangeQuery`. The format of indexed values is described in `NumericUtils`.

  If you only need to sort by numeric value, and never run range querying/filtering, you can index using a `precisionStep` of `Integer.MAX_VALUE`. This will minimize disk space consumed.

  More advanced users can instead use `NumericTokenStream` directly, when indexing numbers. This class is a wrapper around this token stream type for easier, more intuitive usage.

  NOTE: This class is only used during indexing. When retrieving the stored field value from a `Document` instance after search, you will get a conventional `Fieldable` instance where the numeric values are returned as `String`s (according to `toString(value)` of the used data type).

  NOTE: This API is experimental and might change in incompatible ways in the next release.

  Since:
    2.9
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class org.apache.lucene.document.AbstractField

      `binaryLength, binaryOffset, boost, fieldsData, isBinary, isCompressed, isIndexed, isStored, isTokenized, lazy, name, omitNorms, omitTermFreqAndPositions, storeOffsetWithTermVector, storePositionWithTermVector, storeTermVector`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NumericField(java.lang.String name)` Creates a field for numeric values using the default `precisionStep` `NumericUtils.PRECISION_STEP_DEFAULT` (4).
    `NumericField(java.lang.String name, Field.Store store, boolean index)` Creates a field for numeric values using the default `precisionStep` `NumericUtils.PRECISION_STEP_DEFAULT` (4).
    `NumericField(java.lang.String name, int precisionStep)` Creates a field for numeric values with the specified `precisionStep`.
    `NumericField(java.lang.String name, int precisionStep, Field.Store store, boolean index)` Creates a field for numeric values with the specified `precisionStep`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `binaryValue()` Returns always `null` for numeric fields
    `byte[]` | `getBinaryValue(byte[] result)` Returns always `null` for numeric fields
    `java.lang.Number` | `getNumericValue()` Returns the current numeric value as a subclass of `Number`, `null` if not yet initialized.
    `java.io.Reader` | `readerValue()` Returns always `null` for numeric fields
    `NumericField` | `setDoubleValue(double value)` Initializes the field with the supplied `double` value.
    `NumericField` | `setFloatValue(float value)` Initializes the field with the supplied `float` value.
    `NumericField` | `setIntValue(int value)` Initializes the field with the supplied `int` value.
    `NumericField` | `setLongValue(long value)` Initializes the field with the supplied `long` value.
    `java.lang.String` | `stringValue()` Returns the numeric value as a string (how it is stored, when `Field.Store.YES` is chosen).
    `TokenStream` | `tokenStreamValue()` Returns a `NumericTokenStream` for indexing the numeric value.

    - ### Methods inherited from class org.apache.lucene.document.AbstractField

      `getBinaryLength, getBinaryOffset, getBinaryValue, getBoost, getOmitNorms, getOmitTermFreqAndPositions, getOmitTf, isBinary, isCompressed, isIndexed, isLazy, isStored, isStoreOffsetWithTermVector, isStorePositionWithTermVector, isTermVectorStored, isTokenized, name, setBoost, setOmitNorms, setOmitTermFreqAndPositions, setOmitTf, setStoreTermVector, toString`

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

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

- - ### Constructor Detail

    - #### NumericField

          public NumericField(java.lang.String name)

      Creates a field for numeric values using the default `precisionStep` `NumericUtils.PRECISION_STEP_DEFAULT` (4). The instance is not yet initialized with a numeric value, before indexing a document containing this field, set a value using the various set???Value() methods. This constructor creates an indexed, but not stored field.
      Parameters:
        `name` - the field name

    - #### NumericField

          public NumericField(java.lang.String name,
                              Field.Store store,
                              boolean index)

      Creates a field for numeric values using the default `precisionStep` `NumericUtils.PRECISION_STEP_DEFAULT` (4). The instance is not yet initialized with a numeric value, before indexing a document containing this field, set a value using the various set???Value() methods.
      Parameters:
        `name` - the field name
        `store` - if the field should be stored in plain text form (according to `toString(value)` of the used data type)
        `index` - if the field should be indexed using `NumericTokenStream`

    - #### NumericField

          public NumericField(java.lang.String name,
                              int precisionStep)

      Creates a field for numeric values with the specified `precisionStep`. The instance is not yet initialized with a numeric value, before indexing a document containing this field, set a value using the various set???Value() methods. This constructor creates an indexed, but not stored field.
      Parameters:
        `name` - the field name
        `precisionStep` - the used precision step

    - #### NumericField

          public NumericField(java.lang.String name,
                              int precisionStep,
                              Field.Store store,
                              boolean index)

      Creates a field for numeric values with the specified `precisionStep`. The instance is not yet initialized with a numeric value, before indexing a document containing this field, set a value using the various set???Value() methods.
      Parameters:
        `name` - the field name
        `precisionStep` - the used precision step
        `store` - if the field should be stored in plain text form (according to `toString(value)` of the used data type)
        `index` - if the field should be indexed using `NumericTokenStream`

  - ### Method Detail

    - #### tokenStreamValue

          public TokenStream tokenStreamValue()

      Returns a `NumericTokenStream` for indexing the numeric value.
      See Also:
        `Fieldable.stringValue()`

    - #### binaryValue

          public byte[] binaryValue()

      Returns always `null` for numeric fields
      See Also:
        `Fieldable.stringValue()`

    - #### getBinaryValue

          public byte[] getBinaryValue(byte[] result)

      Returns always `null` for numeric fields
      Specified by:
        `getBinaryValue` in interface `Fieldable`
      Overrides:
        `getBinaryValue` in class `AbstractField`
      Parameters:
        `result` - User defined buffer that will be used if possible. If this is null or not large enough, a new buffer is allocated
      Returns:
        reference to the Field value as byte[].

    - #### readerValue

          public java.io.Reader readerValue()

      Returns always `null` for numeric fields
      See Also:
        `Fieldable.stringValue()`

    - #### stringValue

          public java.lang.String stringValue()

      Returns the numeric value as a string (how it is stored, when `Field.Store.YES` is chosen).

    - #### getNumericValue

          public java.lang.Number getNumericValue()

      Returns the current numeric value as a subclass of `Number`, `null` if not yet initialized.

    - #### setLongValue

          public NumericField setLongValue(long value)

      Initializes the field with the supplied `long` value.
      Parameters:
        `value` - the numeric value
      Returns:
        this instance, because of this you can use it the following way: `document.add(new NumericField(name, precisionStep).setLongValue(value))`

    - #### setIntValue

          public NumericField setIntValue(int value)

      Initializes the field with the supplied `int` value.
      Parameters:
        `value` - the numeric value
      Returns:
        this instance, because of this you can use it the following way: `document.add(new NumericField(name, precisionStep).setIntValue(value))`

    - #### setDoubleValue

          public NumericField setDoubleValue(double value)

      Initializes the field with the supplied `double` value.
      Parameters:
        `value` - the numeric value
      Returns:
        this instance, because of this you can use it the following way: `document.add(new NumericField(name, precisionStep).setDoubleValue(value))`

    - #### setFloatValue

          public NumericField setFloatValue(float value)

      Initializes the field with the supplied `float` value.
      Parameters:
        `value` - the numeric value
      Returns:
        this instance, because of this you can use it the following way: `document.add(new NumericField(name, precisionStep).setFloatValue(value))`

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