Class Field

Expert: directly create a field for a document. Most users should use one of the sugar subclasses: Int32Field, Int64Field, SingleField, DoubleField, BinaryDocValuesField, NumericDocValuesField, SortedDocValuesField, StringField, TextField, StoredField.

A field is a section of a Document. Each field has three parts: name, type and value. Values may be text (string, TextReader or pre-analyzed TokenStream), binary (byte[]), or numeric (int, long, float, or double). Fields are optionally stored in the index, so that they may be returned with hits on the document.

NOTE: the field type is an IIndexableFieldType. Making changes to the state of the IIndexableFieldType will impact any Field it is used in. It is strongly recommended that no changes be made after Field instantiation.
Inheritance
object
Field
BinaryDocValuesField
DoubleField
Int32Field
Int64Field
NumericDocValuesField
SingleField
SortedDocValuesField
SortedSetDocValuesField
StoredField
StringField
TextField
Inherited Members
Namespace: Lucene.Net.Documents
Assembly: Lucene.Net.dll
Syntax
public class Field : IIndexableField, IFormattable

Constructors

Field(string, TokenStream)

Create a tokenized and indexed field that is not stored. Term vectors will not be stored. This is useful for pre-analyzed fields. The TokenStream is read only when the Document is added to the index, i.e. you may not close the TokenStream until AddDocument(IEnumerable<IIndexableField>) has been called.

Declaration
[Obsolete("Use TextField instead.")]
public Field(string name, TokenStream tokenStream)
Parameters
Type Name Description
string name

The name of the field
TokenStream tokenStream

The TokenStream with the content
Exceptions
Type Condition
ArgumentNullException

if name or tokenStream is null

Field(string, TokenStream, TermVector)

Create a tokenized and indexed field that is not stored, optionally with storing term vectors. This is useful for pre-analyzed fields. The TokenStream is read only when the Document is added to the index, i.e. you may not close the TokenStream until AddDocument(IEnumerable<IIndexableField>) has been called.

Declaration
[Obsolete("Use TextField instead.")]
public Field(string name, TokenStream tokenStream, Field.TermVector termVector)
Parameters
Type Name Description
string name

The name of the field
TokenStream tokenStream

The TokenStream with the content
Field.TermVector termVector

Whether term vector should be stored
Exceptions
Type Condition
ArgumentNullException

if name or tokenStream is null

Field(string, TokenStream, FieldType)

Create field with TokenStream value.

Declaration
public Field(string name, TokenStream tokenStream, FieldType type)
Parameters
Type Name Description
string name

field name
TokenStream tokenStream

TokenStream value
FieldType type

field type
Exceptions
Type Condition
ArgumentException

if IsStored is true, or if IsTokenized is false, or if IsIndexed is false.
ArgumentNullException

if the name, tokenStream or type is null

Field(string, FieldType)

Expert: creates a field with no initial value. Intended only for custom Field subclasses.

Declaration
protected Field(string name, FieldType type)
Parameters
Type Name Description
string name

field name
FieldType type

field type
Exceptions
Type Condition
ArgumentNullException

if either the name or type is null.

Field(string, BytesRef, FieldType)

Create field with binary value.

NOTE: the provided BytesRef is not copied so be sure not to change it until you're done with this field.
Declaration
public Field(string name, BytesRef bytes, FieldType type)
Parameters
Type Name Description
string name

field name
BytesRef bytes

BytesRef pointing to binary content (not copied)
FieldType type

field type
Exceptions
Type Condition
ArgumentException

if the IsIndexed is true
ArgumentNullException

if the field name is null, or the type is null

Field(string, byte[])

Create a stored field with binary value. Optionally the value may be compressed.

Declaration
[Obsolete("Use StoredField instead.")]
public Field(string name, byte[] value)
Parameters
Type Name Description
string name

The name of the field
byte[] value

The binary value

Field(string, byte[], FieldType)

Create field with binary value.

NOTE: the provided byte[] is not copied so be sure not to change it until you're done with this field.
Declaration
public Field(string name, byte[] value, FieldType type)
Parameters
Type Name Description
string name

field name
byte[] value

byte array pointing to binary content (not copied)
FieldType type

field type
Exceptions
Type Condition
ArgumentException

if the IsIndexed is true
ArgumentNullException

the field name is null, or if the type is null

Field(string, byte[], int, int)

Create a stored field with binary value. Optionally the value may be compressed.

Declaration
[Obsolete("Use StoredField instead.")]
public Field(string name, byte[] value, int offset, int length)
Parameters
Type Name Description
string name

