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.
Modifier and Type | Class and Description |
---|---|
static class |
NumericField.DataType
Data type of the value in
NumericField . |
binaryLength, binaryOffset, boost, fieldsData, indexOptions, isBinary, isIndexed, isStored, isTokenized, lazy, name, omitNorms, storeOffsetWithTermVector, storePositionWithTermVector, storeTermVector, tokenStream
Constructor and Description |
---|
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 . |
Modifier and Type | Method and Description |
---|---|
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. |
getBinaryLength, getBinaryOffset, getBinaryValue, getBoost, getIndexOptions, getOmitNorms, getOmitTermFreqAndPositions, isBinary, isIndexed, isLazy, isStored, isStoreOffsetWithTermVector, isStorePositionWithTermVector, isTermVectorStored, isTokenized, name, setBoost, setIndexOptions, setOmitNorms, setOmitTermFreqAndPositions, setStoreTermVector, toString
public NumericField(String name)
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.name
- the field namepublic NumericField(String name, Field.Store store, boolean index)
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.name
- the field namestore
- 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
public NumericField(String name, int precisionStep)
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.name
- the field nameprecisionStep
- the used precision steppublic NumericField(String name, int precisionStep, Field.Store store, boolean index)
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.name
- the field nameprecisionStep
- the used precision stepstore
- 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
public TokenStream tokenStreamValue()
NumericTokenStream
for indexing the numeric value.Fieldable.stringValue()
public byte[] getBinaryValue(byte[] result)
null
for numeric fieldsgetBinaryValue
in interface Fieldable
getBinaryValue
in class AbstractField
result
- User defined buffer that will be used if
possible. If this is null or not large enough, a new
buffer is allocatedpublic Reader readerValue()
null
for numeric fieldsFieldable.stringValue()
public String stringValue()
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.public Number getNumericValue()
Number
, null
if not yet initialized.public int getPrecisionStep()
public NumericField.DataType getDataType()
null
if not yet set.public NumericField setLongValue(long value)
long
value.value
- the numeric valuedocument.add(new NumericField(name, precisionStep).setLongValue(value))
public NumericField setIntValue(int value)
int
value.value
- the numeric valuedocument.add(new NumericField(name, precisionStep).setIntValue(value))
public NumericField setDoubleValue(double value)
double
value.value
- the numeric valuedocument.add(new NumericField(name, precisionStep).setDoubleValue(value))
public NumericField setFloatValue(float value)
float
value.value
- the numeric valuedocument.add(new NumericField(name, precisionStep).setFloatValue(value))