org.apache.lucene.document
Class NumericField

java.lang.Object
  extended by org.apache.lucene.document.AbstractField
      extended by 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))