Field (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.document, class: Field

Package org.apache.lucene.document

# Class Field

java.lang.Object
org.apache.lucene.document.Field

All Implemented Interfaces:
  `IndexableField`

Direct Known Subclasses:
  `BinaryDocValuesField`, `BinaryPoint`, `ColumnFieldAdapter`, `DoubleField`, `DoublePoint`, `DoubleRange`, `FeatureField`, `FloatField`, `FloatPoint`, `FloatRange`, `InetAddressPoint`, `InetAddressRange`, `IntField`, `IntPoint`, `IntRange`, `KeywordField`, `KnnByteVectorField`, `KnnFloatVectorField`, `LatLonDocValuesField`, `LatLonPoint`, `LongField`, `LongPoint`, `LongRange`, `NumericDocValuesField`, `ShapeDocValuesField`, `ShapeField.Triangle`, `SortedDocValuesField`, `SortedNumericDocValuesField`, `SortedSetDocValuesField`, `StoredField`, `StringField`, `TextField`, `XYDocValuesField`, `XYPointField`

public class Field extends Object implements IndexableField
Expert: directly create a field for a document. Most users should use one of the sugar subclasses:

- `TextField`: `Reader` or `String` indexed for full-text search
- `StringField`: `String` indexed verbatim as a single token
- `IntField`: `int` indexed for exact/range queries.
- `LongField`: `long` indexed for exact/range queries.
- `FloatField`: `float` indexed for exact/range queries.
- `DoubleField`: `double` indexed for exact/range queries.
- `SortedDocValuesField`: `byte[]` indexed column-wise for sorting/faceting
- `SortedSetDocValuesField`: `SortedSet<byte[]>` indexed column-wise for sorting/faceting
- `NumericDocValuesField`: `long` indexed column-wise for sorting/faceting
- `SortedNumericDocValuesField`: `SortedSet<long>` indexed column-wise for sorting/faceting
- `StoredField`: Stored-only value for retrieving in summary results

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 enum`
  `Field.Store`
  Specifies whether and how a field should be stored.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Object`
  `fieldsData`
  Field's value
  `protected final String`
  `name`
  Field's name
  `protected final IndexableFieldType`
  `type`
  Field's type

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `Field(String name, byte[] value, int offset, int length, IndexableFieldType type)`
  Create field with binary value.
  ``
  `Field(String name, byte[] value, IndexableFieldType type)`
  Create field with binary value.
  ``
  `Field(String name, Reader reader, IndexableFieldType type)`
  Create field with Reader value.
  ``
  `Field(String name, CharSequence value, IndexableFieldType type)`
  Create field with String value.
  ``
  `Field(String name, TokenStream tokenStream, IndexableFieldType type)`
  Create field with TokenStream value.
  `protected`
  `Field(String name, IndexableFieldType type)`
  Expert: creates a field with no initial value.
  ``
  `Field(String name, BytesRef bytes, IndexableFieldType type)`
  Create field with binary value.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BytesRef`
  `binaryValue()`
  Non-null if this field has a binary value
  `IndexableFieldType`
  `fieldType()`
  Returns the `FieldType` for this field.
  `CharSequence`
  `getCharSequenceValue()`
  Non-null if this field has a string value
  `InvertableType`
  `invertableType()`
  Describes how this field should be inverted.
  `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`
  `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.
  `StoredValue`
  `storedValue()`
  Stored value.
  `String`
  `stringValue()`
  The value of the field as a String, or null.
  `TokenStream`
  `tokenStream(Analyzer analyzer, TokenStream reuse)`
  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.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### type

    protected final IndexableFieldType type
    Field's type

  - ### name

    protected final String name
    Field's name

  - ### fieldsData

    protected Object fieldsData
    Field's value

- ## Constructor Details

  - ### Field

    protected Field(String name, IndexableFieldType type)
    Expert: creates a field with no initial value. This is intended to be used by custom `Field` sub-classes with pre-configured `IndexableFieldType`s.
    Parameters:
      `name` - field name
      `type` - field type
    Throws:
      `IllegalArgumentException` - if either the name or type is null.

  - ### Field

    public Field(String name, Reader reader, IndexableFieldType 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, IndexableFieldType 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, IndexableFieldType 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, value or type is null, or the field's type is indexed().

  - ### Field

    public Field(String name, byte[] value, int offset, int length, IndexableFieldType 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, value or type is null, or the field's type is indexed().

  - ### Field

    public Field(String name, BytesRef bytes, IndexableFieldType 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, bytes or type is null, or the field's type is indexed().

  - ### Field

    public Field(String name, CharSequence value, IndexableFieldType type)
    Create field with String value.
    Parameters:
      `name` - field name
      `value` - string value
      `type` - field type
    Throws:
      `IllegalArgumentException` - if either the name, value or type is null, or if the field's type is neither indexed() nor stored(), or if indexed() is false but storeTermVectors() is true.

- ## Method Details

  - ### 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 binaryValue() must be set.
    Specified by:
      `stringValue` in interface `IndexableField`

  - ### getCharSequenceValue

    public CharSequence getCharSequenceValue()
    Description copied from interface: `IndexableField`
    Non-null if this field has a string value
    Specified by:
      `getCharSequenceValue` 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 binaryValue() 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.

  - ### name

    public String name()
    Description copied from interface: `IndexableField`
    Field name
    Specified by:
      `name` in interface `IndexableField`

  - ### 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 IndexableFieldType fieldType()
    Returns the `FieldType` for this field.
    Specified by:
      `fieldType` in interface `IndexableField`

  - ### invertableType

    public InvertableType invertableType()
    Description copied from interface: `IndexableField`
    Describes how this field should be inverted. This must return a non-null value if the field indexes terms and postings.
    Specified by:
      `invertableType` in interface `IndexableField`

  - ### tokenStream

    public TokenStream tokenStream(Analyzer analyzer, TokenStream reuse)
    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
      `reuse` - TokenStream for a previous instance of this field name. This allows custom field types (like StringField and NumericField) that do not use the analyzer to still have good performance. Note: the passed-in type may be inappropriate, for example if you mix up different types of Fields for the same field name. So it's the responsibility of the implementation to check.
    Returns:
      TokenStream value for indexing the document. Should always return a non-null value if the field is to be indexed

  - ### storedValue

    public StoredValue storedValue()
    Description copied from interface: `IndexableField`
    Stored value. This method is called to populate stored fields and must return a non-null value if the field stored.
    Specified by:
      `storedValue` in interface `IndexableField`