The name of the field
byte[] value

The binary value
int offset

Starting offset in value where this Field's bytes are
int length

Number of bytes to use for this Field, starting at offset

Field(string, byte[], int, int, FieldType)

Create field with binary value.

NOTE: the provided byte[] is not copied so be sure not to change it until you're done with this field.
Declaration
public Field(string name, byte[] value, int offset, int length, FieldType type)
Parameters
Type Name Description
string name

field name
byte[] value

byte array pointing to binary content (not copied)
int offset

starting position of the byte array
int length

valid length of the byte array
FieldType type

field type
Exceptions
Type Condition
ArgumentException

if the IsIndexed is true
ArgumentNullException

if the field name is null, or the type is null

Field(string, TextReader)

Create a tokenized and indexed field that is not stored. Term vectors will not be stored. The TextReader is read only when the Document is added to the index, i.e. you may not close the TextReader until AddDocument(IEnumerable<IIndexableField>) has been called.

Declaration
[Obsolete("Use TextField instead.")]
public Field(string name, TextReader reader)
Parameters
Type Name Description
string name

The name of the field
TextReader reader

The reader with the content
Exceptions
Type Condition
ArgumentNullException

if name or reader is null

Field(string, TextReader, TermVector)

Create a tokenized and indexed field that is not stored, optionally with storing term vectors. The TextReader is read only when the Document is added to the index, i.e. you may not close the TextReader until AddDocument(IEnumerable<IIndexableField>) has been called.

Declaration
[Obsolete("Use TextField instead.")]
public Field(string name, TextReader reader, Field.TermVector termVector)
Parameters
Type Name Description
string name

The name of the field
TextReader reader

The reader with the content
Field.TermVector termVector

Whether term vector should be stored
Exceptions
Type Condition
ArgumentNullException

if name or reader is null

Field(string, TextReader, FieldType)

Create field with TextReader value.

Declaration
public Field(string name, TextReader reader, FieldType type)
Parameters
Type Name Description
string name

field name
TextReader reader

reader value
FieldType type

field type
Exceptions
Type Condition
ArgumentException

if IsStored is true, or if IsTokenized is false.
ArgumentNullException

if the name, reader or type is null

Field(string, string, Store, Index)

Create a field by specifying its name, value and how it will be saved in the index. Term vectors will not be stored in the index.

Declaration
[Obsolete("Use StringField, TextField instead.")]
public Field(string name, string value, Field.Store store, Field.Index index)
Parameters
Type Name Description
string name

The name of the field
string value

The string to process
Field.Store store

Whether value should be stored in the index
Field.Index index

Whether the field should be indexed, and if so, if it should be tokenized before indexing
Exceptions
Type Condition
ArgumentNullException

if name or value is null
ArgumentException

if the field is neither stored nor indexed

Field(string, string, Store, Index, TermVector)

Create a field by specifying its name, value and how it will be saved in the index.

Declaration
[Obsolete("Use StringField, TextField instead.")]
public Field(string name, string value, Field.Store store, Field.Index index, Field.TermVector termVector)
Parameters
Type Name Description
string name

The name of the field
string value

The string to process
Field.Store store

Whether value should be stored in the index
Field.Index index

Whether the field should be indexed, and if so, if it should be tokenized before indexing
Field.TermVector termVector

Whether term vector should be stored
Exceptions
Type Condition
ArgumentNullException

if name or value is null
ArgumentException

in any of the following situations:

  • the field is neither stored nor indexed
  • the field is not indexed but termVector is YES

Field(string, string, FieldType)

Create field with string value.

Declaration
public Field(string name, string value, FieldType type)
Parameters
Type Name Description
string name

field name
string value

string value
FieldType type

field type
Exceptions
Type Condition
ArgumentException

if the field's type is neither indexed() nor stored(), or if indexed() is false but storeTermVectors() is true.
ArgumentNullException

if either the name or value is null, or if the type is null

Fields

m_boost

Field's boost

Declaration
protected float m_boost
Field Value
Type Description
float
See Also

m_name

Field's name

Declaration
protected readonly string m_name
Field Value
Type Description
string

m_tokenStream

Pre-analyzed TokenStream for indexed fields; this is separate from FieldsData because you are allowed to have both; eg maybe field has a string value but you customize how it's tokenized

Declaration
protected TokenStream m_tokenStream
Field Value
Type Description
TokenStream

m_type

Field's type

Declaration
protected readonly FieldType m_type
Field Value
Type Description
FieldType

Properties

Boost

Gets or sets the boost factor on this field.

