Package org.apache.druid.segment

Interface DimensionHandler<EncodedType extends Comparable<EncodedType>,EncodedKeyComponentType,ActualType extends Comparable<ActualType>>

Type Parameters:

EncodedType - class of a single encoded value

EncodedKeyComponentType - A row key contains a component for each dimension, this param specifies the class of this dimension's key component. A column type that supports multivalue rows should use an array type (Strings would use int[]). Column types without multivalue row support should use single objects (e.g., Long, Float).

ActualType - class of a single actual value

All Known Implementing Classes:

DoubleDimensionHandler, FloatDimensionHandler, LongDimensionHandler, NestedCommonFormatColumnHandler, StringDimensionHandler

public interface DimensionHandler<EncodedType extends Comparable<EncodedType>,EncodedKeyComponentType,ActualType extends Comparable<ActualType>>

Processing related interface A DimensionHandler is an object that encapsulates indexing, column merging/building, and querying operations for a given dimension type (e.g., dict-encoded String, Long). These operations are handled by sub-objects created through a DimensionHandler's methods: DimensionIndexer, DimensionMerger, and DimensionColumnReader, respectively. Each DimensionHandler object is associated with a single dimension. This interface allows type-specific behavior column logic, such as choice of indexing structures and disk formats. to be contained within a type-specific set of handler objects, simplifying processing classes such as IncrementalIndex and IndexMerger and allowing for abstracted development of additional dimension types. A DimensionHandler is a stateless object, and thus thread-safe; its methods should be pure functions. The EncodedType and ActualType are Comparable because columns used as dimensions must have sortable values.

Method Summary

Modifier and Type	Method	Description
String	getDimensionName()	Get the name of the column associated with this handler.
DimensionSchema	getDimensionSchema(ColumnCapabilities capabilities)
default DimensionSpec	getDimensionSpec()	Create a DimensionSpec for this handler
Comparator<ColumnValueSelector>	getEncodedValueSelectorComparator()	Returns a comparator that knows how to compare ColumnValueSelector of the assumed dimension type, corresponding to this DimensionHandler.
int	getLengthOfEncodedKeyComponent(EncodedKeyComponentType dimVals)	Given an key component representing a single set of row value(s) for this dimension as an Object, return the length of the key component after appropriate type-casting.
default DimensionSchema.MultiValueHandling	getMultivalueHandling()	Get DimensionSchema.MultiValueHandling for the column associated with this handler.
DimensionIndexer<EncodedType,EncodedKeyComponentType,ActualType>	makeIndexer()	Creates a new DimensionIndexer, a per-dimension object responsible for processing ingested rows in-memory, used by the IncrementalIndex.
default DimensionMergerV9	makeMerger(String outputName, IndexSpec indexSpec, SegmentWriteOutMedium segmentWriteOutMedium, ColumnCapabilities capabilities, ProgressIndicator progress, File segmentBaseDir, Closer closer)	Creates a new DimensionMergerV9, a per-dimension object responsible for merging indexes/row data across segments and building the on-disk representation of a dimension.
default DimensionMergerV9	makeMerger(String outputName, IndexSpec indexSpec, SegmentWriteOutMedium segmentWriteOutMedium, ColumnCapabilities capabilities, ProgressIndicator progress, Closer closer)	Deprecated. use makeMerger(String, IndexSpec, SegmentWriteOutMedium, ColumnCapabilities, ProgressIndicator, File, Closer) This method exists for backwards compatiblity with older versions of Druid since this is an unofficial extension point that must be implemented to create custom dimension types, and will be removed in a future release.
SettableColumnValueSelector	makeNewSettableEncodedValueSelector()	Creates and returns a new object of some implementation of SettableColumnValueSelector, that corresponds to the type of this DimensionHandler.

Method Details

getDimensionName

String getDimensionName()

Get the name of the column associated with this handler. This string would be the output name of the column during ingestion, and the name of an input column when querying.

Returns:

Dimension name

getDimensionSpec

