org.apache.lucene.document

## Class LongField

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

- All Implemented Interfaces:
    IndexableField

      public final class LongField
      extends Field

  Field that indexes `long` values for efficient range filtering and sorting. Here's an example usage:

       document.add(new LongField(name, 6L, Field.Store.NO));

  For optimal performance, re-use the `LongField` and `Document` instance for more than one document:

        LongField field = new LongField(name, 0L, Field.Store.NO);
        Document document = new Document();
        document.add(field);

        for(all documents) {
          ...
          field.setLongValue(value)
          writer.addDocument(document);
          ...
        }

  See also `IntField`, `FloatField`, `DoubleField`. Any type that can be converted to long can also be indexed. For example, date/time values represented by a `Date` can be translated into a long value using the `Date.getTime()` method. If you don't need millisecond precision, you can quantize the value, either by dividing the result of `Date.getTime()` or using the separate getters (for year, month, etc.) to construct an `int` or `long` value.

  To perform range querying or filtering against a `LongField`, use `NumericRangeQuery` or `NumericRangeFilter`. To sort according to a `LongField`, use the normal numeric sort types, eg `SortField.Type.LONG`. `LongField` values can also be loaded directly from `FieldCache`.

  You may add the same field name as an `LongField` to the same document more than once. Range querying and filtering will be the logical OR of all values; so a range query will hit all documents that have at least one value in the range. However sort behavior is not defined. If you need to sort, you should separately index a single-valued `LongField`.

  A `LongField` will consume somewhat more disk space in the index than an ordinary single-valued field. However, for a typical index that includes substantial textual content per document, this increase will likely be in the noise.

  Within Lucene, each numeric value is indexed as a trie structure, where each term is logically assigned to larger and larger pre-defined brackets (which are simply lower-precision representations of the value). The step size between each successive bracket is called the `precisionStep`, measured in bits. Smaller `precisionStep` values result in larger number of brackets, which consumes more disk space in the index but may result in faster range search performance. The default value, 4, was selected for a reasonable tradeoff of disk space consumption versus performance. You can create a custom `FieldType` and invoke the `FieldType.setNumericPrecisionStep(int)` method if you'd like to change the value. Note that you must also specify a congruent value when creating `NumericRangeQuery` or `NumericRangeFilter`. For low cardinality fields larger precision steps are good. If the cardinality is < 100, it is fair to use `Integer.MAX_VALUE`, which produces one term per value.

  For more information on the internals of numeric trie indexing, including the `precisionStep` configuration, see `NumericRangeQuery`. The format of indexed values is described in `NumericUtils`.

  If you only need to sort by numeric value, and never run range querying/filtering, you can index using a `precisionStep` of `Integer.MAX_VALUE`. This will minimize disk space consumed.

  More advanced users can instead use `NumericTokenStream` directly, when indexing numbers. This class is a wrapper around this token stream type for easier, more intuitive usage.

  Since:
    2.9

- - ### Nested Class Summary

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

      `Field.Index, Field.Store, Field.TermVector`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static FieldType` | `TYPE_NOT_STORED` Type for a LongField that is not stored: normalization factors, frequencies, and positions are omitted.
    `static FieldType` | `TYPE_STORED` Type for a stored LongField: normalization factors, frequencies, and positions are omitted.

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

      `boost, fieldsData, name, tokenStream, type`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LongField(String name, long value, Field.Store stored)` Creates a stored or un-stored LongField with the provided value and default `precisionStep` `NumericUtils.PRECISION_STEP_DEFAULT` (4).
    `LongField(String name, long value, FieldType type)` Expert: allows you to customize the `FieldType`.

  - ### Method Summary

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

      `binaryValue, boost, fieldType, name, numericValue, readerValue, setBoost, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue, toString, translateFieldType`

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

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

- - ### Field Detail

    - #### TYPE_NOT_STORED

          public static final FieldType TYPE_NOT_STORED

      Type for a LongField that is not stored: normalization factors, frequencies, and positions are omitted.

    - #### TYPE_STORED

          public static final FieldType TYPE_STORED

      Type for a stored LongField: normalization factors, frequencies, and positions are omitted.

  - ### Constructor Detail

    - #### LongField

          public LongField(String name,
                   long value,
                   Field.Store stored)

      Creates a stored or un-stored LongField with the provided value and default `precisionStep` `NumericUtils.PRECISION_STEP_DEFAULT` (4).
      Parameters:
        `name` - field name
        `value` - 64-bit long value
        `stored` - Store.YES if the content should also be stored
      Throws:
        `IllegalArgumentException` - if the field name is null.

    - #### LongField

          public LongField(String name,
                   long value,
                   FieldType type)

      Expert: allows you to customize the `FieldType`.
      Parameters:
        `name` - field name
        `value` - 64-bit long value
        `type` - customized field type: must have `FieldType.numericType()` of `FieldType.NumericType.LONG`.
      Throws:
        `IllegalArgumentException` - if the field name or type is null, or if the field type does not have a LONG numericType()

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