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 theNumericField
andDocument
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
anddouble
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 aDate
can be translated into a long value using theDate.getTime()
method. If you don't need millisecond precision, you can quantize the value, either by dividing the result ofDate.getTime()
or using the separate getters (for year, month, etc.) to construct anint
orlong
value.To perform range querying or filtering against a
NumericField
, useNumericRangeQuery
orNumericRangeFilter
. To sort according to aNumericField
, use the normal numeric sort types, egSortField.INT
.NumericField
values can also be loaded directly fromFieldCache
.By default, a
NumericField
's value is not stored but is indexed for range filtering and sorting. You can use theNumericField(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-valuedNumericField
.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. SmallerprecisionStep
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 constructorNumericField(String,int,Field.Store,boolean)
if you'd like to change the value. Note that you must also specify a congruent value when creatingNumericRangeQuery
orNumericRangeFilter
. For low cardinality fields larger precision steps are good. If the cardinality is < 100, it is fair to useInteger.MAX_VALUE
, which produces one term per value.For more information on the internals of numeric trie indexing, including the
precisionStep
configuration, seeNumericRangeQuery
. The format of indexed values is described inNumericUtils
.If you only need to sort by numeric value, and never run range querying/filtering, you can index using a
precisionStep
ofInteger.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
Nested Classes Modifier and Type Class Description static class
NumericField.DataType
Data type of the value inNumericField
.
-
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
Constructors Constructor Description NumericField(String name)
Creates a field for numeric values using the defaultprecisionStep
NumericUtils.PRECISION_STEP_DEFAULT
(4).NumericField(String name, int precisionStep)
Creates a field for numeric values with the specifiedprecisionStep
.NumericField(String name, int precisionStep, Field.Store store, boolean index)
Creates a field for numeric values with the specifiedprecisionStep
.NumericField(String name, Field.Store store, boolean index)
Creates a field for numeric values using the defaultprecisionStep
NumericUtils.PRECISION_STEP_DEFAULT
(4).
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description byte[]
getBinaryValue(byte[] result)
Returns alwaysnull
for numeric fieldsNumericField.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 ofNumber
,null
if not yet initialized.int
getPrecisionStep()
Returns the precision step.Reader
readerValue()
Returns alwaysnull
for numeric fieldsNumericField
setDoubleValue(double value)
Initializes the field with the supplieddouble
value.NumericField
setFloatValue(float value)
Initializes the field with the suppliedfloat
value.NumericField
setIntValue(int value)
Initializes the field with the suppliedint
value.NumericField
setLongValue(long value)
Initializes the field with the suppliedlong
value.String
stringValue()
Returns the numeric value as a string.TokenStream
tokenStreamValue()
Returns aNumericTokenStream
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
-
-
-
-
Constructor Detail
-
NumericField
public NumericField(String name)
Creates a field for numeric values using the defaultprecisionStep
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 defaultprecisionStep
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 namestore
- if the field should be stored,Document.getFieldable(java.lang.String)
then returnsNumericField
instances on search results.index
- if the field should be indexed usingNumericTokenStream
-
NumericField
public NumericField(String name, int precisionStep)
Creates a field for numeric values with the specifiedprecisionStep
. 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 nameprecisionStep
- the used precision step
-
NumericField
public NumericField(String name, int precisionStep, Field.Store store, boolean index)
Creates a field for numeric values with the specifiedprecisionStep
. 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 nameprecisionStep
- the used precision stepstore
- if the field should be stored,Document.getFieldable(java.lang.String)
then returnsNumericField
instances on search results.index
- if the field should be indexed usingNumericTokenStream
-
-
Method Detail
-
tokenStreamValue
public TokenStream tokenStreamValue()
Returns aNumericTokenStream
for indexing the numeric value.- See Also:
Fieldable.stringValue()
-
getBinaryValue
public byte[] getBinaryValue(byte[] result)
Returns alwaysnull
for numeric fields- Specified by:
getBinaryValue
in interfaceFieldable
- Overrides:
getBinaryValue
in classAbstractField
- 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 alwaysnull
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 callDocument.get(String)
on search results. It is recommended to useDocument.getFieldable(java.lang.String)
instead that returnsNumericField
instances. You can then usegetNumericValue()
to return the stored value.
-
getNumericValue
public Number getNumericValue()
Returns the current numeric value as a subclass ofNumber
,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 suppliedlong
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 suppliedint
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 supplieddouble
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 suppliedfloat
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))
-
-