org.apache.lucene.document

Class Field

java.lang.Object

org.apache.lucene.document.Field

All Implemented Interfaces:

IndexableField

Direct Known Subclasses:

ByteDocValuesField, DerefBytesDocValuesField, DoubleDocValuesField, DoubleField, FloatDocValuesField, FloatField, IntDocValuesField, IntField, LongDocValuesField, LongField, PackedLongDocValuesField, ShortDocValuesField, SortedBytesDocValuesField, StoredField, StraightBytesDocValuesField, StringField, TextField

public class Field
extends Object
implements IndexableField

Expert: directly create a field for a document. Most users should use one of the sugar subclasses: IntField, LongField, FloatField, DoubleField, ByteDocValuesField, ShortDocValuesField, IntDocValuesField, LongDocValuesField, PackedLongDocValuesField, FloatDocValuesField, DoubleDocValuesField, SortedBytesDocValuesField, DerefBytesDocValuesField, StraightBytesDocValuesField, 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, Reader or pre-analyzed TokenStream), binary (byte[]), or numeric (a Number). Fields are optionally stored in the index, so that they may be returned with hits on the document.

NOTE: the field type is an IndexableFieldType. Making changes to the state of the IndexableFieldType will impact any Field it is used in. It is strongly recommended that no changes be made after Field instantiation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Field.Index Deprecated. This is here only to ease transition from the pre-4.0 APIs.
static class	Field.Store Specifies whether a field's value should be stored.
static class	Field.TermVector Deprecated. This is here only to ease transition from the pre-4.0 APIs.

Field Summary

Fields

Modifier and Type	Field and Description
protected float	boost
protected Object	fieldsData
protected String	name
protected NumericTokenStream	numericTokenStream
protected TokenStream	tokenStream
protected FieldType	type

Constructor Summary

Constructors

Modifier	Constructor and Description
	Field(String name, byte[] value) Deprecated. Use StoredField instead.
	Field(String name, byte[] value, FieldType type) Create field with binary value.
	Field(String name, byte[] value, int offset, int length) Deprecated. Use StoredField instead.
	Field(String name, byte[] value, int offset, int length, FieldType type) Create field with binary value.
	Field(String name, BytesRef bytes, FieldType type) Create field with binary value.
protected	Field(String name, FieldType type)
	Field(String name, Reader reader) Deprecated. Use TextField instead.
	Field(String name, Reader reader, Field.TermVector termVector) Deprecated. Use TextField instead.
	Field(String name, Reader reader, FieldType type) Create field with Reader value.
	Field(String name, String value, Field.Store store, Field.Index index) Deprecated. Use StringField, TextField instead.
	Field(String name, String value, Field.Store store, Field.Index index, Field.TermVector termVector) Deprecated. Use StringField, TextField instead.
	Field(String name, String value, FieldType type) Create field with String value.
	Field(String name, TokenStream tokenStream) Deprecated. Use TextField instead
	Field(String name, TokenStream tokenStream, Field.TermVector termVector) Deprecated. Use TextField instead
	Field(String name, TokenStream tokenStream, FieldType type) Create field with TokenStream value.

Method Summary

Methods

Modifier and Type	Method and Description
BytesRef	binaryValue() Non-null if this field has a binary value
float	boost() Field boost (you must pre-multiply in any doc boost).
FieldType	fieldType() Returns the FieldType for this field.
String	name() Field name
Number	numericValue() Non-null if this field has a numeric value
Reader	readerValue() The value of the field as a Reader, or null.
void	setBoost(float boost) Sets the boost factor hits on this field.
void	setBytesValue(byte[] value) Expert: change the value of this field.
void	setBytesValue(BytesRef value) Expert: change the value of this field.
void	setByteValue(byte value)
void	setDoubleValue(double value)
void	setFloatValue(float value)
void	setIntValue(int value)
void	setLongValue(long value)
void	setReaderValue(Reader value) Expert: change the value of this field.
void	setShortValue(short value)
void	setStringValue(String value) Expert: change the value of this field.
void	setTokenStream(TokenStream tokenStream) Expert: sets the token stream to be used for indexing and causes isIndexed() and isTokenized() to return true.
String	stringValue() The value of the field as a String, or null.
TokenStream	tokenStream(Analyzer analyzer) Creates the TokenStream used for indexing this field.
TokenStream	tokenStreamValue() The TokesStream for this field to be used when indexing, or null.
String	toString() Prints a Field for human consumption.
static FieldType	translateFieldType(Field.Store store, Field.Index index, Field.TermVector termVector) Deprecated. This is here only to ease transition from the pre-4.0 APIs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