Declaration
public virtual float Boost { get; set; }
Property Value
Type Description
float
Remarks

The default value is 1.0f (no boost).

Exceptions
Type Condition
ArgumentException

(setter only) if this field is not indexed, or if it omits norms.

FieldType

Returns the FieldType for this field as type FieldType.

Declaration
public virtual FieldType FieldType { get; }
Property Value
Type Description
FieldType

FieldsData

Field's value

Setting this property will automatically set the backing field for the NumericType property.
Declaration
protected object FieldsData { get; set; }
Property Value
Type Description
object

IndexableFieldType

Returns the FieldType for this field as type IIndexableFieldType.

Declaration
public virtual IIndexableFieldType IndexableFieldType { get; }
Property Value
Type Description
IIndexableFieldType

Name

The field's name

Declaration
public virtual string Name { get; }
Property Value
Type Description
string

NumericType

Gets the NumericFieldType of the underlying value, or NONE if the value is not set or non-numeric.

Expert: The difference between this property and NumericType is this is represents the current state of the field (whether being written or read) and the FieldType property represents instructions on how the field will be written, but does not re-populate when reading back from an index (it is write-only).

In Java, the numeric type was determined by checking the type of GetNumericValue(). However, since there are no reference number types in .NET, using GetNumericValue() so will cause boxing/unboxing. It is therefore recommended to use this property to check the underlying type and the corresponding Get*Value() method to retrieve the value.

NOTE: Since Lucene codecs do not support BYTE or INT16, fields created with these types will always be INT32 when read back from the index.
Declaration
public virtual NumericFieldType NumericType { get; }
Property Value
Type Description
NumericFieldType

Methods

GetBinaryValue()

Non-null if this field has a binary value.

Declaration
public virtual BytesRef GetBinaryValue()
Returns
Type Description
BytesRef

GetByteValue()

Returns the field value as byte or null if the type is non-numeric.

Declaration
public virtual byte? GetByteValue()
Returns
Type Description
byte?

The field value or null if the type is non-numeric.

GetDoubleValue()

Returns the field value as double or null if the type is non-numeric.

Declaration
public virtual double? GetDoubleValue()
Returns
Type Description
double?

The field value or null if the type is non-numeric.

GetInt16Value()

Returns the field value as short or null if the type is non-numeric.

Declaration
public virtual short? GetInt16Value()
Returns
Type Description
short?

The field value or null if the type is non-numeric.

GetInt32Value()

Returns the field value as int or null if the type is non-numeric.

Declaration
public virtual int? GetInt32Value()
Returns
Type Description
int?

The field value or null if the type is non-numeric.

GetInt64Value()

Returns the field value as long or null if the type is non-numeric.

Declaration
public virtual long? GetInt64Value()
Returns
Type Description
long?

The field value or null if the type is non-numeric.

GetNumericValue()

Non-null if this field has a numeric value.

Declaration
[Obsolete("In .NET, use of this method will cause boxing/unboxing. Instead, use the NumericType property to check the underlying type and call the appropriate GetXXXValue() method to retrieve the value.")]
public virtual object GetNumericValue()
Returns
Type Description
object

GetReaderValue()

The value of the field as a TextReader, or null. If null, the string value or binary value is used. Exactly one of GetStringValue(), GetReaderValue(), and GetBinaryValue() must be set.

Declaration
public virtual TextReader GetReaderValue()
Returns
Type Description
TextReader

GetSingleValue()

Returns the field value as float or null if the type is non-numeric.

Declaration
public virtual float? GetSingleValue()
Returns
Type Description
float?

The field value or null if the type is non-numeric.

GetStringValue()

The value of the field as a string, or null. If null, the TextReader value or binary value is used. Exactly one of GetStringValue(), GetReaderValue(), and GetBinaryValue() must be set.

Declaration
public virtual string GetStringValue()
Returns
Type Description
string

The string representation of the value if it is either a string or numeric type.

GetStringValue(IFormatProvider)

The value of the field as a string, or null. If null, the TextReader value or binary value is used. Exactly one of GetStringValue(), GetReaderValue(), and GetBinaryValue() must be set.

Declaration
public virtual string GetStringValue(IFormatProvider provider)
Parameters
Type Name Description
IFormatProvider provider

An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.
Returns
Type Description
string

The string representation of the value if it is either a string or numeric type.

GetStringValue(string)

The value of the field as a string, or null. If null, the TextReader value or binary value is used. Exactly one of GetStringValue(), GetReaderValue(), and GetBinaryValue() must be set.

Declaration
public virtual string GetStringValue(string format)
Parameters
Type Name Description
string format

