NumericField (Lucene 3.6.2 API)
Keywords: org.apache.lucene.document.NumericField class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.lucene.document
Class NumericField

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

All Implemented Interfaces:
  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`. `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.

Since:
  2.9
See Also:
  Serialized Form

Nested Class Summary
`static class` | `NumericField.DataType` Data type of the value in `NumericField`.

Field Summary

Fields inherited from class org.apache.lucene.document.AbstractField
`binaryLength, binaryOffset, boost, fieldsData, indexOptions, isBinary, isIndexed, isStored, isTokenized, lazy, name, omitNorms, storeOffsetWithTermVector, storePositionWithTermVector, storeTermVector, tokenStream`

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

Method Summary
`byte[]` | `getBinaryValue(byte[] result)` Returns always `null` for numeric fields
`NumericField.DataType` | `getDataType()` Returns the data type of the current value, `null` if not yet set.
`Number` | `getNumericValue()` Returns the current numeric value as a subclass of `Number`, `null` if not yet initialized.
`int` | `getPrecisionStep()` Returns the precision step.
`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.
`String` | `stringValue()` Returns the numeric value as a string.
`TokenStream` | `tokenStreamValue()` Returns a `NumericTokenStream` for indexing the numeric value.

Methods inherited from class org.apache.lucene.document.AbstractField
`getBinaryLength, getBinaryOffset, getBinaryValue, getBoost, getIndexOptions, getOmitNorms, getOmitTermFreqAndPositions, isBinary, isIndexed, isLazy, isStored, isStoreOffsetWithTermVector, isStorePositionWithTermVector, isTermVectorStored, isTokenized, name, setBoost, setIndexOptions, setOmitNorms, setOmitTermFreqAndPositions, setStoreTermVector, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### NumericField

    public NumericField(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(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, `Document.getFieldable(java.lang.String)` then returns `NumericField` instances on search results.
    `index` - if the field should be indexed using `NumericTokenStream`

### NumericField

    public NumericField(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(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, `Document.getFieldable(java.lang.String)` then returns `NumericField` instances on search results.
    `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()`

### 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 Reader readerValue()

  Returns always `null` for numeric fields

  See Also:
    `Fieldable.stringValue()`

### stringValue

    public String stringValue()

  Returns the numeric value as a string. This format is also returned if you call `Document.get(String)` on search results. It is recommended to use `Document.getFieldable(java.lang.String)` instead that returns `NumericField` instances. You can then use `getNumericValue()` to return the stored value.

### getNumericValue

    public Number getNumericValue()

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

### getPrecisionStep

    public int getPrecisionStep()

  Returns the precision step.

### getDataType

    public NumericField.DataType getDataType()

  Returns the data type of the current value, `null` if not yet set.

  Since:
    3.2

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD