## 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
`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<? 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.

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