Package org.apache.lucene.document

## Class KeywordField

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

- All Implemented Interfaces:
    `IndexableField`

      public class KeywordField
      extends Field

  Field that indexes a per-document String or `BytesRef` into an inverted index for fast filtering, stores values in a columnar fashion using `DocValuesType.SORTED_SET` doc values for sorting and faceting, and optionally stores values as stored fields for top-hits retrieval. This field does not support scoring: queries produce constant scores. If you need more fine-grained control you can use `StringField`, `SortedDocValuesField` or `SortedSetDocValuesField`, and `StoredField`.

  This field defines static factory methods for creating common query objects:

  - `newExactQuery(java.lang.String, org.apache.lucene.util.BytesRef)` for matching a value.
  - `newSetQuery(java.lang.String, org.apache.lucene.util.BytesRef...)` for matching any of the values coming from a set.
  - `newSortField(java.lang.String, boolean, org.apache.lucene.search.SortedSetSelector.Type)` for matching a value.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.lucene.document.Field

      `Field.Store`

  - ### Field Summary

    - ### Fields inherited from class org.apache.lucene.document.Field

      `fieldsData, name, tokenStream, type`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `KeywordField​(String name, String value, Field.Store stored)` | Creates a new KeywordField from a String value, by indexing its UTF-8 representation.
    `KeywordField​(String name, BytesRef value, Field.Store stored)` | Creates a new KeywordField.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `BytesRef` | `binaryValue()` | Non-null if this field has a binary value
    `InvertableType` | `invertableType()` | Describes how this field should be inverted.
    `static Query` | `newExactQuery​(String field, String value)` | Create a query for matching an exact `String` value.
    `static Query` | `newExactQuery​(String field, BytesRef value)` | Create a query for matching an exact `BytesRef` value.
    `static Query` | `newSetQuery​(String field, Collection<BytesRef> values)` | Create a query for matching any of a set of provided `BytesRef` values.
    `static Query` | `newSetQuery​(String field, BytesRef... values)` | Deprecated, for removal: This API element is subject to removal in a future version. Use `newSetQuery(String, Collection)` instead.
    `static SortField` | `newSortField​(String field, boolean reverse, SortedSetSelector.Type selector)` | Create a new `SortField` for `BytesRef` values.
    `void` | `setBytesValue​(BytesRef value)` | Expert: change the value of this field.
    `void` | `setStringValue​(String value)` | Expert: change the value of this field.
    `StoredValue` | `storedValue()` | Stored value.

    - ### Methods inherited from class org.apache.lucene.document.Field

      `fieldType, getCharSequenceValue, name, numericValue, readerValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setTokenStream, stringValue, tokenStream, tokenStreamValue, toString`

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

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

- - ### Constructor Detail

    - #### KeywordField

          public KeywordField​(String name,
                              BytesRef value,
                              Field.Store stored)

      Creates a new KeywordField.
      Parameters:
        `name` - field name
        `value` - the BytesRef value
        `stored` - whether to store the field
      Throws:
        `IllegalArgumentException` - if the field name or value is null.

    - #### KeywordField

          public KeywordField​(String name,
                              String value,
                              Field.Store stored)

      Creates a new KeywordField from a String value, by indexing its UTF-8 representation.
      Parameters:
        `name` - field name
        `value` - the BytesRef value
        `stored` - whether to store the field
      Throws:
        `IllegalArgumentException` - if the field name or value is null.

  - ### Method Detail

    - #### binaryValue

          public BytesRef binaryValue()

      Description copied from interface: `IndexableField`
      Non-null if this field has a binary value
      Specified by:
        `binaryValue` in interface `IndexableField`
      Overrides:
        `binaryValue` in class `Field`

    - #### 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`
      Overrides:
        `invertableType` in class `Field`

    - #### setStringValue

          public void setStringValue​(String value)

      Description copied from class: `Field`
      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.

      Overrides:
        `setStringValue` in class `Field`

    - #### setBytesValue

          public void setBytesValue​(BytesRef value)

      Description copied from class: `Field`
      Expert: change the value of this field. See `Field.setStringValue(String)`.

      NOTE: the provided BytesRef is not copied so be sure not to change it until you're done with this field.

      Overrides:
        `setBytesValue` in class `Field`

    - #### 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`
      Overrides:
        `storedValue` in class `Field`

    - #### newExactQuery

          public static Query newExactQuery​(String field,
                                            BytesRef value)

      Create a query for matching an exact `BytesRef` value.
      Parameters:
        `field` - field name. must not be `null`.
        `value` - exact value
      Returns:
        a query matching documents with this exact value
      Throws:
        `NullPointerException` - if `field` is null.

    - #### newExactQuery

          public static Query newExactQuery​(String field,
                                            String value)

      Create a query for matching an exact `String` value.
      Parameters:
        `field` - field name. must not be `null`.
        `value` - exact value
      Returns:
        a query matching documents with this exact value
      Throws:
        `NullPointerException` - if `field` is null.

    - #### newSetQuery

          @Deprecated(forRemoval=true,
                      since="9.10")
          public static Query newSetQuery​(String field,
                                          BytesRef... values)

      Deprecated, for removal: This API element is subject to removal in a future version.
      Use `newSetQuery(String, Collection)` instead.
      Create a query for matching any of a set of provided `BytesRef` values.
      Parameters:
        `field` - field name. must not be `null`.
        `values` - the set of values to match
      Returns:
        a query matching documents with this exact value
      Throws:
        `NullPointerException` - if `field` is null.

    - #### newSetQuery

          public static Query newSetQuery​(String field,
                                          Collection<BytesRef> values)

      Create a query for matching any of a set of provided `BytesRef` values.
      Parameters:
        `field` - field name. must not be `null`.
        `values` - the set of values to match
      Returns:
        a query matching documents with this exact value
      Throws:
        `NullPointerException` - if `field` is null.

    - #### newSortField

          public static SortField newSortField​(String field,
                                               boolean reverse,
                                               SortedSetSelector.Type selector)

      Create a new `SortField` for `BytesRef` values.
      Parameters:
        `field` - field name. must not be `null`.
        `reverse` - true if natural order should be reversed.
        `selector` - custom selector type for choosing the sort value from the set.