Package org.apache.lucene.document

Class Field

java.lang.Object

org.apache.lucene.document.Field

All Implemented Interfaces:

IndexableField

Direct Known Subclasses:

BinaryDocValuesField, DoubleField, FloatField, IntField, LongField, NumericDocValuesField, SortedDocValuesField, SortedSetDocValuesField, StoredField, 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, 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, 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	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 and how a field 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	Description
protected float	boost	Field's boost
protected Object	fieldsData	Field's value
protected String	name	Field's name
protected TokenStream	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
protected FieldType	type	Field's type

Constructor Summary

Constructors

Modifier	Constructor	Description
	Field(String name, byte[] value)	Deprecated. Use StoredField instead.
	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, byte[] value, FieldType type)	Create field with binary value.
	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.
protected	Field(String name, FieldType type)	Expert: creates a field with no initial value.
	Field(String name, BytesRef bytes, FieldType type)	Create field with binary value.

Method Summary

Modifier and Type	Method	Description
BytesRef	binaryValue()	Non-null if this field has a binary value
float	boost()	Returns the field's index-time 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 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)	Expert: change the value of this field.
void	setDoubleValue(double value)	Expert: change the value of this field.
void	setFloatValue(float value)	Expert: change the value of this field.
void	setIntValue(int value)	Expert: change the value of this field.
void	setLongValue(long value)	Expert: change the value of this field.
void	setReaderValue(Reader value)	Expert: change the value of this field.
void	setShortValue(short value)	Expert: change the value of this field.
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 TokenStream 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

Field's type

name

protected final String name

Field's name

fieldsData

protected Object fieldsData

Field's value

tokenStream

protected TokenStream 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

boost

protected float boost

Field's boost

See Also:

boost()

Constructor Detail

Field

protected Field(String name,
                FieldType type)

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

Parameters:

name - field name

type - field type

Throws:

IllegalArgumentException - if either the name or type is null.

Field

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

Create field with Reader value.

Parameters:

name - field name

reader - reader value

type - field type

Throws:

IllegalArgumentException - if either the name or type is null, or if the field's type is stored(), or if tokenized() is false.

NullPointerException - if the reader is null

Field

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

Create field with TokenStream value.

Parameters:

name - field name

tokenStream - TokenStream value

type - field type

Throws:

IllegalArgumentException - if either the name or type is null, or if the field's type is stored(), or if tokenized() is false, or if indexed() is false.

NullPointerException - if the tokenStream is null

Field

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

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.

Parameters:

name - field name

value - byte array pointing to binary content (not copied)

type - field type

Throws:

IllegalArgumentException - if the field name is null, or the field's type is indexed()

NullPointerException - if the type is null

Field

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

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.

Parameters:

name - field name

value - byte array pointing to binary content (not copied)

offset - starting position of the byte array

length - valid length of the byte array

type - field type

Throws:

IllegalArgumentException - if the field name is null, or the field's type is indexed()

NullPointerException - if the type is null

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.

Parameters:

name - field name

bytes - BytesRef pointing to binary content (not copied)

type - field type

Throws:

IllegalArgumentException - if the field name is null, or the field's type is indexed()

NullPointerException - if the type is null

Field

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

Create field with String value.

Parameters:

name - field name

value - string value

type - field type

Throws:

IllegalArgumentException - if either the name or value is null, or if the field's type is neither indexed() nor stored(), or if indexed() is false but storeTermVectors() is true.

NullPointerException - if the type is null

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 TokenStream 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)

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

setShortValue

public void setShortValue(short value)

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

setIntValue

public void setIntValue(int value)

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

setLongValue

public void setLongValue(long value)

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

setFloatValue

public void setFloatValue(float value)

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

setDoubleValue

public void setDoubleValue(double value)

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

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

Returns the field's index-time boost.

Only fields can have an index-time boost, if you want to simulate a "document boost", then you must pre-multiply it across all the relevant fields yourself.

The boost is used to compute the norm factor for the field. By default, in the Similarity.computeNorm(FieldInvertState) method, the boost value is multiplied by the length normalization factor and then rounded by DefaultSimilarity.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.

It is illegal to return a boost other than 1.0f for a field that is not indexed (IndexableFieldType.indexed() is false) or omits normalization values (IndexableFieldType.omitNorms() returns true).

The default value is 1.0f (no boost).

Specified by:

boost in interface IndexableField

See Also:

setBoost(float)

setBoost

public void setBoost(float boost)

Sets the boost factor on this field.

Throws:

IllegalArgumentException - if this field is not indexed, or if it omits norms.

See Also:

boost()

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

Description copied from interface: IndexableField

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.