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 (System.String, System.IO.TextReader or pre-analyzed TokenStream), binary (byte[]), or numeric (System.Int32, System.Int64, System.Single, or System.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

System.Object

Field

BinaryDocValuesField

DoubleField

Int32Field

Int64Field

NumericDocValuesField

SingleField

SortedDocValuesField

SortedSetDocValuesField

StoredField

StringField

TextField

Implements

IIndexableField

System.IFormattable

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

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
System.String	name	The name of the field
TokenStream	tokenStream	The TokenStream with the content

Exceptions

Type	Condition
System.ArgumentNullException	if name or tokenStream is null

Field(String, TokenStream, Field.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
System.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
System.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
System.String	name	field name
TokenStream	tokenStream	TokenStream value
FieldType	type	field type

Exceptions

Type	Condition
System.ArgumentException	if IsStored is true, or if IsTokenized is false, or if IsIndexed is false.
System.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
System.String	name	field name
FieldType	type	field type

Exceptions

Type	Condition
System.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
System.String	name	field name
BytesRef	bytes	BytesRef pointing to binary content (not copied)
FieldType	type	field type

Exceptions

Type	Condition
System.ArgumentException	if the IsIndexed is true
System.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
System.String	name	The name of the field
System.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
System.String	name	field name
System.Byte[]	value	byte array pointing to binary content (not copied)
FieldType	type	field type

Exceptions

Type	Condition
System.ArgumentException	if the IsIndexed is true
System.ArgumentNullException	the field name is null, or if the type is null

Field(String, Byte[], Int32, Int32)

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
System.String	name	The name of the field
System.Byte[]	value	The binary value
System.Int32	offset	Starting offset in value where this Field's bytes are
System.Int32	length	Number of bytes to use for this Field, starting at offset

Field(String, Byte[], Int32, Int32, 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
System.String	name	field name
System.Byte[]	value	byte array pointing to binary content (not copied)
System.Int32	offset	starting position of the byte array
System.Int32	length	valid length of the byte array
FieldType	type	field type

Exceptions

Type	Condition
System.ArgumentException	if the IsIndexed is true
System.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 System.IO.TextReader is read only when the Document is added to the index, i.e. you may not close the System.IO.TextReader until AddDocument(IEnumerable<IIndexableField>) has been called.

Declaration

[Obsolete("Use TextField instead.")]
public Field(string name, TextReader reader)

Parameters

Type	Name	Description
System.String	name	The name of the field
System.IO.TextReader	reader	The reader with the content

Exceptions

Type	Condition
System.ArgumentNullException	if name or reader is null

Field(String, TextReader, Field.TermVector)

Create a tokenized and indexed field that is not stored, optionally with storing term vectors. The System.IO.TextReader is read only when the Document is added to the index, i.e. you may not close the System.IO.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
System.String	name	The name of the field
System.IO.TextReader	reader	The reader with the content
Field.TermVector	termVector	Whether term vector should be stored

Exceptions

Type	Condition
System.ArgumentNullException	if name or reader is null

Field(String, TextReader, FieldType)

Create field with System.IO.TextReader value.

Declaration

public Field(string name, TextReader reader, FieldType type)

Parameters

Type	Name	Description
System.String	name	field name
System.IO.TextReader	reader	reader value
FieldType	type	field type

Exceptions

Type	Condition
System.ArgumentException	if IsStored is true, or if IsTokenized is false.
System.ArgumentNullException	if the name, reader or type is null

Field(String, String, Field.Store, Field.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
System.String	name	The name of the field
System.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
System.ArgumentNullException	if name or value is null
System.ArgumentException	if the field is neither stored nor indexed

Field(String, String, Field.Store, Field.Index, Field.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
System.String	name	The name of the field
System.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
System.ArgumentNullException	if name or value is null
System.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 System.String value.

Declaration

public Field(string name, string value, FieldType type)

Parameters

Type	Name	Description
System.String	name	field name
System.String	value	string value
FieldType	type	field type

Exceptions

Type	Condition
System.ArgumentException	if the field's type is neither indexed() nor stored(), or if indexed() is false but storeTermVectors() is true.
System.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
System.Single

See Also

Boost

m_name

Field's name

Declaration

protected readonly string m_name

Field Value

Type	Description
System.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 System.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
System.Single

Remarks

The default value is 1.0f (no boost).

Exceptions

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

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
System.Object

FieldType

Returns the FieldType for this field as type FieldType.

Declaration

public virtual FieldType FieldType { get; }

Property Value

Type	Description
FieldType

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
System.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 System.Byte or null if the type is non-numeric.

Declaration

public virtual byte? GetByteValue()

Returns

Type	Description
System.Nullable<System.Byte>	The field value or null if the type is non-numeric.

GetDoubleValue()

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

Declaration

public virtual double? GetDoubleValue()

Returns

Type	Description
System.Nullable<System.Double>	The field value or null if the type is non-numeric.

GetInt16Value()

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

Declaration

public virtual short? GetInt16Value()

Returns

Type	Description
System.Nullable<System.Int16>	The field value or null if the type is non-numeric.

GetInt32Value()

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

Declaration

public virtual int? GetInt32Value()

Returns

Type	Description
System.Nullable<System.Int32>	The field value or null if the type is non-numeric.

GetInt64Value()

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

Declaration

public virtual long? GetInt64Value()

Returns

Type	Description
System.Nullable<System.Int64>	The field value or null if the type is non-numeric.

GetNumericValue()

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
System.Object

GetReaderValue()

The value of the field as a System.IO.TextReader, or null. If null, the System.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
System.IO.TextReader

GetSingleValue()

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

Declaration

public virtual float? GetSingleValue()

Returns

Type	Description
System.Nullable<System.Single>	The field value or null if the type is non-numeric.

GetStringValue()

The value of the field as a System.String, or null. If null, the System.IO.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
System.String	The string representation of the value if it is either a System.String or numeric type.

GetStringValue(IFormatProvider)

The value of the field as a System.String, or null. If null, the System.IO.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
System.IFormatProvider	provider	An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.

Returns

Type	Description
System.String	The string representation of the value if it is either a System.String or numeric type.

GetStringValue(String)

The value of the field as a System.String, or null. If null, the System.IO.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
System.String	format	A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.

Returns

Type	Description
System.String	The string representation of the value if it is either a System.String or numeric type.

GetStringValue(String, IFormatProvider)

The value of the field as a System.String, or null. If null, the System.IO.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
System.String	format	A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.
System.IFormatProvider	provider	An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.

Returns

Type	Description
System.String	The string representation of the value if it is either a System.String or numeric type.

GetTokenStream(Analyzer)

Declaration

public virtual TokenStream GetTokenStream(Analyzer analyzer)

Parameters

Type	Name	Description
Analyzer	analyzer

Returns

Type	Description
TokenStream

GetTokenStreamValue()

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

Declaration

public virtual TokenStream GetTokenStreamValue()

Returns

Type	Description
TokenStream

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
System.Byte[]	value

SetByteValue(Byte)

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

Declaration

public virtual void SetByteValue(byte value)

Parameters

Type	Name	Description
System.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
System.Double	value

SetInt16Value(Int16)

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

Declaration

public virtual void SetInt16Value(short value)

Parameters

Type	Name	Description
System.Int16	value

SetInt32Value(Int32)

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

Declaration

public virtual void SetInt32Value(int value)

Parameters

Type	Name	Description
System.Int32	value

SetInt64Value(Int64)

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

Declaration

public virtual void SetInt64Value(long value)

Parameters

Type	Name	Description
System.Int64	value

SetReaderValue(TextReader)

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

Declaration

public virtual void SetReaderValue(TextReader value)

Parameters

Type	Name	Description
System.IO.TextReader	value

SetSingleValue(Single)

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

Declaration

public virtual void SetSingleValue(float value)

Parameters

Type	Name	Description
System.Single	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
System.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
System.String

Overrides

System.Object.ToString()

ToString(IFormatProvider)

Prints a Field for human consumption.

Declaration

public virtual string ToString(IFormatProvider provider)

Parameters

Type	Name	Description
System.IFormatProvider	provider	An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.

Returns

Type	Description
System.String

ToString(String)

Prints a Field for human consumption.

Declaration

public virtual string ToString(string format)

Parameters

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

Returns

Type	Description
System.String

ToString(String, IFormatProvider)

Prints a Field for human consumption.

Declaration

public virtual string ToString(string format, IFormatProvider provider)

Parameters

Type	Name	Description
System.String	format	A standard or custom numeric format string. This parameter has no effect if this field is non-numeric.
System.IFormatProvider	provider	An object that supplies culture-specific formatting information. This parameter has no effect if this field is non-numeric.

Returns

Type	Description
System.String

TranslateFieldType(Field.Store, Field.Index, Field.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

IIndexableField

System.IFormattable

Extension Methods

IndexableFieldExtensions.GetByteValueOrDefault(IIndexableField)

IndexableFieldExtensions.GetInt16ValueOrDefault(IIndexableField)

IndexableFieldExtensions.GetInt32ValueOrDefault(IIndexableField)

IndexableFieldExtensions.GetInt64ValueOrDefault(IIndexableField)

IndexableFieldExtensions.GetSingleValueOrDefault(IIndexableField)

IndexableFieldExtensions.GetDoubleValueOrDefault(IIndexableField)