type

protected final FieldType type

name

protected final String name

fieldsData

protected Object fieldsData

tokenStream

protected TokenStream tokenStream

numericTokenStream

protected transient NumericTokenStream numericTokenStream

boost

protected float boost

Constructor Detail

Field

protected Field(String name,
     FieldType type)

Field

public Field(String name,
     Reader reader,
     FieldType type)

Create field with Reader value.

Field

public Field(String name,
     TokenStream tokenStream,
     FieldType type)

Create field with TokenStream value.

Field

public Field(String name,
     byte[] value,
     FieldType type)

Create field with binary value.

Field

public Field(String name,
     byte[] value,
     int offset,
     int length,
     FieldType type)

Create field with binary value.

Field

public Field(String name,
     BytesRef bytes,
     FieldType type)

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.

Field

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

Create field with String value.

Field

@Deprecated
public Field(String name,
                String value,
                Field.Store store,
                Field.Index index)

Deprecated. Use StringField, TextField instead.

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.

Parameters:

name - The name of the field

value - The string to process

store - Whether value should be stored in the index

index - Whether the field should be indexed, and if so, if it should be tokenized before indexing

Throws:

NullPointerException - if name or value is null

IllegalArgumentException - if the field is neither stored nor indexed

Field

@Deprecated
public Field(String name,
                String value,
                Field.Store store,
                Field.Index index,
                Field.TermVector termVector)

Deprecated. Use StringField, TextField instead.

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

Parameters:

name - The name of the field

value - The string to process

store - Whether value should be stored in the index

index - Whether the field should be indexed, and if so, if it should be tokenized before indexing

termVector - Whether term vector should be stored

Throws:

NullPointerException - if name or value is null

IllegalArgumentException - in any of the following situations:

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

Field

@Deprecated
public Field(String name,
                Reader reader)

Deprecated. Use TextField instead.

Create a tokenized and indexed field that is not stored. Term vectors will not be stored. The Reader is read only when the Document is added to the index, i.e. you may not close the Reader until IndexWriter.addDocument(java.lang.Iterable<? extends org.apache.lucene.index.IndexableField>) has been called.

Parameters:

name - The name of the field

reader - The reader with the content

Throws:

NullPointerException - if name or reader is null

Field

@Deprecated
public Field(String name,
                Reader reader,
                Field.TermVector termVector)

Deprecated. Use TextField instead.

Create a tokenized and indexed field that is not stored, optionally with storing term vectors. The Reader is read only when the Document is added to the index, i.e. you may not close the Reader until IndexWriter.addDocument(java.lang.Iterable<? extends org.apache.lucene.index.IndexableField>) has been called.

Parameters:

name - The name of the field

reader - The reader with the content

termVector - Whether term vector should be stored

Throws:

NullPointerException - if name or reader is null

Field

@Deprecated
public Field(String name,
                TokenStream tokenStream)

Deprecated. Use TextField instead

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 IndexWriter.addDocument(java.lang.Iterable<? extends org.apache.lucene.index.IndexableField>) has been called.

Parameters:

name - The name of the field

tokenStream - The TokenStream with the content

Throws:

NullPointerException - if name or tokenStream is null

Field

