org.apache.lucene.document
Class Field

java.lang.Object
  extended by 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
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
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
  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)
          Expert: creates a field with no initial 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.
 
Method Summary
 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) 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) 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) 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) 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.



Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.