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< NumericField > | shared_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< AbstractField > | shared_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

  name | the field name

References Lucene::AbstractField::name().

Referenced by _getClassName().

## ◆ 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

  name | the field name
  store | if the field should be stored in plain text form (according to toString(value) of the used data type)
  index | if the field should be indexed using `NumericTokenStream`

References Lucene::AbstractField::name().

## ◆ 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

  name | the field name
  precisionStep | the used precision step

References Lucene::AbstractField::name().

## ◆ 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

  name | the field name
  precisionStep | the used precision step
  store | if the field should be stored in plain text form (according to toString(value) of the used data type)
  index | if the field should be indexed using `NumericTokenStream`

References Lucene::AbstractField::name().

## ◆ ~NumericField()

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

virtual

## Member Function Documentation

## ◆ _getClassName()

String Lucene::NumericField::_getClassName | ( |  | ) |

inline static

References NumericField().

## ◆ 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 | ( |  | ) |

inline virtual

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

  value | the numeric value

## ◆ setIntValue()

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

virtual

Initializes the field with the supplied int value.

Parameters

  value | the numeric value

## ◆ setLongValue()

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

virtual

Initializes the field with the supplied long value.

Parameters

  value | the 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:

- NumericField.h

clucene.sourceforge.net