@Deprecated
public Field(String name,
                TokenStream tokenStream,
                Field.TermVector termVector)

Deprecated. Use TextField instead

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 IndexWriter.addDocument(java.lang.Iterable<? extends org.apache.lucene.index.IndexableField>) has been called.

Parameters:

name - The name of the field

tokenStream - The TokenStream with the content

termVector - Whether term vector should be stored

Throws:

NullPointerException - if name or tokenStream is null

Field

@Deprecated
public Field(String name,
                byte[] value)

Deprecated. Use StoredField instead.

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

Parameters:

name - The name of the field

value - The binary value

Field

@Deprecated
public Field(String name,
                byte[] value,
                int offset,
                int length)

Deprecated. Use StoredField instead.

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

Parameters:

name - The name of the field

value - The binary value

offset - Starting offset in value where this Field's bytes are

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

Method Detail

stringValue

public String stringValue()

The value of the field as a String, or null. If null, the Reader value or binary value is used. Exactly one of stringValue(), readerValue(), and getBinaryValue() must be set.

Specified by:

stringValue in interface IndexableField

readerValue

public Reader readerValue()

The value of the field as a Reader, or null. If null, the String value or binary value is used. Exactly one of stringValue(), readerValue(), and getBinaryValue() must be set.

Specified by:

readerValue in interface IndexableField

tokenStreamValue

public TokenStream tokenStreamValue()

The TokesStream for this field to be used when indexing, or null. If null, the Reader value or String value is analyzed to produce the indexed tokens.

setStringValue

public void setStringValue(String value)

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.

setReaderValue

public void setReaderValue(Reader value)

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

setBytesValue

public void setBytesValue(byte[] value)

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

setBytesValue

public void setBytesValue(BytesRef value)

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.

setByteValue

public void setByteValue(byte value)

setShortValue

public void setShortValue(short value)

setIntValue

public void setIntValue(int value)

setLongValue

public void setLongValue(long value)

setFloatValue

public void setFloatValue(float value)

setDoubleValue

public void setDoubleValue(double value)

setTokenStream

public void setTokenStream(TokenStream 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 stringValue() or getBinaryValue()

name

public String name()

Description copied from interface: IndexableField

Field name

Specified by:

name in interface IndexableField

boost

public float boost()

Description copied from interface: IndexableField

Field boost (you must pre-multiply in any doc boost).

Specified by:

boost in interface IndexableField

setBoost

public void setBoost(float 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.

The boost is used to compute the norm factor for the field. By default, in the Similarity.computeNorm(FieldInvertState, Norm) method, the boost value is multiplied by the length normalization factor and then rounded by TFIDFSimilarity.encodeNormValue(float) before it is stored in the index. One should attempt to ensure that this product does not overflow the range of that encoding.

See Also:

Similarity.computeNorm(FieldInvertState, Norm), TFIDFSimilarity.encodeNormValue(float)

numericValue

public Number numericValue()

Description copied from interface: IndexableField

Non-null if this field has a numeric value

Specified by:

numericValue in interface IndexableField

binaryValue

public BytesRef binaryValue()

Description copied from interface: IndexableField

Non-null if this field has a binary value

Specified by:

binaryValue in interface IndexableField

toString

public String toString()

Prints a Field for human consumption.

Overrides:

toString in class Object

fieldType

public FieldType fieldType()

Returns the FieldType for this field.

Specified by:

fieldType in interface IndexableField

tokenStream

public TokenStream tokenStream(Analyzer analyzer)
                        throws IOException

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

Specified by:

tokenStream in interface IndexableField

Parameters:

analyzer - Analyzer that should be used to create the TokenStreams from

Returns:

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

Throws:

IOException - Can be thrown while creating the TokenStream

translateFieldType

@Deprecated
public static final FieldType translateFieldType(Field.Store store,
                                      Field.Index index,
                                      Field.TermVector termVector)

Deprecated. This is here only to ease transition from the pre-4.0 APIs.

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