default DimensionSpec getDimensionSpec()

Create a DimensionSpec for this handler

getDimensionSchema

DimensionSchema getDimensionSchema(ColumnCapabilities capabilities)

getMultivalueHandling

@Nullable
default DimensionSchema.MultiValueHandling getMultivalueHandling()

Get DimensionSchema.MultiValueHandling for the column associated with this handler. Only string columns can have DimensionSchema.MultiValueHandling currently.

makeIndexer

DimensionIndexer<EncodedType,EncodedKeyComponentType,ActualType> makeIndexer()

Creates a new DimensionIndexer, a per-dimension object responsible for processing ingested rows in-memory, used by the IncrementalIndex. See DimensionIndexer interface for more information.

Returns:

A new DimensionIndexer object.

makeMerger

@Deprecated
default DimensionMergerV9 makeMerger(String outputName,
 IndexSpec indexSpec,
 SegmentWriteOutMedium segmentWriteOutMedium,
 ColumnCapabilities capabilities,
 ProgressIndicator progress,
 Closer closer)

Deprecated.

use makeMerger(String, IndexSpec, SegmentWriteOutMedium, ColumnCapabilities, ProgressIndicator, File, Closer) This method exists for backwards compatiblity with older versions of Druid since this is an unofficial extension point that must be implemented to create custom dimension types, and will be removed in a future release.

makeMerger

default DimensionMergerV9 makeMerger(String outputName,
 IndexSpec indexSpec,
 SegmentWriteOutMedium segmentWriteOutMedium,
 ColumnCapabilities capabilities,
 ProgressIndicator progress,
 File segmentBaseDir,
 Closer closer)

Creates a new DimensionMergerV9, a per-dimension object responsible for merging indexes/row data across segments and building the on-disk representation of a dimension. For use with IndexMergerV9 only. See DimensionMergerV9 interface for more information.

Parameters:

outputName - Output "file" name for the column to use for serializers, to control where it is stored in the segments internal files

indexSpec - Specification object for the index merge

segmentWriteOutMedium - this SegmentWriteOutMedium object could be used internally in the created merger, if needed

capabilities - The ColumnCapabilities of the dimension represented by this DimensionHandler

progress - ProgressIndicator used by the merging process

segmentBaseDir - segment write out path; temporary files may be created here, though should delete after merge is finished OR be registered with the Closer parameter

closer - Closer tied to segment completion. Anything which is not cleaned up inside of the merger after merge is complete should be registered with this closer. For example, resources which are required for final serialization of the column

Returns:

A new DimensionMergerV9 object.

getLengthOfEncodedKeyComponent

int getLengthOfEncodedKeyComponent(EncodedKeyComponentType dimVals)

Given an key component representing a single set of row value(s) for this dimension as an Object, return the length of the key component after appropriate type-casting. For example, a dictionary encoded String dimension would receive an int[] as input to this method, while a Long numeric dimension would receive a single Long object (no multivalue support)

Parameters:

dimVals - Values for this dimension from a row

Returns:

Size of dimVals

getEncodedValueSelectorComparator

Comparator<ColumnValueSelector> getEncodedValueSelectorComparator()

Returns a comparator that knows how to compare ColumnValueSelector of the assumed dimension type, corresponding to this DimensionHandler. E. g. StringDimensionHandler returns a comparator, that compares ColumnValueSelectors as DimensionSelectors. The comparison rules used by this method should match the rules used by DimensionIndexer.compareUnsortedEncodedKeyComponents(EncodedKeyComponentType, EncodedKeyComponentType), otherwise incorrect ordering/merging of rows can occur during ingestion, causing issues such as imperfect rollup.

makeNewSettableEncodedValueSelector

SettableColumnValueSelector makeNewSettableEncodedValueSelector()

Creates and returns a new object of some implementation of SettableColumnValueSelector, that corresponds to the type of this DimensionHandler. E. g. LongDimensionHandler returns SettableLongColumnValueSelector, etc.