A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.
Returns
Type Description
string

The string representation of the value if it is either a string or numeric type.

GetStringValue(string, IFormatProvider)

The value of the field as a string, or null. If null, the TextReader value or binary value is used. Exactly one of GetStringValue(), GetReaderValue(), and GetBinaryValue() must be set.

Declaration
public virtual string GetStringValue(string format, IFormatProvider provider)
Parameters
Type Name Description
string format

A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.
IFormatProvider provider

An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.
Returns
Type Description
string

The string representation of the value if it is either a string or numeric type.

GetTokenStream(Analyzer)

Creates the TokenStream used for indexing this field. If appropriate, implementations should use the given Analyzer to create the TokenStreams.

Declaration
public virtual TokenStream GetTokenStream(Analyzer analyzer)
Parameters
Type Name Description
Analyzer analyzer

Analyzer that should be used to create the TokenStreams from
Returns
Type Description
TokenStream

TokenStream value for indexing the document. Should always return a non-null value if the field is to be indexed
Exceptions
Type Condition
IOException

Can be thrown while creating the TokenStream

GetTokenStreamValue()

The TokenStream for this field to be used when indexing, or null. If null, the TextReader value or string value is analyzed to produce the indexed tokens.

Declaration
public virtual TokenStream GetTokenStreamValue()
Returns
Type Description
TokenStream

SetByteValue(byte)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetByteValue(byte value)
Parameters
Type Name Description
byte value

SetBytesValue(BytesRef)

Expert: change the value of this field. See SetStringValue(string).

NOTE: the provided BytesRef is not copied so be sure not to change it until you're done with this field.
Declaration
public virtual void SetBytesValue(BytesRef value)
Parameters
Type Name Description
BytesRef value

SetBytesValue(byte[])

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetBytesValue(byte[] value)
Parameters
Type Name Description
byte[] value

SetDoubleValue(double)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetDoubleValue(double value)
Parameters
Type Name Description
double value

SetInt16Value(short)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetInt16Value(short value)
Parameters
Type Name Description
short value

SetInt32Value(int)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetInt32Value(int value)
Parameters
Type Name Description
int value

SetInt64Value(long)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetInt64Value(long value)
Parameters
Type Name Description
long value

SetReaderValue(TextReader)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetReaderValue(TextReader value)
Parameters
Type Name Description
TextReader value

SetSingleValue(float)

Expert: change the value of this field. See SetStringValue(string).

Declaration
public virtual void SetSingleValue(float value)
Parameters
Type Name Description
float value

SetStringValue(string)

Expert: change the value of this field. This can be used during indexing to re-use a single Field instance to improve indexing speed by avoiding GC cost of new'ing and reclaiming Field instances. Typically a single Document instance is re-used as well. This helps most on small documents.

Each Field instance should only be used once within a single Document instance. See ImproveIndexingSpeed for details.

Declaration
public virtual void SetStringValue(string value)
Parameters
Type Name Description
string value

SetTokenStream(TokenStream)

Expert: sets the token stream to be used for indexing and causes IsIndexed and IsTokenized to return true. May be combined with stored values from GetStringValue() or GetBinaryValue()

Declaration
public virtual void SetTokenStream(TokenStream tokenStream)
Parameters
Type Name Description
TokenStream tokenStream

ToString()

Prints a Field for human consumption.

Declaration
public override string ToString()
Returns
Type Description
string
Overrides

ToString(IFormatProvider)

Prints a Field for human consumption.

Declaration
public virtual string ToString(IFormatProvider provider)
Parameters
Type Name Description
IFormatProvider provider

An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.
Returns
Type Description
string

ToString(string)

Prints a Field for human consumption.

Declaration
public virtual string ToString(string format)
Parameters
Type Name Description
string format

A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.
Returns
Type Description
string

ToString(string, IFormatProvider)

Prints a Field for human consumption.

Declaration
public virtual string ToString(string format, IFormatProvider provider)
Parameters
Type Name Description
string format

A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.
IFormatProvider provider

An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.
Returns
Type Description
string

TranslateFieldType(Store, Index, TermVector)

Translates the pre-4.0 enums for specifying how a field should be indexed into the 4.0 FieldType approach.

Declaration
[Obsolete("This is here only to ease transition from the pre-4.0 APIs.")]
public static FieldType TranslateFieldType(Field.Store store, Field.Index index, Field.TermVector termVector)
Parameters
Type Name Description
Field.Store store
Field.Index index
Field.TermVector termVector
Returns
Type Description
FieldType

Implements

Extension Methods