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, java.util.Collection<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, 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

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 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 Details

### 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 Details

### 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

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.