org.apache.lucene.index

Class DocValues

java.lang.Object

org.apache.lucene.index.DocValues

All Implemented Interfaces:

Closeable

public abstract class DocValues
extends Object
implements Closeable

DocValues provides a dense per-document typed storage for fast value access based on the lucene internal document id. DocValues exposes two distinct APIs:

• via getSource() providing RAM resident random access
• via getDirectSource() providing on disk random access

DocValues are exposed via AtomicReader.docValues(String) on a per-segment basis. For best performance DocValues should be consumed per-segment just like IndexReader.

DocValues are fully integrated into the DocValuesFormat API.

NOTE: DocValues is a strongly typed per-field API. Type changes within an indexing session can result in exceptions if the type has changed in a way that the previously give type for a field can't promote the value without losing information. For instance a field initially indexed with DocValues.Type.FIXED_INTS_32 can promote a value with DocValues.Type.FIXED_INTS_8 but can't promote DocValues.Type.FIXED_INTS_64. During segment merging type-promotion exceptions are suppressed. Fields will be promoted to their common denominator or automatically transformed into a 3rd type like DocValues.Type.BYTES_VAR_STRAIGHT to prevent data loss and merge exceptions. This behavior is considered best-effort might change in future releases.

DocValues are exposed via the Field API with type safe specializations for each type variant:

• ByteDocValuesField - for adding byte values to the index
• ShortDocValuesField - for adding short values to the index
• IntDocValuesField - for adding int values to the index
• LongDocValuesField - for adding long values to the index
• FloatDocValuesField - for adding float values to the index
• DoubleDocValuesField - for adding double values to the index
• PackedLongDocValuesField - for adding packed long values to the index
• SortedBytesDocValuesField - for adding sorted BytesRef values to the index
• StraightBytesDocValuesField - for adding straight BytesRef values to the index
• DerefBytesDocValuesField - for adding deref BytesRef values to the index

See DocValues.Type for limitations of each type variant.

See Also:

DocValuesFormat.docsConsumer(org.apache.lucene.index.PerDocWriteState)

WARNING: This API is experimental and might change in incompatible ways in the next release.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DocValues.SortedSource A sorted variant of DocValues.Source for byte[] values per document.
static class	DocValues.Source Source of per document values like long, double or BytesRef depending on the DocValues fields DocValues.Type.
static class	DocValues.SourceCache Abstract base class for DocValues DocValues.Source cache.
static class	DocValues.Type Type specifies the DocValues type for a certain field.

Field Summary

Fields

Modifier and Type	Field and Description
static DocValues[]	EMPTY_ARRAY Zero length DocValues array.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DocValues() Sole constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes this DocValues instance.
static DocValues.SortedSource	getDefaultSortedSource(DocValues.Type type, int size) Returns a SortedSource that always returns default (missing) values for all documents.
static DocValues.Source	getDefaultSource(DocValues.Type type) Returns a Source that always returns default (missing) values for all documents.
abstract DocValues.Source	getDirectSource() Returns a disk resident DocValues.Source instance.
DocValues.Source	getSource() Returns a DocValues.Source instance through the current DocValues.SourceCache.
abstract DocValues.Type	getType() Returns the DocValues.Type of this DocValues instance
int	getValueSize() Returns the size per value in bytes or -1 iff size per value is variable.
abstract DocValues.Source	load() Loads a new DocValues.Source instance for this DocValues field instance.
void	setCache(DocValues.SourceCache cache) Sets the DocValues.SourceCache used by this DocValues instance.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ARRAY

public static final DocValues[] EMPTY_ARRAY

Zero length DocValues array.

Constructor Detail

DocValues

protected DocValues()

Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

load

public abstract DocValues.Source load()
                               throws IOException

Loads a new DocValues.Source instance for this DocValues field instance. Source instances returned from this method are not cached. It is the callers responsibility to maintain the instance and release its resources once the source is not needed anymore.

For managed DocValues.Source instances see getSource().

Throws:

IOException

See Also:

getSource(), setCache(SourceCache)

getSource

public DocValues.Source getSource()
                           throws IOException

Returns a DocValues.Source instance through the current DocValues.SourceCache. Iff no DocValues.Source has been loaded into the cache so far the source will be loaded through load() and passed to the DocValues.SourceCache. The caller of this method should not close the obtained DocValues.Source instance unless it is not needed for the rest of its life time.

DocValues.Source instances obtained from this method are closed / released from the cache once this DocValues instance is closed by the IndexReader, Fields or the DocValues was created from.

Throws:

IOException

getDirectSource

public abstract DocValues.Source getDirectSource()
                                          throws IOException

Returns a disk resident DocValues.Source instance. Direct Sources are not cached in the DocValues.SourceCache and should not be shared between threads.

Throws:

IOException

getType

public abstract DocValues.Type getType()

Returns the DocValues.Type of this DocValues instance

close

public void close()
           throws IOException

Closes this DocValues instance. This method should only be called by the creator of this DocValues instance. API users should not close DocValues instances.

Specified by:

close in interface Closeable

Throws:

IOException

getValueSize

public int getValueSize()

Returns the size per value in bytes or -1 iff size per value is variable.

Returns:

the size per value in bytes or -1 iff size per value is variable.

setCache

public void setCache(DocValues.SourceCache cache)

Sets the DocValues.SourceCache used by this DocValues instance. This method should be called before load() is called. All DocValues.Source instances in the currently used cache will be closed before the new cache is installed.

Note: All instances previously obtained from load() will be lost.

Throws:

IllegalArgumentException - if the given cache is null

getDefaultSource

public static DocValues.Source getDefaultSource(DocValues.Type type)

Returns a Source that always returns default (missing) values for all documents.

getDefaultSortedSource

public static DocValues.SortedSource getDefaultSortedSource(DocValues.Type type,
                                            int size)

Returns a SortedSource that always returns default (missing) values for all documents.