## 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
`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
`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-2011 Apache Software Foundation. All Rights Reserved.