Lucene++ - a full-featured, c++ search engine
API Documentation


Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Attributes
Lucene::NumericField Class Reference

This class provides a Field that enables indexing of numeric values for efficient range filtering and sorting. The native types int32_t, int64_t 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 int64_t value. If you don't need millisecond precision, you can quantize the value, either by dividing the result or using the separate getters (for year, month, etc.) to construct an int32_t or int64_t value. More...

#include <NumericField.h>

+ Inheritance diagram for Lucene::NumericField:

Public Member Functions

 NumericField (const 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.
 
 NumericField (const String &name, Field::Store store, bool 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. This constructor creates an indexed, but not stored field.
 
 NumericField (const String &name, int32_t 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.
 
 NumericField (const String &name, int32_t precisionStep, Field::Store store, bool 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. This constructor creates an indexed, but not stored field.
 
virtual ~NumericField ()
 
virtual String getClassName ()
 
boost::shared_ptr< NumericFieldshared_from_this ()
 
virtual TokenStreamPtr tokenStreamValue ()
 Returns a NumericTokenStream for indexing the numeric value.
 
virtual ByteArray getBinaryValue (ByteArray result)
 Returns always null for numeric fields.
 
virtual ReaderPtr readerValue ()
 Returns always null for numeric fields.
 
virtual String stringValue ()
 Returns the numeric value as a string (how it is stored, when Field.Store#YES is chosen).
 
virtual int64_t getNumericValue ()
 Returns the current numeric value.
 
virtual NumericFieldPtr setLongValue (int64_t value)
 Initializes the field with the supplied long value.
 
virtual NumericFieldPtr setIntValue (int32_t value)
 Initializes the field with the supplied int value.
 
virtual NumericFieldPtr setDoubleValue (double value)
 Initializes the field with the supplied double value.
 
- Public Member Functions inherited from Lucene::AbstractField
virtual ~AbstractField ()
 
boost::shared_ptr< AbstractFieldshared_from_this ()
 
virtual void setBoost (double boost)
 Sets the boost factor hits on this field. This value will be multiplied into the score of all hits on this this field of this document.
 
virtual double getBoost ()
 Returns the boost factor for hits for this field.
 
virtual String name ()
 Returns the name of the field as an interned string. For example "date", "title", "body", ...
 
virtual bool isStored ()
 True if the value of the field is to be stored in the index for return with search hits. It is an error for this to be true if a field is Reader-valued.
 
virtual bool isIndexed ()
 True if the value of the field is to be indexed, so that it may be searched on.
 
virtual bool isTokenized ()
 True if the value of the field should be tokenized as text prior to indexing. Un-tokenized fields are indexed as a single word and may not be Reader-valued.
 
virtual bool isTermVectorStored ()
 True if the term or terms used to index this field are stored as a term vector, available from IndexReader#getTermFreqVector(int,String). These methods do not provide access to the original content of the field, only to terms used to index it. If the original content must be preserved, use the stored attribute instead.
 
virtual bool isStoreOffsetWithTermVector ()
 True if terms are stored as term vector together with their offsets (start and end position in source text).
 
virtual bool isStorePositionWithTermVector ()
 True if terms are stored as term vector together with their token positions.
 
virtual bool isBinary ()
 True if the value of the field is stored as binary.
 
virtual ByteArray getBinaryValue ()
 Return the raw byte[] for the binary field. Note that you must also call getBinaryLength and getBinaryOffset to know which range of bytes in this returned array belong to the field.
 
virtual int32_t getBinaryLength ()
 Returns length of byte[] segment that is used as value, if Field is not binary returned value is undefined.
 
virtual int32_t getBinaryOffset ()
 Returns offset into byte[] segment that is used as value, if Field is not binary returned value is undefined.
 
virtual bool getOmitNorms ()
 True if norms are omitted for this indexed field.
 
virtual bool getOmitTermFreqAndPositions ()
 
virtual void setOmitNorms (bool omitNorms)
 If set, omit normalization factors associated with this indexed field. This effectively disables indexing boosts and length normalization for this field.
 
virtual void setOmitTermFreqAndPositions (bool omitTermFreqAndPositions)
 If set, omit term freq, positions and payloads from postings for this field.
 
virtual bool isLazy ()
 Indicates whether a Field is Lazy or not. The semantics of Lazy loading are such that if a Field is lazily loaded, retrieving it's values via stringValue() or getBinaryValue() is only valid as long as the IndexReader that retrieved the Document is still open.
 
virtual String toString ()
 Prints a Field for human consumption.
 
- Public Member Functions inherited from Lucene::Fieldable
virtual ~Fieldable ()
 
- Public Member Functions inherited from Lucene::LuceneObject
virtual ~LuceneObject ()
 
virtual void initialize ()
 Called directly after instantiation to create objects that depend on this object being fully constructed.
 
virtual LuceneObjectPtr clone (const LuceneObjectPtr &other=LuceneObjectPtr())
 Return clone of this object.
 
virtual int32_t hashCode ()
 Return hash code for this object.
 
virtual bool equals (const LuceneObjectPtr &other)
 Return whether two objects are equal.
 
virtual int32_t compareTo (const LuceneObjectPtr &other)
 Compare two objects.
 
- Public Member Functions inherited from Lucene::LuceneSync
virtual ~LuceneSync ()
 
virtual SynchronizePtr getSync ()
 Return this object synchronize lock.
 
virtual LuceneSignalPtr getSignal ()
 Return this object signal.
 
virtual void lock (int32_t timeout=0)
 Lock this object using an optional timeout.
 
virtual void unlock ()
 Unlock this object.
 
virtual bool holdsLock ()
 Returns true if this object is currently locked by current thread.
 
virtual void wait (int32_t timeout=0)
 Wait for signal using an optional timeout.
 
virtual void notifyAll ()
 Notify all threads waiting for signal.
 

Static Public Member Functions

static String _getClassName ()
 
- Static Public Member Functions inherited from Lucene::AbstractField
static String _getClassName ()
 
- Static Public Member Functions inherited from Lucene::Fieldable
static String _getClassName ()
 

Protected Attributes

NumericTokenStreamPtr tokenStream
 
- Protected Attributes inherited from Lucene::AbstractField
String _name
 
bool storeTermVector
 
bool storeOffsetWithTermVector
 
bool storePositionWithTermVector
 
bool _omitNorms
 
bool _isStored
 
bool _isIndexed
 
bool _isTokenized
 
bool _isBinary
 
bool lazy
 
bool omitTermFreqAndPositions
 
double boost
 
FieldsData fieldsData
 
TokenStreamPtr tokenStream
 
int32_t binaryLength
 
int32_t binaryOffset
 
- Protected Attributes inherited from Lucene::LuceneSync
SynchronizePtr objectLock
 
LuceneSignalPtr objectSignal
 

Additional Inherited Members

- Public Types inherited from Lucene::AbstractField
enum  Store { STORE_YES , STORE_NO }
 Specifies whether and how a field should be stored. More...
 
enum  Index {
  INDEX_NO , INDEX_ANALYZED , INDEX_NOT_ANALYZED , INDEX_NOT_ANALYZED_NO_NORMS ,
  INDEX_ANALYZED_NO_NORMS
}
 Specifies whether and how a field should be indexed. More...
 
enum  TermVector {
  TERM_VECTOR_NO , TERM_VECTOR_YES , TERM_VECTOR_WITH_POSITIONS , TERM_VECTOR_WITH_OFFSETS ,
  TERM_VECTOR_WITH_POSITIONS_OFFSETS
}
 Specifies whether and how a field should have term vectors. More...
 
- Protected Member Functions inherited from Lucene::AbstractField
 AbstractField ()
 
 AbstractField (const String &name, Store store, Index index, TermVector termVector)
 
void setStoreTermVector (TermVector termVector)
 
- Protected Member Functions inherited from Lucene::LuceneObject
 LuceneObject ()
 

Detailed Description

This class provides a Field that enables indexing of numeric values for efficient range filtering and sorting. The native types int32_t, int64_t 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 int64_t value. If you don't need millisecond precision, you can quantize the value, either by dividing the result or using the separate getters (for year, month, etc.) to construct an int32_t or int64_t 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 trade off 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 INT_MAX, 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 MAX_INT. 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 strings (according to toString(value) of the used data type).

Constructor & Destructor Documentation

◆ NumericField() [1/4]

Lucene::NumericField::NumericField ( const 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
namethe field name

◆ NumericField() [2/4]

Lucene::NumericField::NumericField ( const String &  name,
Field::Store  store,
bool  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. This constructor creates an indexed, but not stored field.

Parameters
namethe field name
storeif the field should be stored in plain text form (according to toString(value) of the used data type)
indexif the field should be indexed using NumericTokenStream

◆ NumericField() [3/4]

Lucene::NumericField::NumericField ( const String &  name,
int32_t  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
namethe field name
precisionStepthe used precision step

◆ NumericField() [4/4]

Lucene::NumericField::NumericField ( const String &  name,
int32_t  precisionStep,
Field::Store  store,
bool  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. This constructor creates an indexed, but not stored field.

Parameters
namethe field name
precisionStepthe used precision step
storeif the field should be stored in plain text form (according to toString(value) of the used data type)
indexif the field should be indexed using NumericTokenStream

◆ ~NumericField()

virtual Lucene::NumericField::~NumericField ( )
virtual

Member Function Documentation

◆ _getClassName()

static String Lucene::NumericField::_getClassName ( )
inlinestatic

◆ getBinaryValue()

virtual ByteArray Lucene::NumericField::getBinaryValue ( ByteArray  result)
virtual

Returns always null for numeric fields.

Reimplemented from Lucene::AbstractField.

◆ getClassName()

virtual String Lucene::NumericField::getClassName ( )
inlinevirtual

Reimplemented from Lucene::AbstractField.

◆ getNumericValue()

virtual int64_t Lucene::NumericField::getNumericValue ( )
virtual

Returns the current numeric value.

◆ readerValue()

virtual ReaderPtr Lucene::NumericField::readerValue ( )
virtual

Returns always null for numeric fields.

Implements Lucene::Fieldable.

◆ setDoubleValue()

virtual NumericFieldPtr Lucene::NumericField::setDoubleValue ( double  value)
virtual

Initializes the field with the supplied double value.

Parameters
valuethe numeric value

◆ setIntValue()

virtual NumericFieldPtr Lucene::NumericField::setIntValue ( int32_t  value)
virtual

Initializes the field with the supplied int value.

Parameters
valuethe numeric value

◆ setLongValue()

virtual NumericFieldPtr Lucene::NumericField::setLongValue ( int64_t  value)
virtual

Initializes the field with the supplied long value.

Parameters
valuethe numeric value

◆ shared_from_this()

boost::shared_ptr< NumericField > Lucene::NumericField::shared_from_this ( )
inline

◆ stringValue()

virtual String Lucene::NumericField::stringValue ( )
virtual

Returns the numeric value as a string (how it is stored, when Field.Store#YES is chosen).

Implements Lucene::Fieldable.

◆ tokenStreamValue()

virtual TokenStreamPtr Lucene::NumericField::tokenStreamValue ( )
virtual

Returns a NumericTokenStream for indexing the numeric value.

Implements Lucene::Fieldable.

Field Documentation

◆ tokenStream

NumericTokenStreamPtr Lucene::NumericField::tokenStream
protected

The documentation for this class was generated from the following file:

clucene.sourceforge.net